# Build Agents on Cloudflare

URL: https://developers.cloudflare.com/agents/

import {
	CardGrid,
	Description,
	Feature,
	LinkButton,
	LinkTitleCard,
	PackageManagers,
	Plan,
	RelatedProduct,
	Render,
	TabItem,
	Tabs,
	TypeScriptExample,
} from "~/components";

The Agents SDK enables you to build and deploy AI-powered agents that can autonomously perform tasks, communicate with clients in real time, call AI models, persist state, schedule tasks, run asynchronous workflows, browse the web, query data from your database, support human-in-the-loop interactions, and [a lot more](/agents/api-reference/).

### Ship your first Agent

To use the Agent starter template and create your first Agent with the Agents SDK:

```sh
# install it
npm create cloudflare@latest agents-starter -- --template=cloudflare/agents-starter
# and deploy it
npx wrangler@latest deploy
```

Head to the guide on [building a chat agent](/agents/getting-started/build-a-chat-agent) to learn how the starter project is built and how to use it as a foundation for your own agents.

If you're already building on [Workers](/workers/), you can install the `agents` package directly into an existing project:

```sh
npm i agents
```

And then define your first Agent by creating a class that extends the `Agent` class:

<TypeScriptExample>

```ts
import { Agent, AgentNamespace } from 'agents';

export class MyAgent extends Agent {
	// Define methods on the Agent:
	// https://developers.cloudflare.com/agents/api-reference/agents-api/
	//
	// Every Agent has built in state via this.setState and this.sql
	// Built-in scheduling via this.schedule
	// Agents support WebSockets, HTTP requests, state synchronization and
	// can run for seconds, minutes or hours: as long as the tasks need.
}
```

</TypeScriptExample>

Dive into the [Agent SDK reference](/agents/api-reference/agents-api/) to learn more about how to use the Agents SDK package and defining an `Agent`.

### Why build agents on Cloudflare?

We built the Agents SDK with a few things in mind:

- **Batteries (state) included**: Agents come with [built-in state management](/agents/api-reference/store-and-sync-state/), with the ability to automatically sync state between an Agent and clients, trigger events on state changes, and read+write to each Agent's SQL database.
- **Communicative**: You can connect to an Agent via [WebSockets](/agents/api-reference/websockets/) and stream updates back to client in real-time. Handle a long-running response from a reasoning model, the results of an [asynchronous workflow](/agents/api-reference/run-workflows/), or build a chat app that builds on the `useAgent` hook included in the Agents SDK.
- **Extensible**: Agents are code. Use the [AI models](/agents/api-reference/using-ai-models/) you want, bring-your-own headless browser service, pull data from your database hosted in another cloud, add your own methods to your Agent and call them.

Agents built with Agents SDK can be deployed directly to Cloudflare and run on top of [Durable Objects](/durable-objects/) — which you can think of as stateful micro-servers that can scale to tens of millions — and are able to run wherever they need to. Run your Agents close to a user for low-latency interactivity, close to your data for throughput, and/or anywhere in between.

---

### Build on the Cloudflare Platform

<RelatedProduct header="Workers" href="/workers/" product="workers">

Build serverless applications and deploy instantly across the globe for exceptional performance, reliability, and scale.

</RelatedProduct>

<RelatedProduct header="AI Gateway" href="/ai-gateway/" product="ai-gateway">

Observe and control your AI applications with caching, rate limiting, request retries, model fallback, and more.

</RelatedProduct>

<RelatedProduct header="Vectorize" href="/vectorize/" product="vectorize">

Build full-stack AI applications with Vectorize, Cloudflare’s vector database. Adding Vectorize enables you to perform tasks such as semantic search, recommendations, anomaly detection or can be used to provide context and memory to an LLM.

</RelatedProduct>

<RelatedProduct header="Workers AI" href="/workers-ai/" product="workers-ai">

Run machine learning models, powered by serverless GPUs, on Cloudflare's global network.

</RelatedProduct>

<RelatedProduct header="Workflows" href="/workflows/" product="workflows">

Build stateful agents that guarantee executions, including automatic retries, persistent state that runs for minutes, hours, days, or weeks.

</RelatedProduct>

---

# Changelog

URL: https://developers.cloudflare.com/ai-gateway/changelog/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/ai-gateway.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# OpenAI Compatibility

URL: https://developers.cloudflare.com/ai-gateway/chat-completion/

Cloudflare's AI Gateway offers an OpenAI-compatible `/chat/completions` endpoint, enabling integration with multiple AI providers using a single URL. This feature simplifies the integration process, allowing for seamless switching between different models without significant code modifications.

## Endpoint URL

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions
```

Replace `{account_id}` and `{gateway_id}` with your Cloudflare account and gateway IDs.

## Parameters

Switch providers by changing the `model` and `apiKey` parameters.

Specify the model using `{provider}/{model}` format. For example:

- `openai/gpt-4o-mini`
- `google-ai-studio/gemini-2.0-flash`
- `anthropic/claude-3-haiku`

## Examples

### OpenAI SDK

```js
import OpenAI from "openai";
const client = new OpenAI({
	apiKey: "YOUR_PROVIDER_API_KEY", // Provider API key
  // NOTE: the OpenAI client automatically adds /chat/completions to the end of the URL, you should not add it yourself.
	baseURL: "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat",
});

const response = await client.chat.completions.create({
	model: "google-ai-studio/gemini-2.0-flash",
	messages: [{ role: "user", content: "What is Cloudflare?" }],
});

console.log(response.choices[0].message.content);
```

### cURL

```bash
curl -X POST https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions \
  --header 'Authorization: Bearer {openai_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "google-ai-studio/gemini-2.0-flash",
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ]
  }'
```

### Universal provider

You can also use this pattern with the [Universal Endpoint](/ai-gateway/universal/) to add [fallbacks](/ai-gateway/configuration/fallbacks/) across multiple providers. When used in combination, every request will return the same standardized format, whether from the primary or fallback model. This behavior means that you do not have to add extra parsing logic to your app.

```ts title="index.ts"
export interface Env {
	AI: Ai;
}

export default {
	async fetch(request: Request, env: Env) {
		return env.AI.gateway("default").run({
			provider: "compat",
			endpoint: "chat/completions",
			headers: {
				authorization: "Bearer",
			},
			query: {
				model: "google-ai-studio/gemini-2.0-flash",
				messages: [
					{
						role: "user",
						content: "What is Cloudflare?",
					},
				],
			},
		});
	},
};
```

## Supported Providers

The OpenAI-compatible endpoint supports models from the following providers:

- [Anthropic](/ai-gateway/providers/anthropic/)
- [OpenAI](/ai-gateway/providers/openai/)
- [Groq](/ai-gateway/providers/groq/)
- [Mistral](/ai-gateway/providers/mistral/)
- [Cohere](/ai-gateway/providers/cohere/)
- [Perplexity](/ai-gateway/providers/perplexity/)
- [Workers AI](/ai-gateway/providers/workersai/)
- [Google-AI-Studio](/ai-gateway/providers/google-ai-studio/)
- [Grok](/ai-gateway/providers/grok/)
- [DeepSeek](/ai-gateway/providers/deepseek/)
- [Cerebras](/ai-gateway/providers/cerebras/)

---

# Architectures

URL: https://developers.cloudflare.com/ai-gateway/demos/

import { GlossaryTooltip, ResourcesBySelector } from "~/components";

Learn how you can use AI Gateway within your existing architecture.

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use AI Gateway:

<ResourcesBySelector
	types={[
		"reference-architecture",
		"design-guide",
		"reference-architecture-diagram",
	]}
	products={["AI Gateway"]}
/>

---

# Getting started

URL: https://developers.cloudflare.com/ai-gateway/get-started/

import { Details, DirectoryListing, LinkButton, Render } from "~/components";

In this guide, you will learn how to create your first AI Gateway. You can create multiple gateways to control different applications.

## Prerequisites

Before you get started, you need a Cloudflare account.

<LinkButton variant="primary" href="https://dash.cloudflare.com/sign-up">
	Sign up
</LinkButton>

## Create gateway

Then, create a new AI Gateway.

<Render file="create-gateway" />

## Choosing gateway authentication

When setting up a new gateway, you can choose between an authenticated and unauthenticated gateway. Enabling an authenticated gateway requires each request to include a valid authorization token, adding an extra layer of security. We recommend using an authenticated gateway when storing logs to prevent unauthorized access and protect against invalid requests that can inflate log storage usage and make it harder to find the data you need. Learn more about setting up an [Authenticated Gateway](/ai-gateway/configuration/authentication/).

## Connect application

Next, connect your AI provider to your gateway.

AI Gateway offers multiple endpoints for each Gateway you create - one endpoint per provider, and one Universal Endpoint. To use AI Gateway, you will need to create your own account with each provider and provide your API key. AI Gateway acts as a proxy for these requests, enabling observability, caching, and more.

Additionally, AI Gateway has a [WebSockets API](/ai-gateway/websockets-api/) which provides a single persistent connection, enabling continuous communication. This API supports all AI providers connected to AI Gateway, including those that do not natively support WebSockets.

Below is a list of our supported model providers:

<DirectoryListing folder="ai-gateway/providers" />

If you do not have a provider preference, start with one of our dedicated tutorials:

- [OpenAI](/ai-gateway/tutorials/deploy-aig-worker/)
- [Workers AI](/ai-gateway/tutorials/create-first-aig-workers/)

## View analytics

Now that your provider is connected to the AI Gateway, you can view analytics for requests going through your gateway.

<Render file="analytics-overview" /> <br />

<Render file="analytics-dashboard" />

:::note[Note]

The cost metric is an estimation based on the number of tokens sent and received in requests. While this metric can help you monitor and predict cost trends, refer to your provider's dashboard for the most accurate cost details.

:::

## Next steps

- Learn more about [caching](/ai-gateway/configuration/caching/) for faster requests and cost savings and [rate limiting](/ai-gateway/configuration/rate-limiting/) to control how your application scales.
- Explore how to specify model or provider [fallbacks](/ai-gateway/configuration/fallbacks/) for resiliency.
- Learn how to use low-cost, open source models on [Workers AI](/ai-gateway/providers/workersai/) - our AI inference service.

---

# Header Glossary

URL: https://developers.cloudflare.com/ai-gateway/glossary/

import { Glossary } from "~/components";

AI Gateway supports a variety of headers to help you configure, customize, and manage your API requests. This page provides a complete list of all supported headers, along with a short description

<Glossary product="ai-gateway" />

## Configuration hierarchy

Settings in AI Gateway can be configured at three levels: **Provider**, **Request**, and **Gateway**. Since the same settings can be configured in multiple locations, the following hierarchy determines which value is applied:

1. **Provider-level headers**:
   Relevant only when using the [Universal Endpoint](/ai-gateway/universal/), these headers take precedence over all other configurations.
2. **Request-level headers**:
   Apply if no provider-level headers are set.
3. **Gateway-level settings**:
   Act as the default if no headers are set at the provider or request levels.

This hierarchy ensures consistent behavior, prioritizing the most specific configurations. Use provider-level and request-level headers for more fine-tuned control, and gateway settings for general defaults.

---

# Cloudflare AI Gateway

URL: https://developers.cloudflare.com/ai-gateway/

import {
	CardGrid,
	Description,
	Feature,
	LinkTitleCard,
	Plan,
	RelatedProduct,
} from "~/components";

<Description>

Observe and control your AI applications.

</Description>

<Plan type="all" />

Cloudflare's AI Gateway allows you to gain visibility and control over your AI apps. By connecting your apps to AI Gateway, you can gather insights on how people are using your application with analytics and logging and then control how your application scales with features such as caching, rate limiting, as well as request retries, model fallback, and more. Better yet - it only takes one line of code to get started.

Check out the [Get started guide](/ai-gateway/get-started/) to learn how to configure your applications with AI Gateway.

## Features

<Feature header="Analytics" href="/ai-gateway/observability/analytics/" cta="View Analytics">

View metrics such as the number of requests, tokens, and the cost it takes to run your application.

</Feature>

<Feature header="Logging" href="/ai-gateway/observability/logging/" cta="View Logging">

Gain insight on requests and errors.

</Feature>

<Feature header="Caching" href="/ai-gateway/configuration/caching/">

Serve requests directly from Cloudflare's cache instead of the original model provider for faster requests and cost savings.

</Feature>

<Feature header="Rate limiting" href="/ai-gateway/configuration/rate-limiting">

Control how your application scales by limiting the number of requests your application receives.

</Feature>

<Feature header="Request retry and fallback" href="/ai-gateway/configuration/fallbacks/">

Improve resilience by defining request retry and model fallbacks in case of an error.

</Feature>

<Feature header="Your favorite providers" href="/ai-gateway/providers/">

Workers AI, OpenAI, Azure OpenAI, HuggingFace, Replicate, and more work with AI Gateway.

</Feature>

---

## Related products

<RelatedProduct header="Workers AI" href="/workers-ai/" product="workers-ai">

Run machine learning models, powered by serverless GPUs, on Cloudflare’s global network.

</RelatedProduct>

<RelatedProduct header="Vectorize" href="/vectorize/" product="vectorize">

Build full-stack AI applications with Vectorize, Cloudflare's vector database. Adding Vectorize enables you to perform tasks such as semantic search, recommendations, anomaly detection or can be used to provide context and memory to an LLM.

</RelatedProduct>

## More resources

<CardGrid>

<LinkTitleCard
	title="Developer Discord"
	href="https://discord.cloudflare.com"
	icon="discord"
>
	Connect with the Workers community on Discord to ask questions, show what you
	are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard title="Use cases" href="/use-cases/ai/" icon="document">
	Learn how you can build and deploy ambitious AI applications to Cloudflare's
	global network.
</LinkTitleCard>

<LinkTitleCard
	title="@CloudflareDev"
	href="https://x.com/cloudflaredev"
	icon="x.com"
>
	Follow @CloudflareDev on Twitter to learn about product announcements, and
	what is new in Cloudflare Workers.
</LinkTitleCard>

</CardGrid>

---

# Universal Endpoint

URL: https://developers.cloudflare.com/ai-gateway/universal/

import { Render, Badge } from "~/components";

You can use the Universal Endpoint to contact every provider.

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}
```

AI Gateway offers multiple endpoints for each Gateway you create - one endpoint per provider, and one Universal Endpoint. The Universal Endpoint requires some adjusting to your schema, but supports additional features. Some of these features are, for example, retrying a request if it fails the first time, or configuring a [fallback model/provider](/ai-gateway/configuration/fallbacks/).

You can use the Universal endpoint to contact every provider. The payload is expecting an array of message, and each message is an object with the following parameters:

- `provider` : the name of the provider you would like to direct this message to. Can be OpenAI, workers-ai, or any of our supported providers.
- `endpoint`: the pathname of the provider API you’re trying to reach. For example, on OpenAI it can be `chat/completions`, and for Workers AI this might be [`@cf/meta/llama-3.1-8b-instruct`](/workers-ai/models/llama-3.1-8b-instruct/). See more in the sections that are specific to [each provider](/ai-gateway/providers/).
- `authorization`: the content of the Authorization HTTP Header that should be used when contacting this provider. This usually starts with 'Token' or 'Bearer'.
- `query`: the payload as the provider expects it in their official API.

## cURL example

<Render file="universal-gateway-example" />

The above will send a request to Workers AI Inference API, if it fails it will proceed to OpenAI. You can add as many fallbacks as you need, just by adding another JSON in the array.

## WebSockets API <Badge text="beta" variant="tip" size="small" />

The Universal Endpoint can also be accessed via a [WebSockets API](/ai-gateway/websockets-api/) which provides a single persistent connection, enabling continuous communication. This API supports all AI providers connected to AI Gateway, including those that do not natively support WebSockets.

## WebSockets example

```javascript
import WebSocket from "ws";
const ws = new WebSocket(
	"wss://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/",
	{
		headers: {
			"cf-aig-authorization": "Bearer AI_GATEWAY_TOKEN",
		},
	},
);

ws.send(
	JSON.stringify({
		type: "universal.create",
		request: {
			eventId: "my-request",
			provider: "workers-ai",
			endpoint: "@cf/meta/llama-3.1-8b-instruct",
			headers: {
				Authorization: "Bearer WORKERS_AI_TOKEN",
				"Content-Type": "application/json",
			},
			query: {
				prompt: "tell me a joke",
			},
		},
	}),
);

ws.on("message", function incoming(message) {
	console.log(message.toString());
});
```

## Workers Binding example

import { WranglerConfig } from "~/components";

<WranglerConfig>

```toml title="wrangler.toml"
[ai]
binding = "AI"
```

</WranglerConfig>

```typescript title="src/index.ts"
type Env = {
	AI: Ai;
};

export default {
	async fetch(request: Request, env: Env) {
		return env.AI.gateway('my-gateway').run({
			provider: "workers-ai",
			endpoint: "@cf/meta/llama-3.1-8b-instruct",
			headers: {
				authorization: "Bearer my-api-token",
			},
			query: {
				prompt: "tell me a joke",
			},
		});
	},
};
```

## Header configuration hierarchy

The Universal Endpoint allows you to set fallback models or providers and customize headers for each provider or request. You can configure headers at three levels:

1. **Provider level**: Headers specific to a particular provider.
2. **Request level**: Headers included in individual requests.
3. **Gateway settings**: Default headers configured in your gateway dashboard.

Since the same settings can be configured in multiple locations, AI Gateway applies a hierarchy to determine which configuration takes precedence:

- **Provider-level headers** override all other configurations.
- **Request-level headers** are used if no provider-level headers are set.
- **Gateway-level settings** are used only if no headers are configured at the provider or request levels.

This hierarchy ensures consistent behavior, prioritizing the most specific configurations. Use provider-level and request-level headers for fine-tuned control, and gateway settings for general defaults.

## Hierarchy example

This example demonstrates how headers set at different levels impact caching behavior:

- **Request-level header**: The `cf-aig-cache-ttl` is set to `3600` seconds, applying this caching duration to the request by default.
- **Provider-level header**: For the fallback provider (OpenAI), `cf-aig-cache-ttl` is explicitly set to `0` seconds, overriding the request-level header and disabling caching for responses when OpenAI is used as the provider.

This shows how provider-level headers take precedence over request-level headers, allowing for granular control of caching behavior.

```bash
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id} \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-cache-ttl: 3600' \
  --data '[
    {
      "provider": "workers-ai",
      "endpoint": "@cf/meta/llama-3.1-8b-instruct",
      "headers": {
        "Authorization": "Bearer {cloudflare_token}",
        "Content-Type": "application/json"
      },
      "query": {
        "messages": [
          {
            "role": "system",
            "content": "You are a friendly assistant"
          },
          {
            "role": "user",
            "content": "What is Cloudflare?"
          }
        ]
      }
    },
    {
      "provider": "openai",
      "endpoint": "chat/completions",
      "headers": {
        "Authorization": "Bearer {open_ai_token}",
        "Content-Type": "application/json",
        "cf-aig-cache-ttl": "0"
      },
      "query": {
        "model": "gpt-4o-mini",
        "stream": true,
        "messages": [
          {
            "role": "user",
            "content": "What is Cloudflare?"
          }
        ]
      }
    }
  ]'
```

---

# Getting started

URL: https://developers.cloudflare.com/autorag/get-started/

AutoRAG allows developers to create fully managed retrieval-augmented generation (RAG) pipelines to power AI applications with accurate and up-to-date information without needing to manage infrastructure.

## 1. Upload data or use existing data in R2

AutoRAG integrates with R2 for data import. Create an R2 bucket if you do not have one and upload your data.

:::note
Before you create your first bucket, you must purchase R2 from the Cloudflare dashboard.
:::

To create and upload objects to your bucket from the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/r2) and select **R2**.
2. Select Create bucket, name the bucket, and select **Create bucket**.
3. Choose to either drag and drop your file into the upload area or **select from computer**. Review the [file limits](/autorag/configuration/data-source/) when creating your knowledge base.

_If you need inspiration for what document to use to make your first AutoRAG, try downloading and uploading the [RSS](/changelog/rss/index.xml) of the [Cloudflare Changelog](/changelog/)._

## 2. Create an AutoRAG

To create a new AutoRAG:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/ai/autorag) and select **AI** > **AutoRAG**.
2. Select **Create AutoRAG**, configure the AutoRAG, and complete the setup process.
3. Select **Create**.

## 3. Monitor indexing

Once created, AutoRAG will create a Vectorize index in your account and begin indexing the data.

To monitor the indexing progress:

1. From the **AutoRAG** page in the dashboard, locate and select your AutoRAG.
2. Navigate to the **Overview** page to view the current indexing status.

## 4. Try it out

Once indexing is complete, you can run your first query:

1. From the **AutoRAG** page in the dashboard, locate and select your AutoRAG.
2. Navigate to the **Playground** page.
3. Select **Search with AI** or **Search**.
4. Enter a **query** to test out its response.

## 5. Add to your application

There are multiple ways you can create [RAG applications](/autorag/) with Cloudflare AutoRAG:

- [Workers Binding](/autorag/usage/workers-binding/)
- [REST API](/autorag/usage/rest-api/)

---

# Overview

URL: https://developers.cloudflare.com/autorag/

import {
	CardGrid,
	Description,
	LinkTitleCard,
	Plan,
	RelatedProduct,
	LinkButton,
	Feature,
} from "~/components";

<Description>
	Create fully-managed RAG applications that continuously update and scale on Cloudflare.
</Description>

<Plan type="all" />

AutoRAG lets you create retrieval-augmented generation (RAG) pipelines that power your AI applications with accurate and up-to-date information. Create RAG applications that integrate context-aware AI without managing infrastructure.

You can use AutoRAG to build:

- **Product Chatbot:** Answer customer questions using your own product content.
- **Docs Search:** Make documentation easy to search and use.

<div>
	<LinkButton href="/autorag/get-started">Get started</LinkButton>
	<LinkButton
		target="_blank"
		variant="secondary"
		icon="external"
		href="https://www.youtube.com/watch?v=JUFdbkiDN2U"
	>
		Watch AutoRAG demo
	</LinkButton>
</div>

---

## Features

<Feature header="Automated indexing" href="/autorag/configuration/indexing/" cta="View indexing">

Automatically and continuously index your data source, keeping your content fresh without manual reprocessing.

</Feature>

<Feature header="Multitenancy support" href="/autorag/how-to/multitenancy/" cta="Add filters">

Create multitenancy by scoping search to each tenant’s data using folder-based metadata filters.

</Feature>

<Feature header="Workers Binding" href="/autorag/usage/workers-binding/" cta="Add to Worker">

Call your AutoRAG instance for search or AI Search directly from a Cloudflare Worker using the native binding integration.

</Feature>

<Feature header="Similarity caching" href="/autorag/configuration/cache/" cta="Use caching">

Cache repeated queries and results to improve latency and reduce compute on repeated requests.

</Feature>

---

## Related products

<RelatedProduct header="Workers AI" href="/workers-ai/" product="workers-ai">

Run machine learning models, powered by serverless GPUs, on Cloudflare’s global network.

</RelatedProduct>

<RelatedProduct header="AI Gateway" href="/ai-gateway/" product="ai-gateway">

Observe and control your AI applications with caching, rate limiting, request retries, model fallback, and more.

</RelatedProduct>

<RelatedProduct header="Vectorize" href="/vectorize/" product="vectorize">

Build full-stack AI applications with Vectorize, Cloudflare’s vector database.

</RelatedProduct>

<RelatedProduct header="Workers" href="/workers/" product="workers">

Build serverless applications and deploy instantly across the globe for exceptional performance, reliability, and scale.

</RelatedProduct>

<RelatedProduct header="R2" href="/r2/" product="r2">

Store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.

</RelatedProduct>

---

## More resources

<CardGrid>

<LinkTitleCard
	title="Get started"
	href="/workers-ai/get-started/workers-wrangler/"
	icon="open-book"
>
	Build and deploy your first Workers AI application.
</LinkTitleCard>

<LinkTitleCard
	title="Developer Discord"
	href="https://discord.cloudflare.com"
	icon="discord"
>
	Connect with the Workers community on Discord to ask questions, share what you
	are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard
	title="@CloudflareDev"
	href="https://x.com/cloudflaredev"
	icon="x.com"
>
	Follow @CloudflareDev on Twitter to learn about product announcements, and
	what is new in Cloudflare Workers.
</LinkTitleCard>

</CardGrid>

---

# Changelog

URL: https://developers.cloudflare.com/browser-rendering/changelog/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/browser-rendering.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# FAQ

URL: https://developers.cloudflare.com/browser-rendering/faq/

import { GlossaryTooltip } from "~/components";

Below you will find answers to our most commonly asked questions. If you cannot find the answer you are looking for, refer to the [Discord](https://discord.cloudflare.com) to explore additional resources.

### I see `Cannot read properties of undefined (reading 'fetch')` when using Browser Rendering. How do I fix this?

This error occurs because your Puppeteer launch is not receiving the Browser binding or you are not on a Workers Paid plan.

To resolve: Pass your Browser binding into `puppeteer.launch`.

### Will Browser Rendering bypass Cloudflare's Bot Protection?

No, Browser Rendering requests are always identified as bots by Cloudflare and do not bypass Bot Protection. Additionally, Browser Rendering respects the robots.txt protocol, ensuring that any disallowed paths specified for user agents are not accessed during rendering.

If you are attempting to scan your **own zone** and need Browser Rendering to access areas protected by Cloudflare’s Bot Protection, you can create a [WAF skip rule](/waf/custom-rules/skip/) to bypass the bot protection using a header or a custom user agent.

### Why can't I use an XPath selector when using Browser Rendering with Puppeteer?

Currently it is not possible to use Xpath to select elements since this poses a security risk to Workers.

As an alternative try to use a css selector or `page.evaluate` for example:

```ts
const innerHtml = await page.evaluate(() => {
	return (
		// @ts-ignore this runs on browser context
		new XPathEvaluator()
			.createExpression("/html/body/div/h1")
			// @ts-ignore this runs on browser context
			.evaluate(document, XPathResult.FIRST_ORDERED_NODE_TYPE).singleNodeValue
			.innerHTML
	);
});
```

:::note

Keep in mind that `page.evaluate` can only return primitive types like strings, numbers, etc.

Returning an `HTMLElement` will not work.

:::

### What are the usage limits and pricing tiers for Cloudflare Browser Rendering and how do I estimate my costs?

You can view the complete breakdown of concurrency caps, request rates, timeouts, and REST API quotas on the [limits page](/browser-rendering/platform/limits/).

By default, idle browser sessions close after 60 seconds of inactivity. You can adjust this with the [`keep_alive` option](/browser-rendering/platform/puppeteer/#keep-alive).

#### Pricing

Browser Rendering is currently free up to the limits above until billing begins. Pricing will be announced in advance.

### Does Browser Rendering rotate IP addresses for outbound requests?

No. Browser Rendering requests originate from Cloudflares global network, but you cannot configure per-request IP rotation. All rendering traffic comes from Cloudflare IP ranges and requests include special headers [(`cf-biso-request-id`, `cf-biso-devtools`)](/browser-rendering/reference/automatic-request-headers/) so origin servers can identify them.

### I see `Error processing the request: Unable to create new browser: code: 429: message: Browser time limit exceeded for today`. How do I fix it?

This error indicates you have hit the daily browser-instance limit on the Workers Free plan. [Free-plan accounts are capped at free plan limit is 10 minutes of browser use a day](/browser-rendering/platform/limits/#workers-free) once you exceed those, further creation attempts return a 429 until the next UTC day.

To resolve:[Upgrade to a Workers Paid plan](/workers/platform/pricing/) - Paid accounts raise these limits to [10 concurrent browsers and 10 new instances per minute](/browser-rendering/platform/limits/#workers-paid).

---

# Get started

URL: https://developers.cloudflare.com/browser-rendering/get-started/

Browser rendering can be used in two ways:

- [Workers Bindings](/browser-rendering/workers-bindings/) for complex scripts.
- [REST API](/browser-rendering/rest-api/) for simple actions.

---

# Browser Rendering

URL: https://developers.cloudflare.com/browser-rendering/

import {
	CardGrid,
	Description,
	LinkTitleCard,
	Plan,
	RelatedProduct,
} from "~/components";

<Description>

Browser automation for [Cloudflare Workers](/workers/) and [quick browser actions](/browser-rendering/rest-api/).

</Description>

<Plan type="workers-all" />

Browser Rendering enables developers to programmatically control and interact with headless browser instances running on Cloudflare’s global network. This facilitates tasks such as automating browser interactions, capturing screenshots, generating PDFs, and extracting data from web pages.

## Integration Methods

You can integrate Browser Rendering into your applications using one of the following methods:

- **[REST API](/browser-rendering/rest-api/)**: Ideal for simple, stateless tasks like capturing screenshots, generating PDFs, extracting HTML content, and more.
- **[Workers Bindings](/browser-rendering/workers-bindings/)**: Suitable for advanced browser automation within [Cloudflare Workers](/workers/). This method provides greater control, enabling more complex workflows and persistent sessions.

Choose the method that best fits your use case. For example, use the [REST API endpoints](/browser-rendering/rest-api/) for straightforward tasks from external applications and use [Workers Bindings](/browser-rendering/workers-bindings/) for complex automation within the Cloudflare ecosystem.

## Use Cases

Browser Rendering can be utilized for various purposes, including:

- Fetch HTML content of a page.
- Capture screenshot of a webpage.
- Convert a webpage into a PDF document.
- Take a webpage snapshot.
- Scrape specified HTML elements from a webpage.
- Retrieve data in a structured format.
- Extract Markdown content from a webpage.
- Gather all hyperlinks found on a webpage.

## Related products

<RelatedProduct header="Workers" href="/workers/" product="workers">

Build serverless applications and deploy instantly across the globe for exceptional performance, reliability, and scale.

</RelatedProduct>

<RelatedProduct header="Durable Objects" href="/durable-objects/" product="durable-objects">

A globally distributed coordination API with strongly consistent storage.

</RelatedProduct>

<RelatedProduct header="Agents" href="/agents/" product="agents">

Build and deploy AI-powered agents that can autonomously perform tasks.

</RelatedProduct>

## More resources

<CardGrid>

<LinkTitleCard
	title="Get started"
	href="/browser-rendering/get-started/"
	icon="open-book"
>
	Deploy your first Browser Rendering project using Wrangler and Cloudflare's
	version of Puppeteer.
</LinkTitleCard>

<LinkTitleCard
	title="Learning Path"
	href="/learning-paths/workers/concepts/"
	icon="pen"
>
	New to Workers? Get started with the Workers Learning Path.
</LinkTitleCard>

<LinkTitleCard
	title="Limits"
	href="/browser-rendering/platform/limits/"
	icon="document"
>
	Learn about Browser Rendering limits.
</LinkTitleCard>

<LinkTitleCard
	title="Developer Discord"
	href="https://discord.cloudflare.com"
	icon="discord"
>
	Connect with the Workers community on Discord to ask questions, show what you
	are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard
	title="@CloudflareDev"
	href="https://x.com/cloudflaredev"
	icon="x.com"
>
	Follow @CloudflareDev on Twitter to learn about product announcements, and
	what is new in Cloudflare Workers.
</LinkTitleCard>

</CardGrid>

---

# Cloudflare for Platforms

URL: https://developers.cloudflare.com/cloudflare-for-platforms/

import { Description, Feature } from "~/components"

<Description>

Build your own multitenant platform using Cloudflare as infrastructure
</Description>

Cloudflare for Platforms lets you run untrusted code written by your customers, or by AI, in a secure, hosted sandbox, and give each customer their own subdomain or custom domain.

![Figure 1: Cloudflare for Platforms Architecture Diagram](~/assets/images/reference-architecture/programmable-platforms/programmable-platforms-2.svg)

You can think of Cloudflare for Platforms as the exact same products and functionality that Cloudflare offers its own customers, structured so that you can offer it to your own customers, embedded within your own product. This includes:

- **Isolation and multitenancy** — each of your customers runs code in their own Worker — a [secure and isolated sandbox](/workers/reference/how-workers-works/)
- **Programmable routing, ingress, egress and limits** — you write code that dispatches requests to your customers' code, and can control [ingress](/cloudflare-for-platforms/workers-for-platforms/get-started/dynamic-dispatch/), [egress](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/) and set [per-customer limits](/cloudflare-for-platforms/workers-for-platforms/configuration/custom-limits/)
- **Databases and storage** — you can provide [databases, object storage and more](/workers/runtime-apis/bindings/) to your customers as APIs they can call directly, without API tokens, keys, or external dependencies
- **Custom Domains and Subdomains** — you [call an API](/cloudflare-for-platforms/cloudflare-for-saas/) to create custom subdomains or configure custom domains for each of your customers

Cloudflare for Platforms is used by leading platforms big and small to:

- Build application development platforms tailored to specific domains, like ecommerce storefronts or mobile apps
- Power AI coding platforms that let anyone build and deploy software
- Customize product behavior by allowing any user to write a short code snippet
- Offer every customer their own isolated database
- Provide each customer with their own subdomain

***

## Products

<Feature header="Workers for Platforms" href="/cloudflare-for-platforms/workers-for-platforms/">
Let your customers build and deploy their own applications to your platform, using Cloudflare's developer platform.
</Feature>

<Feature header="Cloudflare for SaaS" href="/cloudflare-for-platforms/cloudflare-for-saas/">
Give your customers their own subdomain or custom domain, protected and accelerated by Cloudflare.
</Feature>

---

# Overview

URL: https://developers.cloudflare.com/constellation/

import { CardGrid, Description, LinkTitleCard } from "~/components"

<Description>

Run machine learning models with Cloudflare Workers.
</Description>

Constellation allows you to run fast, low-latency inference tasks on pre-trained machine learning models natively on Cloudflare Workers. It supports some of the most popular machine learning (ML) and AI runtimes and multiple classes of models.

Cloudflare provides a curated list of verified models, or you can train and upload your own.

Functionality you can deploy to your application with Constellation:

* Content generation, summarization, or similarity analysis
* Question answering
* Audio transcription
* Image or audio classification
* Object detection
* Anomaly detection
* Sentiment analysis

***

## More resources

<CardGrid>

<LinkTitleCard title="Developer Discord" href="https://discord.cloudflare.com" icon="discord">
Connect with the Workers community on Discord to ask questions, show what you are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard title="@CloudflareDev" href="https://x.com/cloudflaredev" icon="x.com">
Follow @CloudflareDev on Twitter to learn about product announcements, and what is new in Cloudflare Workers.
</LinkTitleCard>

</CardGrid>

---

# Architecture

URL: https://developers.cloudflare.com/containers/architecture/

This page describes the architecture of Cloudflare Containers.

## How and where containers run

After you deploy a Worker that uses a Container, your image is uploaded to
[Cloudflare's Registry](/containers/image-management) and distributed globally to Cloudflare's Network.
Cloudflare will pre-schedule instances and pre-fetch images across the globe to ensure quick start
times when scaling up the number of concurrent container instances. This allows you to call
`env.YOUR_CONTAINER.get(id)` and get a new instance quickly without worrying
about the underlying scaling.

When a request is made to start a new container instance, the nearest location
with a pre-fetched image is selected. Subsequent requests to the same instance,
regardless of where they originate, will be routed to this location as long as
the instance stays alive.

Starting additional container instances will use other locations with pre-fetched images,
and Cloudflare will automatically begin prepping additional machines behind the scenes
for additional scaling and quick cold starts. Because there are a finite number pre-warmed
locations, some container instances may be started in locations that are farther away from
the end-user. This is done to ensure that the container instance starts quickly. You are
only charged for actively running instances and not for any unused pre-warmed images.

Each container instance runs inside its own VM, which provides strong
isolation from other workloads running on Cloudflare's network. Containers
should be built for the `linux/amd64` architecture, and should stay within
[size limits](/containers/platform-details/#limits). Logging, metrics collection, and
networking are automatically set up on each container.

## Life of a Container Request

When a request is made to any Worker, including one with an associated Container, it is generally handled
by a datacenter in a location with the best latency between itself and the requesting user.
A different datacenter may be selected to optimize overall latency, if [Smart Placement](/workers/configuration/smart-placement/)
is on, or if the nearest location is under heavy load.

When a request is made to a Container instance, it is sent through a Durable Object, which
can be defined by either using a `DurableObject` or the [`Container` class](/containers/container-package), which
extends Durable Objects with Container-specific APIs and helpers. We recommend using `Container`, see
the [`Container` class documentation](/containers/container-package) for more details.

Each Durable Object is a globally routable isolate that can execute code and store state. This allows
developers to easily address and route to specific container instances (no matter where they are placed),
define and run hooks on container status changes, execute recurring checks on the instance, and store persistent
state associated with each instance.

As mentioned above, when a container instance starts, it is launched in the nearest pre-warmed location. This means that
code in a container is usually executed in a different location than the one handling the Workers request.

:::note
Currently, Durable Objects may be co-located with their associated Container instance, but often are not.

Cloudflare is currently working on expanding the number of locations in which a Durable Object can run,
which will allow container instances to always run in the same location as their Durable Object.
:::

Because all Container requests are passed through a Worker, end-users cannot make TCP or
UDP requests to a Container instance. If you have a use case that requires inbound TCP
or UDP from an end-user, please [let us know](https://forms.gle/AGSq54VvUje6kmKu8).

---

# Beta Info & Roadmap

URL: https://developers.cloudflare.com/containers/beta-info/

Currently, Containers are in beta. There are several changes we plan to make prior to GA:

## Upcoming Changes and Known Gaps

### Limits

Container limits will be raised in the future. We plan to increase
both maximum instance size and maximum number of instances in an account.

See the [Limits documentation](/containers/platform-details/#limits) for more information.

### Autoscaling and load balancing

Currently, Containers are not autoscaled or load balanced. Containers can be scaled manually
by calling `get()` on their binding with a unique ID.

We plan to add official support for utilization-based autoscaling and latency-aware load balancing
in the future.

See the [Autoscaling documentation](/containers/scaling-and-routing) for more information.

### Reduction of log noise

Currently, the `Container` class uses Durable Object alarms to help manage Container shutdown. This
results in unnecessary log noise in the Worker logs. You can filter these logs out in the dashboard
by adding a Query, but this is not ideal.

We plan to automatically reduce log noise in the future.

### Dashboard Updates

The dashboard will be updated to show:

- the status of Container rollouts
- links from Workers to their associated Containers

### Co-locating Durable Objects and Containers

Currently, Durable Objects are not co-located with their associated Container. When requesting a container,
the Durable Object will find one close to it, but not on the same machine.

We plan to co-locate Durable Objects with their Container in the future.

### More advanced Container placement

We currently prewarm servers across our global network with container images to ensure quick start times.
There are times in which you may request a new container and it will be started in a location that
farther from the end user than is desired. We are optimizing this process to ensure that this happens
as little as possible, but it may still occur.

### Atomic code updates across Workers and Containers

When deploying a Container with `wrangler deploy`, the Worker code will be immediately
updated while the Container code will slowly be updated using a rolling deploy.

This means that you must ensure Worker code is backwards compatible with the old Container code.

In the future, Worker code in the Durable Object will only update when associated Container code updates.

## Feedback wanted

There are several areas where we wish to gather feedback from users:

- Do you want to integrate Containers with any other Cloudflare services? If so, which ones and how?
- Do you want more ways to interact with a Container via Workers? If so, how?
- Do you need different mechanisms for routing requests to containers?
- Do you need different mechanisms for scaling containers? (see [scaling documentation](/containers/scaling-and-routing) for information on autoscaling plans)

At any point during the Beta, feel free to [give feedback using this form](https://forms.gle/CscdaEGuw5Hb6H2s7).

---

# Container Package

URL: https://developers.cloudflare.com/containers/container-package/

When writing code that interacts with a container instance, you can either use a
Durable Object directly or use the [`Container` module](https://github.com/cloudflare/containers)
importable from [`@cloudflare/containers`](https://www.npmjs.com/package/@cloudflare/containers).

```javascript
import { Container } from "@cloudflare/containers";

class MyContainer extends Container {
	defaultPort = 8080;
	sleepAfter = "5m";
}
```

We recommend using the `Container` class for most use cases.

Install it with `npm install @cloudflare/containers`.

The `Container` class extends `DurableObject` so all Durable Object functionality is available.
It also provides additional functionality and a nice interface for common container behaviors,
such as:

- sleeping instances after an inactivity timeout
- making requests to specific ports
- running status hooks on startup, stop, or error
- awaiting specific ports before making requests
- setting environment variables and secrets

See the [Containers GitHub repo](https://github.com/cloudflare/containers) for more details
and the complete API.

---

# Frequently Asked Questions

URL: https://developers.cloudflare.com/containers/faq/

import { WranglerConfig } from "~/components";

Frequently Asked Questions:

## How do Container logs work?

To get logs in the Dashboard, including live tailing of logs, toggle `observability` to true
in your Worker's wrangler config:

<WranglerConfig>

```json
{
	"observability": {
		"enabled": true
	}
}
```

</WranglerConfig>

Logs are subject to the same [limits as Worker logs](/workers/observability/logs/workers-logs/#limits), which means that they are
retained for 3 days on Free plans and 7 days on Paid plans.

See [Workers Logs Pricing](/workers/observability/logs/workers-logs/#pricing) for details on cost.

If you are an Enterprise user, you are able to export container logs via [Logpush](/logs/about)
to your preferred destination.

## How are container instance locations selected?

When initially deploying a Container, Cloudflare will select various locations across our
network to deploy instances to. These locations will span multiple regions.

When a Container instance is requested with `this.ctx.container.start`, the nearest free
container instance will be selected from the pre-initialized locations. This will
likely be in the same region as the external request, but may not be. Once the container
instance is running, any future requests will be routed to the initial location.

An Example:

- A user deploys a Container. Cloudflare automatically readies instances across its Network.
- A request is made from a client in Bariloche, Argentia. It reaches the Worker in
  Cloudflare's location in Neuquen, Argentina.
- This Worker request calls `MY_CONTAINER.get("session-1337")` which brings up a Durable
  Object, which then calls `this.ctx.container.start`.
- This requests the nearest free Container instance.
- Cloudflare recognizes that an instance is free in Buenos Aires, Argentina, and
  starts it there.
- A different user needs to route to the same container. This user's request reaches
  the Worker running in Cloudflare's location in San Diego.
- The Worker again calls `MY_CONTAINER.get("session-1337")`.
- If the initial container instance is still running, the request is routed to the location
  in Buenos Aires. If the initial container has gone to sleep, Cloudflare will once
  again try to find the nearest "free" instance of the Container, likely
  one in North America, and start an instance there.

## How do container updates and rollouts work?

When you run `wrangler deploy`, the Worker code is updated immediately and Container
instances are updated using a rolling deploy strategy. Container instances are updated
in batches, with 25% of instances being updated at a time by default.

When a Container instance is ready to be stopped, it is sent a `SIGTERM` signal, which
allows it to gracefully shut down. If the instance does not stop within 15 minutes,
it is forcefully stopped with a `SIGKILL` signal. If you have cleanup that must occur
before a Container instance is stopped, you should do it during this period.

Once stopped, the instance is replaced with a new instance running the updated code. When the
new instance starts, requests will hang during container startup.

## How does scaling work?

See [scaling & routing documentation](/containers/scaling-and-routing/) for details.

## What are cold starts? How fast are they?

A cold start is when a container instance is started from a completely stopped state.

If you call `env.MY_CONTAINER.get(id)` with a completely novel ID and launch
this instance for the first time, it will result in a cold start.

This will start the container image from its entrypoint for the first time. Depending
on what this entrypoint does, it will take a variable amount of time to start.

Container cold starts can often be the 2-3 second range, but this is dependent
on image size and code execution time, among other factors.

## How do I use an existing container image?

See [image management documentation](/containers/image-management/#using-existing-images) for details.

## Is disk persistent? What happens to my disk when my container sleeps?

All disk is ephemeral. When a Container instance goes to sleep, the next time
it is started, it will have a fresh disk as defined by its container image.

Persistent disk is something the Cloudflare team is exploring in the future, but
is not slated for the near term.

## What happens if I run out of memory?

If you run out of memory, your instance will throw an Out of Memory (OOM) error and
will be restarted.

Containers do not use swap memory.

## How long can instances run for? What happens when a host server is shutdown?

Cloudflare will not actively shut off a container instance after a specific amount of
time. If you do not set `sleepAfter` on your Container class, or stop the instance
manually, it will continue to run unless its host server is restarted. This
happens on an irregular cadence, but frequently enough where Cloudflare does not
guarantee that any instance will run for any set period of time.

When a container instance is going to be shut down, it is sent a `SIGTERM` signal,
and then a `SIGKILL` signal after 15 minutes. You should perform any necessary
cleanup to ensure a graceful shutdown in this time. The container instance
will be rebooted elsewhere shortly after this.

## How can I pass secrets to my container?

You can use [Worker Secrets](/workers/configuration/secrets/) or the [Secrets Store](/secrets-store/integrations/workers/)
to define secrets for your Workers.

Then you can pass these secrets to your Container using the `envVars` property:

```javascript
class MyContainer extends Container {
	defaultPort = 5000;
	envVars = {
		MY_SECRET: this.env.MY_SECRET,
	};
}
```

Or when starting a Container instance on a Durable Object:

```javascript
this.ctx.container.start({
	env: {
		MY_SECRET: this.env.MY_SECRET,
	},
});
```

See [the Env Vars and Secrets Example](/containers/examples/env-vars-and-secrets/) for details.

## How do I allow or disallow egress from my container?

When booting a Container, you can specify `enableInternet`, which will toggle
internet access on or off.

To disable it, configure it on your Container class:

```javascript
class MyContainer extends Container {
	defaultPort = 7000;
	enableInternet = false;
}
```

or when starting a Container instance on a Durable Object:

```javascript
this.ctx.container.start({
	enableInternet: false,
});
```

---

# Getting started

URL: https://developers.cloudflare.com/containers/get-started/

import { WranglerConfig, PackageManagers } from "~/components";

In this guide, you will deploy a Worker that can make requests to one or more Containers in response to end-user requests.
In this example, each container runs a small webserver written in Go.

This example Worker should give you a sense for simple Container use, and provide a starting point for more complex use cases.

## Prerequisites

### Ensure Docker is running locally

In this guide, we will build and push a container image alongside your Worker code. By default, this process uses
[Docker](https://www.docker.com/) to do so. You must have Docker running locally when you run `wrangler deploy`. For most people, the best way to install Docker is to follow the [docs for installing Docker Desktop](https://docs.docker.com/desktop/).

You can check that Docker is running properly by running the `docker info` command in your terminal. If Docker is running, the command will succeed. If Docker is not running,
the `docker info` command will hang or return an error including the message "Cannot connect to the Docker daemon".

{/* FUTURE CHANGE: Add some image you can use if you don't have Docker running. */}
{/* FUTURE CHANGE: Link to docs on alternative build/push options */}

## Deploy your first Container



Run the following command to create and deploy a new Worker with a container, from the starter template:

```sh
npm create cloudflare@latest -- --template=cloudflare/templates/containers-template
```

When you want to deploy a code change to either the Worker or Container code, you can run the following command using [Wrangler CLI](/workers/wrangler/:

<PackageManagers type="exec" pkg="wrangler" args="deploy" />

When you run `wrangler deploy`, the following things happen:

- Wrangler builds your container image using Docker.
- Wrangler pushes your image to a [Container Image Registry](/containers/image-management/) that is automatically
  integrated with your Cloudflare account.
- Wrangler deploys your Worker, and configures Cloudflare's network to be ready to spawn instances of your container

The build and push usually take the longest on the first deploy. Subsequent deploys
are faster, because they [reuse cached image layers](https://docs.docker.com/build/cache/).

:::note
After you deploy your Worker for the first time, you will need to wait several minutes until
it is ready to receive requests. Unlike Workers, Containers take a few minutes to be provisioned.
During this time, requests are sent to the Worker, but calls to the Container will error.
:::

### Check deployment status

After deploying, run the following command to show a list of containers containers in your Cloudflare account, and their deployment status:

<PackageManagers type="exec" pkg="wrangler" args="containers list" />

And see images deployed to the Cloudflare Registry with the following command:

<PackageManagers type="exec" pkg="wrangler" args="containers images list" />

### Make requests to Containers

Now, open the URL for your Worker. It should look something like `https://hello-containers.YOUR_ACCOUNT_NAME.workers.dev`.

If you make requests to the paths `/container/1` or `/container/2`, these requests are routed to specific containers.
Each different path after "/container/" routes to a unique container.

If you make requests to `/lb`, you will load balanace requests to one of 3 containers chosen at random.

You can confirm this behavior by reading the output of each request.

## Understanding the Code

Now that you've deployed your first container, let's explain what is happening in your Worker's code, in your configuration file, in your container's code, and how requests are routed.

## Each Container is backed by its own Durable Object

Incoming requests are initially handled by the Worker, then passed to a container-enabled [Durable Object](/durable-objects).
To simplify and reduce boilerplate code, Cloudflare provides a [`Container` class](https://github.com/cloudflare/containers) as part of the `@cloudflare/containers` NPM package.

You don't have to be familiar with Durable Objects to use Containers, but it may be helpful
to understand how the basics.

Each Durable Object runs alongside an individual container instance, manages starting and stopping it, and
can interact with the container through its ports. Containers will likely run near the Worker instance
requesting them, but not necessarily. Refer to ["How Locations are Selected"](/containers/platform-details/#how-are-locations-are-selected)
for details.

In a simple app, the Durable Object may just boot the container and proxy requests to it.

In a more complex app, having container-enabled Durable Objects allows you to route requests to individual stateful container
instances, manage the container lifecycle, pass in custom starting commands and environment variables to containers, run hooks
on container status changes, and more.

See the [documentation for Durable Object container methods](/durable-objects/api/container/) and the
[`Container` class repository](https://github.com/cloudflare/containers) for more details.


### Configuration

Your [Wrangler configuration file](/workers/wrangler/configuration/) defines the configuration for both your Worker and your container:

<WranglerConfig>

```toml
[[containers]]
max_instances = 10
name = "hello-containers"
class_name = "MyContainer"
image = "./Dockerfile"

[[durable_objects.bindings]]
name = "MY_CONTAINER"
class_name = "MyContainer"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["MyContainer"]
```

</WranglerConfig>

Important points about this config:

- `image` points to a Dockerfile or to a directory containing a Dockerfile.
- `class_name` must be a [Durable Object class name](/durable-objects/api/base/).
- `max_instances` declares the maximum number of simultaneously running container instances
  that will run.
- The Durable Object must use [`new_sqlite_classes`](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class) not `new_classes`.

### The Container Image

Your container image must be able to run on the `linux/amd64` architecture, but aside from that, has few limitations.

In the example you just deployed, it is a simple Golang server that responds to requests on port 8080 using
the `MESSAGE` environment variable that will be set in the Worker and an [auto-generated
environment variable](/containers/platform-details/#environment-variables) `CLOUDFLARE_DEPLOYMENT_ID.`

```go
func handler(w http.ResponseWriter, r *http.Request) {
	message := os.Getenv("MESSAGE")
	instanceId := os.Getenv("CLOUDFLARE_DEPLOYMENT_ID")

	fmt.Fprintf(w, "Hi, I'm a container and this is my message: %s, and my instance ID is: %s", message, instanceId)
}
```

:::note
After deploying the example code, to deploy a different image, you can replace the provided image with one of your own.
:::

### Worker code

#### Container Configuration

First note `MyContainer` which extends the [`Container`](https://github.com/cloudflare/containers) class:

```js
export class MyContainer extends Container {
  defaultPort = 8080;
  sleepAfter = '10s';
  envVars = {
    MESSAGE: 'I was passed in via the container class!',
  };

  override onStart() {
    console.log('Container successfully started');
  }

  override onStop() {
    console.log('Container successfully shut down');
  }

  override onError(error: unknown) {
    console.log('Container error:', error);
  }
}
```

This defines basic configuration for the container:

- `defaultPort` sets the port that the `fetch` and `containerFetch` methods will use to communicate with the container. It also blocks
  requests until the container is listening on this port.
- `sleepAfter` sets the timeout for the container to sleep after it has been idle for a certain amount of time.
- `envVars` sets environment variables that will be passed to the container when it starts.
- `onStart`, `onStop`, and `onError` are hooks that run when the container starts, stops, or errors, respectively.

See the [Container class documentation](/containers/container-package) for more details and configuration options.

#### Routing to Containers

When a request enters Cloudflare, your Worker's [`fetch` handler](/workers/runtime-apis/handlers/fetch/) is invoked. This is the code that handles the incoming request. The fetch handler in the example code, launches containers in two ways, on different routes:

- Making requests to `/container/` passes requests to a new container for
  each path. This is done by spinning up a new Container instance. You may note
  that the first request to a new path takes longer than subsequent requests, this is
  because a new container is booting.

  ```js
  if (pathname.startsWith("/container")) {
  	const id = env.MY_CONTAINER.idFromName(pathname);
		const container = env.MY_CONTAINER.get(id);
		return await container.fetch(request);
  }
  ```

- Making requests to `/lb` will load balance requests across several containers.
  This uses a simple `getRandom` helper method, which picks an ID at random
  from a set number (in this case 3), then routes to that Container instance. You can replace this with any routing or load balancing logic you choose to implement:

  ```js
  if (pathname.startsWith("/lb")) {
  	const container = await getRandom(env.MY_CONTAINER, 3);
  	return await container.fetch(request);
  }
  ```

This allows for multiple ways of using Containers:

- If you simply want to send requests to many stateless and interchangeable containers,
  you should load balance.
- If you have stateful services or need individually addressable
  containers, you should request specific Container instances.
- If you are running short-lived jobs, want fine-grained control over the container
  lifecycle, want to parameterize container entrypoint or env vars, or
  want to chain together multiple container calls, you should request specific
  Container instances.

:::note
Currently, routing requests to one of many interchangeable Container instances is accomplished
with the `getRandom` helper.

This is temporary — we plan to add native support for latency-aware autoscaling and load balancing in the coming months.
:::

## View Containers in your Dashboard

The [Containers Dashboard](http://dash.cloudflare.com/?to=/:account/workers/containers) shows you helpful
information about your Containers, including:

- Status and Health
- Metrics
- Logs
- A link to associated Workers and Durable Objects

After launching your Worker, navigate to the Containers Dashboard
by clicking on "Containers" under "Workers & Pages" in your sidebar.

## Next Steps

To do more:

- Modify the image by changing the Dockerfile and calling `wrangler deploy`
- Review our [examples](/containers/examples) for more inspiration
- Get [more information on the Containers Beta](/containers/beta-info)

---

# Containers (Beta)

URL: https://developers.cloudflare.com/containers/

import {
	CardGrid,
	Description,
	Feature,
	LinkTitleCard,
	Plan,
	RelatedProduct,
	TabItem,
	Tabs,
	Badge,
	WranglerConfig,
	LinkButton,
} from "~/components";

<Description>

Enhance your Workers with serverless containers

</Description>

<Plan type="workers-paid" />

Run code written in any programming language, built for any runtime, as part of apps built on [Workers](/workers).

Deploy your container image to Region:Earth without worrying about managing infrastructure - just define your
Worker and `wrangler deploy`.

With Containers you can run:

- Resource-intensive applications that require CPU cores running in parallel, large amounts of memory or disk space
- Applications and libraries that require a full filesystem, specific runtime, or Linux-like environment
- Existing applications and tools that have been distributed as container images

Container instances are spun up on-demand and controlled by code you write in your [Worker](/workers).  Instead of chaining together API calls or writing Kubernetes operators, you just write JavaScript:
<Tabs>
	<TabItem label="Worker Code">
```js
import { Container, getContainer } from "@cloudflare/containers";

export class MyContainer extends Container {
	defaultPort = 4000; // Port the container is listening on
	sleepAfter = "10m"; // Stop the instance if requests not sent for 10 minutes
}

async fetch(request, env) {
	const { "session-id": sessionId } = await request.json();
	// Get the container instance for the given session ID
	const containerInstance = getContainer(env.MY_CONTAINER, sessionId)
	// Pass the request to the container instance on its default port
	return containerInstance.fetch(request);
}

```
</TabItem>
<TabItem label="Worker Config">
<WranglerConfig>

```json
{
  "name": "container-starter",
  "main": "src/index.js",
  "containers": [
    {
      "class_name": "MyContainer",
      "image": "./Dockerfile",
      "instances": 5,
      "name": "hello-containers-go"
    }
  ],
  "durable_objects": {
		"bindings": [
			{
				"class_name": "MyContainer",
        "name": "MY_CONTAINER"
      }
    ]
  }
	"migrations": [
		{
			"new_sqlite_classes": [
				"MyContainer"
			],
			"tag": "v1"
		}
	],
}
```

</WranglerConfig>
</TabItem>
</Tabs>


 <LinkButton variant="primary" href="/containers/get-started/">Get started</LinkButton> <LinkButton variant="secondary" href="https://dash.cloudflare.com/?to=/:account/workers/containers">Containers dashboard</LinkButton>

---

## Next Steps

<Feature header="Deploy your first Container" href="/containers/get-started/" cta="Deploy a Container">

Build and push an image, call a Container from a Worker, and understand scaling and routing.

</Feature>

<Feature header="Container Examples" href="/containers/examples/" cta="See Examples">

See examples of how to use a Container with a Worker, including stateless and stateful routing,
regional placement, Workflow and Queue integrations, AI-generated code execution, and short-lived workloads.

</Feature>

---

## More resources

<CardGrid>

<LinkTitleCard
	title="Beta Information"
	href="/containers/beta-info/"
	icon="seti:shell"
>
	Learn about the Containers Beta and upcoming features.
</LinkTitleCard>

<LinkTitleCard
	title="Wrangler"
	href="/workers/wrangler/commands/#containers"
	icon="document"
>
	Learn more about the commands to develop, build and push images, and deploy
	containers with Wrangler.
</LinkTitleCard>

<LinkTitleCard title="Limits" href="/containers/platform-details/#limits" icon="seti:lock">
	Learn about what limits Containers have and how to work within them.
</LinkTitleCard>

<LinkTitleCard
	title="Containers Discord"
	href="https://discord.cloudflare.com"
	icon="discord"
>
	Connect with other users of Containers on Discord. Ask questions, show what
	you are building, and discuss the platform with other developers.
</LinkTitleCard>

</CardGrid>

---

# Image Management

URL: https://developers.cloudflare.com/containers/image-management/

import { WranglerConfig, PackageManagers } from "~/components";

## Pushing images during `wrangler deploy`

When running `wrangler deploy`, if you set the `image` attribute in you [Wranlger configuration](/workers/wrangler/configuration/#containers)
file to a path, wrangler will build your container image locally using Docker, then push it to a registry run by Cloudflare.
This registry is integrated with your Cloudflare account and is backed by [R2](/r2/). All authentication is handled automatically by
Cloudflare both when pushing and pulling images.

Just provide the path to your Dockerfile:

<WranglerConfig>

```json
{
	"containers": {
		"image": "./Dockerfile"
		// ...rest of config...
	}
}
```

</WranglerConfig>

And deploy your Worker with `wrangler deploy`. No other image management is necessary.

On subsequent deploys, Wrangler will only push image layers that have changed, which saves space and time on `wrangler deploy`
calls after the initial deploy.

:::note
Docker or a Docker-compatible CLI tool must be running for Wrangler to build and push images.
:::

## Using pre-built container images

If you wish to use a pre-built image, first, push it to the Cloudflare Registry:

Wrangler provides a command to push images to the Cloudflare Registry:

<PackageManagers type="exec" pkg="wrangler" args="push <image>:<tag>" />

Additionally, you can use the `-p` flag with `wrangler containers build` to build and push an image in one step:

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="containers build -p -t <tag> ."
/>

Then you can specify the URL in the image attribute:

<WranglerConfig>

```json
{
	"containers": {
		"image": "registry.cloudflare.com/your-namespace/your-image:tag"
		// ...rest of config...
	}
}
```

</WranglerConfig>

Currently, all images must use `registry.cloudflare.com`, which is the default registry for Wrangler.

To use an existing image from another repo, you can pull it, tag it, then push it to the Cloudflare Registry:

```bash
docker pull <public-image>
docker tag <public-image> <image>:<tag>
wrangler containers push <image>:<tag>
```

:::note
We plan to allow configuring public images directly in wrangler config. Cloudflare will
download your image, optionally using auth credentials, then cache it globally in the Cloudflare Registry.

This is not yet available.
:::

## Pushing images with CI

To use an image built in a continuous integration environment, install `wrangler` then
build and pushi images using either `wrangler containers build` with the `--push` flag, or
using the `wrangler containers push` command.

## Registry Limits

Images are limited to 2 GB in size and you are limited to 50 total GB in your account's registry.

:::note
These limits will likely increase in the future.
:::

Delete images with `wrangler containers delete` to free up space, but note that reverting a
Worker to a previous version that uses a deleted image will then error.

---

# Local Development

URL: https://developers.cloudflare.com/containers/local-dev/

You can run both your container and your Worker locally, without additional configuration, by running [`npx wrangler dev`](/workers/wrangler/commands/#dev) in your project's directory.

To develop Container-enabled Workers locally, you will need to first ensure that a
Docker compatible CLI tool and Engine are installed. For instance, you can use [Docker Desktop](https://docs.docker.com/desktop/)
on Mac, Windows, or Linux.

When you run `wrangler dev`, your container image will be built or downloaded. If your
[wrangler configuration](/workers/wrangler/configuration/#containers) sets
the `image` attribute to a local path, the image will be built using the local Dockerfile.
If the `image` attribute is set to a URL, the image will be pulled from the associated registry.

Container instances will be launched locally when your Worker code calls to create
a new container. This may happen when calling `.get()` on a `Container` instance or
by calling `start()` if `manualStart` is set to `true`. Wrangler will
boot new instances and automatically route requests to the correct local container.

When `wrangler dev` stops, all associated container instances are stopped, but
local images are not removed, so that they can be reused in subsequent calls to
`wrangler dev` or `wrangler deploy`.

:::note
If your Worker app creates many container instances, your local machine may not be able to run as many containers concurrently as is possible when you deploy to Cloudflare.

Additionally, if you regularly rebuild containers locally, you may want to clear
out old container images (using `docker image prune` or similar) to reduce disk used.
:::

## Iterating on Container code

When you use `wrangler dev`, your Worker's code is automatically reloaded by Wrangler each time you save a change,
but code running within the container is not.

To rebuild your container with new code changes, you can hit the `[r]` key on your keyboard, which
triggers a rebuild. Container instances will then be restarted with the newly built images.

You may prefer to set up your own code watchers and reloading mechanisms, or mount a local directory
into the local container images to sync code changes. This can be done, but there is no built-in
mechanism for doing so in Wrangler, and best-practices will depend on the languages and frameworks
you are using in your container code.

---

# Platform

URL: https://developers.cloudflare.com/containers/platform-details/

import { WranglerConfig } from "~/components";


## Instance Types

The memory, vCPU, and disk space for Containers are set through predefined instance types.
Three instance types are currently available:

| Instance Type | Memory  | vCPU | Disk |
| ------------- | ------- | ---- | ---- |
| dev           | 256 MiB | 1/16 | 2 GB |
| basic         | 1 GiB   | 1/4  | 4 GB |
| standard      | 4 GiB   | 1/2  | 4 GB |

These are specified using the [`instance_type` property](/workers/wrangler/configuration/#containers) in your Worker's Wrangler configuration file. Looking for larger instances? [Give us feedback here](/containers/beta-info/#feedback-wanted) and tell us what size instances you need, and what you want to use them for.

## Limits


While in open beta, the following limits are currently in effect:

| Feature                                           | Workers Paid |
| ------------------------------------------------- | ------------ |
| GB Memory for all concurrent live Container instances | 40GB [^1]    |
| vCPU for all concurrent live Container instances      | 20 [^1]      |
| GB Disk for all concurrent live Container instances   | 100GB [^1]   |
| Image size                                        | 2 GB         |
| Total image storage per account                   | 50 GB [^2]   |

[^1]: This limit will be raised as we continue the beta.

[^2]: Delete container images with `wrangler containers delete` to free up space. Note that if you delete a container image and then [roll back](/workers/configuration/versions-and-deployments/rollbacks/) your Worker to a previous version, this version may no longer work.

## Environment variables

The container runtime automatically sets the following variables:

- `CLOUDFLARE_COUNTRY_A2` - a two-letter code of a country the container is placed in
- `CLOUDFLARE_DEPLOYMENT_ID` - the ID of the container instance
- `CLOUDFLARE_LOCATION` - a name of a location the container is placed in
- `CLOUDFLARE_NODE_ID` - an ID of a machine the container runs on
- `CLOUDFLARE_PLACEMENT_ID` - a placement ID
- `CLOUDFLARE_REGION` - a region name

:::note
If you supply environment variables with the same names, supplied values will override predefined values.
:::

Custom environment variables can be set when defining a Container in your Worker:

```javascript
class MyContainer extends Container {
	defaultPort = 4000;
	envVars = {
		MY_CUSTOM_VAR: "value",
		ANOTHER_VAR: "another_value",
	};
}
```

---

# Pricing

URL: https://developers.cloudflare.com/containers/pricing/

## vCPU, Memory and Disk

Containers are billed for every 10ms that they are actively running at the following rates, with included monthly usage as part of the $5 USD per month [Workers Paid plan](/workers/platform/pricing/):

|                  | Memory                                                                  | CPU                                                                | Disk                                                           |
| ---------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------- |
| **Free**         | N/A                                                                     | N/A                                                                |                                                                |
| **Workers Paid** | 25 GiB-hours/month included <br/> +$0.0000025 per additional GiB-second | 375 vCPU-minutes/month <br/>+ $0.000020 per additional vCPU-second | 200 GB-hours/month <br/> +$0.00000007 per additional GB-second |

You only pay for what you use — charges start when a request is sent to the container or when it is manually started. Charges stop after the container instance goes to sleep, which can happen automatically after a timeout. This makes it easy to scale to zero, and allows you to get high utilization even with bursty traffic.

#### Instance Types

When you add containers to your Worker, you specify an [instance type](/containers/platform-details/#instance-types). The instance type you select will impact your bill — larger instances include more vCPUs, memory and disk, and therefore incur additional usage costs. The following instance types are currently available, and larger instance types are coming soon:

| Name     | Memory  | CPU       | Disk |
| -------- | ------- | --------- | ---- |
| dev      | 256 MiB | 1/16 vCPU | 2 GB |
| basic    | 1 GiB   | 1/4 vCPU  | 4 GB |
| standard | 4 GiB   | 1/2 vCPU  | 4 GB |

## Network Egress

Egress from Containers is priced at the following rates:

| Region                 | Price per GB | Included Allotment per month |
| ---------------------- | ------------ | ---------------------------- |
| North America & Europe | $0.025       | 1 TB                         |
| Oceania, Korea, Taiwan | $0.05        | 500 GB                       |
| Everywhere Else        | $0.04        | 500 GB                       |

## Workers and Durable Objects Pricing

When you use Containers, incoming requests to your containers are handled by your [Worker](/workers/platform/pricing/), and each container has its own
[Durable Object](/durable-objects/platform/pricing/). You are billed for your usage of both Workers and Durable Objects.

## Logs and Observability

Containers are integrated with the [Workers Logs](/workers/observability/logs/workers-logs/) platform, and billed at the same rate. Refer to [Workers Logs pricing](/workers/observability/logs/workers-logs/#pricing) for details.

When you [enable observability for your Worker](/workers/observability/logs/workers-logs/#enable-workers-logs) with a binding to a container, logs from your container will show in both the Containers and Observability sections of the Cloudflare dashboard.

---

# Scaling and Routing

URL: https://developers.cloudflare.com/containers/scaling-and-routing/

### Scaling container instances with `get()`

Currently, Containers are only scaled manually by calling `BINDING.get()` with a unique ID, then
starting the container. Unless `manualStart` is set to `true` on the Container class, each
instance will start when `get()` is called.

```
// gets 3 container instances
env.MY_CONTAINER.get(idOne)
env.MY_CONTAINER.get(idTwo)
env.MY_CONTAINER.get(idThree)
```

Each instance will run until its `sleepAfter` time has elapsed, or until it is manually stopped.

This behavior is very useful when you want explicit control over the lifecycle of container instances.
For instance, you may want to spin up a container backend instance for a specific user, or you may briefly
run a code sandbox to isolate AI-generated code, or you may want to run a short-lived batch job.

#### The `getRandom` helper function

However, sometimes you want to run multiple instances of a container and easily route requests to them.

Currently, the best way to achieve this is with the _temporary_ `getRandom` helper function:

```javascript
import { Container, getRandom } from "@cloudflare/containers";

const INSTANCE_COUNT = 3;

class Backend extends Container {
	defaultPort = 8080;
	sleepAfter = "2h";
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		// note: "getRandom" to be replaced with latency-aware routing in the near future
		const containerInstance = getRandom(env.BACKEND, INSTANCE_COUNT)
		return containerInstance.fetch(request);
	},
};
```

We have provided the getRandom function as a stopgap solution to route to multiple stateless container instances.
It will randomly select one of N instances for each request and route to it. Unfortunately, it has two major downsides:

- It requires that the user set a fixed number of instances to route to.
- It will randomly select each instance, regardless of location.

We plan to fix these issues with built-in autoscaling and routing features in the near future.

### Autoscaling and routing (unreleased)

:::note
This is an unreleased feature. It is subject to change.
:::

You will be able to turn autoscaling on for a Container, by setting the `autoscale` property to on the Container class:

```javascript
class MyBackend extends Container {
	autoscale = true;
	defaultPort = 8080;
}
```

This instructs the platform to automatically scale instances based on incoming traffic and resource usage (memory, CPU).

Container instances will be launched automatically to serve local traffic, and will be stopped when they are no longer needed.

To route requests to the correct instance, you will use the `getContainer()` helper function to get a container instance, then
pass requests to it:

```javascript
export default {
	async fetch(request, env) {
		return getContainer(env.MY_BACKEND).fetch(request);
	},
};
```

This will send traffic to the nearest ready instance of a container. If a container is overloaded or has not yet launched,
requests will be routed to potentially more distant container. Container readiness can be automatically determined based
on resource use, but will also be configurable with custom readiness checks.

Autoscaling and latency-aware routing will be available in the near future, and will be documented in more detail when released.
Until then, you can use the `getRandom` helper function to route requests to multiple container instances.

---

# Demos and architectures

URL: https://developers.cloudflare.com/d1/demos/

import { ExternalResources, GlossaryTooltip, ResourcesBySelector } from "~/components"

Learn how you can use D1 within your existing application and architecture.

## Featured Demos

- [Starter code for D1 Sessions API](https://github.com/cloudflare/templates/tree/main/d1-starter-sessions-api-template): An introduction to D1 Sessions API. This demo simulates purchase orders administration.

  [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/templates/tree/main/d1-starter-sessions-api-template)

:::note[Tip: Place your database further away for the read replication demo]
To simulate how read replication can improve a worst case latency scenario, select your primary database location to be in a farther away region (one of the deployment steps).

You can find this in the **Database location hint** dropdown.
:::

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for D1.

<ExternalResources type="apps" products={["D1"]} />

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use D1:

<ResourcesBySelector types={["reference-architecture","design-guide","reference-architecture-diagram"]} products={["D1"]} />

---

# Getting started

URL: https://developers.cloudflare.com/d1/get-started/

import { Render, PackageManagers, Steps, FileTree, Tabs, TabItem, TypeScriptExample, WranglerConfig } from "~/components";

This guide instructs you through:

- Creating your first database using D1, Cloudflare's native serverless SQL database.
- Creating a schema and querying your database via the command-line.
- Connecting a [Cloudflare Worker](/workers/) to your D1 database using bindings, and querying your D1 database programmatically.

You can perform these tasks through the CLI or through the Cloudflare dashboard.

:::note
If you already have an existing Worker and an existing D1 database, follow this tutorial from [3. Bind your Worker to your D1 database](/d1/get-started/#3-bind-your-worker-to-your-d1-database).
:::

## Quick start

If you want to skip the steps and get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/d1-get-started/d1/d1-get-started)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers. Use this option if you are familiar with Cloudflare Workers, and wish to skip the step-by-step guidance.

You may wish to manually follow the steps if you are new to Cloudflare Workers.

## Prerequisites

<Render file="prereqs" product="workers" />

## 1. Create a Worker

Create a new Worker as the means to query your database.

<Tabs syncKey='CLIvDash'> <TabItem label='CLI'>

<Steps>
1. Create a new project named `d1-tutorial` by running:

    <PackageManagers type="create" pkg="cloudflare@latest" args={"d1-tutorial"} />

    <Render
    	file="c3-post-run-steps"
    	product="workers"
    	params={{
    	category: "hello-world",
    	type: "Worker only",
    	lang: "TypeScript",
    	}}
    />

    This creates a new `d1-tutorial` directory as illustrated below.

    <FileTree>
    - d1-tutorial
    	- node_modules/
    	- test/
    	- src
    		- **index.ts**
    	- package-lock.json
    	- package.json
    	- testconfig.json
    	- vitest.config.mts
    	- worker-configuration.d.ts
    	- **wrangler.jsonc**
    </FileTree>

    Your new `d1-tutorial` directory includes:

    - A `"Hello World"` [Worker](/workers/get-started/guide/#3-write-code) in `index.ts`.
    - A [Wrangler configuration file](/workers/wrangler/configuration/). This file is how your `d1-tutorial` Worker accesses your D1 database.

</Steps>

:::note

If you are familiar with Cloudflare Workers, or initializing projects in a Continuous Integration (CI) environment, initialize a new project non-interactively by setting `CI=true` as an [environmental variable](/workers/configuration/environment-variables/) when running `create cloudflare@latest`.

For example: `CI=true npm create cloudflare@latest d1-tutorial --type=simple --git --ts --deploy=false` creates a basic "Hello World" project ready to build on.

:::

</TabItem> <TabItem label='Dashboard'>

<Steps>
1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Go to your account > **Compute (Workers)** > **Workers & Pages**.
3. Select **Create**.
4. Under **Start from a template**, select **Hello world**.
5. Name your Worker. For this tutorial, name your Worker `d1-tutorial`.
6. Select **Deploy**.
</Steps>
</TabItem> </Tabs>

## 2. Create a database

A D1 database is conceptually similar to many other SQL databases: a database may contain one or more tables, the ability to query those tables, and optional indexes. D1 uses the familiar [SQL query language](https://www.sqlite.org/lang.html) (as used by SQLite).

To create your first D1 database:

<Tabs syncKey='CLIvDash'> <TabItem label='CLI'>

<Steps>
1. Change into the directory you just created for your Workers project:

    ```sh
    cd d1-tutorial
    ```

2. Run the following `wrangler@latest d1` command and give your database a name. In this tutorial, the database is named `prod-d1-tutorial`:

    :::note
    The [Wrangler command-line interface](/workers/wrangler/) is Cloudflare's tool for managing and deploying Workers applications and D1 databases in your terminal. It was installed when you used `npm create cloudflare@latest` to initialize your new project.

    While Wrangler gets installed locally to your project, you can use it outside the project by using the command `npx wrangler`.
    :::

   ```sh
   npx wrangler@latest d1 create prod-d1-tutorial
   ```

   ```sh output

		✅ Successfully created DB 'prod-d1-tutorial' in region WEUR
		Created your new D1 database.

		{
			"d1_databases": [
				{
					"binding": "DB",
					"database_name": "prod-d1-tutorial",
					"database_id": "<unique-ID-for-your-database>"
				}
			]
		}

   ```



</Steps>

This creates a new D1 database and outputs the [binding](/workers/runtime-apis/bindings/) configuration needed in the next step.

</TabItem> <TabItem label='Dashboard'>

<Steps>
1. Go to **Storage & Databases** > **D1 SQL Database**.
2. Select **Create Database**.
3. Name your database. For this tutorial, name your D1 database `prod-d1-tutorial`.
4. (Optional) Provide a location hint. Location hint is an optional parameter you can provide to indicate your desired geographical location for your database. Refer to [Provide a location hint](/d1/configuration/data-location/#provide-a-location-hint) for more information.
5. Select **Create**.

</Steps>

</TabItem>
</Tabs>

:::note

For reference, a good database name:

- Uses a combination of ASCII characters, shorter than 32 characters, and uses dashes (-) instead of spaces.
- Is descriptive of the use-case and environment. For example, "staging-db-web" or "production-db-backend".
- Only describes the database, and is not directly referenced in code.

:::

## 3. Bind your Worker to your D1 database

You must create a binding for your Worker to connect to your D1 database. [Bindings](/workers/runtime-apis/bindings/) allow your Workers to access resources, like D1, on the Cloudflare developer platform.

To bind your D1 database to your Worker:

<Tabs syncKey='CLIvDash'> <TabItem label='CLI'>

You create bindings by updating your Wrangler file.

<Steps>

1. Copy the lines obtained from [step 2](/d1/get-started/#2-create-a-database) from your terminal.
2. Add them to the end of your Wrangler file.

   <WranglerConfig>

   ```toml
   [[d1_databases]]
   binding = "DB" # available in your Worker on env.DB
   database_name = "prod-d1-tutorial"
   database_id = "<unique-ID-for-your-database>"
   ```

   </WranglerConfig>

   Specifically:

   - The value (string) you set for `binding` is the **binding name**, and is used to reference this database in your Worker. In this tutorial, name your binding `DB`.
   - The binding name must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). For example, `binding = "MY_DB"` or `binding = "productionDB"` would both be valid names for the binding.
   - Your binding is available in your Worker at `env.<BINDING_NAME>` and the D1 [Workers Binding API](/d1/worker-api/) is exposed on this binding.

</Steps>

:::note
When you execute the `wrangler d1 create` command, the client API package (which implements the D1 API and database class) is automatically installed. For more information on the D1 Workers Binding API, refer to [Workers Binding API](/d1/worker-api/).
:::

You can also bind your D1 database to a [Pages Function](/pages/functions/). For more information, refer to [Functions Bindings for D1](/pages/functions/bindings/#d1-databases).

</TabItem> <TabItem label='Dashboard'>

You create bindings by adding them to the Worker you have created.

<Steps>
1. Go to **Compute (Workers)** > **Workers & Pages**.
2. Select the `d1-tutorial` Worker you created in [step 1](/d1/get-started/#1-create-a-worker).
3. Select **Settings**.
4. Scroll to **Bindings**, then select **Add**.
5. Select **D1 database**.
6. Name your binding in **Variable name**, then select the `prod-d1-tutorial` D1 database you created in [step 2](/d1/get-started/#2-create-a-database) from the dropdown menu. For this tutorial, name your binding `DB`.
7. Select **Deploy** to deploy your binding. When deploying, there are two options:
	- **Deploy:** Immediately deploy the binding to 100% of your audience.
	- **Save version:** Save a version of the binding which you can deploy in the future.

    For this tutorial, select **Deploy**.

</Steps>

</TabItem>
</Tabs>

## 4. Run a query against your D1 database

### Populate your D1 database

<Tabs syncKey='CLIvDash'> <TabItem label='CLI'>

After correctly preparing your [Wrangler configuration file](/workers/wrangler/configuration/), set up your database. Create a `schema.sql` file using the SQL syntax below to initialize your database.

<Steps>
1. Copy the following code and save it as a `schema.sql` file in the `d1-tutorial` Worker directory you created in step 1:

    ```sql
    DROP TABLE IF EXISTS Customers;
    CREATE TABLE IF NOT EXISTS Customers (CustomerId INTEGER PRIMARY KEY, CompanyName TEXT, ContactName TEXT);
    INSERT INTO Customers (CustomerID, CompanyName, ContactName) VALUES (1, 'Alfreds Futterkiste', 'Maria Anders'), (4, 'Around the Horn', 'Thomas Hardy'), (11, 'Bs Beverages', 'Victoria Ashworth'), (13, 'Bs Beverages', 'Random Name');
    ```

2. Initialize your database to run and test locally first. Bootstrap your new D1 database by running:

   ```sh
   npx wrangler d1 execute prod-d1-tutorial --local --file=./schema.sql
   ```
    ```output
     ⛅️ wrangler 4.13.2
    -------------------

    🌀 Executing on local database prod-d1-tutorial (<DATABASE_ID>) from .wrangler/state/v3/d1:
    🌀 To execute on your remote database, add a --remote flag to your wrangler command.
    🚣 3 commands executed successfully.
    ```

    :::note
    The command `npx wrangler d1 execute` initializes your database locally, not on the remote database.
    :::

3. Validate that your data is in the database by running:

   ```sh
   npx wrangler d1 execute prod-d1-tutorial --local --command="SELECT * FROM Customers"
   ```

   ```sh output
   🌀 Mapping SQL input into an array of statements
   🌀 Executing on local database production-db-backend (<DATABASE_ID>) from .wrangler/state/v3/d1:
   ┌────────────┬─────────────────────┬───────────────────┐
   │ CustomerId │ CompanyName         │ ContactName       │
   ├────────────┼─────────────────────┼───────────────────┤
   │ 1          │ Alfreds Futterkiste │ Maria Anders      │
   ├────────────┼─────────────────────┼───────────────────┤
   │ 4          │ Around the Horn     │ Thomas Hardy      │
   ├────────────┼─────────────────────┼───────────────────┤
   │ 11         │ Bs Beverages        │ Victoria Ashworth │
   ├────────────┼─────────────────────┼───────────────────┤
   │ 13         │ Bs Beverages        │ Random Name       │
   └────────────┴─────────────────────┴───────────────────┘
   ```

</Steps>

</TabItem> <TabItem label='Dashboard'>

Use the Dashboard to create a table and populate it with data.

<Steps>
1. Go to **Storage & Databases** > **D1 SQL Database**.
2. Select the `prod-d1-tutorial` database you created in [step 2](/d1/get-started/#2-create-a-database).
3. Select **Console**.
4. Paste the following SQL snippet.

    ```sql
    DROP TABLE IF EXISTS Customers;
    CREATE TABLE IF NOT EXISTS Customers (CustomerId INTEGER PRIMARY KEY, CompanyName TEXT, ContactName TEXT);
    INSERT INTO Customers (CustomerID, CompanyName, ContactName) VALUES (1, 'Alfreds Futterkiste', 'Maria Anders'), (4, 'Around the Horn', 'Thomas Hardy'), (11, 'Bs Beverages', 'Victoria Ashworth'), (13, 'Bs Beverages', 'Random Name');
    ```

5. Select **Execute**. This creates a table called `Customers` in your `prod-d1-tutorial` database.
6. Select **Tables**, then select the `Customers` table to view the contents of the table.

</Steps>

</TabItem>
</Tabs>

### Write queries within your Worker

After you have set up your database, run an SQL query from within your Worker.

<Tabs syncKey='CLIvDash'> <TabItem label='CLI'>

<Steps>
1. Navigate to your `d1-tutorial` Worker and open the `index.ts` file. The `index.ts` file is where you configure your Worker's interactions with D1.
2. Clear the content of `index.ts`.
3. Paste the following code snippet into your `index.ts` file:

    <TypeScriptExample filename="index.ts">
    ```typescript
    export interface Env {
    	// If you set another name in the Wrangler config file for the value for 'binding',
    	// replace "DB" with the variable name you defined.
    	DB: D1Database;
    }

    export default {
    	async fetch(request, env): Promise<Response> {
    		const { pathname } = new URL(request.url);

    		if (pathname === "/api/beverages") {
    			// If you did not use `DB` as your binding name, change it here
    			const { results } = await env.DB.prepare(
    				"SELECT * FROM Customers WHERE CompanyName = ?",
    			)
    				.bind("Bs Beverages")
    				.all();
    			return Response.json(results);
    		}

    		return new Response(
    			"Call /api/beverages to see everyone who works at Bs Beverages",
    		);
    	},
    } satisfies ExportedHandler<Env>;
    ```
    </TypeScriptExample>

    In the code above, you:

    1. Define a binding to your D1 database in your code. This binding matches the `binding` value you set in the [Wrangler configuration file](/workers/wrangler/configuration/) under `d1_databases`.
    2. Query your database using `env.DB.prepare` to issue a [prepared query](/d1/worker-api/d1-database/#prepare) with a placeholder (the `?` in the query).
    3. Call `bind()` to safely and securely bind a value to that placeholder. In a real application, you would allow a user to pass the `CompanyName` they want to list results for. Using `bind()` prevents users from executing arbitrary SQL (known as "SQL injection") against your application and deleting or otherwise modifying your database.
    4. Execute the query by calling `all()` to return all rows (or none, if the query returns none).
    5. Return your query results, if any, in JSON format with `Response.json(results)`.

</Steps>

After configuring your Worker, you can test your project locally before you deploy globally.

</TabItem> <TabItem label='Dashboard'>

You can query your D1 database using your Worker.

<Steps>
1. Go to **Compute (Workers)** > **Workers & Pages**.
2. Select the `d1-tutorial` Worker you created.
3. Select the **Edit code** icon (**\<\/\>**).
4. Clear the contents of the `worker.js` file, then paste the following code:

    ```js
    export default {
    	async fetch(request, env) {
    		const { pathname } = new URL(request.url);

    		if (pathname === "/api/beverages") {
    			// If you did not use `DB` as your binding name, change it here
    			const { results } = await env.DB.prepare(
    				"SELECT * FROM Customers WHERE CompanyName = ?"
    			)
    				.bind("Bs Beverages")
    				.all();
    			return new Response(JSON.stringify(results), {
    				headers: { 'Content-Type': 'application/json' }
    			});
    		}

    		return new Response(
    			"Call /api/beverages to see everyone who works at Bs Beverages"
    		);
    	},
    };
    ```

5. Select **Save**.

</Steps>
</TabItem>
</Tabs>

## 5. Deploy your application

Deploy your application on Cloudflare's global network.

<Tabs syncKey='CLIvDash'> <TabItem label='CLI'>

To deploy your Worker to production using Wrangler, you must first repeat the [database configuration](/d1/get-started/#populate-your-d1-database) steps after replacing the `--local` flag with the `--remote` flag to give your Worker data to read. This creates the database tables and imports the data into the production version of your database.

<Steps>
1. Create tables and add entries to your remote database with the `schema.sql` file you created in step 4. Enter `y` to confirm your decision.

    ```sh
    npx wrangler d1 execute prod-d1-tutorial --remote --file=./schema.sql
    ```
    ```sh output
    ✔ ⚠️ This process may take some time, during which your D1 database will be unavailable to serve queries.
    Ok to proceed? y
    🚣 Executed 3 queries in 0.00 seconds (5 rows read, 6 rows written)
   	Database is currently at bookmark 00000002-00000004-00004ef1-ad4a06967970ee3b20860c86188a4b31.
    ┌────────────────────────┬───────────┬──────────────┬────────────────────┐
    │ Total queries executed │ Rows read │ Rows written │ Database size (MB) │
    ├────────────────────────┼───────────┼──────────────┼────────────────────┤
    │ 3                      │ 5         │ 6            │ 0.02               │
    └────────────────────────┴───────────┴──────────────┴────────────────────┘
		```

2. Validate the data is in production by running:

    ```sh
    npx wrangler d1 execute prod-d1-tutorial --remote --command="SELECT * FROM Customers"
    ```
    ```sh output
     ⛅️ wrangler 4.13.2
    -------------------

    🌀 Executing on remote database prod-d1-tutorial (<DATABASE_ID>):
    🌀 To execute on your local development database, remove the --remote flag from your wrangler command.
    🚣 Executed 1 command in 0.4069ms
    ┌────────────┬─────────────────────┬───────────────────┐
    │ CustomerId │ CompanyName         │ ContactName       │
    ├────────────┼─────────────────────┼───────────────────┤
    │ 1          │ Alfreds Futterkiste │ Maria Anders      │
    ├────────────┼─────────────────────┼───────────────────┤
    │ 4          │ Around the Horn     │ Thomas Hardy      │
    ├────────────┼─────────────────────┼───────────────────┤
    │ 11         │ Bs Beverages        │ Victoria Ashworth │
    ├────────────┼─────────────────────┼───────────────────┤
    │ 13         │ Bs Beverages        │ Random Name       │
    └────────────┴─────────────────────┴───────────────────┘
    ```

3. Deploy your Worker to make your project accessible on the Internet. Run:

   ```sh
   npx wrangler deploy
   ```
   ```sh output
    ⛅️ wrangler 4.13.2
    -------------------

    Total Upload: 0.19 KiB / gzip: 0.16 KiB
    Your worker has access to the following bindings:
    - D1 Databases:
      - DB: prod-d1-tutorial (<DATABASE_ID>)
    Uploaded d1-tutorial (3.76 sec)
    Deployed d1-tutorial triggers (2.77 sec)
      https://d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev
    Current Version ID: <VERSION_ID>
    ```

   You can now visit the URL for your newly created project to query your live database.

   For example, if the URL of your new Worker is `d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev`, accessing `https://d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev/api/beverages` sends a request to your Worker that queries your live database directly.

4. Test your database is running successfully. Add `/api/beverages` to the provided Wrangler URL. For example, `https://d1-tutorial.<YOUR_SUBDOMAIN>.workers.dev/api/beverages`.

</Steps>

</TabItem> <TabItem label='Dashboard'>
<Steps>

1. Go to **Compute (Workers)** > **Workers & Pages**.
2. Select your `d1-tutorial` Worker.
3. Select **Deployments**.
4. From the **Version History** table, select **Deploy version**.
5. From the **Deploy version** page, select **Deploy**.

</Steps>

This deploys the latest version of the Worker code to production.

</TabItem></Tabs>

## 6. (Optional) Develop locally with Wrangler

If you are using D1 with Wrangler, you can test your database locally. While in your project directory:

<Steps>
1. Run `wrangler dev`:

    ```sh
    npx wrangler dev
    ```

    When you run `wrangler dev`, Wrangler provides a URL (most likely `localhost:8787`) to review your Worker.

2. Go to the URL.

   The page displays `Call /api/beverages to see everyone who works at Bs Beverages`.

3. Test your database is running successfully. Add `/api/beverages` to the provided Wrangler URL. For example, `localhost:8787/api/beverages`.

</Steps>

If successful, the browser displays your data.

:::note
You can only develop locally if you are using Wrangler. You cannot develop locally through the Cloudflare dashboard.
:::

## 7. (Optional) Delete your database

To delete your database:

<Tabs syncKey='CLIvDash'> <TabItem label='CLI'>

Run:

```sh
npx wrangler d1 delete prod-d1-tutorial
```

</TabItem><TabItem label='Dashboard'>

<Steps>
1. Go to **Storages & Databases** > **D1 SQL Database**.

2. Select your `prod-d1-tutorial` D1 database.

3. Select **Settings**.

4. Select **Delete**.

5. Type the name of the database (`prod-d1-tutorial`) to confirm the deletion.

</Steps>

</TabItem> </Tabs>

:::caution
Note that deleting your D1 database will stop your application from functioning as before.
:::

If you want to delete your Worker:

<Tabs syncKey='CLIvDash'> <TabItem label='CLI'>

Run:

```sh
npx wrangler delete d1-tutorial
```

</TabItem> <TabItem label='Dashboard'>

<Steps>
1. Go to **Compute (Workers)** > **Workers & Pages**.

2. Select your `d1-tutorial` Worker.

3. Select **Settings**.

4. Scroll to the bottom of the page, then select **Delete**.

5. Type the name of the Worker (`d1-tutorial`) to confirm the deletion.

</Steps>

</TabItem></Tabs>

## Summary

In this tutorial, you have:

- Created a D1 database
- Created a Worker to access that database
- Deployed your project globally

## Next steps

If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the [Cloudflare Developers community on Discord](https://discord.cloudflare.com).

- See supported [Wrangler commands for D1](/workers/wrangler/commands/#d1).
- Learn how to use [D1 Worker Binding APIs](/d1/worker-api/) within your Worker, and test them from the [API playground](/d1/worker-api/#api-playground).
- Explore [community projects built on D1](/d1/reference/community-projects/).

---

# Cloudflare D1

URL: https://developers.cloudflare.com/d1/

import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct } from "~/components"

<Description>


Create new serverless SQL databases to query from your Workers and Pages projects.


</Description>

<Plan type="workers-all" />

D1 is Cloudflare's managed, serverless database with SQLite's SQL semantics, built-in disaster recovery, and Worker and HTTP API access.

D1 is designed for horizontal scale out across multiple, smaller (10 GB) databases, such as per-user, per-tenant or per-entity databases. D1 allows you to build applications with thousands of databases at no extra cost for isolating with multiple databases. D1 pricing is based only on query and storage costs.

Create your first D1 database by [following the Get started guide](/d1/get-started/), learn how to [import data into a database](/d1/best-practices/import-export-data/), and how to [interact with your database](/d1/worker-api/) directly from [Workers](/workers/) or [Pages](/pages/functions/bindings/#d1-databases).

***

## Features

<Feature header="Create your first D1 database" href="/d1/get-started/" cta="Create your D1 database">

Create your first D1 database, establish a schema, import data and query D1 directly from an application [built with Workers](/workers/).


</Feature>

<Feature header="SQLite" href="/d1/sql-api/sql-statements/" cta="Execute SQL queries">

Execute SQL with SQLite's SQL compatibility and D1 Client API.


</Feature>

<Feature header="Time Travel" href="/d1/reference/time-travel/" cta="Learn about Time Travel">

Time Travel is D1’s approach to backups and point-in-time-recovery, and allows you to restore a database to any minute within the last 30 days.


</Feature>

***

## Related products

<RelatedProduct header="Workers" href="/workers/" product="workers">

Build serverless applications and deploy instantly across the globe for exceptional performance, reliability, and scale.


</RelatedProduct>

<RelatedProduct header="Pages" href="/pages/" product="pages">

Deploy dynamic front-end applications in record time.


</RelatedProduct>

***

## More resources

<CardGrid>

<LinkTitleCard title="Pricing" href="/d1/platform/pricing/" icon="seti:shell">
Learn about D1's pricing and how to estimate your usage.
</LinkTitleCard>

<LinkTitleCard title="Limits" href="/d1/platform/limits/" icon="document">
Learn about what limits D1 has and how to work within them.
</LinkTitleCard>

<LinkTitleCard title="Community projects" href="/d1/reference/community-projects/" icon="pen">
Browse what developers are building with D1.
</LinkTitleCard>

<LinkTitleCard title="Storage options" href="/workers/platform/storage-options/" icon="document">
Learn more about the storage and database options you can build on with Workers.
</LinkTitleCard>

<LinkTitleCard title="Developer Discord" href="https://discord.cloudflare.com" icon="discord">
Connect with the Workers community on Discord to ask questions, show what you are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard title="@CloudflareDev" href="https://x.com/cloudflaredev" icon="x.com">
Follow @CloudflareDev on Twitter to learn about product announcements, and what is new in Cloudflare Developer Platform.
</LinkTitleCard>

</CardGrid>

---

# Wrangler commands

URL: https://developers.cloudflare.com/d1/wrangler-commands/

import { Render, Type, MetaInfo } from "~/components"

D1 Wrangler commands use REST APIs to interact with the control plane. This page lists the Wrangler commands for D1.

<Render file="wrangler-commands/d1" product="workers" />

## Global commands

<Render file="wrangler-commands/global-flags" product="workers" />

## Experimental commands

### `insights`

Returns statistics about your queries.

```sh
npx wrangler d1 insights <database_name> --<option>
```

For more information, see [Query `insights`](/d1/observability/metrics-analytics/#query-insights).

---

# Application guide

URL: https://developers.cloudflare.com/developer-spotlight/application-guide/

If you use Cloudflare's developer products and would like to share your expertise then Cloudflare's Developer Spotlight program is for you. Whether you use Cloudflare in your profession, as a student or as a hobby, let us spotlight your creativity. Write a tutorial for our documentation and earn credits for your Cloudflare account along with having your name credited on your work.

The Developer Spotlight program is open for applicants until Thursday, the 24th of October 2024.

## Who can apply?

The following is required in order to be an eligible applicant for the Developer Spotlight program:

- You must not be an employee of Cloudflare.
- You must be 18 or older.
- All participants must agree to the [Developer Spotlight terms](/developer-spotlight/terms/).

## Submission rules

Your tutorial must be:

1. Easy for anyone to follow.
2. Technically accurate.
3. Entirely original, written only by you.
4. Written following Cloudflare's documentation style guide. For more information, please visit our [style guide documentation](/style-guide/) and our [tutorial style guide documentation](/style-guide/documentation-content-strategy/content-types/tutorial/#template)
5. About how to use [Cloudflare's Developer Platform products](/products/?product-group=Developer+platform) to create a project or solve a problem.
6. Complete, not an unfinished draft.

## How to apply

To apply to the program, submit an application through the [Developer Spotlight signup form](https://forms.gle/anpTPu45tnwjwXsk8). Successful applicants will be contacted by email.

## Account credits

Account credits can be used towards recurring monthly charges for Cloudflare plans or add-on services. Once a tutorial submission has been approved and published, we can then add 350 credits to your Cloudflare account. Credits are only valid for three years. Valid payment details must be stored on the receiving account before credits can be added.

## FAQ

### How many tutorial topic ideas can I submit?

You may submit as many tutorial topics ideas as you like in your application.

### When will I be compensated for my tutorial?

We will add the account credits to your Cloudflare account after your tutorial has been approved and published under the Developer Spotlight program.

### If my tutorial is accepted and published on Cloudflare's Developer Spotlight program, can I republish it elsewhere?

We ask that you do not republish any tutorials that have been published under the Cloudflare Developer Spotlight program.

### Will I be credited for my work?

You will be credited as the author of any tutorial you submit that is successfully published through the Cloudflare Developer Spotlight program. We will add your details to your work after it has been approved.

### What happens If my topic of choice gets accepted but the tutorial submission gets rejected?

Our team will do our best to help you edit your tutorial's pull request to be ready for submission; however, in the unlikely chance that your tutorial's pull request is rejected, you are still free to publish your work elsewhere.

---

# Developer Spotlight program

URL: https://developers.cloudflare.com/developer-spotlight/

import { LinkTitleCard } from "~/components";

![Illustration of a laptop.](~/assets/images/developer_spotlight/developer_spotlight.png)

Find examples of how our community of developers are getting the most out of our products.

Applications are currently open until Thursday, the 24th of October 2024. To apply, please read the [application guide](/developer-spotlight/application-guide/)

## View latest contributions

<LinkTitleCard
	title="Setup Fullstack Authentication with Next.js, Auth.js, and Cloudflare D1"
	href="/developer-spotlight/tutorials/fullstack-authentication-with-next-js-and-cloudflare-d1/"
>
	By Mackenly Jones
</LinkTitleCard>

<LinkTitleCard
	title="Build a Voice Notes App with auto transcriptions using Workers AI"
	href="/workers-ai/tutorials/build-a-voice-notes-app-with-auto-transcription/"
>
	By Rajeev R. Sharma
</LinkTitleCard>

<LinkTitleCard
	title="Protect payment forms from malicious bots using Turnstile"
	href="/turnstile/tutorials/protecting-your-payment-form-from-attackers-bots-using-turnstile/"
>
	By Hidetaka Okamoto
</LinkTitleCard>

<LinkTitleCard
	title="Build Live Cursors with Next.js, RPC and Durable Objects"
	href="/workers/tutorials/live-cursors-with-nextjs-rpc-do/"
>
	By Ivan Buendia
</LinkTitleCard>

<LinkTitleCard
	title="Build an interview practice tool with Workers AI"
	href="/workers-ai/tutorials/build-ai-interview-practice-tool/"
>
	By Vasyl
</LinkTitleCard>

<LinkTitleCard
	title="Automate analytics reporting with Cloudflare Workers and email routing"
	href="/workers/tutorials/automated-analytics-reporting/"
>
	By Aleksej Komnenovic
</LinkTitleCard>

<LinkTitleCard
	title="Create a sitemap from Sanity CMS with Workers"
	href="/developer-spotlight/tutorials/create-sitemap-from-sanity-cms/"
>
	By John Siciliano
</LinkTitleCard>

<LinkTitleCard
	title="Recommend products on e-commerce sites using Workers AI and Stripe"
	href="/developer-spotlight/tutorials/creating-a-recommendation-api/"
>
	By Hidetaka Okamoto
</LinkTitleCard>

<LinkTitleCard
	title="Custom access control for files in R2 using D1 and Workers"
	href="/developer-spotlight/tutorials/custom-access-control-for-files/"
>
	By Dominik Fuerst
</LinkTitleCard>

<LinkTitleCard
	title="Send form submissions using Astro and Resend"
	href="/developer-spotlight/tutorials/handle-form-submission-with-astro-resend/"
>
	By Cody Walsh
</LinkTitleCard>

---

# Developer Spotlight Terms

URL: https://developers.cloudflare.com/developer-spotlight/terms/

These Developer Spotlight Terms (the “Terms”) govern your participation in the Cloudflare Developer Spotlight Program (the “Program”). As used in these Terms, "Cloudflare", "us" or "we" refers to Cloudflare, Inc. and its affiliates.

THESE TERMS DO NOT APPLY TO YOUR ACCESS AND USE OF THE CLOUDFLARE PRODUCTS AND SERVICES THAT ARE PROVIDED UNDER THE [SELF-SERVE SUBSCRIPTION AGREEMENT](https://www.cloudflare.com/terms/), THE [ENTERPRISE SUBSCRIPTION AGREEMENT](https://www.cloudflare.com/enterpriseterms/), OR OTHER WRITTEN AGREEMENT SIGNED BETWEEN YOU AND CLOUDFLARE (IF APPLICABLE).

1. Eligibility. By agreeing to these Terms, you represent and warrant to us: (i) that you are at least eighteen (18) years of age; (ii) that you have not previously been suspended or removed from the Program and (iii) that your participation in the Program is in compliance with any and all applicable laws and regulations.

2. Submissions. From time-to-time, Cloudflare may accept certain tutorials, blogs, and other content submissions from its developer community (“Dev Content”) for consideration for publication on a Cloudflare blog, developer documentation, social media platform or other website. You grant us a worldwide, perpetual, irrevocable, non-exclusive, royalty-free license (with the right to sublicense) to use, copy, reproduce, process, adapt, modify, publish, transmit, display and distribute such Dev Content in any and all media or distribution methods now known or later developed.

a. Likeness. You hereby grant to Cloudflare the royalty free right to use your name and likeness and any trademarks you include in the Dev Content in any and all manner, media, products, means, or methods, now known or hereafter created, throughout the world, in perpetuity, in connection with Cloudflare’s exercise of its rights under these Terms, including Cloudflare’s use of the Dev Content. Notwithstanding any other provision of these Terms, nothing herein will obligate Cloudflare to use the Dev Content in any manner. You understand and agree that you will have no right to any proceeds derived by Cloudflare or any third party from the use of the Dev Content.

b. Representations & Warranties. By submitting Dev Content, you represent and warrant that (1) you are the author and sole owner of all rights to the Dev Content; (2) the Dev Content is original and has not in whole or in part previously been published in any form and is not in the public domain; (3) your Dev Content is accurate and not misleading; (4) your Dev Content, does not: (i) infringe, violate, or misappropriate any third-party right, including any copyright, trademark, patent, trade secret, moral right, privacy right, right of publicity, or any other intellectual property or proprietary right; or (ii) slander, defame, or libel any third-party; and (2) no payments will be due from Cloudflare to any third party for the exercise of any rights granted under these Terms.

c. Compensation. Unless otherwise agreed by Cloudflare in writing, you understand and agree that Cloudflare will have no obligation to you or any third-party for any compensation, reimbursement, or any other payments in connection with your participation in the Program or publication of Dev Content.

3. Termination. These Terms will continue in full force and effect until either party terminates upon 30 days’ written notice to the other party. The provisions of Sections 2, 4, and 5 shall survive any termination or expiration of this agreement.

4. Indemnification. You agree to defend, indemnify, and hold harmless Cloudflare and its officers, directors, employees, consultants, affiliates, subsidiaries and agents (collectively, the "Cloudflare Entities") from and against any and all claims, liabilities, damages, losses, and expenses, including reasonable attorneys' fees and costs, arising out of or in any way connected with your violation of any third-party right, including without limitation any intellectual property right, publicity, confidentiality, property or privacy right. We reserve the right, at our own expense, to assume the exclusive defense and control of any matter otherwise subject to indemnification by you (and without limiting your indemnification obligations with respect to such matter), and in such case, you agree to cooperate with our defense of such claim.

5. Limitation of Liability. IN NO EVENT WILL THE CLOUDFLARE ENTITIES BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES ARISING OUT OF OR RELATING TO YOUR PARTICIPATION IN THE PROGRAM, WHETHER BASED ON WARRANTY, CONTRACT, TORT (INCLUDING NEGLIGENCE), STATUTE, OR ANY OTHER LEGAL THEORY, WHETHER OR NOT THE CLOUDFLARE ENTITIES HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGE.

6. Independent Contractor. The parties acknowledge and agree that you are an independent contractor, and nothing in these Terms will create a relationship of employment, joint venture, partnership or agency between the parties. Neither party will have the right, power or authority at any time to act on behalf of, or represent the other party. Cloudflare will not obtain workers’ compensation or other insurance on your behalf, and you are solely responsible for all payments, benefits, and insurance required for the performance of services hereunder, including, without limitation, taxes or other withholdings, unemployment, payroll disbursements, and other related expenses. You hereby acknowledge and agree that these Terms are not governed by any union or collective bargaining agreement and Cloudflare will not pay you any union-required residuals, reuse fees, pension, health and welfare benefits or other benefits/payments.

7. Governing Law. These Terms will be governed by the laws of the State of California without regard to conflict of law principles. To the extent that any lawsuit or court proceeding is permitted hereunder, you and Cloudflare agree to submit to the personal and exclusive jurisdiction of the state and federal courts located within San Francisco County, California for the purpose of litigating all such disputes.

8. Modifications. Cloudflare reserves the right to make modifications to these Terms at any time. Revised versions of these Terms will be posted publicly online. Unless otherwise specified, any modifications to the Terms will take effect the day they are posted publicly online. If you do not agree with the revised Terms, your sole and exclusive remedy will be to discontinue your participation in the Program.

9. General. These Terms, together with any applicable product limits, disclaimers, or other terms presented to you on a Cloudflare controlled website (e.g., www.cloudflare.com, as well as the other websites that Cloudflare operates and that link to these Terms) or documentation, each of which are incorporated by reference into these Terms, constitute the entire and exclusive understanding and agreement between you and Cloudflare regarding your participation in the Program. Use of section headers in these Terms is for convenience only and will not have any impact on the interpretation of particular provisions. You may not assign or transfer these Terms or your rights hereunder, in whole or in part, by operation of law or otherwise, without our prior written consent. We may assign these Terms at any time without notice. The failure to require performance of any provision will not affect our right to require performance at any time thereafter, nor will a waiver of any breach or default of these Terms or any provision of these Terms constitute a waiver of any subsequent breach or default or a waiver of the provision itself. In the event that any part of these Terms is held to be invalid or unenforceable, the unenforceable part will be given effect to the greatest extent possible and the remaining parts will remain in full force and effect. Upon termination of these Terms, any provision that by its nature or express terms should survive will survive such termination or expiration.

---

# Demos and architectures

URL: https://developers.cloudflare.com/durable-objects/demos/

import { ExternalResources, GlossaryTooltip, ResourcesBySelector } from "~/components"

Learn how you can use a <GlossaryTooltip term = "Durable Object">Durable Object</GlossaryTooltip> within your existing application and architecture.

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Durable Objects.

<ExternalResources type="apps" products={["Durable Objects"]} />

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use Durable Objects:

<ResourcesBySelector types={["reference-architecture","design-guide","reference-architecture-diagram"]} products={["Durable Objects"]} />

---

# Getting started

URL: https://developers.cloudflare.com/durable-objects/get-started/

import { Render, TabItem, Tabs, PackageManagers, WranglerConfig, TypeScriptExample } from "~/components";

This guide will instruct you through:

- Writing a JavaScript class that defines a Durable Object.
- Using Durable Objects SQL API to query a Durable Object's private, embedded SQLite database.
- Instantiating and communicating with a Durable Object from another Worker.
- Deploying a Durable Object and a Worker that communicates with a Durable Object.

If you wish to learn more about Durable Objects, refer to [What are Durable Objects?](/durable-objects/what-are-durable-objects/).

## Quick start

If you want to skip the steps and get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/templates/tree/main/hello-world-do-template)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers. Use this option if you are familiar with Cloudflare Workers, and wish to skip the step-by-step guidance.

You may wish to manually follow the steps if you are new to Cloudflare Workers.

## Prerequisites

<Render file="prereqs" product="workers" />

## 1. Create a Worker project

You will access your Durable Object from a [Worker](/workers/). Your Worker application is an interface to interact with your Durable Object.

To create a Worker project, run:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"durable-object-starter"}
/>

Running `create cloudflare@latest` will install [Wrangler](/workers/wrangler/install-and-update/), the Workers CLI. You will use Wrangler to test and deploy your project.

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker + Durable Objects",
		lang: "TypeScript",
	}}
/>

This will create a new directory, which will include either a `src/index.js` or `src/index.ts` file to write your code and a [`wrangler.jsonc`](/workers/wrangler/configuration/) configuration file.

Move into your new directory:

```sh
cd durable-object-starter
```

## 2. Write a Durable Object class using SQL API

Before you create and access a Durable Object, its behavior must be defined by an ordinary exported JavaScript class.

:::note
If you do not use JavaScript or TypeScript, you will need a [shim](https://developer.mozilla.org/en-US/docs/Glossary/Shim) to translate your class definition to a JavaScript class.
:::

Your `MyDurableObject` class will have a constructor with two parameters. The first parameter, `ctx`, passed to the class constructor contains state specific to the Durable Object, including methods for accessing storage. The second parameter, `env`, contains any bindings you have associated with the Worker when you uploaded it.

<Tabs syncKey="workersExamples">

<TypeScriptExample omitTabs={true}>
```ts
export class MyDurableObject extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		// Required, as we're extending the base class.
		super(ctx, env)
	}
}
```
</TypeScriptExample>

<TabItem label="Python" icon="seti:python">

```python
from workers import DurableObject

class MyDurableObject(DurableObject):
    def __init__(self, ctx, env):
        super().__init__(ctx, env)
```

</TabItem>

</Tabs>

Workers communicate with a Durable Object using [remote-procedure call](/workers/runtime-apis/rpc/#_top). Public methods on a Durable Object class are exposed as [RPC methods](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) to be called by another Worker.

Your file should now look like:

<Tabs syncKey="workersExamples">

<TypeScriptExample omitTabs={true}>
```ts
export class MyDurableObject extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		// Required, as we're extending the base class.
		super(ctx, env)
	}

	async sayHello(): Promise<string> {
		let result = this.ctx.storage.sql
			.exec("SELECT 'Hello, World!' as greeting")
			.one();
		return result.greeting;
	}
}
```
</TypeScriptExample>

<TabItem label="Python" icon="seti:python">

```python
from workers import DurableObject

class MyDurableObject(DurableObject):
    def __init__(self, ctx, env):
        super().__init__(ctx, env)

    async def say_hello(self):
        result = self.ctx.storage.sql \
            .exec("SELECT 'Hello, World!' as greeting") \
            .one()

        return result.greeting
```

</TabItem>

</Tabs>

In the code above, you have:

1. Defined a RPC method, `sayHello()`, that can be called by a Worker to communicate with a Durable Object.
2. Accessed a Durable Object's attached storage, which is a private SQLite database only accessible to the object, using [SQL API](/durable-objects/api/storage-api/#exec) methods (`sql.exec()`) available on `ctx.storage` .
3. Returned an object representing the single row query result using `one()`, which checks that the query result has exactly one row.
4. Return the `greeting` column from the row object result.

## 3. Instantiate and communicate with a Durable Object

:::note

Durable Objects do not receive requests directly from the Internet. Durable Objects receive requests from Workers or other Durable Objects.
This is achieved by configuring a binding in the calling Worker for each Durable Object class that you would like it to be able to talk to. These bindings must be configured at upload time. Methods exposed by the binding can be used to communicate with particular Durable Objects.
:::

A Worker is used to [access Durable Objects](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/).

To communicate with a Durable Object, the Worker's fetch handler should look like the following:


<Tabs syncKey="workersExamples">

<TypeScriptExample omitTabs={true}>
```ts
export default {
	async fetch(request, env, ctx): Promise<Response> {
		const id:DurableObjectId = env.MY_DURABLE_OBJECT.idFromName(new URL(request.url).pathname);

		const stub = env.MY_DURABLE_OBJECT.get(id);

		const greeting = await stub.sayHello();

		return new Response(greeting);
	},
} satisfies ExportedHandler<Env>;
```
</TypeScriptExample>

<TabItem label="Python" icon="seti:python">

```python
from workers import handler, Response
from urllib.parse import urlparse

@handler
async def on_fetch(request, env, ctx):
    url = urlparse(request.url)
    id = env.MY_DURABLE_OBJECT.idFromName(url.path)
    stub = env.MY_DURABLE_OBJECT.get(id)
    greeting = await stub.say_hello()
    return Response(greeting)
```

</TabItem>

</Tabs>

In the code above, you have:

1. Exported your Worker's main event handlers, such as the `fetch()` handler for receiving HTTP requests.
2. Passed `env` into the `fetch()` handler. Bindings are delivered as a property of the environment object passed as the second parameter when an event handler or class constructor is invoked. By calling the `idFromName()` function on the binding, you use a string-derived object ID. You can also ask the system to [generate random unique IDs](/durable-objects/api/namespace/#newuniqueid). System-generated unique IDs have better performance characteristics, but require you to store the ID somewhere to access the Object again later.
3. Derived an object ID from the URL path. `MY_DURABLE_OBJECT.idFromName()` always returns the same ID when given the same string as input (and called on the same class), but never the same ID for two different strings (or for different classes). In this case, you are creating a new object for each unique path.
4. Constructed the stub for the Durable Object using the ID. A stub is a client object used to send messages to the Durable Object.
5. Called a Durable Object by invoking a RPC method, `sayHello()`, on the Durable Object, which returns a `Hello, World!` string greeting.
6. Received an HTTP response back to the client by constructing a HTTP Response with `return new Response()`.

Refer to [Access a Durable Object from a Worker](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) to learn more about communicating with a Durable Object.

## 4. Configure Durable Object bindings

[Bindings](/workers/runtime-apis/bindings/) allow your Workers to interact with resources on the Cloudflare developer platform. The Durable Object bindings in your Worker project's [Wrangler configuration file](/workers/wrangler/configuration/) will include a binding name (for this guide, use `MY_DURABLE_OBJECT`) and the class name (`MyDurableObject`).

<WranglerConfig>

```toml
[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObject"
```

</WranglerConfig>

The `bindings` section contains the following fields:

- `name` - Required. The binding name to use within your Worker.
- `class_name` - Required. The class name you wish to bind to.
- `script_name` - Optional. Defaults to the current [environment's](/durable-objects/reference/environments/) Worker code.

## 5. Configure Durable Object class with SQLite storage backend

A migration is a mapping process from a class name to a runtime state. You perform a migration when creating a new Durable Object class, or when renaming, deleting or transferring an existing Durable Object class.

Migrations are performed through the `[[migrations]]` configurations key in your Wrangler file.

The Durable Object migration to create a new Durable Object class with SQLite storage backend will look like the following in your Worker's Wrangler file:

<WranglerConfig>

```toml
[[migrations]]
tag = "v1" # Should be unique for each entry
new_sqlite_classes = ["MyDurableObject"] # Array of new classes
```

</WranglerConfig>

Refer to [Durable Objects migrations](/durable-objects/reference/durable-objects-migrations/) to learn more about the migration process.

## 6. Develop a Durable Object Worker locally

To test your Durable Object locally, run [`wrangler dev`](/workers/wrangler/commands/#dev):

```sh
npx wrangler dev
```

In your console, you should see a`Hello world` string returned by the Durable Object.

## 7. Deploy your Durable Object Worker

To deploy your Durable Object Worker:

```sh
npx wrangler deploy
```

Once deployed, you should be able to see your newly created Durable Object Worker on the [Cloudflare dashboard](https://dash.cloudflare.com/), **Workers & Pages** > **Overview**.

Preview your Durable Object Worker at `<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev`.

## Summary and final code

Your final code should look like this:


<Tabs syncKey="workersExamples">

<TypeScriptExample omitTabs={true}>
```ts title="index.ts"
import { DurableObject } from "cloudflare:workers";
export class MyDurableObject extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		// Required, as we are extending the base class.
		super(ctx, env)
	}

	async sayHello():Promise<string> {
		let result = this.ctx.storage.sql
			.exec("SELECT 'Hello, World!' as greeting")
			.one();
		return result.greeting;
	}
}
export default {
	async fetch(request, env, ctx):Promise<Response> {
		const id:DurableObjectId = env.MY_DURABLE_OBJECT.idFromName(new URL(request.url).pathname);

		const stub = env.MY_DURABLE_OBJECT.get(id);

		const greeting = await stub.sayHello();

		return new Response(greeting);
	},
} satisfies ExportedHandler<Env>;
```
</TypeScriptExample>

<TabItem label="Python" icon="seti:python">

```python
from workers import DurableObject, handler, Response
from urllib.parse import urlparse

class MyDurableObject(DurableObject):
    def __init__(self, ctx, env):
        super().__init__(ctx, env)

    async def say_hello(self):
        result = self.ctx.storage.sql \
            .exec("SELECT 'Hello, World!' as greeting") \
            .one()

        return result.greeting

@handler
async def on_fetch(request, env, ctx):
    url = urlparse(request.url)
    id = env.MY_DURABLE_OBJECT.idFromName(url.path)
    stub = env.MY_DURABLE_OBJECT.get(id)
    greeting = await stub.say_hello()
    return Response(greeting)
```

</TabItem>

</Tabs>

By finishing this tutorial, you have:

- Successfully created a Durable Object
- Called the Durable Object by invoking a [RPC method](/workers/runtime-apis/rpc/)
- Deployed the Durable Object globally

## Related resources

- [Create Durable Object stubs](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/)
- [Access Durable Objects Storage](/durable-objects/best-practices/access-durable-objects-storage/)
- [Miniflare](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare) - Helpful tools for mocking and testing your Durable Objects.

---

# Cloudflare Durable Objects

URL: https://developers.cloudflare.com/durable-objects/

import { Render, CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct, LinkButton } from "~/components"

<Description>
Create AI agents, collaborative applications, real-time interactions like chat, and more without needing to coordinate state, have separate storage, or manage infrastructure.
</Description>

<Plan type="workers-all" />

Durable Objects provide a building block for stateful applications and distributed systems.

Use Durable Objects to build applications that need coordination among multiple clients, like collaborative editing tools, interactive chat, multiplayer games, live notifications, and deep distributed systems, without requiring you to build serialization and coordination primitives on your own.

<LinkButton href="/durable-objects/get-started/">Get started</LinkButton>

:::note
SQLite-backed Durable Objects are now available on the Workers Free plan with these [limits](/durable-objects/platform/pricing/).

[SQLite storage](/durable-objects/best-practices/access-durable-objects-storage/) and corresponding [Storage API](/durable-objects/api/storage-api/) methods like `sql.exec` have moved from beta to general availability. New Durable Object classes should use wrangler configuration for [SQLite storage](/durable-objects/best-practices/access-durable-objects-storage/#wrangler-configuration-for-sqlite-durable-objects).
:::

### What are Durable Objects?

<Render file="what-are-durable-objects"/>

For more information, refer to the full [What are Durable Objects?](/durable-objects/what-are-durable-objects/) page.

***

## Features

<Feature header="In-memory State" href="/durable-objects/reference/in-memory-state/">

Learn how Durable Objects coordinate connections among multiple clients or events.


</Feature>

<Feature header="Storage API" href="/durable-objects/api/storage-api/">

Learn how Durable Objects provide transactional, strongly consistent, and serializable storage.


</Feature>

<Feature header="WebSocket Hibernation" href="/durable-objects/best-practices/websockets/#websocket-hibernation-api">

Learn how WebSocket Hibernation allows you to manage the connections of multiple clients at scale.


</Feature>

<Feature header="Durable Objects Alarms" href="/durable-objects/api/alarms/">

Learn how to use alarms to trigger a Durable Object and perform compute in the future at customizable intervals.


</Feature>

***

## Related products

<RelatedProduct header="Workers" href="/workers/" product="workers">

Cloudflare Workers provides a serverless execution environment that allows you to create new applications or augment existing ones without configuring or maintaining infrastructure.


</RelatedProduct>

<RelatedProduct header="D1" href="/d1/" product="d1">

D1 is Cloudflare's SQL-based native serverless database. Create a database by importing data or defining your tables and writing your queries within a Worker or through the API.


</RelatedProduct>

<RelatedProduct header="R2" href="/r2/" product="r2">

Cloudflare R2 Storage allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.


</RelatedProduct>

***

## More resources

<CardGrid>

<LinkTitleCard title="Built with Durable Objects" href="https://workers.cloudflare.com/built-with/collections/durable-objects/" icon="pen">
Browse what other developers are building with Durable Objects.
</LinkTitleCard>

<LinkTitleCard title="Limits" href="/durable-objects/platform/limits/" icon="document">
Learn about Durable Objects limits.
</LinkTitleCard>

<LinkTitleCard title="Pricing" href="/durable-objects/platform/pricing/" icon="pen">
Learn about Durable Objects pricing.
</LinkTitleCard>

<LinkTitleCard title="Storage options" href="/workers/platform/storage-options/" icon="document">
Learn more about storage and database options you can build with Workers.
</LinkTitleCard>

<LinkTitleCard title="Developer Discord" href="https://discord.cloudflare.com" icon="discord">
Connect with the Workers community on Discord to ask questions, show what you are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard title="@CloudflareDev" href="https://x.com/cloudflaredev" icon="x.com">
Follow @CloudflareDev on Twitter to learn about product announcements, and what is new in Cloudflare Developer Platform.
</LinkTitleCard>

</CardGrid>

---

# Release notes

URL: https://developers.cloudflare.com/durable-objects/release-notes/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/durable-objects.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Videos

URL: https://developers.cloudflare.com/durable-objects/video-tutorials/

import { CardGrid, LinkCard } from "~/components";

<CardGrid>
    <LinkCard
        title="Introduction to Durable Objects"
        description="Dive into a hands-on Durable Objects project and learn how to build stateful apps using serverless architecture"
        href="/learning-paths/durable-objects-course/series/introduction-to-series-1/"
    />
</CardGrid>

---

# What are Durable Objects?

URL: https://developers.cloudflare.com/durable-objects/what-are-durable-objects/

import { Render } from "~/components";

<Render file="what-are-durable-objects"/>

## Durable Objects highlights

Durable Objects have properties that make them a great fit for distributed stateful scalable applications.

**Serverless compute, zero infrastructure management**

- Durable Objects are built on-top of the Workers runtime, so they support exactly the same code (JavaScript and WASM), and similar memory and CPU limits.
- Each Durable Object is [implicitly created on first access](/durable-objects/api/namespace/#get). User applications are not concerned with their lifecycle, creating them or destroying them. Durable Objects migrate among healthy servers, and therefore applications never have to worry about managing them.
- Each Durable Object stays alive as long as requests are being processed, and remains alive for several seconds after being idle before hibernating, allowing applications to [exploit in-memory caching](/durable-objects/reference/in-memory-state/) while handling many consecutive requests and boosting their performance.

**Storage colocated with compute**

- Each Durable Object has its own [durable, transactional, and strongly consistent storage](/durable-objects/api/storage-api/) (up to 10 GB[^1]), persisted across requests, and accessible only within that object.

**Single-threaded concurrency**

- Each [Durable Object instance has an identifier](/durable-objects/api/id/), either randomly-generated or user-generated, which allows you to globally address which Durable Object should handle a specific action or request.
- Durable Objects are single-threaded and cooperatively multi-tasked, just like code running in a web browser. For more details on how safety and correctness are achieved, refer to the blog post ["Durable Objects: Easy, Fast, Correct — Choose three"](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/).

**Elastic horizontal scaling across Cloudflare's global network**

- Durable Objects can be spread around the world, and you can [optionally influence where each instance should be located](/durable-objects/reference/data-location/#provide-a-location-hint). Durable Objects are not yet available in every Cloudflare data center; refer to the [where.durableobjects.live](https://where.durableobjects.live/) project for live locations.
- Each Durable Object type (or ["Namespace binding"](/durable-objects/api/namespace/) in Cloudflare terms) corresponds to a JavaScript class implementing the actual logic. There is no hard limit on how many Durable Objects can be created for each namespace.
- Durable Objects scale elastically as your application creates millions of objects. There is no need for applications to manage infrastructure or plan ahead for capacity.

## Durable Objects features

### In-memory state

Each Durable Object has its own [in-memory state](/durable-objects/reference/in-memory-state/). Applications can use this in-memory state to optimize the performance of their applications by keeping important information in-memory, thereby avoiding the need to access the durable storage at all.

Useful cases for in-memory state include batching and aggregating information before persisting it to storage, or for immediately rejecting/handling incoming requests meeting certain criteria, and more.

In-memory state is reset when the Durable Object hibernates after being idle for some time. Therefore, it is important to persist any in-memory data to the durable storage if that data will be needed at a later time when the Durable Object receives another request.

### Storage API

The [Durable Object Storage API](/durable-objects/api/storage-api/) allows Durable Objects to access fast, transactional, and strongly consistent storage. A Durable Object's attached storage is private to its unique instance and cannot be accessed by other objects.

There are two flavors of the storage API, a [key-value (KV) API](/durable-objects/api/storage-api/#kv-api) and an [SQL API](/durable-objects/api/storage-api/#sql-api).

When using the [new SQLite in Durable Objects storage backend](/durable-objects/reference/durable-objects-migrations/#enable-sqlite-storage-backend-on-new-durable-object-class-migration), you have access to both the APIs. However, if you use the previous storage backend you only have access to the key-value API.

### Alarms API

Durable Objects provide an [Alarms API](/durable-objects/api/alarms/) which allows you to schedule the Durable Object to be woken up at a time in the future. This is useful when you want to do certain work periodically, or at some specific point in time, without having to manually manage infrastructure such as job scheduling runners on your own.

You can combine Alarms with in-memory state and the durable storage API to build batch and aggregation applications such as queues, workflows, or advanced data pipelines.

### WebSockets

WebSockets are long-lived TCP connections that enable bi-directional, real-time communication between client and server. Because WebSocket sessions are long-lived, applications commonly use Durable Objects to accept either the client or server connection.

Because Durable Objects provide a single-point-of-coordination between Cloudflare Workers, a single Durable Object instance can be used in parallel with WebSockets to coordinate between multiple clients, such as participants in a chat room or a multiplayer game.

Durable Objects support the [WebSocket Standard API](/durable-objects/best-practices/websockets/#websocket-standard-api), as well as the [WebSockets Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api) which extends the Web Standard WebSocket API to reduce costs by not incurring billing charges during periods of inactivity.

### RPC

Durable Objects support Workers [Remote-Procedure-Call (RPC)](/workers/runtime-apis/rpc/) which allows applications to use JavaScript-native methods and objects to communicate between Workers and Durable Objects.

Using RPC for communication makes application development easier and simpler to reason about, and more efficient.

## Actor programming model

Another way to describe and think about Durable Objects is through the lens of the [Actor programming model](https://en.wikipedia.org/wiki/Actor_model). There are several popular examples of the Actor model supported at the programming language level through runtimes or library frameworks, like [Erlang](https://www.erlang.org/), [Elixir](https://elixir-lang.org/), [Akka](https://akka.io/), or [Microsoft Orleans for .NET](https://learn.microsoft.com/en-us/dotnet/orleans/overview).

The Actor model simplifies a lot of problems in distributed systems by abstracting away the communication between actors using RPC calls (or message sending) that could be implemented on-top of any transport protocol, and it avoids most of the concurrency pitfalls you get when doing concurrency through shared memory such as race conditions when multiple processes/threads access the same data in-memory.

Each Durable Object instance can be seen as an Actor instance, receiving messages (incoming HTTP/RPC requests), executing some logic in its own single-threaded context using its attached durable storage or in-memory state, and finally sending messages to the outside world (outgoing HTTP/RPC requests or responses), even to another Durable Object instance.

Each Durable Object has certain capabilities in terms of [how much work it can do](/durable-objects/platform/limits/#how-much-work-can-a-single-durable-object-do), which should influence the application's [architecture to fully take advantage of the platform](/reference-architecture/diagrams/storage/durable-object-control-data-plane-pattern/).

Durable Objects are natively integrated into Cloudflare's infrastructure, giving you the ultimate serverless platform to build distributed stateful applications exploiting the entirety of Cloudflare's network.

## Durable Objects in Cloudflare

Many of Cloudflare's products use Durable Objects. Some of our technical blog posts showcase real-world applications and use-cases where Durable Objects make building applications easier and simpler.

These blog posts may also serve as inspiration on how to architect scalable applications using Durable Objects, and how to integrate them with the rest of Cloudflare Developer Platform.

- [Durable Objects aren't just durable, they're fast: a 10x speedup for Cloudflare Queues](https://blog.cloudflare.com/how-we-built-cloudflare-queues/)
- [Behind the scenes with Stream Live, Cloudflare's live streaming service](https://blog.cloudflare.com/behind-the-scenes-with-stream-live-cloudflares-live-streaming-service/)
- [DO it again: how we used Durable Objects to add WebSockets support and authentication to AI Gateway](https://blog.cloudflare.com/do-it-again/)
- [Workers Builds: integrated CI/CD built on the Workers platform](https://blog.cloudflare.com/workers-builds-integrated-ci-cd-built-on-the-workers-platform/)
- [Build durable applications on Cloudflare Workers: you write the Workflows, we take care of the rest](https://blog.cloudflare.com/building-workflows-durable-execution-on-workers/)
- [Building D1: a Global Database](https://blog.cloudflare.com/building-d1-a-global-database/)
- [Billions and billions (of logs): scaling AI Gateway with the Cloudflare Developer Platform](https://blog.cloudflare.com/billions-and-billions-of-logs-scaling-ai-gateway-with-the-cloudflare/)
- [Indexing millions of HTTP requests using Durable Objects](https://blog.cloudflare.com/r2-rayid-retrieval/)

Finally, the following blog posts may help you learn some of the technical implementation aspects of Durable Objects, and how they work.

- [Durable Objects: Easy, Fast, Correct — Choose three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/)
- [Zero-latency SQLite storage in every Durable Object](https://blog.cloudflare.com/sqlite-in-durable-objects/)
- [Workers Durable Objects Beta: A New Approach to Stateful Serverless](https://blog.cloudflare.com/introducing-workers-durable-objects/)

## Get started

Get started now by following the ["Get started" guide](/durable-objects/get-started/) to create your first application using Durable Objects.

[^1]: Storage per Durable Object with SQLite is currently 1 GB. This will be raised to 10 GB for general availability.

---

# Cloudflare Email Routing

URL: https://developers.cloudflare.com/email-routing/

import { Description, Feature, Plan, RelatedProduct, Render } from "~/components"

<Description>

Create custom email addresses for your domain and route incoming emails to your preferred mailbox.
</Description>

<Plan id="email.email_routing.properties.availability.summary" />

<Render file="email-routing-definition" />

It is available to all Cloudflare customers [using Cloudflare as an authoritative nameserver](/dns/zone-setups/full-setup/).

***

## Features

<Feature header="Email Workers" href="/email-routing/email-workers/">
Leverage the power of Cloudflare Workers to implement any logic you need to process your emails. Create rules as complex or simple as you need.
</Feature>

<Feature header="Custom addresses" href="/email-routing/get-started/enable-email-routing/">
With Email Routing you can have many custom email addresses to use for specific situations.
</Feature>

<Feature header="Analytics" href="/email-routing/get-started/email-routing-analytics/">
Email Routing includes metrics to help you check on your email traffic history.
</Feature>

***

## Related products

<RelatedProduct header="Email Security" href="/cloudflare-one/email-security/" product="email-security">
Cloudflare Email Security is a cloud based service that stops phishing attacks, the biggest cybersecurity threat, across all traffic vectors - email, web and network.
</RelatedProduct>

<RelatedProduct header="DNS" href="/dns/" product="dns">
Email Routing is available to customers using Cloudflare as an authoritative nameserver.
</RelatedProduct>

---

# Limits

URL: https://developers.cloudflare.com/email-routing/limits/

import { Render } from "~/components"

## Email Workers size limits

When you process emails with Email Workers and you are on [Workers’ free pricing tier](/workers/platform/pricing/) you might encounter an allocation error. This may happen due to the size of the emails you are processing and/or the complexity of your Email Worker. Refer to [Worker limits](/workers/platform/limits/#worker-limits) for more information.

You can use the [log functionality for Workers](/workers/observability/logs/) to look for messages related to CPU limits (such as `EXCEEDED_CPU`) and troubleshoot any issues regarding allocation errors.

If you encounter these error messages frequently, consider upgrading to the [Workers Paid plan](/workers/platform/pricing/) for higher usage limits.

## Message size

Currently, Email Routing does not support messages bigger than 25 MiB.

## Rules and addresses

| Feature                                                                          | Limit |
| -------------------------------------------------------------------------------- | ----- |
| [Rules](/email-routing/setup/email-routing-addresses/)                           | 200   |
| [Addresses](/email-routing/setup/email-routing-addresses/#destination-addresses) | 200   |

<Render file="limits_increase" product="workers" />

## Email Routing summary for emails sent through Workers

Emails sent through Workers will show up in the Email Routing summary page as dropped even if they were successfully delivered.

---

# Postmaster

URL: https://developers.cloudflare.com/email-routing/postmaster/

This page provides technical information about Email Routing to professionals who administer email systems, and other email providers.

Here you will find information regarding Email Routing, along with best practices, rules, guidelines, troubleshooting tools, as well as known limitations for Email Routing.

## Postmaster

### Authenticated Received Chain (ARC)

Email Routing supports [Authenticated Received Chain (ARC)](http://arc-spec.org/). ARC is an email authentication system designed to allow an intermediate email server (such as Email Routing) to preserve email authentication results. Google also supports ARC.

### Contact information

The best way to contact us is using our [community forum](https://community.cloudflare.com/new-topic?category=Feedback/Previews%20%26%20Betas&tags=email) or our [Discord server](https://discord.com/invite/cloudflaredev).

### DKIM signature

[DKIM (DomainKeys Identified Mail)](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) ensures that email messages are not altered in transit between the sender and the recipient's SMTP servers through public-key cryptography.

Through this standard, the sender publishes its public key to a domain's DNS once, and then signs the body of each message before it leaves the server. The recipient server reads the message, gets the domain public key from the domain's DNS, and validates the signature to ensure the message was not altered in transit.

Email Routing adds two new signatures to the emails in transit, one on behalf of the Cloudflare domain used for sender rewriting `email.cloudflare.net`, and another one on behalf of the customer's recipient domain.

Below is the DKIM key for `email.cloudflare.net`:

```sh
dig TXT cf2024-1._domainkey.email.cloudflare.net +short
```

```sh output
"v=DKIM1; h=sha256; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAiweykoi+o48IOGuP7GR3X0MOExCUDY/BCRHoWBnh3rChl7WhdyCxW3jgq1daEjPPqoi7sJvdg5hEQVsgVRQP4DcnQDVjGMbASQtrY4WmB1VebF+RPJB2ECPsEDTpeiI5ZyUAwJaVX7r6bznU67g7LvFq35yIo4sdlmtZGV+i0H4cpYH9+3JJ78k" "m4KXwaf9xUJCWF6nxeD+qG6Fyruw1Qlbds2r85U9dkNDVAS3gioCvELryh1TxKGiVTkg4wqHTyHfWsp7KD3WQHYJn0RyfJJu6YEmL77zonn7p2SRMvTMP3ZEXibnC9gz3nnhR6wcYL8Q7zXypKTMD58bTixDSJwIDAQAB"
```

You can find the DKIM key for the customer's `example.com` domain by querying the following:

```sh
dig TXT cf2024-1._domainkey.example.com +short
```

### DMARC enforcing

Email Routing enforces Domain-based Message Authentication, Reporting & Conformance (DMARC). Depending on the sender's DMARC policy, Email Routing will reject emails when there is an authentication failure. Refer to [dmarc.org](https://dmarc.org/) for more information on this protocol.

### IPv6 support

Currently, Email Routing will connect to the upstream SMTP servers using IPv6 if they provide AAAA records for their MX servers, and fall back to IPv4 if that is not possible.

Below is an example of a popular provider that supports IPv6:

```sh
dig mx gmail.com
```

```sh output

gmail.com. 3084 IN MX 5 gmail-smtp-in.l.google.com.
gmail.com. 3084 IN MX 20 alt2.gmail-smtp-in.l.google.com.
gmail.com. 3084 IN MX 40 alt4.gmail-smtp-in.l.google.com.
gmail.com. 3084 IN MX 10 alt1.gmail-smtp-in.l.google.com.
gmail.com. 3084 IN MX 30 alt3.gmail-smtp-in.l.google.com.
```

```sh
dig AAAA gmail-smtp-in.l.google.com
```

```sh output
gmail-smtp-in.l.google.com. 17 IN AAAA 2a00:1450:400c:c09::1b
```

Email Routing also supports IPv6 through Cloudflare’s inbound MX servers.

### MX, SPF, and DKIM records

Email Routing automatically adds a few DNS records to the zone when our customers enable Email Routing. If we take `example.com` as an example:

```txt
example.com. 300 IN MX 13 amir.mx.cloudflare.net.
example.com. 300 IN MX 86 linda.mx.cloudflare.net.
example.com. 300 IN MX 24 isaac.mx.cloudflare.net.

example.com. 300 IN TXT "v=spf1 include:_spf.mx.cloudflare.net ~all"
```

[The MX (mail exchange) records](https://www.cloudflare.com/learning/dns/dns-records/dns-mx-record/) tell the Internet where the inbound servers receiving email messages for the zone are. In this case, anyone who wants to send an email to `example.com` can use the `amir.mx.cloudflare.net`, `linda.mx.cloudflare.net`, or `isaac.mx.cloudflare.net` SMTP servers.

### Outbound prefixes

Email Routing sends its traffic using both IPv4 and IPv6 prefixes, when supported by the upstream SMTP server.

If you are a postmaster and are having trouble receiving Email Routing's emails, allow the following outbound IP addresses in your server configuration:

**IPv4**

`104.30.0.0/19`

**IPv6**

`2405:8100:c000::/38`

_Ranges last updated: December 13th, 2023_

### Outbound hostnames

In addition to the outbound prefixes, Email Routing will use the following outbound domains for the `HELO/EHLO` command:

- `cloudflare-email.net`
- `cloudflare-email.org`
- `cloudflare-email.com`

PTR records (reverse DNS) ensure that each hostname has an corresponding IP. For example:

```sh
dig a-h.cloudflare-email.net +short
```

```sh output
104.30.0.7
```

```sh
dig -x 104.30.0.7 +short
```

```sh output
a-h.cloudflare-email.net.
```

### Sender rewriting

Email Routing rewrites the SMTP envelope sender (`MAIL FROM`) to the forwarding domain to avoid issues with [SPF](#spf-record). Email Routing uses the [Sender Rewriting Scheme](https://en.wikipedia.org/wiki/Sender_Rewriting_Scheme) to achieve this.

This has no effect to the end user's experience, though. The message headers will still report the original sender's `From:` address.

### SMTP errors

In most cases, Email Routing forwards the upstream SMTP errors back to the sender client in-session.

### Realtime Block Lists

Email Routing uses an internal Domain Name System Blocklists (DNSBL) service to check if the sender's IP is present in one or more Realtime Block Lists (RBL) lists. When the system detects an abusive IP, it blocks the email and returns an SMTP error:

```txt
554 <YOUR_IP_ADDRESS> found on one or more RBLs (abusixip). Refer to https://developers.cloudflare.com/email-routing/postmaster/#spam-and-abusive-traffic/
```
We update our RBLs regularly. You can use combined block list lookup services like [MxToolbox](https://mxtoolbox.com/blacklists.aspx) to check if your IP matches other RBLs. IP reputation blocks are usually temporary, but if you feel your IP should be removed immediately, please contact the RBL's maintainer mentioned in the SMTP error directly.

### Anti-spam

In addition to DNSBL, Email Routing uses advanced heuristic and statistical analysis of the email's headers and text to calculate a spam score. We inject the score in the custom `X-Cf-Spamh-Score` header:

```
X-Cf-Spamh-Score: 2
```

This header is visible in the forwarded email. The higher the score, 5 being the maximum, the more likely the email is spam. Currently, this system is experimental and passive; we do not act on it and suggest that upstream servers and email clients don't act on it either.

We will update this page with more information as we fine-tune the system.

### SPF record

A SPF DNS record is an anti-spoofing mechanism that is used to specify which IP addresses and domains are allowed to send emails on behalf of your zone.

The Internet Engineering Task Force (IETF) tracks the SPFv1 specification [in RFC 7208](https://datatracker.ietf.org/doc/html/rfc7208). Refer to the [SPF Record Syntax](http://www.open-spf.org/SPF_Record_Syntax/) to learn the SPF syntax.

Email Routing's SPF record contains the following:

```txt
v=spf1 include:_spf.mx.cloudflare.net ~all
```

In the example above:

- `spf1`: Refers to SPF version 1, the most common and more widely adopted version of SPF.
- `include`: Include a second query to `_spf.mx.cloudflare.net` and allow its contents.
- `~all`: Otherwise [`SoftFail`](http://www.open-spf.org/SPF_Record_Syntax/) on all other origins. `SoftFail` means NOT allowed to send, but in transition. This instructs the upstream server to accept the email but mark it as suspicious if it came from any IP addresses outside of those defined in the SPF records.

If we do a TXT query to `_spf.mx.cloudflare.net`, we get:

```txt
_spf.mx.cloudflare.net. 300 IN TXT "v=spf1 ip4:104.30.0.0/20 ~all"
```

This response means:

- Allow all IPv4 IPs coming from the `104.30.0.0/20` subnet.
- Otherwise, `SoftFail`.

You can read more about SPF, DKIM, and DMARC in our [Tackling Email Spoofing and Phishing](https://blog.cloudflare.com/tackling-email-spoofing/) blog.

---

## Known limitations

Below, you will find information regarding known limitations for Email Routing.

### Email address internationalization (EAI)

Email Routing does not support [internationalized email addresses](https://en.wikipedia.org/wiki/International_email). Email Routing only supports [internationalized domain names](https://en.wikipedia.org/wiki/Internationalized_domain_name).

This means that you can have email addresses with an internationalized domain, but not an internationalized local-part (the first part of your email address, before the `@` symbol). Refer to the following examples:

- `info@piñata.es` - Supported.
- `piñata@piñata.es` - Not supported.

### Non-delivery reports (NDRs)

Email Routing does not forward non-delivery reports to the original sender. This means the sender will not receive a notification indicating that the email did not reach the intended destination.

### Restrictive DMARC policies can make forwarded emails fail

Due to the nature of email forwarding, restrictive DMARC policies might make forwarded emails fail to be delivered. Refer to [dmarc.org](https://dmarc.org/wiki/FAQ#My_users_often_forward_their_emails_to_another_mailbox.2C_how_do_I_keep_DMARC_valid.3F) for more information.

### Sending or replying to an email from your Cloudflare domain

Email Routing does not support sending or replying from your Cloudflare domain. When you reply to emails forwarded by Email Routing, the reply will be sent from your destination address (like `my-name@gmail.com`), not your custom address (like `info@my-company.com`).

### Signs such "`+`" and "`.`" are treated as normal characters for custom addresses

Email Routing does not have advanced routing options. Characters such as `+` or `.`, which perform special actions in email providers like Gmail and Outlook, are currently treated as normal characters on custom addresses. More flexible routing options are in our roadmap.

---

# Demos and architectures

URL: https://developers.cloudflare.com/images/demos/

import { ExternalResources, GlossaryTooltip, ResourcesBySelector } from "~/components"

Learn how you can use Images within your existing architecture.

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Images.

<ExternalResources type="apps" products={["Images"]} />

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use Images:

<ResourcesBySelector types={["reference-architecture","design-guide","reference-architecture-diagram"]} products={["Images"]} />

---

# Getting started

URL: https://developers.cloudflare.com/images/get-started/

In this guide, you will get started with Cloudflare Images and make your first API request.

## Prerequisites

Before you make your first API request, ensure that you have a Cloudflare Account ID and an API token.

Refer to [Find zone and account IDs](/fundamentals/account/find-account-and-zone-ids/) for help locating your Account ID and [Create an API token](/fundamentals/api/get-started/create-token/) to learn how to create an access your API token.

## Make your first API request

```bash
curl --request POST \
  --url https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/images/v1 \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@./<YOUR_IMAGE.IMG>
```

## Enable transformations on your zone

You can dynamically optimize images that are stored outside of Cloudflare Images and deliver them using [transformation URLs](/images/transform-images/transform-via-url/).

Cloudflare will automatically cache every transformed image on our global network so that you store only the original image at your origin.

To enable transformations on your zone:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Go to **Images** > **Transformations**.
3. Go to the specific zone where you want to enable transformations.
4. Select **Enable for zone**. This will allow you to optimize and deliver remote images.

:::note


With **Resize images from any origin** unchecked, only the initial URL passed will be checked. Any redirect returned will be followed, including if it leaves the zone, and the resulting image will be transformed.


:::

:::note


If you are using transformations in a Worker, you need to include the appropriate logic in your Worker code to prevent resizing images from any origin. Unchecking this option in the dash does not apply to transformation requests coming from Cloudflare Workers.


:::

---

# Cloudflare Images

URL: https://developers.cloudflare.com/images/

import { CardGrid, Description, Feature, LinkTitleCard, Plan } from "~/components"

<Description>

Store, transform, optimize, and deliver images at scale
</Description>

<Plan type="all" />

Cloudflare Images provides an end-to-end solution designed to help you streamline your image infrastructure from a single API and runs on [Cloudflare's global network](https://www.cloudflare.com/network/).

There are two different ways to use Images:

- **Efficiently store and deliver images.** You can upload images into Cloudflare Images and dynamically deliver multiple variants of the same original image.
- **Optimize images that are stored outside of Images** You can make transformation requests to optimize any publicly available image on the Internet.

Cloudflare Images is available on both [Free and Paid plans](/images/pricing/). By default, all users have access to the Images Free plan, which includes limited usage of the transformations feature to optimize images in remote sources.

:::note[Image Resizing is now available as transformations]

All Image Resizing features are available as transformations with Images. Each unique transformation is billed only once per 30 days.

If you are using a legacy plan with Image Resizing, visit the [dashboard](https://dash.cloudflare.com/) to switch to an Imagesplan.


:::

***

## Features

<Feature header="Storage" href="/images/upload-images/">
Use Cloudflare’s edge network to store your images.


</Feature>

<Feature header="Direct creator upload" href="/images/upload-images/direct-creator-upload/">
Accept uploads directly and securely from your users by generating a one-time token.
</Feature>

<Feature header="Variants" href="/images/transform-images" cta="Create variants by transforming images">
Add up to 100 variants to specify how images should be resized for various use cases.
</Feature>

<Feature header="Signed URLs" href="/images/manage-images/serve-images/serve-private-images" cta="Serve private images">
Control access to your images by using signed URL tokens.
</Feature>

***

## More resources

<CardGrid>

<LinkTitleCard title="Community Forum" href="https://community.cloudflare.com/c/developers/images/63" icon="open-book">

Engage with other users and the Images team on Cloudflare support forum.
</LinkTitleCard>

</CardGrid>

---

# Pricing

URL: https://developers.cloudflare.com/images/pricing/

By default, all users are on the Images Free plan. The Free plan includes access to the transformations feature, which lets you optimize images stored outside of Images, like in R2.

The Paid plan allows transformations, as well as access to storage in Images.

Pricing is dependent on which features you use. The table below shows which metrics are used for each use case.

| Use case | Metrics | Availability |
|----------|---------|--------------|
| Optimize images stored outside of Images | Images Transformed | Free and Paid plans |
| Optimized images that are stored in Cloudflare Images | Images Stored, Images Delivered | Only Paid plans |

## Images Free

On the Free plan, you can request up to 5,000 unique transformations each month for free.

Once you exceed 5,000 unique transformations:

- Existing transformations in cache will continue to be served as expected.
- New transformations will return a `9422` error. If your source image is from the same domain where the transformation is served, then you can use the [`onerror` parameter](/images/transform-images/transform-via-url/#onerror) to redirect to the original image.
- You will not be charged for exceeding the limits in the Free plan.

To request more than 5,000 unique transformations each month, you can purchase an Images Paid plan.

## Images Paid

When you purchase an Images Paid plan, you can choose your own storage or add storage in Images.

| Metric | Pricing |
|--------|---------|
| Images Transformed | First 5,000 unique transformations included + $0.50 / 1,000 unique transformations / month |
| Images Stored | $5 / 100,000 images stored / month |
| Images Delivered | $1 / 100,000 images delivered / month |

If you optimize an image stored outside of Images, then you will be billed only for Images Transformed.

Alternatively, Images Stored and Images Delivered apply only to images that are stored in your Images bucket. When you optimize an image that is stored in Images, then this counts toward Images Delivered — not Images Transformed.

## Metrics

### Images Transformed

A unique transformation is a request to transform an original image based on a set of [supported parameters](/images/transform-images/transform-via-url/#options). This metric is used only when optimizing images that are stored outside of Images.

For example, if you transform `thumbnail.jpg` as 100x100, then this counts as 1 unique transformation. If you transform the same `thumbnail.jpg` as 200x200, then this counts as a separate unique transformation.

You are billed for the number of unique transformations that are counted during each billing period.

Unique transformations are counted over a 30-day sliding window. For example, if you request `width=100/thumbnail.jpg` on June 30, then this counts once for that billing period. If you request the same transformation on July 1, then this will not count as a billable request, since the same transformation was already requested within the last 30 days.

The `format` parameter counts as only 1 billable transformation, even if multiple copies of an image are served. In other words, if `width=100,format=auto/thumbnail.jpg` is served to some users as AVIF and to others as WebP, then this counts as 1 unique transformation instead of 2.

#### Example

A retail website has 1,000 original product images that get served in 5 different sizes each month. This results in 5,000 unique transformations — or a cost of $2.50 per month.

### Images Stored

Storage in Images is available only with an Images Paid plan. You can purchase storage in increments of $5 for every 100,000 images stored per month.

You can create predefined variants to specify how an image should be resized, such as `thumbnail` as 100x100 and `hero` as 1600x500.

Only uploaded images count toward Images Stored; defining variants will not impact your storage limit.

### Images Delivered

For images that are stored in Images, you will incur $1 for every 100,000 images delivered per month. This metric does not include transformed images that are stored in remote sources.

Every image requested by the browser counts as 1 billable request.

#### Example

A retail website has a product page that uses Images to serve 10 images. If the page was visited 10,000 times this month, then this results in 100,000 images delivered — or $1.00 in billable usage.

---

# Demos and architectures

URL: https://developers.cloudflare.com/hyperdrive/demos/

import { ExternalResources, GlossaryTooltip, ResourcesBySelector } from "~/components"

Learn how you can use Hyperdrive within your existing application and architecture.

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Hyperdrive.

<ExternalResources type="apps" products={["Hyperdrive"]} />

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use Hyperdrive:

<ResourcesBySelector types={["reference-architecture","design-guide","reference-architecture-diagram"]} products={["Hyperdrive"]} />

---

# Getting started

URL: https://developers.cloudflare.com/hyperdrive/get-started/

import { Render, PackageManagers, Tabs, TabItem } from "~/components";

Hyperdrive accelerates access to your existing databases from Cloudflare Workers, making even single-region databases feel globally distributed.

By maintaining a connection pool to your database within Cloudflare's network, Hyperdrive reduces seven round-trips to your database before you can even send a query: the TCP handshake (1x), TLS negotiation (3x), and database authentication (3x).

Hyperdrive understands the difference between read and write queries to your database, and caches the most common read queries, improving performance and reducing load on your origin database.

This guide will instruct you through:

- Creating your first Hyperdrive configuration.
- Creating a [Cloudflare Worker](/workers/) and binding it to your Hyperdrive configuration.
- Establishing a database connection from your Worker to a public database.

:::note

Hyperdrive currently works with PostgreSQL, MySQL and many compatible databases. This includes CockroachDB and Materialize (which are PostgreSQL-compatible), and Planetscale.

Learn more about the [databases that Hyperdrive supports](/hyperdrive/reference/supported-databases-and-features).

:::

## Prerequisites

Before you begin, ensure you have completed the following:

1. Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages) if you have not already.
2. Install [`Node.js`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). Use a Node version manager like [nvm](https://github.com/nvm-sh/nvm) or [Volta](https://volta.sh/) to avoid permission issues and change Node.js versions. [Wrangler](/workers/wrangler/install-and-update/) requires a Node version of `16.17.0` or later.
3. Have **a publicly accessible** PostgreSQL/MySQL (or compatible) database.

## 1. Log in

Before creating your Hyperdrive binding, log in with your Cloudflare account by running:

```sh
npx wrangler login
```

You will be directed to a web page asking you to log in to the Cloudflare dashboard. After you have logged in, you will be asked if Wrangler can make changes to your Cloudflare account. Scroll down and select **Allow** to continue.

## 2. Create a Worker

:::note[New to Workers?]

Refer to [How Workers works](/workers/reference/how-workers-works/) to learn about the Workers serverless execution model works. Go to the [Workers Get started guide](/workers/get-started/guide/) to set up your first Worker.

:::

Create a new project named `hyperdrive-tutorial` by running:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"hyperdrive-tutorial"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

This will create a new `hyperdrive-tutorial` directory. Your new `hyperdrive-tutorial` directory will include:

- A `"Hello World"` [Worker](/workers/get-started/guide/#3-write-code) at `src/index.ts`.
- A [`wrangler.jsonc`](/workers/wrangler/configuration/) configuration file. `wrangler.jsonc` is how your `hyperdrive-tutorial` Worker will connect to Hyperdrive.

### Enable Node.js compatibility

[Node.js compatibility](/workers/runtime-apis/nodejs/) is required for database drivers, and needs to be configured for your Workers project.

<Render file="nodejs_compat" product="workers" />

## 3. Connect Hyperdrive to a database

Hyperdrive works by connecting to your database, pooling database connections globally, and speeding up your database access through Cloudflare's network.

It will provide a secure connection string that is only accessible from your Worker which you can use to connect to your database through Hyperdrive.
This means that you can use the Hyperdrive connection string with your existing drivers or ORM libraries without needing significant changes to your code.

To create your first Hyperdrive database configuration, change into the directory you just created for your Workers project:

```sh
cd hyperdrive-tutorial
```

To create your first Hyperdrive, you will need:

- The IP address (or hostname) and port of your database.
- The database username (for example, `hyperdrive-demo`).
- The password associated with that username.
- The name of the database you want Hyperdrive to connect to. For example, `postgres` or `mysql`.

Hyperdrive accepts the combination of these parameters in the common connection string format used by database drivers:

<Tabs>
	<TabItem label="PostgreSQL">
		```txt

		postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

    	```

    		Most database providers will provide a connection string you can copy-and-paste directly into Hyperdrive.

To create a Hyperdrive connection, run the `wrangler` command, replacing the placeholder values passed to the `--connection-string` flag with the values of your existing database:

```sh
npx wrangler hyperdrive create <YOUR_CONFIG_NAME> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"
```

    </TabItem>
    <TabItem label="MySQL">
    	```txt

    	mysql://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name

    	```

    		Most database providers will provide a connection string you can copy-and-paste directly into Hyperdrive.

    		To create a Hyperdrive connection, run the `wrangler` command, replacing the placeholder values passed to the `--connection-string` flag with the values of your existing database:

```sh
npx wrangler hyperdrive create <YOUR_CONFIG_NAME> --connection-string="mysql://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"
```

    </TabItem>

</Tabs>

:::note[Manage caching]
By default, Hyperdrive will cache query results. If you wish to disable caching, pass the flag `--caching-disabled`.

Alternatively, you can use the `--max-age` flag to specify the maximum duration (in seconds) for which items should persist in the cache, before they are evicted. Default value is 60 seconds.

Refer to [Hyperdrive Wrangler commands](/hyperdrive/reference/wrangler-commands/) for more information.
:::

If successful, the command will output your new Hyperdrive configuration:

```json
{
	"hyperdrive": [
		{
			"binding": "HYPERDRIVE",
			"id": "<example id: 57b7076f58be42419276f058a8968187>"
		}
	]
}
```

Copy the `id` field: you will use this in the next step to make Hyperdrive accessible from your Worker script.

:::note

Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](/hyperdrive/observability/troubleshooting/) to debug possible causes.

:::

## 4. Bind your Worker to Hyperdrive

<Render file="create-hyperdrive-binding" product="hyperdrive" />

## 5. Run a query against your database

Once you have created a Hyperdrive configuration and bound it to your Worker, you can run a query against your database.

### Install a database driver

<Tabs>
<TabItem label="PostgreSQL">

To connect to your database, you will need a database driver which allows you to authenticate and query your database. For this tutorial, you will use [node-postgres (pg)](https://node-postgres.com/), one of the most widely used PostgreSQL drivers.

To install `pg`, ensure you are in the `hyperdrive-tutorial` directory. Open your terminal and run the following command:

<PackageManagers pkg="pg" comment="This should install v8.13.0 or later" />

If you are using TypeScript, you should also install the type definitions for `pg`:

<PackageManagers pkg="@types/pg" dev comment="This should install v8.13.0 or later" />

With the driver installed, you can now create a Worker script that queries your database.

</TabItem>
<TabItem label="MySQL">

To connect to your database, you will need a database driver which allows you to authenticate and query your database. For this tutorial, you will use [mysql2](https://github.com/sidorares/node-mysql2), one of the most widely used MySQL drivers.

To install `mysql2`, ensure you are in the `hyperdrive-tutorial` directory. Open your terminal and run the following command:

<PackageManagers pkg="mysql2" comment="This should install v3.13.0 or later" />

With the driver installed, you can now create a Worker script that queries your database.

</TabItem>
</Tabs>

### Write a Worker

<Tabs>
<TabItem label="PostgreSQL">
After you have set up your database, you will run a SQL query from within your Worker.

Go to your `hyperdrive-tutorial` Worker and open the `index.ts` file.

The `index.ts` file is where you configure your Worker's interactions with Hyperdrive.

Populate your `index.ts` file with the following code:

```typescript
// pg 8.13.0 or later is recommended
import { Client } from "pg";

export interface Env {
	// If you set another name in the Wrangler config file as the value for 'binding',
	// replace "HYPERDRIVE" with the variable name you defined.
	HYPERDRIVE: Hyperdrive;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a client using the pg driver (or any supported driver, ORM or query builder)
    // with the Hyperdrive credentials. These credentials are only accessible from your Worker.
    const sql = new Client({
      connectionString: env.HYPERDRIVE.connectionString,
    });

		try {
			// Connect to the database
			await sql.connect();
			
			// Sample query
			const results = await sql.query(`SELECT * FROM pg_tables`);

			// Clean up the client after the response is returned, before the Worker is killed
			ctx.waitUntil(sql.end());

			// Return result rows as JSON
			return Response.json(results.rows);
		} catch (e) {
			console.error(e);
			return Response.json(
				{ error: e instanceof Error ? e.message : e },
				{ status: 500 },
			);
		}
	},
} satisfies ExportedHandler<Env>;
```

Upon receiving a request, the code above does the following:

1. Creates a new database client configured to connect to your database via Hyperdrive, using the Hyperdrive connection string.
2. Initiates a query via `await sql.query()` that outputs all tables (user and system created) in the database (as an example query).
3. Returns the response as JSON to the client.

</TabItem>
<TabItem label="MySQL">
After you have set up your database, you will run a SQL query from within your Worker.

Go to your `hyperdrive-tutorial` Worker and open the `index.ts` file.

The `index.ts` file is where you configure your Worker's interactions with Hyperdrive.

Populate your `index.ts` file with the following code:

```typescript
// mysql2 v3.13.0 or later is required
import { createConnection  } from 'mysql2/promise';

export interface Env {
  // If you set another name in the Wrangler config file as the value for 'binding',
  // replace "HYPERDRIVE" with the variable name you defined.
  HYPERDRIVE: Hyperdrive;
}

export default {
 async fetch(request, env, ctx): Promise<Response> {

		// Create a connection using the mysql2 driver (or any support driver, ORM or query builder)
		// with the Hyperdrive credentials. These credentials are only accessible from your Worker.
		const connection = await createConnection({
			host: env.HYPERDRIVE.host,
			user: env.HYPERDRIVE.user,
			password: env.HYPERDRIVE.password,
			database: env.HYPERDRIVE.database,
			port: env.HYPERDRIVE.port

			// The following line is needed for mysql2 compatibility with Workers
			// mysql2 uses eval() to optimize result parsing for rows with > 100 columns
			// Configure mysql2 to use static parsing instead of eval() parsing with disableEval
			disableEval: true
		});

		try{
			// Sample query
			const [results, fields] = await connection.query(
				'SHOW tables;'
			);

			// Clean up the client after the response is returned, before the Worker is killed
			ctx.waitUntil(connection.end());

			// Return result rows as JSON
			return new Response(JSON.stringify({ results, fields }), {
				headers: {
					'Content-Type': 'application/json',
					'Access-Control-Allow-Origin': '*',
				},
			});
		}
		catch(e){
			console.error(e);
			return Response.json(
				{ error: e instanceof Error ? e.message : e },
				{ status: 500 },
			);
		}

 },
} satisfies ExportedHandler<Env>;

```

Upon receiving a request, the code above does the following:

1. Creates a new database client configured to connect to your database via Hyperdrive, using the Hyperdrive connection string.
2. Initiates a query via `await connection.query` that outputs all tables (user and system created) in the database (as an example query).
3. Returns the response as JSON to the client.

</TabItem>
</Tabs>

## 6. Deploy your Worker

You can now deploy your Worker to make your project accessible on the Internet. To deploy your Worker, run:

```sh
npx wrangler deploy
# Outputs: https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev
```

You can now visit the URL for your newly created project to query your live database.

For example, if the URL of your new Worker is `hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev`, accessing `https://hyperdrive-tutorial.<YOUR_SUBDOMAIN>.workers.dev/` will send a request to your Worker that queries your database directly.

By finishing this tutorial, you have created a Hyperdrive configuration, a Worker to access that database and deployed your project globally.

## Next steps

- Learn more about [how Hyperdrive works](/hyperdrive/configuration/how-hyperdrive-works/).
- How to [configure query caching](/hyperdrive/configuration/query-caching/).
- [Troubleshooting common issues](/hyperdrive/observability/troubleshooting/) when connecting a database to Hyperdrive.

If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the [Cloudflare Developers community on Discord](https://discord.cloudflare.com).

---

# Hyperdrive

URL: https://developers.cloudflare.com/hyperdrive/

import {
	CardGrid,
	Description,
	Feature,
	LinkTitleCard,
	Plan,
	RelatedProduct,
	Tabs,
	TabItem,
	LinkButton,
} from "~/components";

<Description>

Turn your existing regional database into a globally distributed database.

</Description>

<Plan type="workers-all" />

Hyperdrive is a service that accelerates queries you make to existing databases, making it faster to access your data from across the globe from [Cloudflare Workers](/workers/), irrespective of your users' location.

Hyperdrive supports any Postgres or MySQL database, including those hosted on AWS, Google Cloud, Azure, Neon and Planetscale. Hyperdrive also supports Postgres-compatible databases like CockroachDB and Timescale.
You do not need to write new code or replace your favorite tools: Hyperdrive works with your existing code and tools you use.

Use Hyperdrive's connection string from your Cloudflare Workers application with your existing Postgres drivers and object-relational mapping (ORM) libraries:

<Tabs>
	<TabItem label="PostgreSQL">
	<Tabs>
	<TabItem label="index.ts">
```ts
import postgres from 'postgres';

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Hyperdrive provides a unique generated connection string to connect to
		// your database via Hyperdrive that can be used with your existing tools
		const sql = postgres(env.HYPERDRIVE.connectionString);

    	try {
    		// Sample SQL query
    		const results = await sql`SELECT * FROM pg_tables`;

    		// Close the client after the response is returned
    		ctx.waitUntil(sql.end());

    		return Response.json(results);
    	} catch (e) {
    		return Response.json({ error: e instanceof Error ? e.message : e }, { status: 500 });
    	}
    },

} satisfies ExportedHandler<{ HYPERDRIVE: Hyperdrive }>;

````

    </TabItem>
    <TabItem label="wrangler.jsonc">
```json
	{
		"$schema": "node_modules/wrangler/config-schema.json",
		"name": "WORKER-NAME",
		"main": "src/index.ts",
		"compatibility_date": "2025-02-04",
		"compatibility_flags": [
			"nodejs_compat"
		],
		"observability": {
			"enabled": true
		},
		"hyperdrive": [
			{
				"binding": "HYPERDRIVE",
				"id": "<YOUR_HYPERDRIVE_ID>",
				"localConnectionString": "<ENTER_LOCAL_CONNECTION_STRING_FOR_LOCAL_DEVELOPMENT_HERE>"
			}
		]
	}
````

</TabItem>
</Tabs>
</TabItem>
<TabItem label="MySQL">
	<Tabs>
	<TabItem label="index.ts">
```ts
import { createConnection  } from 'mysql2/promise';

export default {
 async fetch(request, env, ctx): Promise<Response> {
    const connection = await createConnection({
     host: env.DB_HOST,
     user: env.DB_USER,
     password: env.DB_PASSWORD,
     database: env.DB_NAME,
     port: env.DB_PORT

    	 // This is needed to use mysql2 with Workers
     // This configures mysql2 to use static parsing instead of eval() parsing (not available on Workers)
     disableEval: true

});

const [results, fields] = await connection.query(
'SHOW tables;'
);

return new Response(JSON.stringify({ results, fields }), {
headers: {
'Content-Type': 'application/json',
'Access-Control-Allow-Origin': '\*',
},
});
},
} satisfies ExportedHandler<Env>;

````

    </TabItem>
    <TabItem label="wrangler.jsonc">
```json
	{
		"$schema": "node_modules/wrangler/config-schema.json",
		"name": "WORKER-NAME",
		"main": "src/index.ts",
		"compatibility_date": "2025-02-04",
		"compatibility_flags": [
			"nodejs_compat"
		],
		"observability": {
			"enabled": true
		},
		"hyperdrive": [
			{
				"binding": "HYPERDRIVE",
				"id": "<YOUR_HYPERDRIVE_ID>",
				"localConnectionString": "<ENTER_LOCAL_CONNECTION_STRING_FOR_LOCAL_DEVELOPMENT_HERE>"
			}
		]
	}
````

</TabItem>
</Tabs>

</TabItem>
</Tabs>

<LinkButton href="/hyperdrive/get-started/">Get started</LinkButton>

---

## Features

<Feature header="Connect your database" href="/hyperdrive/get-started/" cta="Connect Hyperdrive to your database">

Connect Hyperdrive to your existing database and deploy a [Worker](/workers/) that queries it.

</Feature>

<Feature header="PostgreSQL support" href="/hyperdrive/examples/connect-to-postgres/" cta="Connect Hyperdrive to your PostgreSQL database">

Hyperdrive allows you to connect to any PostgreSQL or PostgreSQL-compatible database.

</Feature>

<Feature header="MySQL support" href="/hyperdrive/examples/connect-to-mysql/" cta="Connect Hyperdrive to your MySQL database">

Hyperdrive allows you to connect to any MySQL database.

</Feature>

<Feature header="Query Caching" href="/hyperdrive/configuration/query-caching/" cta="Learn about Query Caching">

Use Hyperdrive to cache the most popular queries executed against your database.

</Feature>

---

## Related products

<RelatedProduct header="Workers" href="/workers/" product="workers">

Build serverless applications and deploy instantly across the globe for exceptional performance, reliability, and scale.

</RelatedProduct>

<RelatedProduct header="Pages" href="/pages/" product="pages">

Deploy dynamic front-end applications in record time.

</RelatedProduct>

---

## More resources

<CardGrid>

<LinkTitleCard
	title="Pricing"
	href="/hyperdrive/platform/pricing/"
	icon="seti:shell"
>
	Learn about Hyperdrive's pricing.
</LinkTitleCard>

<LinkTitleCard
	title="Limits"
	href="/hyperdrive/platform/limits/"
	icon="document"
>
	Learn about Hyperdrive limits.
</LinkTitleCard>

<LinkTitleCard
	title="Storage options"
	href="/workers/platform/storage-options/"
	icon="document"
>
	Learn more about the storage and database options you can build on with
	Workers.
</LinkTitleCard>

<LinkTitleCard
	title="Developer Discord"
	href="https://discord.cloudflare.com"
	icon="discord"
>
	Connect with the Workers community on Discord to ask questions, show what you
	are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard
	title="@CloudflareDev"
	href="https://x.com/cloudflaredev"
	icon="x.com"
>
	Follow @CloudflareDev on Twitter to learn about product announcements, and
	what is new in Cloudflare Developer Platform.
</LinkTitleCard>

</CardGrid>

---

# Demos and architectures

URL: https://developers.cloudflare.com/kv/demos/

import { ExternalResources, GlossaryTooltip, ResourcesBySelector } from "~/components"

Learn how you can use KV within your existing application and architecture.

## Demo applications

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for KV.

<ExternalResources type="apps" products={["KV"]} />

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use KV:

<ResourcesBySelector types={["reference-architecture","design-guide","reference-architecture-diagram"]} products={["KV"]} />

---

# Getting started

URL: https://developers.cloudflare.com/kv/get-started/

import { Render, PackageManagers, Steps, FileTree, Details, Tabs, TabItem, WranglerConfig, GitHubCode } from "~/components";

Workers KV provides low-latency, high-throughput global storage to your [Cloudflare Workers](/workers/) applications. Workers KV is ideal for storing user configuration data, routing data, A/B testing configurations and authentication tokens, and is well suited for read-heavy workloads.

This guide instructs you through:

- Creating a KV namespace.
- Writing key-value pairs to your KV namespace from a Cloudflare Worker.
- Reading key-value pairs from a KV namespace.

You can perform these tasks through the Wrangler CLI or through the Cloudflare dashboard.

## Quick start

If you want to skip the setup steps and get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/update/kv/kv/kv-get-started)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers. Use this option if you are familiar with Cloudflare Workers, and wish to skip the step-by-step guidance.

You may wish to manually follow the steps if you are new to Cloudflare Workers.

## Prerequisites

<Render file="prereqs" product="workers" />

## 1. Create a Worker project

:::note[New to Workers?]

Refer to [How Workers works](/workers/reference/how-workers-works/) to learn about the Workers serverless execution model works. Go to the [Workers Get started guide](/workers/get-started/guide/) to set up your first Worker.

:::

<Tabs syncKey = 'CLIvsDash'> <TabItem label='CLI'>

Create a new Worker to read and write to your KV namespace.

<Steps>
1. Create a new project named `kv-tutorial` by running:

    <PackageManagers type="create" pkg="cloudflare@latest" args={"kv-tutorial"} />

    <Render
    	file="c3-post-run-steps"
    	product="workers"
    	params={{
    	category: "hello-world",
    	type: "Worker only",
    	lang: "TypeScript",
    	}}
    />

    This creates a new `kv-tutorial` directory, illustrated below.

    <FileTree>
    	- kv-tutorial/
    		- node_modules/
    		- test/
    		- src
    			- **index.ts**
    		- package-lock.json
    		- package.json
    		- testconfig.json
    		- vitest.config.mts
    		- worker-configuration.d.ts
    		- **wrangler.jsonc**
    </FileTree>

    Your new `kv-tutorial` directory includes:

    - A `"Hello World"` [Worker](/workers/get-started/guide/#3-write-code) in `index.ts`.
    - A [`wrangler.jsonc`](/workers/wrangler/configuration/) configuration file. `wrangler.jsonc` is how your `kv-tutorial` Worker accesses your kv database.

2. Change into the directory you just created for your Worker project:

	```sh
	cd kv-tutorial
	```

	:::note

	If you are familiar with Cloudflare Workers, or initializing projects in a Continuous Integration (CI) environment, initialize a new project non-interactively by setting `CI=true` as an [environmental variable](/workers/configuration/environment-variables/) when running `create cloudflare@latest`.

	For example: `CI=true npm create cloudflare@latest kv-tutorial --type=simple --git --ts --deploy=false` creates a basic "Hello World" project ready to build on.

	:::

</Steps>
</TabItem> <TabItem label = 'Dashboard'>

<Steps>
1. Log in to your Cloudflare dashboard and select your account.
2. Go to [your account > **Workers & Pages** > **Overview**](https://dash.cloudflare.com/?to=/:account/workers-and-pages).
3. Select **Create**.
4. Select **Create Worker**.
5. Name your Worker. For this tutorial, name your Worker `kv-tutorial`.
6. Select **Deploy**.
</Steps>
</TabItem>
</Tabs>

## 2. Create a KV namespace

A [KV namespace](/kv/concepts/kv-namespaces/) is a key-value database replicated to Cloudflare's global network.

<Tabs syncKey = 'CLIvsDash'> <TabItem label='CLI'>

You can use [Wrangler](/workers/wrangler/) to create a new KV namespace. You can also use it to perform operations such as put, list, get, and delete within your KV namespace.

:::note

KV operations are scoped to your account.
:::

To create a KV namespace via Wrangler:

<Steps>
1. Open your terminal and run the following command:

	```sh
	npx wrangler kv namespace create <BINDING_NAME>
	```

	The `npx wrangler kv namespace create <BINDING_NAME>` subcommand takes a new binding name as its argument. A KV namespace is created using a concatenation of your Worker's name (from your Wrangler file) and the binding name you provide. A `<BINDING_ID>` is randomly generated for you.

	For this tutorial, use the binding name `USERS_NOTIFICATION_CONFIG`.

	```sh ins="USERS_NOTIFICATION_CONFIG"
	npx wrangler kv namespace create USERS_NOTIFICATION_CONFIG
	```

	```sh output
	🌀 Creating namespace with title "USERS_NOTIFICATION_CONFIG"
	✨ Success!
	Add the following to your configuration file in your kv_namespaces array:
	{
		"kv_namespaces": [
			{
				"binding": "USERS_NOTIFICATION_CONFIG",
				"id": "<BINDING_ID>"
			}
		]
	}
	```

</Steps>

</TabItem><TabItem label = 'Dashboard'>

<Steps>
1. Go to [**Storage & Databases** > **KV**](https://dash.cloudflare.com/?to=/:account/workers/kv/namespaces).
2. Select **Create a namespace**.
3. Enter a name for your namespace. For this tutorial, use `kv_tutorial_namespace`.
4. Select **Add**.
</Steps>

</TabItem></Tabs>

## 3. Bind your Worker to your KV namespace

You must create a binding to connect your Worker with your KV namespace. [Bindings](/workers/runtime-apis/bindings/) allow your Workers to access resources, like KV, on the Cloudflare developer platform.

:::note[Bindings]

A binding is how your Worker interacts with external resources such as [KV namespaces](/kv/concepts/kv-namespaces/). A binding is a runtime variable that the Workers runtime provides to your code. You can declare a variable name in your Wrangler file that binds to these resources at runtime, and interact with them through this variable. Every binding's variable name and behavior is determined by you when deploying the Worker.

Refer to [Environment](/kv/reference/environments/) for more information.

:::

To bind your KV namespace to your Worker:

<Tabs syncKey='CLIvsDash'><TabItem label='CLI'>
<Steps>
1. In your Wrangler file, add the following with the values generated in your terminal from [step 2](/kv/get-started/#2-create-a-kv-namespace):

	<WranglerConfig>

	```toml
	[[kv_namespaces]]
	binding = "USERS_NOTIFICATION_CONFIG"
	id = "<BINDING_ID>"
	```

	</WranglerConfig>

   Binding names do not need to correspond to the namespace you created. Binding names are only a reference. Specifically:

	- The value (string) you set for `binding` is used to reference this KV namespace in your Worker. For this tutorial, this should be `USERS_NOTIFICATION_CONFIG`.
	- The binding must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). For example, `binding = "MY_KV"` or `binding = "routingConfig"` would both be valid names for the binding.
	- Your binding is available in your Worker at `env.<BINDING_NAME>` from within your Worker. For this tutorial, the binding is available at `env.USERS_NOTIFICATION_CONFIG`.
</Steps>

</TabItem><TabItem label='Dashboard'>

<Steps>
1. Go to [**Workers & Pages** > **Overview**](https://dash.cloudflare.com/?to=/:account/workers-and-pages).
2. Select the `kv-tutorial` Worker you created in [step 1](/kv/get-started/#1-create-a-worker-project).
3. Select **Settings**.
4. Scroll to **Bindings**, then select **Add**.
5. Select **KV namespace**.
6. Name your binding (`BINDING_NAME`) in **Variable name**, then select the KV namespace (`kv_tutorial_namespace`) you created in [step 2](/kv/get-started/#2-create-a-kv-namespace) from the dropdown menu.
7. Select **Deploy** to deploy your binding.
</Steps>
</TabItem></Tabs>

## 4. Interact with your KV namespace

You can interact with your KV namespace via [Wrangler](/workers/wrangler/install-and-update/) or directly from your [Workers](/workers/) application.

### 4.1. Write a value

<Tabs syncKey='CLIvsDash'><TabItem label = 'CLI'>

To write a value to your empty KV namespace using Wrangler:

<Steps>
1. Run the `wrangler kv key put` subcommand in your terminal, and input your key and value respectively. `<KEY>` and `<VALUE>` are values of your choice.

	```sh
	npx wrangler kv key put --binding=<BINDING_NAME> "<KEY>" "<VALUE>"
	```

	In this tutorial, you will add a key `user_1` with value `enabled` to the KV namespace you created in [step 2](/kv/get-started/#2-create-a-kv-namespace).

	```sh
	npx wrangler kv key put --binding=USERS_NOTIFICATION_CONFIG "user_1" "enabled"
	```
	```sh output
	Writing the value "enabled" to key "user_1" on namespace <BINDING_ID>.
	```
</Steps>

:::note[Using `--namespace-id`]
Instead of using `--binding`, you can also use `--namespace-id` to specify which KV namespace should receive the operation:

```sh "--namespace-id=<BINDING_ID>"
npx wrangler kv key put --namespace-id=<BINDING_ID> "<KEY>" "<VALUE>"
```

```sh output
Writing the value "<VALUE>" to key "<KEY>" on namespace <BINDING_ID>.
```
:::

:::note[Storing values in remote KV namespace]

By default, the values are written locally. To create a key and a value in your remote KV namespace, add the `--remote` flag at the end of the command:

```sh ins="--remote"
npx wrangler kv key put --namespace-id=xxxxxxxxxxxxxxxx "<KEY>" "<VALUE>" --remote
```

:::

</TabItem><TabItem label = 'Dashboard'>
<Steps>
1. Go to [**Storage & Databases** > **KV**](https://dash.cloudflare.com/?to=/:account/workers/kv/namespaces).
2. Select the KV namespace you created (`kv_tutorial_namespace`), then select **View**.
3. Select **KV Pairs**.
4. Enter a `<KEY>` of your choice.
5. Enter a `<VALUE>` of your choice.
6. Select **Add entry**.
</Steps>

</TabItem> </Tabs>

### 4.2. Get a value

<Tabs syncKey='CLIvsDash'><TabItem label = 'CLI'>

To access the value from your KV namespace using Wrangler:

<Steps>
1. Run the `wrangler kv key get` subcommand in your terminal, and input your key value:

    ```sh
    npx wrangler kv key get --binding=<BINDING_NAME> "<KEY>"
    ```

		In this tutorial, you will get the value of the key `user_1` from the KV namespace you created in [step 2](/kv/get-started/#2-create-a-kv-namespace).

	:::note
	To view the value directly within the terminal, you use the `--text` flag.
	:::

    ```sh
    npx wrangler kv key get --binding=USERS_NOTIFICATION_CONFIG "user_1" --text
    ```

    Similar to the `put` command, the `get` command can also be used to access a KV namespace in two ways - with `--binding` or `--namespace-id`:

</Steps>

:::caution

Exactly **one** of `--binding` or `--namespace-id` is required.
:::

Refer to the [`kv bulk` documentation](/kv/reference/kv-commands/#kv-bulk) to write a file of multiple key-value pairs to a given KV namespace.

</TabItem><TabItem label='Dashboard'>

You can view key-value pairs directly from the dashboard.
<Steps>
1. Go to your account > **Storage & Databases** > **KV**.
2. Go to the KV namespace you created (`kv_tutorial_namespace`), then select **View**.
3. Select **KV Pairs**.
</Steps>
</TabItem></Tabs>

## 5. Access your KV namespace from your Worker

<Tabs syncKey = 'CLIvsDash'><TabItem label = 'CLI'>

:::note

When using [`wrangler dev`](/workers/wrangler/commands/#dev) to develop locally, Wrangler defaults to using a local version of KV to avoid interfering with any of your live production data in KV. This means that reading keys that you have not written locally returns null.

To have `wrangler dev` connect to your Workers KV namespace running on Cloudflare's global network, call `wrangler dev --remote` instead. This uses the `preview_id` of the KV binding configuration in the Wrangler file. Refer to the [KV binding docs](/kv/concepts/kv-bindings/#use-kv-bindings-when-developing-locally) for more information.

:::

<Steps>
1. In your Worker script, add your KV binding in the `Env` interface. If you have bootstrapped your project with JavaScript, this step is not required.

	```ts
	interface Env {
		USERS_NOTIFICATION_CONFIG: KVNamespace;
		// ... other binding types
	}
	```

2. Use the `put()` method on `USERS_NOTIFICATION_CONFIG` to create a new key-value pair. You will add a new key `user_2` with value `disabled` to your KV namespace.

	```ts
	let value = await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
	```

3. Use the KV `get()` method to fetch the data you stored in your KV namespace. You will fetch the value of the key `user_2` from your KV namespace.

	```ts
	let value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");
	```
</Steps>

Your Worker code should look like this:

<GitHubCode
    repo="cloudflare/docs-examples"
    file="kv/kv-get-started/src/index.ts"
    commit="831724c421748229864c1ea28c854e352c62625e"
    lang="ts"
		lines="1-26"
    useTypeScriptExample={true}
/>

The code above:

1. Writes a key to your KV namespace using KV's `put()` method.
2. Reads the same key using KV's `get()` method.
3. Checks if the key is null, and returns a `404` response if it is.
4. If the key is not null, it returns the value of the key.
5. Uses JavaScript's [`try...catch`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/try...catch) exception handling to catch potential errors. When writing or reading from any service, such as Workers KV or external APIs using `fetch()`, you should expect to handle exceptions explicitly.

</TabItem><TabItem label = 'Dashboard'>

<Steps>
1. Go to **Workers & Pages** > **Overview**.
2. Go to the `kv-tutorial` Worker you created.
3. Select **Edit Code**.
4. Clear the contents of the `workers.js` file, then paste the following code.

	<GitHubCode
			repo="cloudflare/docs-examples"
			file="kv/kv-get-started/src/index.ts"
			commit="831724c421748229864c1ea28c854e352c62625e"
			lang="ts"
			lines="1-26"
			useTypeScriptExample={true}
	/>

	The code above:

	1. Writes a key to `BINDING_NAME` using KV's `put()` method.
	2. Reads the same key using KV's `get()` method, and returns an error if the key is null (or in case the key is not set, or does not exist).
	3. Uses JavaScript's [`try...catch`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) exception handling to catch potential errors. When writing or reading from any service, such as Workers KV or external APIs using `fetch()`, you should expect to handle exceptions explicitly.

	The browser should simply return the `VALUE` corresponding to the `KEY` you have specified with the `get()` method.
2. Select **Save**.

</Steps>

</TabItem></Tabs>

## 6. Deploy your Worker

Deploy your Worker to Cloudflare's global network.

<Tabs syncKey = 'CLIvsDash'><TabItem label = 'CLI'>

<Steps>
1. Run the following command to deploy KV to Cloudflare's global network:

    ```sh
    npm run deploy
    ```

2. Visit the URL for your newly created Workers KV application.

   For example, if the URL of your new Worker is `kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev`, accessing `https://kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev/` sends a request to your Worker that writes (and reads) from Workers KV.

</Steps>

</TabItem><TabItem label='Dashboard'>
<Steps>

1. Go to **Workers & Pages** > **Overview**.
2. Select your `kv-tutorial` Worker.
3. Select **Deployments**.
4. From the **Version History** table, select **Deploy version**.
5. From the **Deploy version** page, select **Deploy**.

	This deploys the latest version of the Worker code to production.

</Steps>
</TabItem></Tabs>

## Summary

By finishing this tutorial, you have:

1. Created a KV namespace
2. Created a Worker that writes and reads from that namespace
3. Deployed your project globally.

## Next steps

If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the [Cloudflare Developers community on Discord](https://discord.cloudflare.com).

- Learn more about the [KV API](/kv/api/).
- Understand how to use [Environments](/kv/reference/environments/) with Workers KV.
- Read the Wrangler [`kv` command documentation](/kv/reference/kv-commands/).

---

# Glossary

URL: https://developers.cloudflare.com/kv/glossary/

import { Glossary } from "~/components"

Review the definitions for terms used across Cloudflare's KV documentation.

<Glossary product="kv" />

---

# Cloudflare Workers KV

URL: https://developers.cloudflare.com/kv/

import {
	CardGrid,
	Description,
	Feature,
	LinkTitleCard,
	Plan,
	RelatedProduct,
	Tabs,
	TabItem,
	LinkButton,
} from "~/components";

<Description>

Create a global, low-latency, key-value data storage.

</Description>

<Plan type="workers-all" />

Workers KV is a data storage that allows you to store and retrieve data globally. With Workers KV, you can build dynamic and performant APIs and websites that support high read volumes with low latency.

For example, you can use Workers KV for:

- Caching API responses.
- Storing user configurations / preferences.
- Storing user authentication details.

Access your Workers KV namespace from Cloudflare Workers using [Workers Bindings](/workers/runtime-apis/bindings/) or from your external application using the REST API:

<Tabs>
<TabItem label="Workers Binding API">
	<Tabs>
	<TabItem label="index.ts">
```ts
export default {
	async fetch(request, env, ctx): Promise<Response> {
		// write a key-value pair
		await env.KV_BINDING.put('KEY', 'VALUE');

		// read a key-value pair
		const value = await env.KV_BINDING.get('KEY');

		// list all key-value pairs
		const allKeys = await env.KV_BINDING.list();

		// delete a key-value pair
		await env.KV_BINDING.delete('KEY');

		// return a Workers response
		return new Response(
			JSON.stringify({
				value: value,
				allKeys: allKeys,
			}),
		);
	},

} satisfies ExportedHandler<{ KV_BINDING: KVNamespace }>;

    ```
    </TabItem>
    <TabItem label="wrangler.jsonc">

```json
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<ENTER_WORKER_NAME>",
	"main": "src/index.ts",
	"compatibility_date": "2025-02-04",
	"observability": {
		"enabled": true
	},

	"kv_namespaces": [
		{
			"binding": "KV_BINDING",
			"id": "<YOUR_BINDING_ID>"
		}
	]
}
```

    </TabItem>
    </Tabs>

See the full [Workers KV binding API reference](/kv/api/read-key-value-pairs/).

</TabItem>
<TabItem label="REST API">

    <Tabs>
    	<TabItem label="cURL">
    	```
    	curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/storage/kv/namespaces/$NAMESPACE_ID/values/$KEY_NAME \
    			-X PUT \
    			-H 'Content-Type: multipart/form-data' \
    			-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    			-H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    			-d '{
    				"value": "Some Value"
    			}'

    	curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/storage/kv/namespaces/$NAMESPACE_ID/values/$KEY_NAME \
    			-H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    			-H "X-Auth-Key: $CLOUDFLARE_API_KEY"
    	```
    	</TabItem>
    	<TabItem label="TypeScript">
    		```ts
    		const client = new Cloudflare({
    			apiEmail: process.env['CLOUDFLARE_EMAIL'], // This is the default and can be omitted
    			apiKey: process.env['CLOUDFLARE_API_KEY'], // This is the default and can be omitted
    		});

    		const value = await client.kv.namespaces.values.update('<KV_NAMESPACE_ID>', 'KEY', {
    			account_id: '<ACCOUNT_ID>',
    			value: 'VALUE',
    		});

    		const value = await client.kv.namespaces.values.get('<KV_NAMESPACE_ID>', 'KEY', {
    			account_id: '<ACCOUNT_ID>',
    		});

    		const value = await client.kv.namespaces.values.delete('<KV_NAMESPACE_ID>', 'KEY', {
    			account_id: '<ACCOUNT_ID>',
    		});

    		// Automatically fetches more pages as needed.
    		for await (const namespace of client.kv.namespaces.list({ account_id: '<ACCOUNT_ID>' })) {
    			console.log(namespace.id);
    		}

    		```
    	</TabItem>
    </Tabs>

See the full Workers KV [REST API and SDK reference](/api/resources/kv/) for details on using REST API from external applications, with pre-generated SDK's for external TypeScript, Python, or Go applications.

</TabItem>
</Tabs>

<LinkButton href="/kv/get-started/">Get started</LinkButton>

---

## Features

<Feature header="Key-value storage" href="/kv/get-started/">
	Learn how Workers KV stores and retrieves data.
</Feature>

<Feature header="Wrangler" href="/workers/wrangler/install-and-update/">

The Workers command-line interface, Wrangler, allows you to [create](/workers/wrangler/commands/#init), [test](/workers/wrangler/commands/#dev), and [deploy](/workers/wrangler/commands/#publish) your Workers projects.

</Feature>

<Feature header="Bindings" href="/kv/concepts/kv-bindings/">

Bindings allow your Workers to interact with resources on the Cloudflare developer platform, including [R2](/r2/), [Durable Objects](/durable-objects/), and [D1](/d1/).

</Feature>

---

## Related products

<RelatedProduct header="R2" href="/r2/" product="r2">

Cloudflare R2 Storage allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.

</RelatedProduct>

<RelatedProduct header="Durable Objects" href="/durable-objects/" product="durable-objects">

Cloudflare Durable Objects allows developers to access scalable compute and permanent, consistent storage.

</RelatedProduct>

<RelatedProduct header="D1" href="/d1/" product="d1">

Built on SQLite, D1 is Cloudflare’s first queryable relational database. Create an entire database by importing data or defining your tables and writing your queries within a Worker or through the API.

</RelatedProduct>

---

### More resources

<CardGrid>

<LinkTitleCard title="Limits" href="/kv/platform/limits/" icon="document">
	&#x20;Learn about KV limits.
</LinkTitleCard>

<LinkTitleCard title="Pricing" href="/kv/platform/pricing/" icon="seti:shell">
	&#x20;Learn about KV pricing.
</LinkTitleCard>

<LinkTitleCard
	title="Discord"
	href="https://discord.com/channels/595317990191398933/893253103695065128"
	icon="discord"
>
	&#x20;Ask questions, show off what you are building, and discuss the platform
	with other developers.
</LinkTitleCard>

<LinkTitleCard title="Twitter" href="https://x.com/cloudflaredev" icon="x.com">
	&#x20;Learn about product announcements, new tutorials, and what is new in
	Cloudflare Developer Platform.
</LinkTitleCard>

</CardGrid>

---

# Demos and architectures

URL: https://developers.cloudflare.com/pages/demos/

import {
	ExternalResources,
	GlossaryTooltip,
	ResourcesBySelector,
} from "~/components";

Learn how you can use Pages within your existing application and architecture.

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Pages.

<ExternalResources type="apps" products={["Pages"]} />

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use Pages:

<ResourcesBySelector
	types={[
		"reference-architecture",
		"design-guide",
		"reference-architecture-diagram",
	]}
	products={["Pages"]}
/>

---

# Cloudflare Pages

URL: https://developers.cloudflare.com/pages/

import {
	CardGrid,
	Description,
	Feature,
	LinkTitleCard,
	Plan,
	RelatedProduct,
	Render,
	Aside,
} from "~/components";

<Description>

Create full-stack applications that are instantly deployed to the Cloudflare global network.

</Description>

<Plan type="all" />

Deploy your Pages project by connecting to [your Git provider](/pages/get-started/git-integration/), uploading prebuilt assets directly to Pages with [Direct Upload](/pages/get-started/direct-upload/) or using [C3](/pages/get-started/c3/) from the command line.

---

## Features

<Feature header="Pages Functions" href="/pages/functions/">

Use Pages Functions to deploy server-side code to enable dynamic functionality without running a dedicated server.

</Feature>

<Feature header="Rollbacks" href="/pages/configuration/rollbacks/">

Rollbacks allow you to instantly revert your project to a previous production deployment.

</Feature>

<Feature header="Redirects" href="/pages/configuration/redirects/">

Set up redirects for your Cloudflare Pages project.

</Feature>

---

## Related products

<RelatedProduct header="Workers" href="/workers/" product="workers">

Cloudflare Workers provides a serverless execution environment that allows you to create new applications or augment existing ones without configuring or maintaining infrastructure.

</RelatedProduct>

<RelatedProduct header="R2" href="/r2/" product="r2">

Cloudflare R2 Storage allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.

</RelatedProduct>

<RelatedProduct header="D1" href="/d1/" product="d1">

D1 is Cloudflare’s native serverless database. Create a database by importing data or defining your tables and writing your queries within a Worker or through the API.

</RelatedProduct>

<RelatedProduct header="Zaraz" href="/zaraz/" product="zaraz">

Offload third-party tools and services to the cloud and improve the speed and security of your website.

</RelatedProduct>

---

## More resources

<CardGrid>

<LinkTitleCard title="Limits" href="/pages/platform/limits/" icon="document">
	Learn about limits that apply to your Pages project (500 deploys per month on
	the Free plan).
</LinkTitleCard>

<LinkTitleCard
	title="Framework guides"
	href="/pages/framework-guides/"
	icon="open-book"
>
	Deploy popular frameworks such as React, Hugo, and Next.js on Pages.
</LinkTitleCard>

<LinkTitleCard
	title="Developer Discord"
	href="https://discord.cloudflare.com"
	icon="discord"
>
	Connect with the Workers community on Discord to ask questions, show what you
	are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard
	title="@CloudflareDev"
	href="https://x.com/cloudflaredev"
	icon="x.com"
>
	Follow @CloudflareDev on Twitter to learn about product announcements, and
	what is new in Cloudflare Workers.
</LinkTitleCard>

</CardGrid>

---

# Getting started

URL: https://developers.cloudflare.com/pipelines/getting-started/

import { Render, PackageManagers, Details } from "~/components";

Cloudflare Pipelines allows you to ingest load high volumes of real time streaming data, and load into [R2 Object Storage](/r2/), without managing any infrastructure.

By following this guide, you will:
1. Setup an R2 bucket.
2. Create a pipeline, with HTTP as a source, and an R2 bucket as a sink.
3. Send data to your pipeline's HTTP ingestion endpoint.
4. Verify the output delivered to R2.

:::note

Pipelines is in **public beta**, and any developer with a [paid Workers plan](/workers/platform/pricing/#workers) can start using Pipelines immediately.

:::

***

## Prerequisites

To use Pipelines, you will need:

<Render file="prereqs" product="workers" />

## 1. Set up an R2 bucket

Create a bucket by following the [get started guide for R2](/r2/get-started/), or by running the command below:

```sh
npx wrangler r2 bucket create my-bucket
```

Save the bucket name for the next step.

## 2. Create a Pipeline

To create a pipeline using Wrangler, run the following command in a terminal, and specify:

- The name of your pipeline
- The name of the R2 bucket you created in step 1

```sh
npx wrangler pipelines create my-clickstream-pipeline --r2-bucket my-bucket --batch-max-seconds 5 --compression none
```

After running this command, you will be prompted to authorize Cloudflare Workers Pipelines to create an R2 API token on your behalf. These tokens used by your pipeline when loading data into your bucket. You can approve the request through the browser link which will open automatically.

<details>
	<summary> Choosing a pipeline name </summary>
When choosing a name for your pipeline:

- Ensure it is descriptive and relevant to the type of events you intend to ingest. You cannot change the name of the pipeline after creating it.
- The pipeline name must be between 1 and 63 characters long.
- The name cannot contain special characters outside dashes (`-`).
- The name must start and end with a letter or a number.
</details>

You will notice two optional flags are set while creating the pipeline: `--batch-max-seconds` and `--compression`. These flags are added to make it faster for you to see the output of your first pipeline. For production use cases, we recommend keeping the default settings.

Once you create your pipeline, you will receive a summary of your pipeline's configuration, as well as an HTTP endpoint which you can post data to:

```sh
🌀 Authorizing R2 bucket "my-bucket"
🌀 Creating pipeline named "my-clickstream-pipeline"
✅ Successfully created pipeline my-clickstream-pipeline

Id:    [PIPELINE-ID]
Name:  my-clickstream-pipeline
Sources:
  HTTP:
    Endpoint:        https://[PIPELINE-ID].pipelines.cloudflare.com/
    Authentication:  off
    Format:          JSON
  Worker:
    Format:  JSON
Destination:
  Type:         R2
  Bucket:       my-bucket
  Format:       newline-delimited JSON
  Compression:  GZIP
Batch hints:
  Max bytes:     100 MB
  Max duration:  300 seconds
  Max records:   100,000

🎉 You can now send data to your Pipeline!

Send data to your Pipeline's HTTP endpoint:
curl "https://[PIPELINE-ID].pipelines.cloudflare.com/" -d '[{ ...JSON_DATA... }]'

To send data to your Pipeline from a Worker, add the following configuration to your config file:
{
  "pipelines": [
    {
      "pipeline": "my-clickstream-pipeline",
      "binding": "PIPELINE"
    }
  ]
}
```

## 3. Post data to your pipeline

Use a curl command in your terminal to post an array of JSON objects to the endpoint you received in step 1.

```sh
curl -H "Content-Type:application/json" \
    -d '[{"event":"viewedCart", "timestamp": "2025-04-03T15:42:30Z"},{"event":"cartAbandoned", "timestamp": "2025-04-03T15:42:37Z"}]' \
    <HTTP-ENDPOINT>
```

Once the pipeline successfully accepts the data, you will receive a success message.

You can continue posting data to the pipeline. The pipeline will automatically buffer ingested data. Based on the batch settings (`--batch-max-seconds`) specified in step 2, a batch will be generated every 5 seconds, turned into a file, and written out to your R2 bucket.

## 4. Verify in R2

Open the [R2 dashboard](https://dash.cloudflare.com/?to=/:account/r2/overview), and navigate to the R2 bucket you created in step 1. You will see a directory, labeled with today's date (such as `event_date=2025-04-05`). Click on the directory, and you'll see a sub-directory with the current hour (such as `hr=04`). You should see a newline delimited JSON file, containing the data you posted in step 3. Download the file, and open it in a text editor of your choice, to verify that the data posted in step 2 is present.

***

## Next steps

* Learn about how to [setup authentication, or CORS settings](/pipelines/build-with-pipelines/sources/http), on your HTTP endpoint.
* Send data to your Pipeline from a Cloudflare Worker using the [Workers API documentation](/pipelines/build-with-pipelines/sources/workers-apis).

If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the [Cloudflare Developers community on Discord](https://discord.cloudflare.com).

---

# Overview

URL: https://developers.cloudflare.com/pipelines/

import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct } from "~/components";

<Description>

Ingest real time data streams and load into R2, using Cloudflare Pipelines.

</Description>

<Plan type="paid" />

Cloudflare Pipelines lets you ingest high volumes of real time data, without managing any infrastructure. Ingested data is automatically batched, written to output files, and delivered to an [R2 bucket](/r2/) in your account. You can use Pipelines to build a data lake of clickstream data, or to store events from a Worker.

## Create your first pipeline
You can setup a pipeline to ingest data via HTTP, and deliver output to R2, with a single command:

```sh
$ npx wrangler@latest pipelines create my-clickstream-pipeline --r2-bucket my-bucket

🌀 Authorizing R2 bucket "my-bucket"
🌀 Creating pipeline named "my-clickstream-pipeline"
✅ Successfully created pipeline my-clickstream-pipeline

Id:    0e00c5ff09b34d018152af98d06f5a1xvc
Name:  my-clickstream-pipeline
Sources:
  HTTP:
    Endpoint:        https://0e00c5ff09b34d018152af98d06f5a1xvc.pipelines.cloudflare.com/
    Authentication:  off
    Format:          JSON
  Worker:
    Format:  JSON
Destination:
  Type:         R2
  Bucket:       my-bucket
  Format:       newline-delimited JSON
  Compression:  GZIP
Batch hints:
  Max bytes:     100 MB
  Max duration:  300 seconds
  Max records:   100,000

🎉 You can now send data to your pipeline!

Send data to your pipeline's HTTP endpoint:
curl "https://0e00c5ff09b34d018152af98d06f5a1xvc.pipelines.cloudflare.com/" -d '[{ ...JSON_DATA... }]'

To send data to your pipeline from a Worker, add the following configuration to your config file:
{
  "pipelines": [
    {
      "pipeline": "my-clickstream-pipeline",
      "binding": "PIPELINE"
    }
  ]
}
```

Refer to the [getting started guide](/pipelines/getting-started) to start building with pipelines.

:::note
While in beta, you will not be billed for Pipelines usage. You will be billed only for [R2 usage](/r2/pricing/).
:::

***
## Features

<Feature header="HTTP as a source" href="/pipelines/build-with-pipelines/sources/http">
Each pipeline generates a globally scalable HTTP endpoint, which supports authentication and CORS settings.
</Feature>

<Feature header="Workers API" href="/pipelines/build-with-pipelines/sources/workers-apis/">
Send data to a pipeline directly from a Cloudflare Worker.
</Feature>

<Feature header="Customize output settings" href="/pipelines/build-with-pipelines/output-settings">
Define batch sizes and enable compression to generate output files that are efficient to query.
</Feature>

***

## Related products

<RelatedProduct header="R2" href="/r2/" product="r2">

Cloudflare R2 Object Storage allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.

</RelatedProduct>

<RelatedProduct header="Workers" href="/workers/" product="workers">

Cloudflare Workers allows developers to build serverless applications and deploy instantly across the globe for exceptional performance, reliability, and scale.

</RelatedProduct>

***

## More resources

<CardGrid>

<LinkTitleCard title="Limits" href="/pipelines/platform/limits/" icon="document">
Learn about pipelines limits.
</LinkTitleCard>

<LinkTitleCard title="@CloudflareDev" href="https://x.com/cloudflaredev" icon="x.com">
Follow @CloudflareDev on Twitter to learn about product announcements, and what is new in Cloudflare Workers.
</LinkTitleCard>

<LinkTitleCard title="Developer Discord" href="https://discord.cloudflare.com" icon="discord">
Connect with the Workers community on Discord to ask questions, show what you are building, and discuss the platform with other developers.
</LinkTitleCard>

</CardGrid>

---

# Get started

URL: https://developers.cloudflare.com/privacy-gateway/get-started/

Privacy Gateway implementation consists of three main parts:

1. Application Gateway Server/backend configuration (operated by you).
2. Client configuration (operated by you).
3. Connection to a Privacy Gateway Relay Server (operated by Cloudflare).

***

## Before you begin

Privacy Gateway is currently in closed beta. If you are interested, [contact us](https://www.cloudflare.com/lp/privacy-edge/).

***

## Step 1 - Configure your server

As a customer of the Privacy Gateway, you also need to add server support for OHTTP by implementing an application gateway server. The application gateway is responsible for decrypting incoming requests, forwarding the inner requests to their destination, and encrypting the corresponding response back to the client.

The [server implementation](#resources) will handle incoming requests and produce responses, and it will also advertise its public key configuration for clients to access. The public key configuration is generated securely and made available via an API. Refer to the [README](https://github.com/cloudflare/privacy-gateway-server-go#readme) for details about configuration.

Applications can also implement this functionality themselves. Details about [public key configuration](https://datatracker.ietf.org/doc/html/draft-ietf-ohai-ohttp-05#section-3), HTTP message [encryption and decryption](https://datatracker.ietf.org/doc/html/draft-ietf-ohai-ohttp-05#section-4), and [server-specific details](https://datatracker.ietf.org/doc/html/draft-ietf-ohai-ohttp-05#section-5) can be found in the OHTTP specification.

### Resources

Use the following resources for help with server configuration:

* **Go**:
  * [Sample gateway server](https://github.com/cloudflare/privacy-gateway-server-go)
  * [Gateway library](https://github.com/chris-wood/ohttp-go)
* **Rust**: [Gateway library](https://github.com/martinthomson/ohttp/tree/main/ohttp-server)
* **JavaScript / TypeScript**: [Gateway library](https://github.com/chris-wood/ohttp-js)

***

## Step 2 - Configure your client

As a customer of the Privacy Gateway, you need to set up client-side support for the gateway. Clients are responsible for encrypting requests, sending them to the Cloudflare Privacy Gateway, and then decrypting the corresponding responses.

Additionally, app developers need to [configure the client](#resources-1) to fetch or otherwise discover the gateway’s public key configuration. How this is done depends on how the gateway makes its public key configuration available. If you need help with this configuration, [contact us](https://www.cloudflare.com/lp/privacy-edge/).

### Resources

Use the following resources for help with client configuration:

* **Objective C**: [Sample application](https://github.com/cloudflare/privacy-gateway-client-demo)
* **Rust**: [Client library](https://github.com/martinthomson/ohttp/tree/main/ohttp-client)
* **JavaScript / TypeScript**: [Client library](https://github.com/chris-wood/ohttp-js)

***

## Step 3 - Review your application

After you have configured your client and server, review your application to make sure you are only sending intended data to Cloudflare and the application backend. In particular, application data should not contain anything unique to an end-user, as this would invalidate the benefits that OHTTP provides.

* Applications should scrub identifying user data from requests forwarded through the Privacy Gateway. This includes, for example, names, email addresses, phone numbers, etc.
* Applications should encourage users to disable crash reporting when using Privacy Gateway. Crash reports can contain sensitive user information and data, including email addresses.
* Where possible, application data should be encrypted on the client device with a key known only to the client. For example, iOS generally has good support for [client-side encryption (and key synchronization via the KeyChain)](https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys). Android likely has similar features available.

***

## Step 4 - Relay requests through Cloudflare

Before sending any requests, you need to first set up your account with Cloudflare. That requires [contacting us](https://www.cloudflare.com/lp/privacy-edge/) and providing the URL of your application gateway server.

Then, make sure you are forwarding requests to a mutually agreed URL with the following conventions.

```txt
https://<APPLICATION_NAME>.privacy-gateway.cloudflare.com/
```

---

# FAQs

URL: https://developers.cloudflare.com/pub-sub/faq/

## What messaging systems are similar?

Messaging systems that also implement or strongly align to the "publish-subscribe" model include AWS SNS (Simple Notification Service), Google Cloud Pub/Sub, Redis' PUBLISH-SUBSCRIBE features, and RabbitMQ. If you have used one of these systems before, you will notice that Pub/Sub shares similar foundations (topics, subscriptions, fan-in/fan-out models) and is easy to migrate to.

## How is Pub/Sub priced?

Cloudflare is still exploring pricing models for Pub/Sub and will share more with developers prior to GA. Users will be given prior notice and will require beta users to explicitly opt-in.

## Does Pub/Sub show data in the Cloudflare dashboard?

Pub/Sub today does not support the Cloudflare dashboard. You can set up Pub/Sub through Wrangler by following [these steps](/pub-sub/guide/).

## Where can I speak with other like-minded developers about Pub/Sub?

Try the #pubsub-beta channel on the [Cloudflare Developers Discord](https://discord.com/invite/cloudflaredev).

## What limits does Pub/Sub have?

Refer to [Limits](/pub-sub/platform/limits) for more details on client, broker, and topic-based limits.

---

# Cloudflare Privacy Gateway

URL: https://developers.cloudflare.com/privacy-gateway/

import { Description, Feature, Plan } from "~/components"

<Description>

Implements the Oblivious HTTP IETF standard to improve client privacy.
</Description>

<Plan type="enterprise" />

[Privacy Gateway](https://blog.cloudflare.com/building-privacy-into-internet-standards-and-how-to-make-your-app-more-private-today/) is a managed service deployed on Cloudflare’s global network that implements part of the [Oblivious HTTP (OHTTP) IETF](https://www.ietf.org/archive/id/draft-thomson-http-oblivious-01.html) standard. The goal of Privacy Gateway and Oblivious HTTP is to hide the client's IP address when interacting with an application backend.

OHTTP introduces a trusted third party between client and server, called a relay, whose purpose is to forward encrypted requests and responses between client and server. These messages are encrypted between client and server such that the relay learns nothing of the application data, beyond the length of the encrypted message and the server the client is interacting with.

***

## Availability

Privacy Gateway is currently in closed beta – available to select privacy-oriented companies and partners. If you are interested, [contact us](https://www.cloudflare.com/lp/privacy-edge/).

***

## Features

<Feature header="Get started" href="/privacy-gateway/get-started/" cta="Get started">
Learn how to set up Privacy Gateway for your application.
</Feature>

<Feature header="Legal" href="/privacy-gateway/reference/legal/" cta="Learn more">
Learn about the different parties and data shared in Privacy Gateway.
</Feature>

<Feature header="Metrics" href="/privacy-gateway/reference/metrics/" cta="Learn more">
Learn about how to query Privacy Gateway metrics.
</Feature>

---

# Pub/Sub

URL: https://developers.cloudflare.com/pub-sub/

:::note

Pub/Sub is currently in private beta. Browse the documentation to understand how Pub/Sub works and integrates with our broader Developer Platform, and [sign up for the waitlist](https://www.cloudflare.com/cloudflare-pub-sub-lightweight-messaging-private-beta/) to get access in the near future.

:::

Pub/Sub is Cloudflare's distributed MQTT messaging service. MQTT is one of the most popular messaging protocols used for consuming sensor data from thousands (or tens of thousands) of remote, distributed Internet of Things clients; publishing configuration data or remote commands to fleets of devices in the field; and even for building notification or messaging systems for online games and mobile apps.

Pub/Sub is ideal for cases where you have many (from a handful to tens of thousands of) clients sending small, sub-1MB messages — such as event, telemetry or transaction data — into a centralized system for aggregation, or where you need to push configuration updates or remote commands to remote clients at scale.

Pub/Sub:

* Scales automatically. You do not have to provision "vCPUs" or "memory", or set autoscaling parameters to handle spikes in message rates.
* Is global. Cloudflare's Pub/Sub infrastructure runs in [hundreds of cities worldwide](https://www.cloudflare.com/network/). Every edge location is part of one, globally distributed Pub/Sub system.
* Is secure by default. Clients must authenticate and connect over TLS, and clients are issued credentials that are scoped to a specific broker.
* Allows you to create multiple brokers to isolate clients or use cases, for example, staging vs. production or customers A vs. B vs. C — as needed. Each broker is addressable by a unique DNS hostname.
* Integrates with Cloudflare Workers to enable programmable messaging capabilities: parse, filter, aggregate, and re-publish MQTT messages directly from your serverless code.
* Supports MQTT v5.0, the most recent version of the MQTT specification, and one of the most ubiquitous messaging protocols in use today.

If you are new to the MQTT protocol, visit the [How Pub/Sub works](/pub-sub/learning/how-pubsub-works/) to better understand how MQTT differs from other messaging protocols.

---

# Get started

URL: https://developers.cloudflare.com/pub-sub/guide/

import { Render, PackageManagers } from "~/components";

:::note

Pub/Sub is currently in private beta. You can [sign up for the waitlist](https://www.cloudflare.com/cloudflare-pub-sub-lightweight-messaging-private-beta/) to register your interest.

:::

Pub/Sub is a flexible, scalable messaging service built on top of the MQTT messaging standard, allowing you to publish messages from tens of thousands of devices (or more), deploy code to filter, aggregate and transform messages using Cloudflare Workers, and/or subscribe to topics for fan-out messaging use cases.

This guide will:

- Instruct you through creating your first Pub/Sub Broker using the Cloudflare API.
- Create a `<broker>.<namespace>.cloudflarepubsub.com` endpoint ready to publish and subscribe to using any MQTT v5.0 compatible client.
- Help you send your first message to the Pub/Sub Broker.

Before you begin, you should be familiar with using the command line and running basic terminal commands.

## Prerequisite: Create a Cloudflare account

In order to use Pub/Sub, you need a [Cloudflare account](/fundamentals/account/). If you already have an account, you can skip this step.

## 1. Enable Pub/Sub

During the Private Beta, your account will need to be explicitly granted access. If you have not, sign up for the waitlist, and we will contact you when you are granted access.

## 2. Install Wrangler (Cloudflare CLI)

:::note

Pub/Sub support in Wrangler requires wrangler `2.0.16` or above. If you're using an older version of Wrangler, ensure you [update the installed version](/workers/wrangler/install-and-update/#update-wrangler).

:::

Installing `wrangler`, the Workers command-line interface (CLI), allows you to [`init`](/workers/wrangler/commands/#init), [`dev`](/workers/wrangler/commands/#dev), and [`publish`](/workers/wrangler/commands/#publish) your Workers projects.

To install [`wrangler`](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler), ensure you have [`npm` installed](https://docs.npmjs.com/getting-started), preferably using a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm). Using a version manager helps avoid permission issues and allows you to easily change Node.js versions. Then run:

<PackageManagers pkg="wrangler@latest" dev />

Validate that you have a version of `wrangler` that supports Pub/Sub:

```sh
wrangler --version
```

```sh output
2.0.16 # should show 2.0.16 or greater - e.g. 2.0.17 or 2.1.0
```

With `wrangler` installed, we can now create a Pub/Sub API token for `wrangler` to use.

## 3. Fetch your credentials

To use Wrangler with Pub/Sub, you'll need an API Token that has permissions to both read and write for Pub/Sub. The `wrangler login` flow does not issue you an API Token with valid Pub/Sub permissions.

:::note

This API token requirement will be lifted prior to Pub/Sub becoming Generally Available.

:::

1. From the [Cloudflare dashboard](https://dash.cloudflare.com), click on the profile icon and select **My Profile**.
2. Under **My Profile**, click **API Tokens**.
3. On the [**API Tokens**](https://dash.cloudflare.com/profile/api-tokens) page, click **Create Token**
4. Choose **Get Started** next to **Create Custom Token**
5. Name the token - e.g. "Pub/Sub Write Access"
6. Under the **Permissions** heading, choose **Account**, select **Pub/Sub** from the first drop-down, and **Edit** as the permission.
7. Select **Add More** below the newly created permission. Choose **User** > **Memberships** from the first dropdown and **Read** as the permission.
8. Select **Continue to Summary** at the bottom of the page, where you should see _All accounts - Pub/Sub:Edit_ as the permission.
9. Select **Create Token** and copy the token value.

In your terminal, configure a `CLOUDFLARE_API_TOKEN` environmental variable with your Pub/Sub token. When this variable is set, `wrangler` will use it to authenticate against the Cloudflare API.

```sh
export CLOUDFLARE_API_TOKEN="pasteyourtokenhere"
```

:::caution[Warning]

This token should be kept secret and not committed to source code or placed in any client-side code.

:::

With this environmental variable configured, you can now create your first Pub/Sub Broker!

## 4. Create your first namespace

A namespace represents a collection of Pub/Sub Brokers, and they can be used to separate different environments (production vs. staging), infrastructure teams, and in the future, permissions.

Before you begin, consider the following:

- **Choose your namespace carefully**. Although it can be changed later, it will be used as part of the hostname for your Brokers. You should not use secrets or other data that cannot be exposed on the Internet.
- Namespace names are global; they are globally unique.
- Namespaces must be valid DNS names per RFC 1035. In most cases, this means only a-z, 0-9, and hyphens are allowed. Names are case-insensitive.

For example, a namespace of `my-namespace` and a broker of `staging` would create a hostname of `staging.my-namespace.cloudflarepubsub.com` for clients to connect to.

With this in mind, create a new namespace. This example will use `my-namespace` as a placeholder:

```sh
wrangler pubsub namespace create my-namespace
```

```json output
{
	"id": "817170399d784d4ea8b6b90ae558c611",
	"name": "my-namespace",
	"description": "",
	"created_on": "2022-05-11T23:13:08.383232Z",
	"modified_on": "2022-05-11T23:13:08.383232Z"
}
```

If you receive an HTTP 403 (Forbidden) response, check that your credentials are correct and that you have not pasted erroneous spaces or characters.

## 5. Create a broker

A broker, in MQTT terms, is a collection of connected clients that publish messages to topics, and clients that subscribe to those topics and receive messages. The broker acts as a relay, and with Cloudflare Pub/Sub, a Cloudflare Worker can be configured to act on every message published to it.

This broker will be configured to accept `TOKEN` authentication. In MQTT terms, this is typically defined as username:password authentication. Pub/Sub uses JSON Web Tokens (JWT) that are unique to each client, and that can be revoked, to make authentication more secure.

Broker names must be:

- Chosen carefully. Although it can be changed later, the name will be used as part of the hostname for your brokers. Do not use secrets or other data that cannot be exposed on the Internet.
- Valid DNS names (per RFC 1035). In most cases, this means only `a-z`, `0-9` and hyphens are allowed. Names are case-insensitive.
- Unique per namespace.

To create a new MQTT Broker called `example-broker` in the `my-namespace` namespace from the example above:

```sh
wrangler pubsub broker create example-broker --namespace=my-namespace
```

```json output
{
	"id": "4c63fa30ee13414ba95be5b56d896fea",
	"name": "example-broker",
	"authType": "TOKEN",
	"created_on": "2022-05-11T23:19:24.356324Z",
	"modified_on": "2022-05-11T23:19:24.356324Z",
	"expiration": null,
	"endpoint": "mqtts://example-broker.namespace.cloudflarepubsub.com:8883"
}
```

In the example above, a broker is created with an endpoint of `mqtts://example-broker.my-namespace.cloudflarepubsub.com`. This means:

- Our Pub/Sub (MQTT) Broker is reachable over MQTTS (MQTT over TLS) - port 8883
- The hostname is `example-broker.my-namespace.cloudflarepubsub.com`
- [Token authentication](/pub-sub/platform/authentication-authorization/) is required to clients to connect.

## 6. Create credentials for your broker

In order to connect to a Pub/Sub Broker, you need to securely authenticate. Credentials are scoped to each broker and credentials issued for `broker-a` cannot be used to connect to `broker-b`.

Note that:

- You can generate multiple credentials at once (up to 100 per API call), which can be useful when configuring multiple clients (such as IoT devices).
- Credentials are associated with a specific Client ID and encoded as a signed JSON Web Token (JWT).
- Each token has a unique identifier (a `jti` - or `JWT ID`) that you can use to revoke a specific token.
- Tokens are prefixed with the broker name they are associate with (for example, `my-broker`) to make identifying tokens across multiple Pub/Sub brokers easier.

:::note

Ensure you do not commit your credentials to source control, such as GitHub. A valid token allows anyone to connect to your broker and publish or subscribe to messages. Treat credentials as secrets.

:::

To generate two tokens for a broker called `example-broker` with a 48 hour expiry:

```sh
wrangler pubsub broker issue example-broker --namespace=NAMESPACE_NAME --number=2 --expiration=48h
```

You should receive a success response that resembles the example below, which is a map of Client IDs and their associated tokens.

```json
{
  "01G3A5GBJE5P3GPXJZ72X4X8SA": "eyJhbGciOiJFZERTQSIsImtpZCI6IkpEUHVZSnFIT3Zxemxha2tORlE5a2ZON1dzWXM1dUhuZHBfemlSZG1PQ1UifQ.
  not-a-real-token.ZZL7PNittVwJOeMpFMn2CnVTgIz4AcaWXP9NqMQK0D_iavcRv_p2DVshg6FPe5xCdlhIzbatT6gMyjMrOA2wBg",
  "01G3A5GBJECX5DX47P9RV1C5TV": "eyJhbGciOiJFZERTQSIsImtpZCI6IkpEUHVZSnFIT3Zxemxha2tORlE5a2ZON1dzWXM1dUhuZHBfemlSZG1PQ1UifQ.also-not-a-real-token.WrhK-VTs_IzOEALB-T958OojHK5AjYBC5ZT9xiI_6ekdQrKz2kSPGnvZdUXUsTVFDf9Kce1Smh-mw1sF2rSQAQ",
}
```

Each token allows you to publish or subscribe to the associated broker.

## 7. Subscribe and publish messages to a topic

Your broker is now created and ready to accept messages from authenticated clients. Because Pub/Sub is based on the MQTT protocol, there are client libraries for most popular programming languages. Refer to the list of [recommended client libraries](/pub-sub/learning/client-libraries/).

:::note

You can view a live demo available at [demo.mqtt.dev](http://demo.mqtt.dev) that allows you to use your own Pub/Sub Broker and a valid token to subscribe to a topic and publish messages to it. The `JWT` field in the demo accepts a valid token from your Broker.
:::

The example below uses [MQTT.js](https://github.com/mqttjs/MQTT.js) with Node.js to subscribe to a topic on a broker and publish a very basic "hello world" style message. You will need to have a [supported Node.js](https://nodejs.org/en/download/current/) version installed.

```sh
# Check that Node.js is installed
which node
# Install MQTT.js
npm i mqtt --save
```

Set your environment variables.

```sh
export CLOUDFLARE_API_TOKEN="YourAPIToken"
export CLOUDFLARE_ACCOUNT_ID="YourAccountID"
export DEFAULT_NAMESPACE="TheNamespaceYouCreated"
export BROKER_NAME="TheBrokerYouCreated"
```

We can now generate an access token for Pub/Sub. We will need both the client ID and the token (a JSON Web Token) itself to authenticate from our MQTT client:

```sh
curl -s -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" -H "Content-Type: application/json" "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/pubsub/namespaces/namespace/brokers/is-it-broken/credentials?type=TOKEN&topicAcl=#" | jq '.result | to_entries | .[0]'
```

This will output a `key` representing the `clientId`, and a `value` representing our (secret) access token, resembling the following:

```json
{
	"key": "01HDQFD5Y8HWBFGFBBZPSWQ22M",
	"value": "eyJhbGciOiJFZERTQSIsImtpZCI6IjU1X29UODVqQndJbjlFYnY0V3dzanRucG9ycTBtalFlb1VvbFZRZDIxeEUifQ....NVpToBedVYGGhzHJZmpEG1aG_xPBWrE-PgG1AFYcTPEBpZ_wtN6ApeAUM0JIuJdVMkoIC9mUg4vPtXM8jLGgBw"
}
```

Copy the `value` field and set it as the `BROKER_TOKEN` environmental variable:

```sh
export BROKER_TOKEN="<VALUE>"
```

Create a file called `index.js `, making sure that:

- `brokerEndpoint` is set to the address of your Pub/Sub broker.
- `clientId` is the `key` from your newly created access token
- The `BROKER_TOKEN` environmental variable populated with your access token.

:::note

Your `BROKER_TOKEN` is sensitive, and should be kept secret to avoid unintended access to your Pub/Sub broker. Avoid committing it to source code.

:::

```js
const mqtt = require("mqtt");

const brokerEndpoint = "mqtts://my-broker.my-namespace.cloudflarepubsub.com";
const clientId = "01HDQFD5Y8HWBFGFBBZPSWQ22M"; // Replace this with your client ID

const options = {
	port: 8883,
	username: clientId, // MQTT.js requires this, but Pub/Sub does not
	clientId: clientId, // Required by Pub/Sub
	password: process.env.BROKER_TOKEN,
	protocolVersion: 5, // MQTT 5
};

const client = mqtt.connect(brokerEndpoint, options);

client.subscribe("example-topic");
client.publish(
	"example-topic",
	`message from ${client.options.clientId}: hello at ${Date.now()}`,
);
client.on("message", function (topic, message) {
	console.log(`received message on ${topic}: ${message}`);
});
```

Run the example. You should see the output written to your terminal (stdout).

```sh
node index.js
```

```sh output
> received message on example-topic: hello from 01HDQFD5Y8HWBFGFBBZPSWQ22M at 1652102228
```

Your client ID and timestamp will be different from above, but you should see a very similar message. You can also try subscribing to multiple topics and publishing to them by passing the same topic name to `client.publish`. Provided they have permission to, clients can publish to multiple topics at once or as needed.

If you do not see the message you published, or you are receiving error messages, ensure that:

- The `BROKER_TOKEN` environmental variable is not empty. Try echo `$BROKER_TOKEN` in your terminal.
- You updated the `brokerEndpoint` to match the broker you created. The **Endpoint** field of your broker will show this address and port.
- You correctly [installed MQTT.js](https://github.com/mqttjs/MQTT.js#install).

## Next Steps

What's next?

- [Connect a worker to your broker](/pub-sub/learning/integrate-workers/) to programmatically read, parse, and filter messages as they are published to a broker
- [Learn how PubSub and the MQTT protocol work](/pub-sub/learning/how-pubsub-works)
- [See example client code](/pub-sub/examples) for publishing or subscribing to a PubSub broker

---

# Demos and architectures

URL: https://developers.cloudflare.com/queues/demos/

import { ExternalResources, GlossaryTooltip, ResourcesBySelector } from "~/components"

Learn how you can use Queues within your existing application and architecture.

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Queues.

<ExternalResources type="apps" products={["Queues"]} />

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use Queues:

<ResourcesBySelector types={["reference-architecture","design-guide","reference-architecture-diagram"]} products={["Queues"]} />

---

# Getting started

URL: https://developers.cloudflare.com/queues/get-started/

import { Render, PackageManagers, WranglerConfig } from "~/components";

Cloudflare Queues is a flexible messaging queue that allows you to queue messages for asynchronous processing. By following this guide, you will create your first queue, a Worker to publish messages to that queue, and a consumer Worker to consume messages from that queue.

## Prerequisites

To use Queues, you will need:

<Render file="prereqs" product="workers" />

## 1. Create a Worker project

You will access your queue from a Worker, the producer Worker. You must create at least one producer Worker to publish messages onto your queue. If you are using [R2 Bucket Event Notifications](/r2/buckets/event-notifications/), then you do not need a producer Worker.

To create a producer Worker, run:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"producer-worker"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

This will create a new directory, which will include both a `src/index.ts` Worker script, and a [`wrangler.jsonc`](/workers/wrangler/configuration/) configuration file. After you create your Worker, you will create a Queue to access.

Move into the newly created directory:

```sh
cd producer-worker
```

## 2. Create a queue

To use queues, you need to create at least one queue to publish messages to and consume messages from.

To create a queue, run:

```sh
npx wrangler queues create <MY-QUEUE-NAME>
```

Choose a name that is descriptive and relates to the types of messages you intend to use this queue for. Descriptive queue names look like: `debug-logs`, `user-clickstream-data`, or `password-reset-prod`.

Queue names must be 1 to 63 characters long. Queue names cannot contain special characters outside dashes (`-`), and must start and end with a letter or number.

You cannot change your queue name after you have set it. After you create your queue, you will set up your producer Worker to access it.

## 3. Set up your producer Worker

To expose your queue to the code inside your Worker, you need to connect your queue to your Worker by creating a binding. [Bindings](/workers/runtime-apis/bindings/) allow your Worker to access resources, such as Queues, on the Cloudflare developer platform.

To create a binding, open your newly generated `wrangler.jsonc` file and add the following:

<WranglerConfig>

```toml
[[queues.producers]]
 queue = "MY-QUEUE-NAME"
 binding = "MY_QUEUE"
```

</WranglerConfig>

Replace `MY-QUEUE-NAME` with the name of the queue you created in [step 2](/queues/get-started/#2-create-a-queue). Next, replace `MY_QUEUE` with the name you want for your `binding`. The binding must be a valid JavaScript variable name. This is the variable you will use to reference this queue in your Worker.

### Write your producer Worker

You will now configure your producer Worker to create messages to publish to your queue. Your producer Worker will:

1. Take a request it receives from the browser.
2. Transform the request to JSON format.
3. Write the request directly to your queue.

In your Worker project directory, open the `src` folder and add the following to your `index.ts` file:

```ts null {8}
export default {
  async fetch(request, env, ctx): Promise<Response> {
    let log = {
      url: request.url,
      method: request.method,
      headers: Object.fromEntries(request.headers),
    };
    await env.<MY_QUEUE>.send(log);
    return new Response('Success!');
  },
} satisfies ExportedHandler<Env>;
```

Replace `MY_QUEUE` with the name you have set for your binding from your `wrangler.jsonc` file.

Also add the queue to `Env` interface in `index.ts`.

```ts null {2}
export interface Env {
   <MY_QUEUE>: Queue<any>;
}
```

If this write fails, your Worker will return an error (raise an exception). If this write works, it will return `Success` back with a HTTP `200` status code to the browser.

In a production application, you would likely use a [`try...catch`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) statement to catch the exception and handle it directly (for example, return a custom error or even retry).

### Publish your producer Worker

With your Wrangler file and `index.ts` file configured, you are ready to publish your producer Worker. To publish your producer Worker, run:

```sh
npx wrangler deploy
```

You should see output that resembles the below, with a `*.workers.dev` URL by default.

```
Uploaded <YOUR-WORKER-NAME> (0.76 sec)
Published <YOUR-WORKER-NAME> (0.29 sec)
  https://<YOUR-WORKER-NAME>.<YOUR-ACCOUNT>.workers.dev
```

Copy your `*.workers.dev` subdomain and paste it into a new browser tab. Refresh the page a few times to start publishing requests to your queue. Your browser should return the `Success` response after writing the request to the queue each time.

You have built a queue and a producer Worker to publish messages to the queue. You will now create a consumer Worker to consume the messages published to your queue. Without a consumer Worker, the messages will stay on the queue until they expire, which defaults to four (4) days.

## 4. Create your consumer Worker

A consumer Worker receives messages from your queue. When the consumer Worker receives your queue's messages, it can write them to another source, such as a logging console or storage objects.

In this guide, you will create a consumer Worker and use it to log and inspect the messages with [`wrangler tail`](/workers/wrangler/commands/#tail). You will create your consumer Worker in the same Worker project that you created your producer Worker.

:::note

Queues also supports [pull-based consumers](/queues/configuration/pull-consumers/), which allows any HTTP-based client to consume messages from a queue. This guide creates a push-based consumer using Cloudflare Workers.

:::

To create a consumer Worker, open your `index.ts` file and add the following `queue` handler to your existing `fetch` handler:

```ts null {11}
export default {
  async fetch(request, env, ctx): Promise<Response> {
    let log = {
      url: request.url,
      method: request.method,
      headers: Object.fromEntries(request.headers),
    };
    await env.<MY_QUEUE>.send(log);
    return new Response('Success!');
  },
  async queue(batch, env): Promise<void> {
    let messages = JSON.stringify(batch.messages);
    console.log(`consumed from our queue: ${messages}`);
  },
} satisfies ExportedHandler<Env>;
```

Replace `MY_QUEUE` with the name you have set for your binding from your `wrangler.jsonc` file.

Every time messages are published to the queue, your consumer Worker's `queue` handler (`async queue`) is called and it is passed one or more messages.

In this example, your consumer Worker transforms the queue's JSON formatted message into a string and logs that output. In a real world application, your consumer Worker can be configured to write messages to object storage (such as [R2](/r2/)), write to a database (like [D1](/d1/)), further process messages before calling an external API (such as an [email API](/workers/tutorials/)) or a data warehouse with your legacy cloud provider.

When performing asynchronous tasks from within your consumer handler, use `waitUntil()` to ensure the response of the function is handled. Other asynchronous methods are not supported within the scope of this method.

### Connect the consumer Worker to your queue

After you have configured your consumer Worker, you are ready to connect it to your queue.

Each queue can only have one consumer Worker connected to it. If you try to connect multiple consumers to the same queue, you will encounter an error when attempting to publish that Worker.

To connect your queue to your consumer Worker, open your Wrangler file and add this to the bottom:

<WranglerConfig>

```toml
[[queues.consumers]]
 queue = "<MY-QUEUE-NAME>"
 # Required: this should match the name of the queue you created in step 3.
 # If you misspell the name, you will receive an error when attempting to publish your Worker.
 max_batch_size = 10 # optional: defaults to 10
 max_batch_timeout = 5 # optional: defaults to 5 seconds
```

</WranglerConfig>

Replace `MY-QUEUE-NAME` with the queue you created in [step 2](/queues/get-started/#2-create-a-queue).

In your consumer Worker, you are using queues to auto batch messages using the `max_batch_size` option and the `max_batch_timeout` option. The consumer Worker will receive messages in batches of `10` or every `5` seconds, whichever happens first.

`max_batch_size` (defaults to 10) helps to reduce the amount of times your consumer Worker needs to be called. Instead of being called for every message, it will only be called after 10 messages have entered the queue.

`max_batch_timeout` (defaults to 5 seconds) helps to reduce wait time. If the producer Worker is not sending up to 10 messages to the queue for the consumer Worker to be called, the consumer Worker will be called every 5 seconds to receive messages that are waiting in the queue.

### Publish your consumer Worker

With your Wrangler file and `index.ts` file configured, publish your consumer Worker by running:

```sh
npx wrangler deploy
```

## 5. Read messages from your queue

After you set up consumer Worker, you can read messages from the queue.

Run `wrangler tail` to start waiting for our consumer to log the messages it receives:

```sh
npx wrangler tail
```

With `wrangler tail` running, open the Worker URL you opened in [step 3](/queues/get-started/#3-set-up-your-producer-worker).

You should receive a `Success` message in your browser window.

If you receive a `Success` message, refresh the URL a few times to generate messages and push them onto the queue.

With `wrangler tail` running, your consumer Worker will start logging the requests generated by refreshing.

If you refresh less than 10 times, it may take a few seconds for the messages to appear because batch timeout is configured for 10 seconds. After 10 seconds, messages should arrive in your terminal.

If you get errors when you refresh, check that the queue name you created in [step 2](/queues/get-started/#2-create-a-queue) and the queue you referenced in your Wrangler file is the same. You should ensure that your producer Worker is returning `Success` and is not returning an error.

By completing this guide, you have now created a queue, a producer Worker that publishes messages to that queue, and a consumer Worker that consumes those messages from it.

## Related resources

- Learn more about [Cloudflare Workers](/workers/) and the applications you can build on Cloudflare.

---

# Glossary

URL: https://developers.cloudflare.com/queues/glossary/

import { Glossary } from "~/components"

Review the definitions for terms used across Cloudflare's Queues documentation.

<Glossary product="queues" />

---

# Cloudflare Queues

URL: https://developers.cloudflare.com/queues/

import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct } from "~/components"

<Description>


Send and receive messages with guaranteed delivery and no charges for egress bandwidth.


</Description>

<Plan type="paid" />

Cloudflare Queues integrate with [Cloudflare Workers](/workers/) and enable you to build applications that can [guarantee delivery](/queues/reference/delivery-guarantees/), [offload work from a request](/queues/reference/how-queues-works/), [send data from Worker to Worker](/queues/configuration/configure-queues/), and [buffer or batch data](/queues/configuration/batching-retries/).

***

## Features

<Feature header="Batching, Retries and Delays" href="/queues/configuration/batching-retries/">

Cloudflare Queues allows you to batch, retry and delay messages.


</Feature>

<Feature header="Dead Letter Queues" href="/queues/configuration/dead-letter-queues/">

Redirect your messages when a delivery failure occurs.


</Feature>

<Feature header="Pull consumers" href="/queues/configuration/pull-consumers/">

Configure pull-based consumers to pull from a queue over HTTP from infrastructure outside of Cloudflare Workers.


</Feature>

***

## Related products

<RelatedProduct header="R2" href="/r2/" product="r2">

Cloudflare R2 Storage allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.


</RelatedProduct>

<RelatedProduct header="Workers" href="/workers/" product="workers">

Cloudflare Workers allows developers to build serverless applications and deploy instantly across the globe for exceptional performance, reliability, and scale.


</RelatedProduct>

***

## More resources

<CardGrid>

<LinkTitleCard title="Pricing" href="/queues/platform/pricing/" icon="seti:shell">
Learn about pricing.
</LinkTitleCard>

<LinkTitleCard title="Limits" href="/queues/platform/limits/" icon="document">
Learn about Queues limits.
</LinkTitleCard>

<LinkTitleCard title="Try the Demo" href="https://github.com/Electroid/queues-demo#cloudflare-queues-demo" icon="open-book">
Try Cloudflare Queues which can run on your local machine.
</LinkTitleCard>

<LinkTitleCard title="@CloudflareDev" href="https://x.com/cloudflaredev" icon="x.com">
Follow @CloudflareDev on Twitter to learn about product announcements, and what is new in Cloudflare Workers.
</LinkTitleCard>

<LinkTitleCard title="Developer Discord" href="https://discord.cloudflare.com" icon="discord">
Connect with the Workers community on Discord to ask questions, show what you are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard title="Configuration" href="/queues/configuration/configure-queues/" icon="open-book">
Learn how to configure Cloudflare Queues using Wrangler.
</LinkTitleCard>

<LinkTitleCard title="JavaScript APIs" href="/queues/configuration/javascript-apis/" icon="open-book">
Learn how to use JavaScript APIs to send and receive messages to a Cloudflare Queue.
</LinkTitleCard>

</CardGrid>

---

# Demos and architectures

URL: https://developers.cloudflare.com/r2/demos/

import {
	ExternalResources,
	GlossaryTooltip,
	ResourcesBySelector,
} from "~/components";

Learn how you can use R2 within your existing application and architecture.

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for R2.

<ExternalResources type="apps" products={["R2"]} />

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use R2:

<ResourcesBySelector
	types={[
		"reference-architecture",
		"design-guide",
		"reference-architecture-diagram",
	]}
	products={["R2"]}
/>

---

# Cloudflare R2

URL: https://developers.cloudflare.com/r2/

import {
	CardGrid,
	Description,
	Feature,
	LinkButton,
	LinkTitleCard,
	Plan,
	RelatedProduct,
} from "~/components";

<Description>

Object storage for all your data.

</Description>

Cloudflare R2 Storage allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.

You can use R2 for multiple scenarios, including but not limited to:

- Storage for cloud-native applications
- Cloud storage for web content
- Storage for podcast episodes
- Data lakes (analytics and big data)
- Cloud storage output for large batch processes, such as machine learning model artifacts or datasets

<LinkButton variant="primary" href="/r2/get-started/">
	Get started
</LinkButton>
<LinkButton variant="secondary" href="/r2/examples/">
	Browse the examples
</LinkButton>

---

## Features

<Feature header="Location Hints" href="/r2/reference/data-location/#location-hints">

Location Hints are optional parameters you can provide during bucket creation to indicate the primary geographical location you expect data will be accessed from.

</Feature>

<Feature header="CORS" href="/r2/buckets/cors/">

Configure CORS to interact with objects in your bucket and configure policies on your bucket.

</Feature>

<Feature header="Public buckets" href="/r2/buckets/public-buckets/">

Public buckets expose the contents of your R2 bucket directly to the Internet.

</Feature>

<Feature header="Bucket scoped tokens" href="/r2/api/tokens/">

Create bucket scoped tokens for granular control over who can access your data.

</Feature>

---

## Related products

<RelatedProduct header="Workers" href="/workers/" product="workers">

A [serverless](https://www.cloudflare.com/learning/serverless/what-is-serverless/) execution environment that allows you to create entirely new applications or augment existing ones without configuring or maintaining infrastructure.

</RelatedProduct>

<RelatedProduct header="Stream" href="/stream/" product="stream">

Upload, store, encode, and deliver live and on-demand video with one API, without configuring or maintaining infrastructure.

</RelatedProduct>

<RelatedProduct header="Images" href="/images/" product="images">

A suite of products tailored to your image-processing needs.

</RelatedProduct>

---

## More resources

<CardGrid>

<LinkTitleCard title="Pricing" href="/r2/pricing" icon="seti:shell">
	&#x20;Understand pricing for free and paid tier rates.
</LinkTitleCard>

<LinkTitleCard
	title="Discord"
	href="https://discord.cloudflare.com"
	icon="discord"
>
	&#x20;Ask questions, show off what you are building, and discuss the platform
	with other developers.
</LinkTitleCard>

<LinkTitleCard title="Twitter" href="https://x.com/cloudflaredev" icon="x.com">
	&#x20;Learn about product announcements, new tutorials, and what is new in
	Cloudflare Workers.
</LinkTitleCard>

</CardGrid>

---

# Getting started

URL: https://developers.cloudflare.com/r2/get-started/

import { Render, PackageManagers } from "~/components";

Cloudflare R2 Storage allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.

<div style="position: relative; padding-top: 56.25%;">
	<iframe
		src="https://customer-6qw1mjlclhl2mqdy.cloudflarestream.com/c247ba8eb4b61355184867bec9e5c532/iframe?poster=https%3A%2F%2Fcustomer-6qw1mjlclhl2mqdy.cloudflarestream.com%2Fc247ba8eb4b61355184867bec9e5c532%2Fthumbnails%2Fthumbnail.jpg%3Ftime%3D%26height%3D600"
		style="border: none; position: absolute; top: 0; left: 0; height: 100%; width: 100%;"
		allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
		allowfullscreen="true"
	></iframe>
</div>

## 1. Install and authenticate Wrangler

:::note
Before you create your first bucket, you must purchase R2 from the Cloudflare dashboard.
:::

1. [Install Wrangler](/workers/wrangler/install-and-update/) within your project using npm and Node.js or Yarn.

<PackageManagers pkg="wrangler@latest" dev />

2. [Authenticate Wrangler](/workers/wrangler/commands/#login) to enable deployments to Cloudflare. When Wrangler automatically opens your browser to display Cloudflare's consent screen, select **Allow** to send the API Token to Wrangler.

```txt
wrangler login
```

## 2. Create a bucket

To create a new R2 bucket from the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select **R2**.
2. Select **Create bucket**.
3. Enter a name for the bucket and select **Create bucket**.

## 3. Upload your first object

1. From the **R2** page in the dashboard, locate and select your bucket.
2. Select **Upload**.
3. Choose to either drag and drop your file into the upload area or **select from computer**.

You will receive a confirmation message after a successful upload.

## Bucket access options

Cloudflare provides multiple ways for developers to access their R2 buckets:

- [R2 Workers Binding API](/r2/api/workers/workers-api-usage/)
- [S3 API compatibility](/r2/api/s3/api/)
- [Public buckets](/r2/buckets/public-buckets/)

---

# Videos

URL: https://developers.cloudflare.com/r2/video-tutorials/

import { CardGrid, LinkCard } from "~/components";

<CardGrid>
    <LinkCard
        title="Introduction to R2"
        description="Learn about Cloudflare R2, an object storage solution designed to handle your data and files efficiently. It is ideal for storing large media files, creating data lakes, or delivering web assets."
        href="/learning-paths/r2-intro/series/r2-1/"
    />
</CardGrid>

---

# Pricing

URL: https://developers.cloudflare.com/r2/pricing/

import { InlineBadge } from "~/components";

R2 charges based on the total volume of data stored, along with two classes of operations on that data:

1. [Class A operations](#class-a-operations) which are more expensive and tend to mutate state.
2. [Class B operations](#class-b-operations) which tend to read existing state.

For the Infrequent Access storage class, [data retrieval](#data-retrieval) fees apply. There are no charges for egress bandwidth for any storage class.

All included usage is on a monthly basis.

:::note

To learn about potential cost savings from using R2, refer to the [R2 pricing calculator](https://r2-calculator.cloudflare.com/).

:::

## R2 pricing

|                                    | Standard storage         | Infrequent Access storage <InlineBadge preset="beta" /> |
| ---------------------------------- | ------------------------ | ------------------------------------------------------- |
| Storage                            | $0.015 / GB-month        | $0.01 / GB-month                                        |
| Class A Operations                 | $4.50 / million requests | $9.00 / million requests                                |
| Class B Operations                 | $0.36 / million requests | $0.90 / million requests                                |
| Data Retrieval (processing)        | None                     | $0.01 / GB                                              |
| Egress (data transfer to Internet) | Free [^1]                | Free [^1]                                               |

### Free tier

You can use the following amount of storage and operations each month for free. The free tier only applies to Standard storage.

|                                    | Free                        |
| ---------------------------------- | --------------------------- |
| Storage                            | 10 GB-month / month         |
| Class A Operations                 | 1 million requests / month  |
| Class B Operations                 | 10 million requests / month |
| Egress (data transfer to Internet) | Free [^1]                   |

### Storage usage

Storage is billed using gigabyte-month (GB-month) as the billing metric. A GB-month is calculated by averaging the _peak_ storage per day over a billing period (30 days).

For example:

- Storing 1 GB constantly for 30 days will be charged as 1 GB-month.
- Storing 3 GB constantly for 30 days will be charged as 3 GB-month.
- Storing 1 GB for 5 days, then 3 GB for the remaining 25 days will be charged as `1 GB * 5/30 month + 3 GB * 25/30 month = 2.66 GB-month`

For objects stored in Infrequent Access storage, you will be charged for the object for the minimum storage duration even if the object was deleted or moved before the duration specified.

### Class A operations

Class A Operations include `ListBuckets`, `PutBucket`, `ListObjects`, `PutObject`, `CopyObject`, `CompleteMultipartUpload`, `CreateMultipartUpload`, `LifecycleStorageTierTransition`, `ListMultipartUploads`, `UploadPart`, `UploadPartCopy`, `ListParts`, `PutBucketEncryption`, `PutBucketCors` and `PutBucketLifecycleConfiguration`.

### Class B operations

Class B Operations include `HeadBucket`, `HeadObject`, `GetObject`, `UsageSummary`, `GetBucketEncryption`, `GetBucketLocation`, `GetBucketCors` and `GetBucketLifecycleConfiguration`.

### Free operations

Free operations include `DeleteObject`, `DeleteBucket` and `AbortMultipartUpload`.

### Data retrieval

Data retrieval fees apply when you access or retrieve data from the Infrequent Access storage class. This includes any time objects are read or copied.

### Minimum storage duration

For objects stored in Infrequent Access storage, you will be charged for the object for the minimum storage duration even if the object was deleted, moved, or replaced before the specified duration.

| Storage class                                          | Minimum storage duration |
| ------------------------------------------------------ | ------------------------ |
| Standard storage                                       | None                     |
| Infrequent Access storage<InlineBadge preset="beta" /> | 30 days                  |

## R2 Data Catalog pricing

R2 Data Catalog is in **public beta**, and any developer with an [R2 subscription](/r2/pricing/) can start using it. Currently, outside of standard R2 storage and operations, you will not be billed for your use of R2 Data Catalog. We will provide at least 30 days' notice before we make any changes or start charging for usage.

To learn more about our thinking on future pricing, refer to the [R2 Data Catalog announcement blog](https://blog.cloudflare.com/r2-data-catalog-public-beta).

## Data migration pricing

### Super Slurper

Super Slurper is free to use. You are only charged for the Class A operations that Super Slurper makes to your R2 bucket. Objects with sizes < 100MiB are uploaded to R2 in a single Class A operation. Larger objects use multipart uploads to increase transfer success rates and will perform multiple Class A operations. Note that your source bucket might incur additional charges as Super Slurper copies objects over to R2.

Once migration completes, you are charged for storage & Class A/B operations as described in previous sections.

### Sippy

Sippy is free to use. You are only charged for the operations Sippy makes to your R2 bucket. If a requested object is not present in R2, Sippy will copy it over from your source bucket. Objects with sizes < 200MiB are uploaded to R2 in a single Class A operation. Larger objects use multipart uploads to increase transfer success rates, and will perform multiple Class A operations. Note that your source bucket might incur additional charges as Sippy copies objects over to R2.

As objects are migrated to R2, they are served from R2, and you are charged for storage & Class A/B operations as described in previous sections.

## Pricing calculator

To learn about potential cost savings from using R2, refer to the [R2 pricing calculator](https://r2-calculator.cloudflare.com/).

## R2 billing examples

### Data storage example 1

If a user writes 1,000 objects in R2 for 1 month with an average size of 1 GB and requests each 1,000 times per month, the estimated cost for the month would be:

|                    | Usage                                       | Free Tier    | Billable Quantity | Price      |
| ------------------ | ------------------------------------------- | ------------ | ----------------- | ---------- |
| Class B Operations | (1,000 objects) \* (1,000 reads per object) | 10 million   | 0                 | $0.00      |
| Class A Operations | (1,000 objects) \* (1 write per object)     | 1 million    | 0                 | $0.00      |
| Storage            | (1,000 objects) \* (1 GB per object)        | 10 GB-months | 990 GB-months     | $14.85     |
| **TOTAL**          |                                             |              |                   | **$14.85** |
|                    |                                             |              |                   |            |

### Data storage example 2

If a user writes 10 objects in R2 for 1 month with an average size of 1 GB and requests 1,000 times per month, the estimated cost for the month would be:

|                    | Usage                                       | Free Tier    | Billable Quantity | Price     |
| ------------------ | ------------------------------------------- | ------------ | ----------------- | --------- |
| Class B Operations | (1,000 objects) \* (1,000 reads per object) | 10 million   | 0                 | $0.00     |
| Class A Operations | (1,000 objects) \* (1 write per object)     | 1 million    | 0                 | $0.00     |
| Storage            | (10 objects) \* (1 GB per object)           | 10 GB-months | 0                 | $0.00     |
| **TOTAL**          |                                             |              |                   | **$0.00** |
|                    |                                             |              |                   |           |

### Asset hosting

If a user writes 100,000 files with an average size of 100 KB object and reads 10,000,000 objects per day, the estimated cost in a month would be:

|                    | Usage                                   | Free Tier    | Billable Quantity | Price       |
| ------------------ | --------------------------------------- | ------------ | ----------------- | ----------- |
| Class B Operations | (10,000,000 reads per day) \* (30 days) | 10 million   | 290,000,000       | $104.40     |
| Class A Operations | (100,000 writes)                        | 1 million    | 0                 | $0.00       |
| Storage            | (100,000 objects) \* (100KB per object) | 10 GB-months | 0 GB-months       | $0.00       |
| **TOTAL**          |                                         |              |                   | **$104.40** |
|                    |                                         |              |                   |             |

## Cloudflare billing policy

To learn more about how usage is billed, refer to [Cloudflare Billing Policy](/billing/billing-policy/).

## Frequently asked questions

### Will I be charged for unauthorized requests to my R2 bucket?

No. You are not charged for operations when the caller does not have permission to make the request (HTTP 401 `Unauthorized` response status code).

[^1]: Egressing directly from R2, including via the [Workers API](/r2/api/workers/), [S3 API](/r2/api/s3/), and [`r2.dev` domains](/r2/buckets/public-buckets/#enable-managed-public-access) does not incur data transfer (egress) charges and is free. If you connect other metered services to an R2 bucket, you may be charged by those services.

---

# Realtime vs Regular SFUs

URL: https://developers.cloudflare.com/realtime/calls-vs-sfus/

## Cloudflare Realtime vs. Traditional SFUs

Cloudflare Realtime represents a paradigm shift in building real-time applications by leveraging a distributed real-time data plane. It creates a seamless experience in real-time communication, transcending traditional geographical limitations and scalability concerns. Realtime is designed for developers looking to integrate WebRTC functionalities in a server-client architecture without delving deep into the complexities of regional scaling or server management.

### The Limitations of Centralized SFUs

Selective Forwarding Units (SFUs) play a critical role in managing WebRTC connections by selectively forwarding media streams to participants in a video call. However, their centralized nature introduces inherent limitations:

- **Regional Dependency:** A centralized SFU requires a specific region for deployment, leading to latency issues for global users except for those in proximity to the selected region.

- **Scalability Concerns:** Scaling a centralized SFU to meet global demand can be challenging and inefficient, often requiring additional infrastructure and complexity.

### How is Cloudflare Realtime different?

Cloudflare Realtime addresses these limitations by leveraging Cloudflare's global network infrastructure:

- **Global Distribution Without Regions:** Unlike traditional SFUs, Cloudflare Realtime operates on a global scale without regional constraints. It utilizes Cloudflare's extensive network of over 250 locations worldwide to ensure low-latency video forwarding, making it fast and efficient for users globally.

- **Decentralized Architecture:** There are no dedicated servers for Realtime. Every server within Cloudflare's network contributes to handling Realtime, ensuring scalability and reliability. This approach mirrors the distributed nature of Cloudflare's products such as 1.1.1.1 DNS or Cloudflare's CDN.

## How Cloudflare Realtime Works

### Establishing Peer Connections

To initiate a real-time communication session, an end user's client establishes a WebRTC PeerConnection to the nearest Cloudflare location. This connection benefits from anycast routing, optimizing for the lowest possible latency.

### Signaling and Media Stream Management

- **HTTPS API for Signaling:** Cloudflare Realtime simplifies signaling with a straightforward HTTPS API. This API manages the initiation and coordination of media streams, enabling clients to push new MediaStreamTracks or request these tracks from the server.

- **Efficient Media Handling:** Unlike traditional approaches that require multiple connections for different media streams from different clients, Cloudflare Realtime maintains a single PeerConnection per client. This streamlined process reduces complexity and improves performance by handling both the push and pull of media through a singular connection.

### Application-Level Management

Cloudflare Realtime delegates the responsibility of state management and participant tracking to the application layer. Developers are empowered to design their logic for handling events such as participant joins or media stream updates, offering flexibility to create tailored experiences in applications.

## Getting Started with Cloudflare Realtime

Integrating Cloudflare Realtime into your application promises a straightforward and efficient process, removing the hurdles of regional scalability and server management so you can focus on creating engaging real-time experiences for users worldwide.

---

# Changelog

URL: https://developers.cloudflare.com/realtime/changelog/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/realtime.yaml. --> */}

<ProductReleaseNotes />

---

# DataChannels

URL: https://developers.cloudflare.com/realtime/datachannels/

DataChannels are a way to send arbitrary data, not just audio or video data, between client in low latency. DataChannels are useful for scenarios like chat, game state, or any other data that doesn't need to be encoded as audio or video but still needs to be sent between clients in real time.

While it is possible to send audio and video over DataChannels, it's not optimal because audio and video transfer includes media specific optimizations that DataChannels do not have, such as simulcast, forward error correction, better caching across the Cloudflare network for retransmissions.

```mermaid
graph LR
    A[Publisher] -->|Arbitrary data| B[Cloudflare Realtime SFU]
    B -->|Arbitrary data| C@{ shape: procs, label: "Subscribers"}
```

DataChannels on Cloudflare Realtime can scale up to many subscribers per publisher, there is no limit to the number of subscribers per publisher.

### How to use DataChannels

1. Create  two Realtime sessions, one for the publisher and one for the subscribers.
2. Create a DataChannel by calling /datachannels/new with the location set to "local" and the dataChannelName set to the name of the DataChannel.
3. Create a DataChannel by calling /datachannels/new with the location set to "remote" and the sessionId set to the sessionId of the publisher.
4. Use the DataChannel to send data from the publisher to the subscribers.

### Unidirectional DataChannels

Cloudflare Realtime SFU DataChannels are one way only. This means that you can only send data from the publisher to the subscribers. Subscribers cannot send data back to the publisher. While regular MediaStream WebRTC DataChannels are bidirectional, this introduces a problem for Cloudflare Realtime because the SFU does not know which session to send the data back to. This is especially problematic for scenarios where you have multiple subscribers and you want to send data from the publisher to all subscribers at scale, such as distributing game score updates to all players in a multiplayer game.

To send data in a bidirectional way, you can use two DataChannels, one for sending data from the publisher to the subscribers and one for sending data the opposite direction.

## Example

An example of DataChannels in action can be found in the [Realtime Examples github repo](https://github.com/cloudflare/calls-examples/tree/main/echo-datachannels).

---

# Demos

URL: https://developers.cloudflare.com/realtime/demos/

import { ExternalResources, GlossaryTooltip } from "~/components"

Learn how you can use Realtime within your existing architecture.

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Realtime.

<ExternalResources type="apps" products={["Realtime"]} />

---

# Example architecture

URL: https://developers.cloudflare.com/realtime/example-architecture/

<div class="full-img">

![Example Architecture](~/assets/images/realtime/video-calling-application.png)

</div>

1. Clients connect to the backend service
2. Backend service manages the relationship between the clients and the tracks they should subscribe to
3. Backend service contacts the Cloudflare Realtime API to pass the SDP from the clients to establish the WebRTC connection.
4. Realtime API relays back the Realtime API SDP reply and renegotiation messages.
5. If desired, headless clients can be used to record the content from other clients or publish content.
6. Admin manages the rooms and room members.

---

# Quickstart guide

URL: https://developers.cloudflare.com/realtime/get-started/

:::note[Before you get started:]


You must first [create a Cloudflare account](/fundamentals/account/create-account/).


:::

## Create your first app

Every Realtime App is a separate environment, so you can make one for development, staging and production versions for your product.
Either using [Dashboard](https://dash.cloudflare.com/?to=/:account/calls), or the [API](/api/resources/calls/subresources/sfu/methods/create/) create a Realtime App. When you create a Realtime App, you will get:

* App ID
* App Secret

These two combined will allow you to make API Realtime from your backend server to Realtime.

---

# Connection API

URL: https://developers.cloudflare.com/realtime/https-api/

Cloudflare Realtime simplifies the management of peer connections and media tracks through HTTPS API endpoints. These endpoints allow developers to efficiently manage sessions, add or remove tracks, and gather session information.

## API Endpoints

- **Create a New Session**: Initiates a new session on Cloudflare Realtime, which can be modified with other endpoints below.
  - `POST /apps/{appId}/sessions/new`
- **Add a New Track**: Adds a media track (audio or video) to an existing session.
  - `POST /apps/{appId}/sessions/{sessionId}/tracks/new`
- **Renegotiate a Session**: Updates the session's negotiation state to accommodate new tracks or changes in the existing ones.
  - `PUT /apps/{appId}/sessions/{sessionId}/renegotiate`
- **Close a Track**: Removes a specified track from the session.
  - `PUT /apps/{appId}/sessions/{sessionId}/tracks/close`
- **Retrieve Session Information**: Fetches detailed information about a specific session.
  - `GET /apps/{appId}/sessions/{sessionId}`

[View full API and schema (OpenAPI format)](/realtime/static/calls-api-2024-05-21.yaml)

## Handling Secrets

It is vital to manage App ID and its secret securely. While track and session IDs can be public, they should be protected to prevent misuse. An attacker could exploit these IDs to disrupt service if your backend server does not authenticate request origins properly, for example by sending requests to close tracks on sessions other than their own. Ensuring the security and authenticity of requests to your backend server is crucial for maintaining the integrity of your application.

## Using STUN and TURN Servers

Cloudflare Realtime is designed to operate efficiently without the need for TURN servers in most scenarios, as Cloudflare exposes a publicly routable IP address for Realtime. However, integrating a STUN server can be necessary for facilitating peer discovery and connectivity.

- **Cloudflare STUN Server**: `stun.cloudflare.com:3478`

Utilizing Cloudflare's STUN server can help the connection process for Realtime applications.

## Lifecycle of a Simple Session

This section provides an overview of the typical lifecycle of a simple session, focusing on audio-only applications. It illustrates how clients are notified by the backend server as new remote clients join or leave, incorporating video would introduce additional tracks and considerations into the session.

```mermaid
sequenceDiagram
    participant WA as WebRTC Agent
    participant BS as Backend Server
    participant CA as Realtime API

    Note over BS: Client Joins

    WA->>BS: Request
    BS->>CA: POST /sessions/new
    CA->>BS: newSessionResponse
    BS->>WA: Response

    WA->>BS: Request
    BS->>CA: POST /sessions/<ID>/tracks/new (Offer)
    CA->>BS: newTracksResponse (Answer)
    BS->>WA: Response

    WA-->>CA: ICE Connectivity Check
    Note over WA: iceconnectionstatechange (connected)
    WA-->>CA: DTLS Handshake
    Note over WA: connectionstatechange (connected)

    WA<<->>CA: *Media Flow*

    Note over BS: Remote Client Joins

    WA->>BS: Request
    BS->>CA: POST /sessions/<ID>/tracks/new
    CA->>BS: newTracksResponse (Offer)
    BS->>WA: Response

    WA->>BS: Request
    BS->>CA: PUT /sessions/<ID>/renegotiate (Answer)
    CA->>BS: OK
    BS->>WA: Response

    Note over BS: Remote Client Leaves

    WA->>BS: Request
    BS->>CA: PUT /sessions/<ID>/tracks/close
    CA->>BS: closeTracksResponse
    BS->>WA: Response

    Note over BS: Client Leaves

    WA->>BS: Request
    BS->>CA: PUT /sessions/<ID>/tracks/close
    CA->>BS: closeTracksResponse
    BS->>WA: Response
```

---

# Cloudflare Realtime

URL: https://developers.cloudflare.com/realtime/

import { Description, LinkButton } from "~/components";

<Description>

Build real-time serverless video, audio and data applications.

</Description>

Cloudflare Realtime is infrastructure for real-time audio/video/data applications. It allows you to build real-time apps without worrying about scaling or regions. It can act as a selective forwarding unit (WebRTC SFU), as a fanout delivery system for broadcasting (WebRTC CDN) or anything in between.

Cloudflare Realtime runs on [Cloudflare's global cloud network](https://www.cloudflare.com/network/) in hundreds of cities worldwide.

<LinkButton variant="primary" href="/realtime/get-started/">
	Get started
</LinkButton>
<LinkButton
	variant="secondary"
	href="https://dash.cloudflare.com/?to=/:account/calls"
>
	Realtime dashboard
</LinkButton>
<LinkButton variant="secondary" href="https://github.com/cloudflare/orange">
	Orange Meets demo app
</LinkButton>

---

# Pricing

URL: https://developers.cloudflare.com/realtime/pricing/

Cloudflare Realtime billing is based on data sent from Cloudflare edge to your application.

Cloudflare Realtime SFU and TURN services cost $0.05 per GB of data egress.

There is a free tier of 1,000 GB before any charges start. This free tier includes usage from both SFU and TURN services, not two independent free tiers. Cloudflare Realtime billing appears as a single line item on your Cloudflare bill, covering both SFU and TURN.

Traffic between Cloudflare Realtime TURN and Cloudflare Realtime SFU or Cloudflare Stream (WHIP/WHEP) does not get double charged, so if you are using both SFU and TURN at the same time, you will get charged for only one.

### TURN

Please see the [TURN FAQ page](/realtime/turn/faq), where there is additional information on speficially which traffic path from RFC8656 is measured and counts towards billing.

### SFU

Only traffic originating from Cloudflare towards clients incurs charges. Traffic pushed to Cloudflare incurs no charge even if there is no client pulling same traffic from Cloudflare.

---

# Limits, timeouts and quotas

URL: https://developers.cloudflare.com/realtime/limits/

Understanding the limits and timeouts of Cloudflare Realtime is crucial for optimizing the performance and reliability of your applications. This section outlines the key constraints and behaviors you should be aware of when integrating Cloudflare Realtime into your app.

## Free

* Each account gets 1,000GB/month of data transfer from Cloudflare to your client for free.
* Data transfer from your client to Cloudflare is always free of charge.

## Limits

* **API Realtime per Session**: You can make up to 50 API calls per second for each session. There is no ratelimit on a App basis, just sessions.

* **Tracks per API Call**: Up to 64 tracks can be added with a single API call. If you need to add more tracks to a session, you should distribute them across multiple API calls.

* **Tracks per Session**: There's no upper limit to the number of tracks a session can contain, the practical limit is governed by your connection's bandwidth to and from Cloudflare.

## Inactivity Timeout

* **Track Timeout**: Tracks will automatically timeout and be garbage collected after 30 seconds of inactivity, where inactivity is defined as no media packets being received by Cloudflare. This mechanism ensures efficient use of resources and session cleanliness across all Sessions that use a track.

## PeerConnection Requirements

* **Session State**: For any operation on a session (e.g., pulling or pushing tracks), the PeerConnection state must be `connected`. Operations will block for up to 5 seconds awaiting this state before timing out. This ensures that only active and viable sessions are engaged in media transmission.

## Handling Connectivity Issues

* **Internet Connectivity Considerations**: The potential for internet connectivity loss between the client and Cloudflare is an operational reality that must be addressed. Implementing a detection and reconnection strategy is recommended to maintain session continuity. This could involve periodic 'heartbeat' signals to your backend server to monitor connectivity status. Upon detecting connectivity issues, automatically attempting to reconnect and establish a new session is advised. Sessions and tracks will remain available for reuse for 30 seconds before timing out, providing a brief window for reconnection attempts.

Adhering to these limits and understanding the timeout behaviors will help ensure that your applications remain responsive and stable while providing a seamless user experience.

---

# Introduction

URL: https://developers.cloudflare.com/realtime/introduction/

Cloudflare Realtime can be used to add realtime audio, video and data into your applications. Cloudflare Realtime uses WebRTC, which is the lowest latency way to communicate across a broad range of platforms like browsers, mobile, and native apps.

Realtime integrates with your backend and frontend application to add realtime functionality.

## Why Cloudflare Realtime exists

* **It is difficult to scale WebRTC**: Many struggle scaling WebRTC servers. Operators run into issues about how many users can be in the same "room" or want to build unique solutions that do not fit into the current concepts in high level APIs.

* **High egress costs**: WebRTC is expensive to use as managed solutions charge a high premium on cloud egress and running your own servers incur system administration and scaling overhead. Cloudflare already has 300+ locations with upwards of 1,000 servers in some locations. Cloudflare Realtime scales easily on top of this architecture and can offer the lowest WebRTC usage costs.

* **WebRTC is growing**: Developers are realizing that WebRTC is not just for video conferencing. WebRTC is supported on many platforms, it is mature and well understood.

## What makes Cloudflare Realtime unique

* **Unopinionated**: Cloudflare Realtime does not offer a SDK. It instead allows you to access raw WebRTC to solve unique problems that might not fit into existing concepts. The API is deliberately simple.

* **No rooms**: Unlike other WebRTC products, Cloudflare Realtime lets you be in charge of each track (audio/video/data) instead of offering abstractions such as rooms. You define the presence protocol on top of simple pub/sub. Each end user can publish and subscribe to audio/video/data tracks as they wish.

* **No lock-in**: You can use Cloudflare Realtime to solve scalability issues with your SFU. You can use in combination with peer-to-peer architecture. You can use Cloudflare Realtime standalone. To what extent you use Cloudflare Realtime is up to you.

## What exactly does Cloudflare Realtime do?

* **SFU**: Realtime is a special kind of pub/sub server that is good at forwarding media data to clients that subscribe to certain data. Each client connects to Cloudflare Realtime via WebRTC and either sends data, receives data or both using WebRTC. This can be audio/video tracks or DataChannels.

* **It scales**: All Cloudflare servers act as a single server so millions of WebRTC clients can connect to Cloudflare Realtime. Each can send data, receive data or both with other clients.

## How most developers get started

1. Get started with the echo example, which you can download from the Cloudflare dashboard when you create a Realtime App or from [demos](/realtime/demos/). This will show you how to send and receive audio and video.

2. Understand how you can manipulate who can receive what media by passing around session and track ids. Remember, you control who receives what media. Each media track is represented by a unique ID. It is your responsibility to save and distribute this ID.

:::note[Realtime is not a presence protocol]
Realtime does not know what a room is. It only knows media tracks. It is up to you to make a room by saving who is in a room along with track IDs that unique identify media tracks. If each participant publishes their audio/video, and receives audio/video from each other, you have got yourself a video conference!
:::

3. Create an app where you manage each connection to Cloudflare Realtime and the track IDs created by each connection. You can use any tool to save and share tracks. Check out the example apps at [demos](/realtime/demos/), such as [Orange Meets](https://github.com/cloudflare/orange), which is a full-fledged video conferencing app that uses [Workers Durable Objects](/durable-objects/) to keep track of track IDs.

---

# Sessions and Tracks

URL: https://developers.cloudflare.com/realtime/sessions-tracks/

Cloudflare Realtime offers a simple yet powerful framework for building real-time experiences. At the core of this system are three key concepts: **Applications**,  **Sessions** and **Tracks**. Familiarizing yourself with these concepts is crucial for using Realtime.

## Application

A Realtime Application is an environment within different Sessions and Tracks can interact. Examples of this could be production, staging or different environments where you'd want separation between Sessions and Tracks. Cloudflare Realtime usage can be queried at Application, Session or Track level.

## Sessions

A **Session** in Cloudflare Realtime correlates directly to a WebRTC PeerConnection. It represents the establishment of a communication channel between a client and the nearest Cloudflare data center, as determined by Cloudflare's anycast routing. Typically, a client will maintain a single Session, encompassing all communications between the client and Cloudflare.

* **One-to-One Mapping with PeerConnection**: Each Session is a direct representation of a WebRTC PeerConnection, facilitating real-time media data transfer.
* **Anycast Routing**: The client connects to the closest Cloudflare data center, optimizing latency and performance.
* **Unified Communication Channel**: A single Session can handle all types of communication between a client and Cloudflare, ensuring streamlined data flow.

## Tracks

Within a Session, there can be one or more **Tracks**.

* **Tracks map to MediaStreamTrack**: Tracks align with the MediaStreamTrack concept, facilitating audio, video, or data transmission.
* **Globally Unique Ids**: When you push a track to Cloudflare, it is assigned a unique ID, which can then be used to pull the track into another session elsewhere.
* **Available globally**: The ability to push and pull tracks is central to what makes Realtime a versatile tool for real-time applications. Each track is available globally to be retrieved from any Session within an App.

## Realtime as a Programmable "Switchboard"

The analogy of a switchboard is apt for understanding Realtime. Historically, switchboard operators connected calls by manually plugging in jacks. Similarly, Realtime allows for the dynamic routing of media streams, acting as a programmable switchboard for modern real-time communication.

## Beyond "Rooms", "Users", and "Participants"

While many SFUs utilize concepts like "rooms" to manage media streams among users, this approach has scalability and flexibility limitations. Cloudflare Realtime opts for a more granular and flexible model with Sessions and Tracks, enabling a wide range of use cases:

* Large-scale remote events, like 'fireside chats' with thousands of participants.
* Interactive conversations with the ability to bring audience members "on stage."
* Educational applications where an instructor can present to multiple virtual classrooms simultaneously.

### Presence Protocol vs. Media Flow

Realtime distinguishes between the presence protocol and media flow, allowing for scalability and flexibility in real-time applications. This separation enables developers to craft tailored experiences, from intimate calls to massive, low-latency broadcasts.

---

# Simulcast

URL: https://developers.cloudflare.com/realtime/simulcast/

Simulcast is a feature of WebRTC that allows a publisher to send multiple video streams of the same media at different qualities. For example, this is useful for scenarios where you want to send a high quality stream for desktop users and a lower quality stream for mobile users.

```mermaid
graph LR
    A[Publisher] -->|Low quality| B[Cloudflare Realtime SFU]
    A -->|Medium quality| B
    A -->|High quality| B
B -->|Low quality| C@{ shape: procs, label: "Subscribers"}
B -->|Medium quality| D@{ shape: procs, label: "Subscribers"}
B -->|High quality| E@{ shape: procs, label: "Subscribers"}
```

### How it works

Simulcast in WebRTC allows a single video source, like a camera or screen share, to be encoded at multiple quality levels and sent simultaneously, which is beneficial for subscribers with varying network conditions and device capabilities. The video source is encoded into multiple streams, each identified by RIDs (RTP Stream Identifiers) for different quality levels, such as low, medium, and high. These simulcast streams are described in the SDP you send to Cloudflare Realtime SFU. It's the responsibility of the Cloudflare Realtime SFU to ensure that the appropriate quality stream is delivered to each subscriber based on their network conditions and device capabilities.

Cloudflare Realtime SFU will automatically handle the simulcast configuration based on the SDP you send to it from the publisher. The SFU will then automatically switch between the different quality levels based on the subscriber's network conditions, or the qaulity level can be controlled manually via the API. You can control the quality switching behavior using the `simulcast` configuration object when you send an API call to start pulling a remote track.

### Quality Control

The `simulcast` configuration object in the API call when you start pulling a remote track allows you to specify:

- `preferredRid`: The preferred quality level for the video stream (RID for the simulcast stream. [RIDs can be specified by the publisher.](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpSender/setParameters#encodings))
- `priorityOrdering`: Controls how the SFU handles bandwidth constraints.
  - `none`: Keep sending the preferred layer, set via the preferredRid, even if there's not enough bandwidth.
  - `asciibetical`: Use alphabetical ordering (a-z) to determine priority, where 'a' is most desirable and 'z' is least desirable.
- `ridNotAvailable`: Controls what happens when the preferred RID is no longer available, for example when the publisher stops sending it.
  - `none`: Do nothing.
  - `asciibetical`: Switch to the next available RID based on the priority ordering, where 'a' is most desirable and 'z' is least desirable.

  You will likely want to order the asciibetical RIDs based on your desired metric, such as higest resoltion to lowest or highest bandwidth to lowest.

### Bandwidth Management across media tracks

Cloudflare Realtime treats all media tracks equally at the transport level. For example, if you have multiple video tracks (cameras, screen shares, etc.), they all have equal priority for bandwidth allocation. This means:

1. Each track's simulcast configuration is handled independently
1. The SFU performs automatic bandwidth estimation and layer switching based on network conditions independently for each track

### Layer Switching Behavior

When a layer switch is requested (through updating `preferredRid`) with the `/tracks/update` API:

1. The SFU will automatically generate a Full Intraframe Request (FIR)
2. PLI generation is debounced to prevent excessive requests

### Publisher Configuration

For publishers (local tracks), you only need to include the simulcast attributes in your SDP. The SFU will automatically handle the simulcast configuration based on the SDP. For example, the SDP should contain a section like this:

```txt
a=simulcast:send f;h;q
a=rid:f send
a=rid:h send
a=rid:q send
```

If the publisher endpoint is a browser you can include these by specifying `sendEncodings` when creating the transceiver like this:

```js
const transceiver = peerConnection.addTransceiver(track, {
  direction: "sendonly",
  sendEncodings: [
    { scaleResolutionDownBy: 1, rid: "f" },
    { scaleResolutionDownBy: 2, rid: "h" },
    { scaleResolutionDownBy: 4, rid: "q" }
  ]
});
```

## Example

Here's an example of how to use simulcast with Cloudflare Realtime:

1. Create a new local track with simulcast configuration. There should be a section in the SDP with `a=simulcast:send`.
2. Use the [Cloudflare Realtime API](/realtime/https-api) to push this local track, by calling the /tracks/new endpoint.
3. Use the [Cloudflare Realtime API](/realtime/https-api) to start pulling a remote track (from another browser or device), by calling the /tracks/new endpoint and specifying the `simulcast` configuration object along with the remote track ID you get from step 2.

For more examples, check out the [Realtime Examples GitHub repository](https://github.com/cloudflare/calls-examples/tree/main/echo-simulcast).

---

# Get started

URL: https://developers.cloudflare.com/stream/get-started/

:::note[Before you get started:]


You must first [create a Cloudflare account](/fundamentals/account/create-account/) and [create an API token](/fundamentals/api/get-started/create-token/) to begin using Stream.


:::

* [Upload your first video](/stream/get-started#upload-your-first-video)
* [Start your first live stream](/stream/get-started#start-your-first-live-stream)

## Upload your first video

### Step 1: Upload an example video from a public URL

You can upload videos directly from the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/stream) or using the API.

To use the API, replace the `API_TOKEN` and `ACCOUNT_ID` values with your credentials in the example below.

```bash title="Upload a video using the API"
curl \
-X POST \
-d '{"url":"https://storage.googleapis.com/stream-example-bucket/video.mp4","meta":{"name":"My First Stream Video"}}' \
-H "Authorization: Bearer <API_TOKEN>" \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/copy
```

### Step 2: Wait until the video is ready to stream

Because Stream must download and process the video, the video might not be available for a few seconds depending on the length of your video. You should poll the Stream API until `readyToStream` is `true`, or use [webhooks](/stream/manage-video-library/using-webhooks/) to be notified when a video is ready for streaming.

Use the video UID from the first step to poll the video:

```bash title="Request"
curl \
-H "Authorization: Bearer <API_TOKEN>" \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>
```

```json title="Response" {6}
{
  "result": {
    "uid": "6b9e68b07dfee8cc2d116e4c51d6a957",
    "preview": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/watch",
    "thumbnail": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg",
    "readyToStream": true,
    "status": {
      "state": "ready"
    },
    "meta": {
      "downloaded-from": "https://storage.googleapis.com/stream-example-bucket/video.mp4",
      "name": "My First Stream Video"
    },
    "created": "2020-10-16T20:20:17.872170843Z",
    "size": 9032701,
   //...
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

### Step 3: Play the video in your website or app

Videos uploaded to Stream can be played on any device and platform, from websites to native apps. See [Play videos](/stream/viewing-videos) for details and examples of video playback across platforms.

To play video on your website with the [Stream Player](/stream/viewing-videos/using-the-stream-player/), copy the `uid` of the video from the request above, along with your unique customer code, and replace `<CODE>` and `<VIDEO_UID>` in the embed code below:

```html
<iframe
  src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_UID>/iframe"
  title="Example Stream video"
  frameBorder="0"
  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen>
</iframe>
```

The embed code above can also be found in the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/stream).

<figure data-type="stream">
  <div class="AspectRatio" style="--aspect-ratio: calc(16 / 9)">
    <iframe
      class="AspectRatio--content"
      src="https://iframe.videodelivery.net/5d5bc37ffcf54c9b82e996823bffbb81?muted=true"
      title="Example Stream video"
      frame-border="0"
      allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
  </div>
</figure>

### Next steps

* [Edit your video](/stream/edit-videos/) and add captions or watermarks
* [Customize the Stream player](/stream/viewing-videos/using-the-stream-player/)

## Start your first live stream

### Step 1: Create a live input

You can create a live input via the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/stream/inputs/create) or using the API.

To use the API, replace the `API_TOKEN` and `ACCOUNT_ID` values with your credentials in the example below.

```bash title="Request"
curl -X POST \
-H "Authorization: Bearer <API_TOKEN>" \
-D '{"meta": {"name":"test stream"},"recording": { "mode": "automatic" }}' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/live_inputs
```

```json title="Response"
{
  "uid": "f256e6ea9341d51eea64c9454659e576",
  "rtmps": {
    "url": "rtmps://live.cloudflare.com:443/live/",
    "streamKey": "MTQ0MTcjM3MjI1NDE3ODIyNTI1MjYyMjE4NTI2ODI1NDcxMzUyMzcf256e6ea9351d51eea64c9454659e576"
  },
  "created": "2021-09-23T05:05:53.451415Z",
  "modified": "2021-09-23T05:05:53.451415Z",
  "meta": {
    "name": "test stream"
  },
  "status": null,
  "recording": {
    "mode": "automatic",
    "requireSignedURLs": false,
    "allowedOrigins": null
  }
}
```

### Step 2: Copy the RTMPS URL and key, and use them with your live streaming application.

We recommend using [Open Broadcaster Software (OBS)](https://obsproject.com/) to get started.

### Step 3: Play the live stream in your website or app

Live streams can be played on any device and platform, from websites to native apps, using the same video players as videos uploaded to Stream. See [Play videos](/stream/viewing-videos) for details and examples of video playback across platforms.

To play the live stream you just started on your website with the [Stream Player](/stream/viewing-videos/using-the-stream-player/), copy the `uid` of the live input from the request above, along with your unique customer code, and replace `<CODE>` and `<VIDEO_UID>` in the embed code below:

```html
<iframe
  src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_UID>/iframe"
  title="Example Stream video"
  frameBorder="0"
  allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen>
</iframe>
```

The embed code above can also be found in the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/stream).

### Next steps

* [Secure your stream](/stream/viewing-videos/securing-your-stream/)
* [View live viewer counts](/stream/getting-analytics/live-viewer-count/)

## Accessibility considerations

To make your video content more accessible, include [captions](/stream/edit-videos/adding-captions/) and [high-quality audio recording](https://www.w3.org/WAI/media/av/av-content/).

---

# Changelog

URL: https://developers.cloudflare.com/stream/changelog/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/stream.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# FAQ

URL: https://developers.cloudflare.com/stream/faq/

import { GlossaryTooltip } from "~/components"

## Stream

### What formats and quality levels are delivered through Cloudflare Stream?

Cloudflare decides on which bitrate, resolution, and codec is best for you. We deliver all videos to industry standard H264 codec. We use a few different adaptive streaming levels from 360p to 1080p to ensure smooth streaming for your audience watching on different devices and bandwidth constraints.

### Can I download original video files from Stream?

You cannot download the *exact* input file that you uploaded. However, depending on your use case, you can use the [Downloadable Videos](/stream/viewing-videos/download-videos/) feature to get encoded MP4s for use cases like offline viewing.

### Is there a limit to the amount of videos I can upload?

* By default, a video upload can be at most 30 GB.

* By default, you can have up to 120 videos queued or being encoded simultaneously. Videos in the `ready` status are playable but may still be encoding certain quality levels until the `pctComplete` reaches 100. Videos in the `error`, `ready`, or `pendingupload` state do not count toward this limit. If you need the concurrency limit raised, [contact Cloudflare support](/support/contacting-cloudflare-support/) explaining your use case and why you would like the limit raised.

:::note


The limit to the number of videos only applies to videos being uploaded to Cloudflare Stream. This limit is not related to the number of end users streaming videos.


:::

* An account cannot upload videos if the total video duration exceeds the video storage capacity purchased.

Limits apply to Direct Creator Uploads at the time of upload URL creation.

Uploads over these limits will receive a [429 (Too Many Requests)](/support/troubleshooting/http-status-codes/4xx-client-error/error-429/) or [413 (Payload too large)](/support/troubleshooting/http-status-codes/4xx-client-error/error-413/) HTTP status codes with more information in the response body. Please write to Cloudflare support or your customer success manager for higher limits.

### Can I embed videos on Stream even if my domain is not on Cloudflare?

Yes. Stream videos can be embedded on any domain, even domains not on Cloudflare.

### What input file formats are supported?

Users can upload video in the following file formats:

MP4, MKV, MOV, AVI, FLV, MPEG-2 TS, MPEG-2 PS, MXF, LXF, GXF, 3GP, WebM, MPG, QuickTime

### Does Stream support High Dynamic Range (HDR) video content?

When HDR videos are uploaded to Stream, they are re-encoded and delivered in SDR format, to ensure compatibility with the widest range of viewing devices.

### What frame rates (FPS) are supported?

Cloudflare Stream supports video file uploads for any FPS, however videos will be re-encoded for 70 FPS playback. If the original video file has a frame rate lower than 70 FPS, Stream will re-encode at the original frame rate.

If the frame rate is variable we will drop frames (for example if there are more than 1 frames within 1/30 seconds, we will drop the extra frames within that period).

### What browsers does Stream work on?

You can embed the Stream player on the following platforms:

<table-wrap>

| Browser | Version                             |
| ------- | ----------------------------------- |
| Chrome  | Supported since Chrome version 88+  |
| Firefox | Supported since Firefox version 87+ |
| Edge    | Supported since Edge 89+            |
| Safari  | Supported since Safari version 14+  |
| Opera   | Supported since Opera version 75+   |

</table-wrap>

:::note[Note]


Cloudflare Stream is not available on Chromium, as Chromium does not support H.264 videos.


:::

<table-wrap>

| Mobile Platform       | Version                                                                  |
| --------------------- | ------------------------------------------------------------------------ |
| Chrome on Android     | Supported on Chrome 90                                                   |
| UC Browser on Android | Supported on version 12.12+                                              |
| Samsung Internet      | Supported on 13+                                                         |
| Safari on iOS         | Supported on iOS 13.4+. Speed selector supported when not in fullscreen. |

</table-wrap>

### What are the recommended upload settings for video uploads?

If you are producing a brand new file for Cloudflare Stream, we recommend you use the following settings:

* MP4 containers, AAC audio codec, H264 video codec, 30 or below frames per second
* moov atom should be at the front of the file (Fast Start)
* H264 progressive scan (no interlacing)
* H264 high profile
* Closed GOP
* Content should be encoded and uploaded in the same frame rate it was recorded
* Mono or Stereo audio (Stream will mix audio tracks with more than 2 channels down to stereo)

Below are bitrate recommendations for encoding new videos for Stream:

<table-wrap>

| Resolution | Recommended bitrate |
| ---------- | ------------------- |
| 1080p      | 8 Mbps              |
| 720p       | 4.8 Mbps            |
| 480p       | 2.4 Mbps            |
| 360p       | 1 Mbps              |

</table-wrap>

### If I cancel my stream subscription, are the videos deleted?

Videos are removed if the subscription is not renewed within 30 days.

### I use Content Security Policy (CSP) on my website. What domains do I need to add to which directives?

If your website uses <GlossaryTooltip term="content security policy (CSP)" link="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy">Content Security Policy (CSP)</GlossaryTooltip> directives, depending on your configuration, you may need to add Cloudflare Stream's domains to particular directives, in order to allow videos to be viewed or uploaded by your users.

If you use the provided [Stream Player](/stream/viewing-videos/using-the-stream-player/), `videodelivery.net` and `*.cloudflarestream.com` must be included in the `frame-src` or `default-src` directive to allow the player's `<iframe>` element to load.

```http
Content-Security-Policy: frame-src 'self' videodelivery.net *.cloudflarestream.com
```

If you use your **own** Player, add `*.videodelivery.net` and `*.cloudflarestream.com` to the `media-src`, `img-src` and `connect-src` CSP directives to allow video files and thumbnail images to load.

```http
Content-Security-Policy: media-src 'self' videodelivery.net *.cloudflarestream.com; img-src 'self' *.videodelivery.net *.cloudflarestream.com; connect-src 'self' *.videodelivery.net *.cloudflarestream.com
```

If you allow users to upload their own videos directly to Cloudflare Stream, add `*.videodelivery.net` and `*.cloudflarestream.com` to the `connect-src` CSP directive.

```http
Content-Security-Policy: connect-src 'self' *.videodelivery.net *.cloudflarestream.com
```

To ensure **only** videos from **your** Cloudflare Stream account can be played on your website, replace `*` in `*.cloudflarestream.com` and `*.videodelivery.net` in the examples above with `customer-<CODE>`, replacing `<CODE>` with your unique customer code, which can be found in the [Stream Dashboard](https://dash.cloudflare.com/?to=/:account/stream). This code is unique to your Cloudflare Account.

### Why is PageSpeed Insights giving a bad score when using the Stream Player?

If your website loads in a lot of player instances, PageSpeed Insights will penalize the JavaScript load for each player instance. Our testing shows that when actually loading the page, the script itself is only downloaded once with the local browser cache retrieving the script for the other player objects on the same page. Therefore, we believe that the PageSpeed Insights score is not matching real-world behavior in this situation.

If you are using thumbnails, you can use [animated thumbnails](/stream/viewing-videos/displaying-thumbnails/#animated-gif-thumbnails) that link to the video pages.

If multiple players are on the same page, you can lazy load any players that are not visible in the initial viewport. For more information about lazy loading, refer to [Mozilla's lazy loading documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#lazy).

---

# Cloudflare Stream

URL: https://developers.cloudflare.com/stream/

import { CardGrid, Description, Feature, LinkButton, LinkTitleCard, Render } from "~/components"

<Description>


Serverless live and on-demand video streaming


</Description>

Cloudflare Stream lets you or your end users upload, store, encode, and deliver live and on-demand video with one API, without configuring or maintaining infrastructure.

You can use Stream to build your own video features in websites and native apps, from simple playback to an entire video platform.

Cloudflare Stream runs on [Cloudflare’s global cloud network](https://www.cloudflare.com/network/) in hundreds of cities worldwide.

 <LinkButton variant="primary" href="/stream/get-started/">Get started</LinkButton> <LinkButton variant="secondary" href="https://dash.cloudflare.com/?to=/:account/stream">Stream dashboard</LinkButton>


***

## Features

<Feature header="Control access to video content" href="/stream/viewing-videos/securing-your-stream/" cta="Use Signed URLs">

Restrict access to paid or authenticated content with signed URLs.


</Feature>

<Feature header="Let your users upload their own videos" href="/stream/uploading-videos/direct-creator-uploads/" cta="Direct Creator Uploads">

Let users in your app upload videos directly to Stream with a unique, one-time upload URL.


</Feature>

<Feature header="Play video on any device" href="/stream/viewing-videos/" cta="Play videos">

Play on-demand and live video on websites, in native iOS and Android apps, and dedicated streaming devices like Apple TV.


</Feature>

<Feature header="Get detailed analytics" href="/stream/getting-analytics/" cta="Explore Analytics">

Understand and analyze which videos and live streams are viewed most and break down metrics on a per-creator basis.


</Feature>

***

## More resources

<CardGrid>

<LinkTitleCard title="Discord" href="https://discord.cloudflare.com" icon="discord">
&#x20;Join the Stream developer community
</LinkTitleCard>

</CardGrid>

---

# Pricing

URL: https://developers.cloudflare.com/stream/pricing/

Cloudflare Stream lets you broadcast, store, and deliver video using a simple, unified API and simple pricing. Stream bills on two dimensions only:

- **Minutes of video stored:** the total duration of uploaded video and live recordings
- **Minutes of video delivered:** the total duration of video delivered to end users

On-demand and live video are billed the same way.

Ingress (sending your content to us) and encoding are always free. Bandwidth is already included in "video delivered" with no additional egress (traffic/bandwidth) fees.

## Minutes of video stored

Storage is a prepaid pricing dimension purchased in increments of $5 per 1,000 minutes stored, regardless of file size. You can check how much storage you have and how much you have used on the [Stream](https://dash.cloudflare.com/?to=/:account/stream) page in Dash.

Storage is consumed by:

- Original videos uploaded to your account
- Recordings of live broadcasts
- The reserved `maxDurationSeconds` for Direct Creator and TUS uploads which have not been completed. After these uploads are complete or the upload link expires, this reservation is released.

Storage is not consumed by:

- Videos in an unplayable or errored state
- Expired Direct Creator upload links
- Deleted videos
- Downloadable files generated for [MP4 Downloads](/stream/viewing-videos/download-videos/)
- Multiple quality levels that Stream generates for each uploaded original

Storage consumption is rounded up to the second of video duration; file size does not matter. Video stored in Stream does not incur additional storage fees from other storage products such as R2.

:::note
If you run out of storage, you will not be able to upload new videos or start new live streams until you purchase more storage or delete videos.

Enterprise customers _may_ continue to upload new content beyond their contracted quota without interruption.
:::

## Minutes of video delivered

Delivery is a post-paid, usage-based pricing dimension billed at $1 per 1,000 minutes delivered. You can check how much delivery you have used on the [Billable Usage](https://dash.cloudflare.com/?to=/:account/billing/billable-usage) page in Dash or the [Stream Analytics](https://dash.cloudflare.com/?to=/:account/stream/analytics) page under Stream.

Delivery is counted for the following uses:

- Playback on the web or an app using [Stream's built-in player](/stream/viewing-videos/using-the-stream-player/) or the [HLS or DASH manifests](/stream/viewing-videos/using-own-player/)
- MP4 Downloads
- Simulcasting via SRT or RTMP live outputs

Delivery is counted by HTTP requests for video segments or parts of the MP4. Therefore:

- Client-side preloading and buffering is counted as billable delivery.
- Content played from client-side/browser cache is _not_ billable, like a short looping video. Some mobile app player libraries do not cache HLS segments by default.
- MP4 Downloads are billed by percentage of the file delivered.

Minutes delivered for web playback (Stream Player, HLS, and DASH) are rounded to the _segment_ length: for uploaded content, segments are four seconds. Live broadcast and recording segments are determined by the keyframe interval or GOP size of the original broadcast.

## Example scenarios

**Two people each watch thirty minutes of a video or live broadcast. How much would it cost?**

This will result in 60 minutes of Minutes Delivered usage (or $0.06). Stream bills on total minutes of video delivered across all users.

**I have a really large file. Does that cost more?**

The cost to store a video is based only on its duration, not its file size. If the file is within the [30GB max file size limitation](/stream/faq/#is-there-a-limit-to-the-amount-of-videos-i-can-upload), it will be accepted. Be sure to use an [upload method](/stream/uploading-videos/) like Upload from Link or TUS that handles large files well.

**If I make a Direct Creator Upload link with a maximum duration (`maxDurationSeconds`) of 600 seconds which expires in 1 hour, how is storage consumed?**

- Ten minutes (600 seconds) will be subtracted from your available storage immediately.
- If the link is unused in one hour, those 10 minutes will be released.
- If the creator link is used to upload a five minute video, when the video is uploaded and processed, the 10 minute reservation will be released and the true five minute duration of the file will be counted.
- If the creator link is used to upload a five minute video but it fails to encode, the video will be marked as errored, the reserved storage will be released, and no storage use will be counted.

**I am broadcasting live, but no one is watching. How much does that cost?**

A live broadcast with no viewers will cost $0 for minutes delivered, but the recording of the broadcast will count toward minutes of video stored.

If someone watches the recording, that will be counted as minutes of video delivered.

If the recording is deleted, the storage use will be released.

**I want to store and deliver millions of minutes a month. Do you have volume pricing?**

Yes, contact our [Sales Team](https://www.cloudflare.com/plans/enterprise/contact/).

---

# WebRTC

URL: https://developers.cloudflare.com/stream/webrtc-beta/

import { Badge, InlineBadge } from '~/components';

Sub-second latency live streaming (using WHIP) and playback (using WHEP) to unlimited concurrent viewers.

WebRTC is ideal for when you need live video to playback in near real-time, such as:

* When the outcome of a live event is time-sensitive (live sports, financial news)
* When viewers interact with the live stream (live Q\&A, auctions, etc.)
* When you want your end users to be able to easily go live or create their own video content, from a web browser or native app

:::note

WebRTC streaming is currently in beta, and we'd love to hear what you think. Join the Cloudflare Discord server [using this invite](https://discord.com/invite/cloudflaredev/) and hop into our [Discord channel](https://discord.com/channels/595317990191398933/893253103695065128) to let us know what you're building with WebRTC!

:::

## Step 1: Create a live input

[Use the Stream Dashboard](https://dash.cloudflare.com/?to=/:account/stream/inputs/create), or make a POST request to the [`/live_inputs` API endpoint](/api/resources/stream/subresources/live_inputs/methods/create/)

```json title="API response from a POST request to /live_inputs" {5}
{
  "uid": "1a553f11a88915d093d45eda660d2f8c",
 ...
  "webRTC": {
    "url": "https://customer-<CODE>.cloudflarestream.com/<SECRET>/webRTC/publish"
  },
  "webRTCPlayback": {
    "url": "https://customer-<CODE>.cloudflarestream.com/<INPUT_UID>/webRTC/play"
  },
...
}
```

## Step 2: Go live using WHIP

Every live input has a unique URL that one creator can be stream to. This URL should *only* be shared with the creator — anyone with this URL has the ability to stream live video to this live input.

Copy the URL from the `webRTC` key in the API response (see above), or directly from the [Cloudflare Dashboard](https://dash.cloudflare.com/?to=/:account/stream/inputs).

Paste this URL into the example code.

```javascript title="Simplified example code" {4}
// Add a <video> element to the HTML page this code runs in:
// <video id="input-video" autoplay muted></video>

import WHIPClient from "./WHIPClient.js";

const url = "<WEBRTC_URL_FROM_YOUR_LIVE_INPUT>"; // add the webRTC URL from your live input here
const videoElement = document.getElementById("input-video");
const client = new WHIPClient(url, videoElement);
```

Once the creator grants permission to their camera and microphone, live video and audio will automatically start being streamed to Cloudflare, using WebRTC.

You can also use this URL with any client that supports the [WebRTC-HTTP ingestion protocol (WHIP)](https://www.ietf.org/archive/id/draft-ietf-wish-whip-16.html). See [supported WHIP clients](#supported-whip-and-whep-clients) for a list of clients we have tested and confirmed compatibility with Cloudflare Stream.

## Step 3: Play live video using WHEP

Copy the URL from the `webRTCPlayback` key in the API response (see above), or directly from the [Cloudflare Dashboard](https://dash.cloudflare.com/?to=/:account/stream/inputs). There are no limits on the number of concurrent viewers.

Paste this URL into the example code.

```javascript title="Simplified example code" {4}
// Add a <video> element to the HTML page this code runs in:
// <video id="output-video" autoplay muted></video>

import WHEPClient from "./WHEPClient.js";

const url = "<WEBRTC_URL_FROM_YOUR_LIVE_INPUT>"; // add the webRTCPlayback URL from your live input here
const videoElement = document.getElementById("output-video");
const client = new WHEPClient(url, videoElement);
```

As long as the creator is actively streaming, viewers should see their broadcast in their browser, with less than 1 second of latency.

You can also use this URL with any client that supports the [WebRTC-HTTP egress protocol (WHEP)](https://www.ietf.org/archive/id/draft-murillo-whep-01.html). See [supported WHEP clients](#supported-whip-and-whep-clients) for a list of clients we have tested and confirmed compatibility with Cloudflare Stream.

## Using WebRTC in native apps

If you are building a native app, the example code above can run within a [WkWebView (iOS)](https://developer.apple.com/documentation/webkit/wkwebview), [WebView (Android)](https://developer.android.com/reference/android/webkit/WebView) or using [react-native-webrtc](https://github.com/react-native-webrtc/react-native-webrtc/blob/master/Documentation/BasicUsage.md). If you need to use WebRTC without a webview, you can use Google's Java and Objective-C native [implementations of WebRTC APIs](https://webrtc.googlesource.com/src/+/refs/heads/main/sdk).

## Debugging WebRTC

* **Chrome**: Navigate to `chrome://webrtc-internals` to view detailed logs and graphs.
* **Firefox**: Navigate to `about:webrtc` to view information about WebRTC sessions, similar to Chrome.
* **Safari**: To enable WebRTC logs, from the inspector, open the settings tab (cogwheel icon), and set WebRTC logging to "Verbose" in the dropdown menu.

## Supported WHIP and WHEP clients

Beyond the example WHIP client and example WHEP client used in the examples above, we have tested and confirmed that the following clients are compatible with Cloudflare Stream:

### WHIP

* [OBS (Open Broadcaster Software)](https://obsproject.com)
* [@eyevinn/whip-web-client](https://www.npmjs.com/package/@eyevinn/whip-web-client) (TypeScript)
* [whip-go](https://github.com/ggarber/whip-go) (Go)
* [gst-plugins-rs](https://gitlab.freedesktop.org/gstreamer/gst-plugins-rs) (Gstreamer plugins, written in Rust)
* [Larix Broadcaster](https://softvelum.com/larix/) (free apps for iOS and Android with WebRTC based on Pion, SDK available)

### WHEP

* [@eyevinn/webrtc-player](https://www.npmjs.com/package/@eyevinn/webrtc-player) (TypeScript)
* [@eyevinn/wrtc-egress](https://www.npmjs.com/package/@eyevinn/wrtc-egress) (TypeScript)
* [gst-plugins-rs](https://gitlab.freedesktop.org/gstreamer/gst-plugins-rs) (Gstreamer plugins, written in Rust)

As more WHIP and WHEP clients are published, we are committed to supporting them and being fully compliant with the both protocols.

## Supported codecs

* [VP9](https://developers.google.com/media/vp9) (recommended for highest quality)
* [VP8](https://en.wikipedia.org/wiki/VP8)
* [h264](https://en.wikipedia.org/wiki/Advanced_Video_Coding) (Constrained Baseline Profile Level 3.1, referred to as `42e01f` in the SDP offer's `profile-level-id` parameter.)

## Conformance with WHIP and WHEP specifications

Cloudflare Stream fully supports all aspects of the [WHIP](https://www.ietf.org/archive/id/draft-ietf-wish-whip-16.html) and [WHEP](https://www.ietf.org/archive/id/draft-murillo-whep-01.html) specifications, including:

* [Trickle ICE](https://datatracker.ietf.org/doc/rfc8838/)
* [Server and client offer modes](https://www.ietf.org/archive/id/draft-murillo-whep-01.html#section-3) for WHEP

You can find the specific version of WHIP and WHEP being used in the `protocol-version` header in WHIP and WHEP API responses. The value of this header references the IETF draft slug for each protocol. Currently, Stream uses `draft-ietf-wish-whip-06` (expected to be the final WHIP draft revision) and `draft-murillo-whep-01` (the most current WHEP draft).

## Limitations while in beta

* [Recording](/stream/stream-live/watch-live-stream/#live-stream-recording-playback) is not yet supported (coming soon)
* [Simulcasting](/stream/stream-live/simulcasting) (restreaming) is not yet supported (coming soon)
* [Live viewer counts](/stream/getting-analytics/live-viewer-count/) are not yet supported (coming soon)
* [Analytics](/stream/getting-analytics/fetching-bulk-analytics/) are not yet supported (coming soon)
* WHIP and WHEP must be used together — we do not yet support streaming using RTMP/SRT and playing using WHEP, or streaming using WHIP and playing using HLS or DASH. (coming soon)
* Once generally available, WebRTC streaming will be priced just like the rest of Cloudflare Stream, based on minutes stored and minutes of video delivered.

---

# Cloudflare Vectorize

URL: https://developers.cloudflare.com/vectorize/

import {
	CardGrid,
	Description,
	Feature,
	LinkTitleCard,
	Plan,
	RelatedProduct,
	Render,
} from "~/components";

<Description>

Build full-stack AI applications with Vectorize, Cloudflare's powerful vector database.

</Description>

Vectorize is a globally distributed vector database that enables you to build full-stack, AI-powered applications with [Cloudflare Workers](/workers/). Vectorize makes querying embeddings — representations of values or objects like text, images, audio that are designed to be consumed by machine learning models and semantic search algorithms — faster, easier and more affordable.

<Render file="vectorize-ga" />

For example, by storing the embeddings (vectors) generated by a machine learning model, including those built-in to [Workers AI](/workers-ai/) or by bringing your own from platforms like [OpenAI](#), you can build applications with powerful search, similarity, recommendation, classification and/or anomaly detection capabilities based on your own data.

The vectors returned can reference images stored in Cloudflare R2, documents in KV, and/or user profiles stored in D1 — enabling you to go from vector search result to concrete object all within the Workers platform, and without standing up additional infrastructure.

---

## Features

<Feature header="Vector database" href="/vectorize/get-started/intro/" cta="Create your Vector database">

Learn how to create your first Vectorize database, upload vector embeddings, and query those embeddings from [Cloudflare Workers](/workers/).

</Feature>

<Feature header="Vector embeddings using Workers AI" href="/vectorize/get-started/embeddings/" cta="Create vector embeddings using Workers AI">

Learn how to use Vectorize to generate vector embeddings using Workers AI.

</Feature>

<Feature header="Search using Vectorize and AutoRAG" href="/autorag/" cta="Build a RAG with Vectorize">

Learn how to automatically index your data and store it in Vectorize, then query it to generate context-aware responses using AutoRAG.

</Feature>

---

## Related products

<RelatedProduct header="Workers AI" href="/workers-ai/" product="workers-ai">

Run machine learning models, powered by serverless GPUs, on Cloudflare’s global network.

</RelatedProduct>

<RelatedProduct header="R2 Storage" href="/r2/" product="r2">

Store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.

</RelatedProduct>

---

## More resources

<CardGrid>

<LinkTitleCard
	title="Limits"
	href="/vectorize/platform/limits/"
	icon="document"
>
	Learn about Vectorize limits and how to work within them.
</LinkTitleCard>

<LinkTitleCard title="Use cases" href="/use-cases/ai/" icon="document">
	Learn how you can build and deploy ambitious AI applications to Cloudflare's
	global network.
</LinkTitleCard>

<LinkTitleCard
	title="Storage options"
	href="/workers/platform/storage-options/"
	icon="document"
>
	Learn more about the storage and database options you can build on with
	Workers.
</LinkTitleCard>

<LinkTitleCard
	title="Developer Discord"
	href="https://discord.cloudflare.com"
	icon="discord"
>
	Connect with the Workers community on Discord to ask questions, join the
	`#vectorize` channel to show what you are building, and discuss the platform
	with other developers.
</LinkTitleCard>

<LinkTitleCard
	title="@CloudflareDev"
	href="https://x.com/cloudflaredev"
	icon="x.com"
>
	Follow @CloudflareDev on Twitter to learn about product announcements, and
	what is new in Cloudflare Developer Platform.
</LinkTitleCard>

</CardGrid>

---

# Architectures

URL: https://developers.cloudflare.com/vectorize/demos/

import { GlossaryTooltip, ResourcesBySelector } from "~/components"

Learn how you can use Vectorize within your existing architecture.

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use Vectorize:

<ResourcesBySelector types={["reference-architecture","design-guide","reference-architecture-diagram"]} products={["Vectorize"]} />

---

# Agents

URL: https://developers.cloudflare.com/workers-ai/agents/

import { LinkButton } from "~/components"

<div style={{ textAlign: 'center', marginBottom: '2rem' }}>
  <p>Build AI assistants that can perform complex tasks on behalf of your users using Cloudflare Workers AI and Agents.</p>
  <LinkButton href="/agents/">Go to Agents documentation</LinkButton>
</div>

---

# Changelog

URL: https://developers.cloudflare.com/workers-ai/changelog/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/workers-ai.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Cloudflare Workers AI

URL: https://developers.cloudflare.com/workers-ai/

import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct, Render, LinkButton, Flex } from "~/components"

<Description>

Run machine learning models, powered by serverless GPUs, on Cloudflare's global network.
</Description>

<Plan type="workers-all" />

Workers AI allows you to run AI models in a serverless way, without having to worry about scaling, maintaining, or paying for unused infrastructure. You can invoke models running on GPUs on Cloudflare's network from your own code — from [Workers](/workers/), [Pages](/pages/), or anywhere via [the Cloudflare API](/api/resources/ai/methods/run/).

Workers AI gives you access to:
- **50+ [open-source models](/workers-ai/models/)**, available as a part of our model catalog
- Serverless, **pay-for-what-you-use** [pricing model](/workers-ai/platform/pricing/)
- All as part of a **fully-featured developer platform**, including [AI Gateway](/ai-gateway/), [Vectorize](/vectorize/), [Workers](/workers/) and more...

<div>
  <LinkButton href="/workers-ai/get-started">Get started</LinkButton>
  <LinkButton target="_blank" variant="secondary" icon="external" href="https://youtu.be/cK_leoJsBWY?si=4u6BIy_uBOZf9Ve8">Watch a Workers AI demo</LinkButton>
</div>


<Render file="custom_requirements" />

<Render file="file_issues" />

***

## Features

<Feature header="Models" href="/workers-ai/models/" cta="Browse models">

Workers AI comes with a curated set of popular open-source models that enable you to do tasks such as image classification, text generation, object detection and more.


</Feature>

***

## Related products

<RelatedProduct header="AI Gateway" href="/ai-gateway/" product="ai-gateway">

Observe and control your AI applications with caching, rate limiting, request retries, model fallback, and more.


</RelatedProduct>

<RelatedProduct header="Vectorize" href="/vectorize/" product="vectorize">

Build full-stack AI applications with Vectorize, Cloudflare’s vector database. Adding Vectorize enables you to perform tasks such as semantic search, recommendations, anomaly detection or can be used to provide context and memory to an LLM.


</RelatedProduct>

<RelatedProduct header="Workers" href="/workers/" product="workers">

Build serverless applications and deploy instantly across the globe for exceptional performance, reliability, and scale.


</RelatedProduct>

<RelatedProduct header="Pages" href="/pages/" product="pages">

Create full-stack applications that are instantly deployed to the Cloudflare global network.


</RelatedProduct>

<RelatedProduct header="R2" href="/r2/" product="r2">

Store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.


</RelatedProduct>

<RelatedProduct header="D1" href="/d1/" product="d1">

Create new serverless SQL databases to query from your Workers and Pages projects.


</RelatedProduct>

<RelatedProduct header="Durable Objects" href="/durable-objects/" product="durable-objects">

A globally distributed coordination API with strongly consistent storage.


</RelatedProduct>

<RelatedProduct header="KV" href="/kv/" product="kv">

Create a global, low-latency, key-value data storage.


</RelatedProduct>

***

## More resources

<CardGrid>

<LinkTitleCard title="Get started" href="/workers-ai/get-started/workers-wrangler/" icon="open-book">
Build and deploy your first Workers AI application.
</LinkTitleCard>

<LinkTitleCard title="Plans" href="/workers-ai/platform/pricing/" icon="seti:shell">
Learn about Free and Paid plans.
</LinkTitleCard>

<LinkTitleCard title="Limits" href="/workers-ai/platform/limits/" icon="document">
Learn about Workers AI limits.
</LinkTitleCard>

<LinkTitleCard title="Use cases" href="/use-cases/ai/" icon="document">
Learn how you can build and deploy ambitious AI applications to Cloudflare's global network.
</LinkTitleCard>

<LinkTitleCard title="Storage options" href="/workers/platform/storage-options/" icon="open-book">
Learn which storage option is best for your project.
</LinkTitleCard>

<LinkTitleCard title="Developer Discord" href="https://discord.cloudflare.com" icon="discord">
Connect with the Workers community on Discord to ask questions, share what you are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard title="@CloudflareDev" href="https://x.com/cloudflaredev" icon="x.com">
Follow @CloudflareDev on Twitter to learn about product announcements, and what is new in Cloudflare Workers.
</LinkTitleCard>

</CardGrid>

---

# Demos and architectures

URL: https://developers.cloudflare.com/workers/demos/

import { ExternalResources, GlossaryTooltip, ResourcesBySelector } from "~/components"

Learn how you can use Workers within your existing application and architecture.

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Workers.

<ExternalResources type="apps" products={["Workers"]} />

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use Workers:

<ResourcesBySelector types={["reference-architecture","design-guide","reference-architecture-diagram"]} products={["Workers"]} />

---

# Cloudflare Workers

URL: https://developers.cloudflare.com/workers/

import { Description, RelatedProduct, LinkButton } from "~/components";

<Description>
A serverless platform for building, deploying, and scaling apps across [Cloudflare's global network](https://www.cloudflare.com/network/) with a single command  —  no infrastructure to manage, no complex configuration
</Description>

With Cloudflare Workers, you can expect to:
- Deliver fast performance with high reliability anywhere in the world
- Build full-stack apps with your framework of choice, including [React](/workers/framework-guides/web-apps/react/), [Vue](/workers/framework-guides/web-apps/vue/), [Svelte](/workers/framework-guides/web-apps/svelte/), [Next](/workers/framework-guides/web-apps/nextjs/), [Astro](/workers/framework-guides/web-apps/astro/), [React Router](/workers/framework-guides/web-apps/react-router/), [and more](/workers/framework-guides/)
- Use your preferred language, including [JavaScript](/workers/languages/javascript/), [TypeScript](/workers/languages/typescript/), [Python](/workers/languages/python/), [Rust](/workers/languages/rust/), [and more](/workers/runtime-apis/webassembly/)
- Gain deep visibility and insight with built-in [observability](/workers/observability/logs/)
- Get started for free and grow with flexible [pricing](/workers/platform/pricing/), affordable at any scale

Get started with your first project:

<LinkButton href="https://dash.cloudflare.com/?to=/:account/workers-and-pages/templates">Deploy a template</LinkButton>


<LinkButton href="/workers/get-started/guide/" variant="minimal">
  Deploy with Wrangler CLI
</LinkButton>

---

## Build with Workers

<div>
#### Front-end applications

<span>Deploy [static assets](/workers/static-assets/) to Cloudflare's [CDN & cache](/cache/) for fast rendering</span>
</div>

<div>
#### Back-end applications

<span>Build APIs and connect to data stores with [Smart Placement](/workers/configuration/smart-placement/) to optimize latency</span>
</div>

<div>
#### Serverless AI inference

<span>Run LLMs, generate images, and more with [Workers AI](/workers-ai/)</span>
</div>

<div>
#### Background jobs

<span>Schedule [cron jobs](/workers/configuration/cron-triggers/), run durable [Workflows](/workflows/), and integrate with [Queues](/queues/)</span>
</div>

---

## Integrate with Workers

Connect to external services like databases, APIs, and storage via [Bindings](/workers/runtime-apis/bindings/), enabling functionality with just a few lines of code:

**Storage**

<RelatedProduct header="Durable Objects" href="/durable-objects/" product="durable-objects">

Scalable stateful storage for real-time coordination.

</RelatedProduct>

<RelatedProduct header="D1" href="/d1/" product="d1">

Serverless SQL database built for fast, global queries.

</RelatedProduct>

<RelatedProduct header="KV" href="/kv/" product="kv">

Low-latency key-value storage for fast, edge-cached reads.

</RelatedProduct>

<RelatedProduct header="Queues" href="/queues/" product="queues">

Guaranteed delivery with no charges for egress bandwidth.

</RelatedProduct>

<RelatedProduct header="Hyperdrive" href="/hyperdrive/" product="hyperdrive">

Connect to your external database with accelerated queries, cached at the edge.

</RelatedProduct>

**Compute**

<RelatedProduct header="Workers AI" href="/workers-ai/" product="workers-ai">

Machine learning models powered by serverless GPUs.

</RelatedProduct>

<RelatedProduct header="Workflows" href="/workflows/" product="workflows">

Durable, long-running operations with automatic retries.

</RelatedProduct>

<RelatedProduct header="Vectorize" href="/vectorize/" product="vectorize">

Vector database for AI-powered semantic search.

</RelatedProduct>

<RelatedProduct header="R2" href="/r2/" product="r2">

Zero-egress object storage for cost-efficient data access.

</RelatedProduct>

<RelatedProduct header="Browser Rendering" href="/browser-rendering/" product="browser-rendering">

Programmatic serverless browser instances.

</RelatedProduct>

**Media**

<RelatedProduct header="Cache / CDN" href="/cache/" product="cache">

Global caching for high-performance, low-latency delivery.

</RelatedProduct>

<RelatedProduct header="Images" href="/images/" product="images">

Streamlined image infrastructure from a single API.

</RelatedProduct>


---

Want to connect with the Workers community? [Join our Discord](https://discord.cloudflare.com)

---

# Glossary

URL: https://developers.cloudflare.com/workers/glossary/

import { Glossary } from "~/components";

Review the definitions for terms used across Cloudflare's Workers documentation.

<Glossary product="workers" />

---

# Playground

URL: https://developers.cloudflare.com/workers/playground/

import { LinkButton } from "~/components";

:::note[Browser support]

The Cloudflare Workers Playground is currently only supported in Firefox and Chrome desktop browsers. In Safari, it will show a `PreviewRequestFailed` error message.

:::

The quickest way to experiment with Cloudflare Workers is in the [Playground](https://workers.cloudflare.com/playground). It does not require any setup or authentication. The Playground is a sandbox which gives you an instant way to preview and test a Worker directly in the browser.

The Playground uses the same editor as the authenticated experience. The Playground provides the ability to [share](#share) the code you write as well as [deploy](#deploy) it instantly to Cloudflare's global network. This way, you can try new things out and deploy them when you are ready.

<LinkButton href="https://workers.cloudflare.com/playground" icon="external">
	Launch the Playground
</LinkButton>

## Hello Cloudflare Workers

When you arrive in the Playground, you will see this default code:

```js
import welcome from "welcome.html";

/**
 * @typedef {Object} Env
 */

export default {
	/**
	 * @param {Request} request
	 * @param {Env} env
	 * @param {ExecutionContext} ctx
	 * @returns {Response}
	 */
	fetch(request, env, ctx) {
		console.log("Hello Cloudflare Workers!");

		return new Response(welcome, {
			headers: {
				"content-type": "text/html",
			},
		});
	},
};
```

This is an example of a multi-module Worker that is receiving a [request](/workers/runtime-apis/request/), logging a message to the console, and then returning a [response](/workers/runtime-apis/response/) body containing the content from `welcome.html`.

Refer to the [Fetch handler documentation](/workers/runtime-apis/handlers/fetch/) to learn more.

## Use the Playground

As you edit the default code, the Worker will auto-update such that the preview on the right shows your Worker running just as it would in a browser. If your Worker uses URL paths, you can enter those in the input field on the right to navigate to them. The Playground provides type-checking via JSDoc comments and [`workers-types`](https://www.npmjs.com/package/@cloudflare/workers-types). The Playground also provides pretty error pages in the event of application errors.

To test a raw HTTP request (for example, to test a `POST` request), go to the **HTTP** tab and select **Send**. You can add and edit headers via this panel, as well as edit the body of a request.

## DevTools

For debugging Workers inside the Playground, use the developer tools at the bottom of the Playground's preview panel to view `console.logs`, network requests, memory and CPU usage. The developer tools for the Workers Playground work similarly to the developer tools in Chrome or Firefox, and are the same developer tools users have access to in the [Wrangler CLI](/workers/wrangler/install-and-update/) and the authenticated dashboard.

### Network tab

**Network** shows the outgoing requests from your Worker — that is, any calls to `fetch` inside your Worker code.

### Console Logs

The console displays the output of any calls to `console.log` that were called for the current preview run as well as any other preview runs in that session.

### Sources

**Sources** displays the sources that make up your Worker. Note that KV, text, and secret bindings are only accessible when authenticated with an account. This means you must be logged in to the dashboard, or use [`wrangler dev`](/workers/wrangler/commands/#dev) with your account credentials.

## Share

To share what you have created, select **Copy Link** in the top right of the screen. This will copy a unique URL to your clipboard that you can share with anyone. These links do not expire, so you can bookmark your creation and share it at any time. Users that open a shared link will see the Playground with the shared code and preview.

## Deploy

You can deploy a Worker from the Playground. If you are already logged in, you can review the Worker before deploying. Otherwise, you will be taken through the first-time user onboarding flow before you can review and deploy.

Once deployed, your Worker will get its own unique URL and be available almost instantly on Cloudflare's global network. From here, you can add [Custom Domains](/workers/configuration/routing/custom-domains/), [storage resources](/workers/platform/storage-options/), and more.

---

# Cloudflare Workflows

URL: https://developers.cloudflare.com/workflows/

import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct } from "~/components"

<Description>

Build durable multi-step applications on Cloudflare Workers with Workflows.

</Description>

<Plan type="workers-all" />

Workflows is a durable execution engine built on Cloudflare Workers. Workflows allow you to build multi-step applications that can automatically retry, persist state and run for minutes, hours, days, or weeks. Workflows introduces a programming model that makes it easier to build reliable, long-running tasks, observe as they progress, and programatically trigger instances based on events across your services.

Refer to the [get started guide](/workflows/get-started/guide/) to start building with Workflows.

***

## Features

<Feature header="Deploy your first Workflow" href="/workflows/get-started/guide/" cta="Deploy your first Workflow">

Define your first Workflow, understand how to compose multi-steps, and deploy to production.

</Feature>

<Feature header="Rules of Workflows" href="/workflows/build/rules-of-workflows/" cta="Best practices">

Understand best practices when writing and building applications using Workflows.

</Feature>

<Feature header="Trigger Workflows" href="/workflows/build/trigger-workflows/" cta="Trigger Workflows from Workers">

Learn how to trigger Workflows from your Workers applications, via the REST API, and the command-line.

</Feature>

***

## Related products

<RelatedProduct header="Workers" href="/workers/" product="workers">

Build serverless applications and deploy instantly across the globe for exceptional performance, reliability, and scale.


</RelatedProduct>

<RelatedProduct header="Pages" href="/pages/" product="pages">

Deploy dynamic front-end applications in record time.


</RelatedProduct>

***

## More resources

<CardGrid>

<LinkTitleCard title="Pricing" href="/workflows/reference/pricing/" icon="seti:shell">
Learn more about how Workflows is priced.
</LinkTitleCard>

<LinkTitleCard title="Limits" href="/workflows/reference/limits/" icon="document">
Learn more about Workflow limits, and how to work within them.
</LinkTitleCard>

<LinkTitleCard title="Storage options" href="/workers/platform/storage-options/" icon="document">
Learn more about the storage and database options you can build on with Workers.
</LinkTitleCard>

<LinkTitleCard title="Developer Discord" href="https://discord.cloudflare.com" icon="discord">
Connect with the Workers community on Discord to ask questions, show what you are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard title="@CloudflareDev" href="https://x.com/cloudflaredev" icon="x.com">
Follow @CloudflareDev on Twitter to learn about product announcements, and what is new in Cloudflare Developer Platform.
</LinkTitleCard>

</CardGrid>

---

# Videos

URL: https://developers.cloudflare.com/workflows/videos/

import { CardGrid, LinkCard } from "~/components";

<CardGrid>
    <LinkCard
        title="Build an application using Cloudflare Workflows"
        description="In this series, we introduce Cloudflare Workflows and the term 'Durable Execution' which comes from the desire to run applications that can resume execution from where they left off, even if the underlying host or compute fails."
        href="/learning-paths/workflows-course/series/workflows-1/"
    />
</CardGrid>

---

# Embeds

URL: https://developers.cloudflare.com/zaraz/embeds/

Embeds are tools for incorporating external content, like social media posts, directly onto webpages, enhancing user engagement without compromising site performance and security.

Cloudflare Zaraz introduces server-side rendering for embeds, avoiding third-party JavaScript to improve security, privacy, and page speed. This method processes content on the server side, removing the need for direct communication between the user's browser and third-party servers.

To add an Embed to Your Website:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools Configuration**.
3. Click "add new tool" and activate the desired tools on your Cloudflare Zaraz dashboard.
4. Add a placeholder in your HTML, specifying the necessary attributes. For a generic embed, the snippet looks like this:

```html
<componentName-embedName attribute="value"></componentName-embedName>
```

Replace `componentName`, `embedName` and `attribute="value"` with the specific Managed Component requirements. Zaraz automatically detects placeholders and replaces them with the content in a secure and efficient way.

## Examples

### X (Twitter) embed

```html
<twitter-post tweet-id="12345"></twitter-post>
```

Replace `tweet-id` with the actual tweet ID for the content you wish to embed.

### Instagram embed

```html
<instagram-post post-url="https://www.instagram.com/p/ABC/" captions="true"></instagram-post>
```

Replace `post-url` with the actual URL for the content you wish to embed. To include posts captions set captions attribute to `true`.

---

# Changelog

URL: https://developers.cloudflare.com/zaraz/changelog/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/zaraz.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Get started

URL: https://developers.cloudflare.com/zaraz/get-started/

Before being able to use Zaraz, it is recommended that you proxy your website through Cloudflare. Refer to [Set up Cloudflare](/fundamentals/account/) for more information. If you do not want to proxy your website through Cloudflare, refer to [Use Zaraz on domains not proxied by Cloudflare](/zaraz/advanced/domains-not-proxied/).

## Add a third-party tool to your website

You can add new third-party tools and load them into your website through the Cloudflare dashboard.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account.
2. Select **Tag Management**, then **Tag Setup** from the side menu and select your website.
3. If you have already added a tool before, select **Third-party tools** and click on **Add new tool**.
4. Choose a tool from the tools catalog. Select **Continue** to confirm your selection.
5. In **Set up**, configure the settings for your new tool. The information you need to enter will depend on the tool you choose. If you want to use any dynamic properties or variables, select the `+` sign in the drop-down menu next to the relevant field.
6. In **Actions** setup the actions for your new tool. You should be able to select Pageviews, Events or E-Commerce [^1].
7. Select **Save**.

[^1]: Some tools do not supported Automatic Actions, see the section about [Custom Actions](/zaraz/custom-actions) if the tool you are adding doesn't present Automatic Actions.

## Events, triggers and actions

Zaraz relies on events, triggers and actions to determine when to load the tools you need in your website, and what action they need to perform. The way you configure Zaraz and where you start largely depend on the tool you wish to use. When using a tool that supports Automatic Actions, this process is largely done for you. If the tool you are adding doesn't support Automatic Actions, read more about configuring [Custom Actions](/zaraz/custom-actions).

When using Automatic Actions, the available actions are as follows:

- **Pageviews** - for tracking every pageview on your website
- **Events** - For tracking calls using the [`zaraz.track` Web API](/zaraz/web-api/track)
- **E-commerce** - For tracking calls to [`zaraz.ecommerce` Web API](/zaraz/web-api/ecommerce)

## Web API

If you need to programmatically start actions in your tools, Cloudflare Zaraz provides a unified Web API to send events to Zaraz, and from there, to third-party tools. This Web API includes the `zaraz.track()`, `zaraz.set()` and `zaraz.ecommerce()` methods.

[The Track method](/zaraz/web-api/track/) allows you to track custom events and actions on your website that might happen in real time. [The Set method](/zaraz/web-api/set/) is an easy shortcut to define a variable once and have it sent with every future Track call. [E-commerce](/zaraz/web-api/ecommerce/) is a unified method for sending e-commerce related data to multiple tools without needing to configure triggers and events. Refer to [Web API](/zaraz/web-api/) for more information.

## Troubleshooting

If you suspect that something is not working the way it should, or if you want to verify the operation of tools on your website, read more about [Debug Mode](/zaraz/web-api/debug-mode/) and [Zaraz Monitoring](/zaraz/monitoring/). Also, check the [FAQ](/zaraz/faq/) page to see if your question was already answered there.

## Platform plugins

Users and companies have developed plugins that make using Zaraz easier on specific platforms. We recommend checking out these plugins if you are using one of these platforms.

### WooCommerce

- [Beetle Tracking](https://beetle-tracking.com/) - Integrate Zaraz with your WordPress WooCommerce website to track e-commerce events with zero configuration. Beetle Tracking also supports consent management and other advanced features.

---

# HTTP Events API

URL: https://developers.cloudflare.com/zaraz/http-events-api/

The Zaraz HTTP Events API allows you to send information to Zaraz from places that cannot run the [Web API](/zaraz/web-api/), such as your server or your mobile app. It is useful for tracking events that are happening outside the browser, like successful transactions, sign-ups and more. The API also allows sending multiple events in batches.

## Configure the API endpoint

The API is disabled unless you configure an endpoint for it. The endpoint determines under what URL the API will be accessible. For example, if you set the endpoint to be `/zaraz/api`, and your domain is `example.com`, requests to the API will go to `https://example.com/zaraz/api`.

To enable the API endpoint:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Zaraz** > **Settings**.
3. Under **Endpoints** > **HTTP Events API**, set your desired path. Remember the path is relative to your domain, and it must start with a `/`.

:::caution[Important]
To avoid getting the API used by unwanted actors, Cloudflare recommends choosing a unique path.
:::

## Send events

The endpoint you have configured for the API will receive `POST` requests with a JSON payload. Below, there is an example payload:

```json
{
  "events": [
    {
      "client": {
        "__zarazTrack": "transaction successful",
        "value": "200"
      }
    }
  ]
}
```

The payload must contain an `events` array. Each Event Object in this array corresponds to one event you want Zaraz to process. The above example is similar to calling `zaraz.track('transaction successful', { value: "200" })` using the Web API.

The Event Object holds the `client` object, in which you can pass information about the event itself. Every key you include in the Event Object will be available as a *Track Property* in the Zaraz dashboard.

There are two reserved keys:

* `__zarazTrack`: The value of this key will be available as *Event Name*. This is what you will usually build your triggers around. In the above example, setting this to `transaction successful` is the same as [using the Web API](/zaraz/web-api/track/) and calling `zaraz.track("transaction successful")`.
* `__zarazEcommerce`: This key needs to be set to `true` if you want Zaraz to process the event as an e-commerce event.

### The `system` key

In addition to the `client` key, you can use the `system` key to include information about the device from which the event originated. For example, you can submit the `User-Agent` string, the cookies and the screen resolution. Zaraz will use this information when connecting to different third-party tools. Since some tools depend on certain fields, it is often useful to include all the information you can.

The same payload from before will resemble the following example, when we add the `system` information:

```json
{
  "events": [
    {
      "client": {
        "__zarazTrack": "transaction successful",
        "value": "200"
      },
      "system": {
        "page": {
          "url": "https://example.com",
          "title": "My website"
        },
        "device": {
          "language": "en-US",
          "ip": "192.168.0.1"
        }
      }
    }
  ]
}
```

For all available system keys, refer to the table below:

| Property                   | Type  | Description                                                                                |
| -------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------ |
| `system.cookies`           | Object                         | A key-value object holding cookies from the device associated with the event.              |
| `system.device.ip`         | String                         | The IP address of the device associated with the event.                                    |
| `system.device.resolution` | String                         | The screen resolution of the device associated with the event, in a `WIDTHxHEIGHT` format. |
| `system.device.viewport`   | String                         | The viewport of the device associated with the event, in a `WIDTHxHEIGHT` format.          |
| `system.device.language`   | String                         | The language code used by the device associated with the event.                            |
| `system.device.user-agent` | String                         | The `User-Agent` string of the device associated with the event.                           |
| `system.page.title`        | String                         | The title of the page associated with the event.                                           |
| `system.page.url`          | String                         | The URL of the page associated with the event.                                             |
| `system.page.referrer`     | String                         | The URL of the referrer page in the time the event took place.                             |
| `system.page.encoding`     | String                         | The encoding of the page associated with the event.                                        |

:::note

It is currently not possible to override location related properties, such as City, Country, and Continent. 
:::

## Process API responses

For each Event Object in your payload, Zaraz will respond with a Result Object. The Result Objects order matches the order of your Event Objects.

Depending on what tools you are loading using Zaraz, the body of the response coming from the API might include information you will want to process. This is because some tools do not have a complete server-side implementation and still depend on cookies, client-side JavaScript or similar mechanisms. Each Result Object can include the following information:

| Result key | Description |
| --- | --- |
| `fetch` | Fetch requests that tools want to send from the user browser. |
| `execute` | JavaScript code that tools want to execute in the user browser. |
| `return` | Information that tools return. |
| `cookies` | Cookies that tools want to set for the user. |

You do not have to process the information above, but some tools might depend on this to work properly. You can start using the HTTP Events API without processing the information in the table above, and adjust accordingly later.

---

# Cloudflare Zaraz

URL: https://developers.cloudflare.com/zaraz/

import {
	CardGrid,
	Description,
	Feature,
	LinkTitleCard,
	Plan,
	Render,
} from "~/components";

<Description>

Offload third-party tools and services to the cloud and improve the speed and security of your website.

</Description>

<Plan id="zaraz.zaraz.properties.availability.summary" />

<Render file="zaraz-definition" />

---

## Features

<Feature header="Third-party tools" href="/zaraz/get-started/">
	You can add many third-party tools to Zaraz, and offload them from your
	website.
</Feature>

<Feature
	header="Custom Managed Components"
	href="/zaraz/advanced/load-custom-managed-component/"
>
	You can add Custom Managed Components to Zaraz and run them as a tool.
</Feature>

<Feature header="Web API" href="/zaraz/web-api/">
Zaraz provides a client-side web API that you can use anywhere inside the `<body>` tag of a page.
</Feature>

<Feature header="Consent management" href="/zaraz/consent-management/">
	Zaraz provides a Consent Management platform to help you address and manage
	required consents.
</Feature>

---

## More resources

<CardGrid>

<LinkTitleCard title="Discord Channel" href="https://discord.cloudflare.com" icon="discord">

If you have any comments, questions, or bugs to report, contact the Zaraz team on their Discord channel.

</LinkTitleCard>

<LinkTitleCard title="Community Forum" href="https://community.cloudflare.com/c/developers/zaraz/67" icon="open-book">

Engage with other users and the Zaraz team on Cloudflare support forum.

</LinkTitleCard>

</CardGrid>

---

# FAQ

URL: https://developers.cloudflare.com/zaraz/faq/

import { GlossaryTooltip } from "~/components";

Below you will find answers to our most commonly asked questions. If you cannot find the answer you are looking for, refer to the [community page](https://community.cloudflare.com/) or [Discord channel](https://discord.cloudflare.com) to explore additional resources.

- [General](#general)
- [Tools](#tools)
- [Consent](#consent)

If you're looking for information regarding Zaraz Pricing, see the [Zaraz Pricing](/zaraz/pricing-info/) page.

---

## General

### Setting up Zaraz

#### Why is Zaraz not working?

If you are experiencing issues with Zaraz, there could be multiple reasons behind it. First, it's important to verify that the Zaraz script is loading properly on your website.

To check if the script is loading correctly, follow these steps:

1. Open your website in a web browser.
2. Open your browser's Developer Tools.
3. In the Console, type `zaraz`.
4. If you see an error message saying `zaraz is not defined`, it means that Zaraz failed to load.

If Zaraz is not loading, please verify the following:

- The domain running Zaraz [is proxied by Cloudflare](/dns/proxy-status/).
- Auto Injection is enabled in your [Zaraz Settings](/zaraz/reference/settings/#auto-inject-script).
- Your website's HTML is valid and includes `<head>` and `</head>` tags.
- You have at least [one enabled tool](/zaraz/get-started/) configured in Zaraz.

#### The browser extension I'm using cannot find the tool I have added. Why?

Zaraz is loading tools server-side, which means code running in the browser will not be able to see it. Running tools server-side is better for your website performance and privacy, but it also means you cannot use normal browser extensions to debug your Zaraz tools.

#### I'm seeing some data discrepancies. Is there a way to check what data reaches Zaraz?

Yes. You can use the metrics in [Zaraz Monitoring](/zaraz/monitoring/) and [Debug Mode](/zaraz/web-api/debug-mode/) to help you find where in the workflow the problem occurred.

#### Can I use Zaraz with Rocket Loader?

We recommend disabling [Rocket Loader](/speed/optimization/content/rocket-loader/) when using Zaraz. While Zaraz can be used together with Rocket Loader, there's usually no need to use both. Rocket Loader can sometimes delay data from reaching Zaraz, causing issues.

#### Is Zaraz compatible with Content Security Policies (CSP)?

Yes. To learn more about how Zaraz works to be compatible with <GlossaryTooltip term="content security policy (CSP)">CSP</GlossaryTooltip> configurations, refer to the [Cloudflare Zaraz supports CSP](https://blog.cloudflare.com/cloudflare-zaraz-supports-csp/) blog post.

#### Does Cloudflare process my HTML, removing existing scripts and then injecting Zaraz?

Cloudflare Zaraz does not remove other third-party scripts from the page. Zaraz [can be auto-injected or not](/zaraz/reference/settings/#auto-inject-script), depending on your configuration, but if you have existing scripts that you intend to load with Zaraz, you should remove them.

#### Does Zaraz work with Cloudflare Page Shield?

Yes. Refer to [Page Shield](/page-shield/) for more information related to this product.

#### Is there a way to prevent Zaraz from loading on specific pages, like under `/wp-admin`?

To prevent Zaraz from loading on specific pages, refer to [Load Zaraz selectively](/zaraz/advanced/load-selectively/).

#### How can I remove my Zaraz configuration?

Resetting your Zaraz configuration will erase all of your configuration settings, including any tools, triggers, and variables you've set up. This action will disable Zaraz immediately. If you want to start over with a clean slate, you can always reset your configuration.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Zaraz** > **Settings** > **Advanced**.
3. Click "Reset" and follow the instructions.

### Zaraz Web API

#### Why would the `zaraz.ecommerce()` method returns an undefined error?

E-commerce tracking needs to be enabled in [the Zaraz Settings page](/zaraz/reference/settings/#e-commerce-tracking) before you can start using the E-commerce Web API.

#### How would I trigger pageviews manually on a Single Page Application (SPA)?

Zaraz comes with built-in [Single Page Application (SPA) support](/zaraz/reference/settings/#single-page-application-support) that automatically sends pageview events when navigating through the pages of your SPA. However, if you have advanced use cases, you might want to build your own system to trigger pageviews. In such cases, you can use the internal SPA pageview event by calling `zaraz.spaPageview()`.

---

## Tools

### Google Analytics

#### After moving from Google Analytics 4 to Zaraz, I can no longer see demographics data. Why?

You probably have enabled **Hide Originating IP Address** in the [Settings option](/zaraz/custom-actions/edit-tools-and-actions/) for Google Analytics 4. This tells Zaraz to not send the IP address to Google. To have access to demographics data and anonymize your visitor's IP, you should use [**Anonymize Originating IP Address**](#i-see-two-ways-of-anonymizing-ip-address-information-on-the-third-party-tool-google-analytics-one-in-privacy-and-one-in-additional-fields-which-is-the-correct-one) instead.

#### I see two ways of anonymizing IP address information on the third-party tool Google Analytics: one in Privacy, and one in Additional fields. Which is the correct one?

There is not a correct option, as the two options available in Google Analytics (GA) do different things.

The "Hide Originating IP Address" option in [Tool Settings](/zaraz/custom-actions/edit-tools-and-actions/) prevents Zaraz from sending the IP address from a visitor to Google. This means that GA treats Zaraz's Worker's IP address as the visitor's IP address. This is often close in terms of location, but it might not be.

With the **Anonymize Originating IP Address** available in the [Add field](/zaraz/custom-actions/additional-fields/) option, Cloudflare sends the visitor's IP address to Google as is, and passes the 'aip' parameter to GA. This asks GA to anonymize the data.

#### If I set up Event Reporting (enhanced measurements) for Google Analytics, why does Zaraz only report Page View, Session Start, and First Visit?

This is not a bug. Zaraz does not offer all the automatic events the normal GA4 JavaScript snippets offer out of the box. You will need to build [triggers](/zaraz/custom-actions/create-trigger/) and [actions](/zaraz/custom-actions/) to capture those events. Refer to [Get started](/zaraz/get-started/) to learn more about how Zaraz works.

#### Can I set up custom dimensions for Google Analytics with Zaraz?

Yes. Refer to [Additional fields](/zaraz/custom-actions/additional-fields/) to learn how to send additional data to tools.

#### How do I attach a User Property to my events?

In your Google Analytics 4 action, select **Add field** > **Add custom field...** and enter a field name that starts with `up.` — for example, `up.name`. This will make Zaraz send the field as a User Property and not as an Event Property.

#### How can I enable Google Consent Mode signals?

Zaraz has built-in support for Google Consent Mode v2. Learn more on how to use it in [Google Consent Mode page](/zaraz/advanced/google-consent-mode/).

### Facebook Pixel

#### If I set up Facebook Pixel on my Zaraz account, why am I not seeing data coming through?

It can take between 15 minutes to several hours for data to appear on Facebook's interface, due the way Facebook Pixel works. You can also use [debug mode](/zaraz/web-api/debug-mode/) to confirm that data is being properly sent from your Zaraz account.

### Google Ads

#### What is the expected format for Conversion ID and Conversion Label

Conversion ID and Conversion Label are usually provided by Google Ads as a "gtag script". Here's an example for a $1 USD conversion:

```js
gtag("event", "conversion", {
	send_to: "AW-123456789/AbC-D_efG-h12_34-567",
	value: 1.0,
	currency: "USD",
});
```

The Conversion ID is the first part of `send_to` parameter, without the `AW-`. In the above example it would be `123456789`. The Conversion Label is the second part of the `send_to` parameter, therefore `AbC-D_efG-h12_34-567` in the above example. When setting up your Google Ads conversions through Zaraz, take the information from the original scripts you were asked to implement.

### Custom HTML

#### Can I use Google Tag Manager together with Zaraz?

You can load Google Tag Manager using Zaraz, but it is not recommended. Tools configured inside Google Tag Manager cannot be optimized by Zaraz, and cannot be restricted by the Zaraz privacy controls. In addition, Google Tag Manager could slow down your website because it requires additional JavaScript, and its rules are evaluated client-side. If you are currently using Google Tag Manager, we recommend replacing it with Zaraz by configuring your tags directly as Zaraz tools.

#### Why should I prefer a native tool integration instead of an HTML snippet?

Adding a tool to your website via a native Zaraz integration is always better than using an HTML snippet. HTML snippets usually depends on additional client-side requests, and require client-side code execution, which can slow down your website. They are often a security risk, as they can be hacked. Moreover, it can be very difficult to control their affect on the privacy of your visitors. Tools included in the Zaraz library are not suffering from these issues - they are fast, executed at the edge, and be controlled and restricted because they are sandboxed.

#### How can I set my Custom HTML to be injected just once in my Single Page App (SPA) website?

If you have enabled "Single Page Application support" in Zaraz Settings, your Custom HTML code may be unnecessarily injected every time a new SPA page is loaded. This can result in duplicates. To avoid this, go to your Custom HTML action and select the "Add Field" option. Then, add the "Ignore SPA" field and enable the toggle switch. Doing so will prevent your code from firing on every SPA pageview and ensure that it is injected only once.

### Other tools

#### What if I want to use a tool that is not supported by Zaraz?

The Zaraz engineering team is adding support to new tools all the time. You can also refer to the [community space](https://community.cloudflare.com/c/developers/integrationrequest/68) to ask for new integrations.

#### I cannot get a tool to load when the website is loaded. Do I have to add code to my website?

If you proxy your domain through Cloudflare, you do not need to add any code to your website. By default, Zaraz includes an automated `Pageview` trigger. Some tools, like Google Analytics, automatically add a `Pageview` action that uses this trigger. With other tools, you will need to add it manually. Refer to [Get started](/zaraz/get-started/) for more information.

#### I am a vendor. How can I integrate my tool with Zaraz?

The Zaraz team is working with third-party vendors to build their own Zaraz integrations using the Zaraz SDK. To request a new tool integration, or to collaborate on our SDK, contact us at [zaraz@cloudflare.com](mailto:zaraz@cloudflare.com).

---

## Consent

### How do I show the consent modal again to all users?

In such a case, you can change the cookie name in the _Consent cookie name_ field in the Zaraz Consent configuration. This will cause the consent modal to reappear for all users. Make sure to use a cookie name that has not been used for Zaraz on your site.

---

# Pricing

URL: https://developers.cloudflare.com/zaraz/pricing-info/

Zaraz is available to all Cloudflare users, across all tiers. Each month, every Cloudflare account gets 1,000,000 free Zaraz Events. For additional usage, the Zaraz Paid plan costs $5 per month for each additional 1,000,000 Zaraz Events.

All Zaraz features and tools are always available on all accounts. Learn more about our pricing in [the following pricing announcement](https://blog.cloudflare.com/zaraz-announces-new-pricing)

## The Zaraz Event unit

One Zaraz Event is an event you’re sending to Zaraz, whether that’s a page view, a `zaraz.track` event, or similar. You can easily see the total number of Zaraz Events you’re currently using under the [Monitoring section](/zaraz/monitoring/) in the Cloudflare Zaraz Dashboard.

## Enabling Zaraz Paid

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Plans**.
3. Click the **Enable Zaraz usage billing** button and follow the instructions.

## Using Zaraz Free

If you don't enable Zaraz Paid, you'll receive email notifications when you reach 50%, 80%, and 90% of your free allocation. Zaraz will be disabled until the next billing cycle if you exceed 1,000,000 events without enabling Zaraz Paid.

---

# Agents API

URL: https://developers.cloudflare.com/agents/api-reference/agents-api/

import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";

This page provides an overview of the Agent SDK API, including the `Agent` class, methods and properties built-in to the Agents SDK.

The Agents SDK exposes two main APIs:

* The server-side `Agent` class. An Agent encapsulates all of the logic for an Agent, including how clients can connect to it, how it stores state, the methods it exposes, how to call AI models, and any error handling.
* The client-side `AgentClient` class, which allows you to connect to an Agent instance from a client-side application. The client APIs also include React hooks, including `useAgent` and `useAgentChat`, and allow you to automatically synchronize state between each unique Agent (running server-side) and your client applications.

:::note

Agents require [Cloudflare Durable Objects](/durable-objects/), see [Configuration](/agents/getting-started/testing-your-agent/#add-the-agent-configuration) to learn how to add the required bindings to your project. 

:::


You can also find more specific usage examples for each API in the [Agents API Reference](/agents/api-reference/).

<TypeScriptExample>

```ts
import { Agent } from "agents";

class MyAgent extends Agent {
	// Define methods on the Agent
}

export default MyAgent;
```

</TypeScriptExample>

An Agent can have many (millions of) instances: each instance is a separate micro-server that runs independently of the others. This allows Agents to scale horizontally: an Agent can be associated with a single user, or many thousands of users, depending on the agent you're building.

Instances of an Agent are addressed by a unique identifier: that identifier (ID) can be the user ID, an email address, GitHub username, a flight ticket number, an invoice ID, or any other identifier that helps to uniquely identify the instance and for whom it is acting on behalf of.

<Render file="unique-agents" />

### Agent class API

Writing an Agent requires you to define a class that extends the `Agent` class from the Agents SDK package. An Agent encapsulates all of the logic for an Agent, including how clients can connect to it, how it stores state, the methods it exposes, and any error handling.

You can also define your own methods on an Agent: it's technically valid to publish an Agent only has your own methods exposed, and create/get Agents directly from a Worker.

Your own methods can access the Agent's environment variables and bindings on `this.env`, state on `this.setState`, and call other methods on the Agent via `this.yourMethodName`.

```ts
import { Agent } from "agents";

interface Env {
	// Define environment variables & bindings here
}

// Pass the Env as a TypeScript type argument
// Any services connected to your Agent or Worker as Bindings
// are then available on this.env.<BINDING_NAME>

// The core class for creating Agents that can maintain state, orchestrate
// complex AI workflows, schedule tasks, and interact with users and other
// Agents.
class MyAgent extends Agent<Env, State> {
  // Optional initial state definition
  initialState = {
    counter: 0,
    messages: [],
    lastUpdated: null
  };

  // Called when a new Agent instance starts or wakes from hibernation
  async onStart() {
    console.log('Agent started with state:', this.state);
  }

  // Handle HTTP requests coming to this Agent instance
  // Returns a Response object
  async onRequest(request: Request): Promise<Response> {
    return new Response("Hello from Agent!");
  }

  // Called when a WebSocket connection is established
  // Access the original request via ctx.request for auth etc.
  async onConnect(connection: Connection, ctx: ConnectionContext) {
  	// Connections are automatically accepted by the SDK.
    // You can also explicitly close a connection here with connection.close()
    // Access the Request on ctx.request to inspect headers, cookies and the URL
  }

  // Called for each message received on a WebSocket connection
  // Message can be string, ArrayBuffer, or ArrayBufferView
  async onMessage(connection: Connection, message: WSMessage) {
    // Handle incoming messages
    connection.send("Received your message");
  }

  // Handle WebSocket connection errors
  async onError(connection: Connection, error: unknown): Promise<void> {
    console.error(`Connection error:`, error);
  }

  // Handle WebSocket connection close events
  async onClose(connection: Connection, code: number, reason: string, wasClean: boolean): Promise<void> {
    console.log(`Connection closed: ${code} - ${reason}`);
  }

  // Called when the Agent's state is updated from any source
  // source can be "server" or a client Connection
  onStateUpdate(state: State, source: "server" | Connection) {
    console.log("State updated:", state, "Source:", source);
  }

  // You can define your own custom methods to be called by requests,
  // WebSocket messages, or scheduled tasks
  async customProcessingMethod(data: any) {
    // Process data, update state, schedule tasks, etc.
    this.setState({ ...this.state, lastUpdated: new Date() });
  }
}
```

<TypeScriptExample>

```ts
// Basic Agent implementation with custom methods
import { Agent } from "agents";

interface MyState {
  counter: number;
  lastUpdated: Date | null;
}

class MyAgent extends Agent<Env, MyState> {
  initialState = {
    counter: 0,
    lastUpdated: null
  };

  async onRequest(request: Request) {
    if (request.method === "POST") {
      await this.incrementCounter();
      return new Response(JSON.stringify(this.state), {
        headers: { "Content-Type": "application/json" }
      });
    }
    return new Response(JSON.stringify(this.state), {
      headers: { "Content-Type": "application/json" }
    });
  }

  async incrementCounter() {
    this.setState({
      counter: this.state.counter + 1,
      lastUpdated: new Date()
    });
  }
}
```

</TypeScriptExample>

### WebSocket API

The WebSocket API allows you to accept and manage WebSocket connections made to an Agent.

#### Connection

Represents a WebSocket connection to an Agent.

```ts
// WebSocket connection interface
interface Connection<State = unknown> {
  // Unique ID for this connection
  id: string;

  // Client-specific state attached to this connection
  state: State;

  // Update the connection's state
  setState(state: State): void;

  // Accept an incoming WebSocket connection
  accept(): void;

  // Close the WebSocket connection with optional code and reason
  close(code?: number, reason?: string): void;

  // Send a message to the client
  // Can be string, ArrayBuffer, or ArrayBufferView
  send(message: string | ArrayBuffer | ArrayBufferView): void;
}
```

<TypeScriptExample>

```ts
// Example of handling WebSocket messages
export class YourAgent extends Agent {
  async onMessage(connection: Connection, message: WSMessage) {
    if (typeof message === 'string') {
      try {
        // Parse JSON message
        const data = JSON.parse(message);

        if (data.type === 'update') {
          // Update connection-specific state
          connection.setState({ ...connection.state, lastActive: Date.now() });

          // Update global Agent state
          this.setState({
            ...this.state,
            connections: this.state.connections + 1
          });

          // Send response back to this client only
          connection.send(JSON.stringify({
            type: 'updated',
            status: 'success'
          }));
        }
      } catch (e) {
        connection.send(JSON.stringify({ error: 'Invalid message format' }));
      }
    }
  }
}
```

</TypeScriptExample>

#### WSMessage

Types of messages that can be received from a WebSocket.

```ts
// Types of messages that can be received from WebSockets
type WSMessage = string | ArrayBuffer | ArrayBufferView;
```

#### ConnectionContext

Context information for a WebSocket connection.

```ts
// Context available during WebSocket connection
interface ConnectionContext {
  // The original HTTP request that initiated the WebSocket connection
  request: Request;
}
```

### State synchronization API

:::note

To learn more about how to manage state within an Agent, refer to the documentation on [managing and syncing state](/agents/api-reference/store-and-sync-state/).

:::

#### State

Methods and types for managing Agent state.

```ts
// State management in the Agent class
class Agent<Env, State = unknown> {
  // Initial state that will be set if no state exists yet
  initialState: State = {} as unknown as State;

  // Current state of the Agent, persisted across restarts
  get state(): State;

  // Update the Agent's state
  // Persists to storage and notifies all connected clients
  setState(state: State): void;

  // Called when state is updated from any source
  // Override to react to state changes
  onStateUpdate(state: State, source: "server" | Connection): void;
}
```

<TypeScriptExample>

```ts
// Example of state management in an Agent
interface ChatState {
  messages: Array<{ sender: string; text: string; timestamp: number }>;
  participants: string[];
  settings: {
    allowAnonymous: boolean;
    maxHistoryLength: number;
  };
}

interface Env {
	// Your bindings and environment variables
}

// Inside your Agent class
export class YourAgent extends Agent<Env, ChatState> {
  async addMessage(sender: string, text: string) {
    // Update state with new message
    this.setState({
      ...this.state,
      messages: [
        ...this.state.messages,
        { sender, text, timestamp: Date.now() }
      ].slice(-this.state.settings.maxHistoryLength) // Maintain max history
    });

    // The onStateUpdate method will automatically be called
    // and all connected clients will receive the update
  }

  // Override onStateUpdate to add custom behavior when state changes
  onStateUpdate(state: ChatState, source: "server" | Connection) {
    console.log(`State updated by ${source === "server" ? "server" : "client"}`);

    // You could trigger additional actions based on state changes
    if (state.messages.length > 0) {
      const lastMessage = state.messages[state.messages.length - 1];
      if (lastMessage.text.includes('@everyone')) {
        this.notifyAllParticipants(lastMessage);
      }
    }
  }
}
```

</TypeScriptExample>

### Scheduling API

#### Scheduling tasks

Schedule tasks to run at a specified time in the future.

```ts
// Scheduling API for running tasks in the future
class Agent<Env, State = unknown> {
  // Schedule a task to run in the future
  // when: seconds from now, specific Date, or cron expression
  // callback: method name on the Agent to call
  // payload: data to pass to the callback
  // Returns a Schedule object with the task ID
  async schedule<T = any>(
    when: Date | string | number,
    callback: keyof this,
    payload?: T
  ): Promise<Schedule<T>>;

  // Get a scheduled task by ID
  // Returns undefined if the task doesn't exist
  async getSchedule<T = any>(id: string): Promise<Schedule<T> | undefined>;

  // Get all scheduled tasks matching the criteria
  // Returns an array of Schedule objects
  getSchedules<T = any>(criteria?: {
    description?: string;
    id?: string;
    type?: "scheduled" | "delayed" | "cron";
    timeRange?: { start?: Date; end?: Date };
  }): Schedule<T>[];

  // Cancel a scheduled task by ID
  // Returns true if the task was cancelled, false otherwise
  async cancelSchedule(id: string): Promise<boolean>;
}
```

<TypeScriptExample>

```ts
// Example of scheduling in an Agent
interface ReminderData {
  userId: string;
  message: string;
  channel: string;
}

export class YourAgent extends Agent {
  // Schedule a one-time reminder in 2 hours
  async scheduleReminder(userId: string, message: string) {
    const twoHoursFromNow = new Date(Date.now() + 2 * 60 * 60 * 1000);

    const schedule = await this.schedule<ReminderData>(
      twoHoursFromNow,
      'sendReminder',
      { userId, message, channel: 'email' }
    );

    console.log(`Scheduled reminder with ID: ${schedule.id}`);
    return schedule.id;
  }

  // Schedule a recurring daily task using cron
  async scheduleDailyReport() {
    // Run at 08:00 AM every day
    const schedule = await this.schedule(
      '0 8 * * *',  // Cron expression: minute hour day month weekday
      'generateDailyReport',
      { reportType: 'daily-summary' }
    );

    console.log(`Scheduled daily report with ID: ${schedule.id}`);
    return schedule.id;
  }

  // Method that will be called when the scheduled task runs
  async sendReminder(data: ReminderData) {
    console.log(`Sending reminder to ${data.userId}: ${data.message}`);
    // Add code to send the actual notification
  }
}
```

</TypeScriptExample>

#### Schedule object

Represents a scheduled task.

```ts
// Represents a scheduled task
type Schedule<T = any> = {
  // Unique identifier for the schedule
  id: string;
  // Name of the method to be called
  callback: string;
  // Data to be passed to the callback
  payload: T;
} & (
  | {
      // One-time execution at a specific time
      type: "scheduled";
      // Timestamp when the task should execute
      time: number;
    }
  | {
      // Delayed execution after a certain time
      type: "delayed";
      // Timestamp when the task should execute
      time: number;
      // Number of seconds to delay execution
      delayInSeconds: number;
    }
  | {
      // Recurring execution based on cron expression
      type: "cron";
      // Timestamp for the next execution
      time: number;
      // Cron expression defining the schedule
      cron: string;
    }
);
```

<TypeScriptExample>

```ts
export class YourAgent extends Agent {
  // Example of managing scheduled tasks
  async viewAndManageSchedules() {
    // Get all scheduled tasks
    const allSchedules = this.getSchedules();
    console.log(`Total scheduled tasks: ${allSchedules.length}`);

    // Get tasks scheduled for a specific time range
    const upcomingSchedules = this.getSchedules({
      timeRange: {
        start: new Date(),
        end: new Date(Date.now() + 24 * 60 * 60 * 1000) // Next 24 hours
      }
    });

    // Get a specific task by ID
    const taskId = "task-123";
    const specificTask = await this.getSchedule(taskId);

    if (specificTask) {
      console.log(`Found task: ${specificTask.callback} at ${new Date(specificTask.time)}`);

      // Cancel a scheduled task
      const cancelled = await this.cancelSchedule(taskId);
      console.log(`Task cancelled: ${cancelled}`);
    }
  }
}
```

</TypeScriptExample>

### SQL API

Each Agent instance has an embedded SQLite database that can be accessed using the `this.sql` method within any method on your `Agent` class.

#### SQL queries

Execute SQL queries against the Agent's built-in SQLite database using the `this.sql` method within any method on your `Agent` class.

```ts
// SQL query API for the Agent's embedded database
class Agent<Env, State = unknown> {
  // Execute a SQL query with tagged template literals
  // Returns an array of rows matching the query
  sql<T = Record<string, string | number | boolean | null>>(
    strings: TemplateStringsArray,
    ...values: (string | number | boolean | null)[]
  ): T[];
}
```

<TypeScriptExample>

```ts
// Example of using SQL in an Agent
interface User {
  id: string;
  name: string;
  email: string;
  created_at: number;
}

export class YourAgent extends Agent {
  async setupDatabase() {
    // Create a table if it doesn't exist
    this.sql`
      CREATE TABLE IF NOT EXISTS users (
        id TEXT PRIMARY KEY,
        name TEXT NOT NULL,
        email TEXT UNIQUE,
        created_at INTEGER
      )
    `;
  }

  async createUser(id: string, name: string, email: string) {
    // Insert a new user
    this.sql`
      INSERT INTO users (id, name, email, created_at)
      VALUES (${id}, ${name}, ${email}, ${Date.now()})
    `;
  }

  async getUserById(id: string): Promise<User | null> {
    // Query a user by ID
    const users = this.sql<User>`
      SELECT * FROM users WHERE id = ${id}
    `;

    return users.length ? users[0] : null;
  }

  async searchUsers(term: string): Promise<User[]> {
    // Search users with a wildcard
    return this.sql<User>`
      SELECT * FROM users
      WHERE name LIKE ${'%' + term + '%'} OR email LIKE ${'%' + term + '%'}
      ORDER BY created_at DESC
    `;
  }
}
```

</TypeScriptExample>

:::note

Visit the [state management API documentation](/agents/api-reference/store-and-sync-state/) within the Agents SDK, including the native `state` APIs and the built-in `this.sql` API for storing and querying data within your Agents.

:::


### Client API

The Agents SDK provides a set of client APIs for interacting with Agents from client-side JavaScript code, including:

* React hooks, including `useAgent` and `useAgentChat`, for connecting to Agents from client applications.
* Client-side [state syncing](/agents/api-reference/store-and-sync-state/) that allows you to subscribe to state updates between the Agent and any connected client(s) when calling `this.setState` within your Agent's code.
* The ability to call remote methods (Remote Procedure Calls; RPC) on the Agent from client-side JavaScript code using the `@callable` method decorator.

#### AgentClient

Client for connecting to an Agent from the browser.

```ts
import { AgentClient } from "agents/client";

// Options for creating an AgentClient
type AgentClientOptions = Omit<PartySocketOptions, "party" | "room"> & {
  // Name of the agent to connect to (class name in kebab-case)
  agent: string;
  // Name of the specific Agent instance (optional, defaults to "default")
  name?: string;
  // Other WebSocket options like host, protocol, etc.
};

// WebSocket client for connecting to an Agent
class AgentClient extends PartySocket {
  static fetch(opts: PartyFetchOptions): Promise<Response>;
  constructor(opts: AgentClientOptions);
}
```

<TypeScriptExample>

```ts
// Example of using AgentClient in the browser
import { AgentClient } from "agents/client";

// Connect to an Agent instance
const client = new AgentClient({
  agent: "chat-agent", // Name of your Agent class in kebab-case
  name: "support-room-123", // Specific instance name
  host: window.location.host, // Using same host
});

client.onopen = () => {
  console.log("Connected to agent");
  // Send an initial message
  client.send(JSON.stringify({ type: "join", user: "user123" }));
};

client.onmessage = (event) => {
	// Handle incoming messages
	const data = JSON.parse(event.data);
	console.log("Received:", data);

	if (data.type === "state_update") {
		// Update local UI with new state
		updateUI(data.state);
	}
};

client.onclose = () => console.log("Disconnected from agent");

// Send messages to the Agent
function sendMessage(text) {
  client.send(JSON.stringify({
    type: "message",
    text,
    timestamp: Date.now()
  }));
}
```

</TypeScriptExample>

#### agentFetch

Make an HTTP request to an Agent.

```ts
import { agentFetch } from "agents/client";

// Options for the agentFetch function
type AgentClientFetchOptions = Omit<PartyFetchOptions, "party" | "room"> & {
  // Name of the agent to connect to
  agent: string;
  // Name of the specific Agent instance (optional)
  name?: string;
};

// Make an HTTP request to an Agent
function agentFetch(
  opts: AgentClientFetchOptions,
  init?: RequestInit
): Promise<Response>;
```

<TypeScriptExample>

```ts
// Example of using agentFetch in the browser
import { agentFetch } from "agents/client";

// Function to get data from an Agent
async function fetchAgentData() {
  try {
    const response = await agentFetch(
      {
        agent: "task-manager",
        name: "user-123-tasks"
      },
      {
        method: "GET",
        headers: {
          "Authorization": `Bearer ${userToken}`
        }
      }
    );

    if (!response.ok) {
      throw new Error(`Error: ${response.status}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error("Failed to fetch from agent:", error);
  }
}
```

</TypeScriptExample>

### React API

The Agents SDK provides a React API for simplifying connection and routing to Agents from front-end frameworks, including React Router (Remix), Next.js, and Astro.

#### useAgent

React hook for connecting to an Agent.

```ts
import { useAgent } from "agents/react";

// Options for the useAgent hook
type UseAgentOptions<State = unknown> = Omit<
  Parameters<typeof usePartySocket>[0],
  "party" | "room"
> & {
  // Name of the agent to connect to
  agent: string;
  // Name of the specific Agent instance (optional)
  name?: string;
  // Called when the Agent's state is updated
  onStateUpdate?: (state: State, source: "server" | "client") => void;
};

// React hook for connecting to an Agent
// Returns a WebSocket connection with setState method
function useAgent<State = unknown>(
  options: UseAgentOptions<State>
): PartySocket & {
  // Update the Agent's state
  setState: (state: State) => void
};
```

### Chat Agent

The Agents SDK exposes an `AIChatAgent` class that extends the `Agent` class and exposes an `onChatMessage` method that simplifies building interactive chat agents.

You can combine this with the `useAgentChat` React hook from the `agents/ai-react` package to manage chat state and messages between a user and your Agent(s).

#### AIChatAgent

Extension of the `Agent` class with built-in chat capabilities.

```ts
import { AIChatAgent } from "agents/ai-chat-agent";
import { Message, StreamTextOnFinishCallback, ToolSet } from "ai";

// Base class for chat-specific agents
class AIChatAgent<Env = unknown, State = unknown> extends Agent<Env, State> {
  // Array of chat messages for the current conversation
  messages: Message[];

  // Handle incoming chat messages and generate a response
  // onFinish is called when the response is complete
  async onChatMessage(
    onFinish: StreamTextOnFinishCallback<ToolSet>
  ): Promise<Response | undefined>;

  // Persist messages within the Agent's local storage.
  async saveMessages(messages: Message[]): Promise<void>;
}
```

<TypeScriptExample>

```ts
// Example of extending AIChatAgent
import { AIChatAgent } from "agents/ai-chat-agent";
import { Message } from "ai";

interface Env {
  AI: any; // Your AI binding
}

class CustomerSupportAgent extends AIChatAgent<Env> {
  // Override the onChatMessage method to customize behavior
  async onChatMessage(onFinish) {
    // Access the AI models using environment bindings
    const { openai } = this.env.AI;

    // Get the current conversation history
    const chatHistory = this.messages;

    // Generate a system prompt based on knowledge base
    const systemPrompt = await this.generateSystemPrompt();

    // Generate a response stream
    const stream = await openai.chat({
      model: "gpt-4o",
      messages: [
        { role: "system", content: systemPrompt },
        ...chatHistory
      ],
      stream: true
    });

    // Return the streaming response
    return new Response(stream, {
      headers: { "Content-Type": "text/event-stream" }
    });
  }

  // Helper method to generate a system prompt
  async generateSystemPrompt() {
    // Query knowledge base or use static prompt
    return `You are a helpful customer support agent.
            Respond to customer inquiries based on the following guidelines:
            - Be friendly and professional
            - If you don't know an answer, say so
            - Current company policies: ...`;
  }
}
```

</TypeScriptExample>

### Chat Agent React API

#### useAgentChat

React hook for building AI chat interfaces using an Agent.

```ts
import { useAgentChat } from "agents/ai-react";
import { useAgent } from "agents/react";
import type { Message } from "ai";

// Options for the useAgentChat hook
type UseAgentChatOptions = Omit<
  Parameters<typeof useChat>[0] & {
    // Agent connection from useAgent
    agent: ReturnType<typeof useAgent>;
  },
  "fetch"
>;

// React hook for building AI chat interfaces using an Agent
function useAgentChat(options: UseAgentChatOptions): {
  // Current chat messages
  messages: Message[];
  // Set messages and synchronize with the Agent
  setMessages: (messages: Message[]) => void;
  // Clear chat history on both client and Agent
  clearHistory: () => void;
  // Append a new message to the conversation
  append: (message: Message, chatRequestOptions?: any) => Promise<string | null | undefined>;
  // Reload the last user message
  reload: (chatRequestOptions?: any) => Promise<string | null | undefined>;
  // Stop the AI response generation
  stop: () => void;
  // Current input text
  input: string;
  // Set the input text
  setInput: React.Dispatch<React.SetStateAction<string>>;
  // Handle input changes
  handleInputChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
  // Submit the current input
  handleSubmit: (event?: { preventDefault?: () => void }, chatRequestOptions?: any) => void;
  // Additional metadata
  metadata?: Object;
  // Whether a response is currently being generated
  isLoading: boolean;
  // Current status of the chat
  status: "submitted" | "streaming" | "ready" | "error";
  // Tool data from the AI response
  data?: any[];
  // Set tool data
  setData: (data: any[] | undefined | ((data: any[] | undefined) => any[] | undefined)) => void;
  // Unique ID for the chat
  id: string;
  // Add a tool result for a specific tool call
  addToolResult: ({ toolCallId, result }: { toolCallId: string; result: any }) => void;
  // Current error if any
  error: Error | undefined;
};
```

<TypeScriptExample>

```tsx
// Example of using useAgentChat in a React component
import { useAgentChat } from "agents/ai-react";
import { useAgent } from "agents/react";
import { useState } from "react";

function ChatInterface() {
  // Connect to the chat agent
  const agentConnection = useAgent({
    agent: "customer-support",
    name: "session-12345"
  });

  // Use the useAgentChat hook with the agent connection
  const {
    messages,
    input,
    handleInputChange,
    handleSubmit,
    isLoading,
    error,
    clearHistory
  } = useAgentChat({
    agent: agentConnection,
    initialMessages: [
      { role: "system", content: "You're chatting with our AI assistant." },
      { role: "assistant", content: "Hello! How can I help you today?" }
    ]
  });

  return (
    <div className="chat-container">
      <div className="message-history">
        {messages.map((message, i) => (
          <div key={i} className={`message ${message.role}`}>
            {message.role === 'user' ? '👤' : '🤖'} {message.content}
          </div>
        ))}

        {isLoading && <div className="loading">AI is typing...</div>}
        {error && <div className="error">Error: {error.message}</div>}
      </div>

      <form onSubmit={handleSubmit} className="message-input">
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Type your message..."
          disabled={isLoading}
        />
        <button type="submit" disabled={isLoading || !input.trim()}>
          Send
        </button>
        <button type="button" onClick={clearHistory}>
          Clear Chat
        </button>
      </form>
    </div>
  );
}
```

</TypeScriptExample>


### Next steps

* [Build a chat Agent](/agents/getting-started/build-a-chat-agent/) using the Agents SDK and deploy it to Workers.
* Learn more [using WebSockets](/agents/api-reference/websockets/) to build interactive Agents and stream data back from your Agent.
* [Orchestrate asynchronous workflows](/agents/api-reference/run-workflows) from your Agent by combining the Agents SDK and [Workflows](/workflows).

---

# Browse the web

URL: https://developers.cloudflare.com/agents/api-reference/browse-the-web/

import {
	MetaInfo,
	Render,
	Type,
	TypeScriptExample,
	WranglerConfig,
	PackageManagers,
} from "~/components";

Agents can browse the web using the [Browser Rendering](/browser-rendering/) API or your preferred headless browser service.

### Browser Rendering API

The [Browser Rendering](/browser-rendering/) allows you to spin up headless browser instances, render web pages, and interact with websites through your Agent.

You can define a method that uses Puppeteer to pull the content of a web page, parse the DOM, and extract relevant information by calling the OpenAI model:

<TypeScriptExample>

```ts
interface Env {
	BROWSER: Fetcher;
}

export class MyAgent extends Agent<Env> {
	async browse(browserInstance: Fetcher, urls: string[]) {
		let responses = [];
		for (const url of urls) {
			const browser = await puppeteer.launch(browserInstance);
			const page = await browser.newPage();
			await page.goto(url);

			await page.waitForSelector("body");
			const bodyContent = await page.$eval(
				"body",
				(element) => element.innerHTML,
			);
			const client = new OpenAI({
				apiKey: this.env.OPENAI_API_KEY,
			});

			let resp = await client.chat.completions.create({
				model: this.env.MODEL,
				messages: [
					{
						role: "user",
						content: `Return a JSON object with the product names, prices and URLs with the following format: { "name": "Product Name", "price": "Price", "url": "URL" } from the website content below. <content>${bodyContent}</content>`,
					},
				],
				response_format: {
					type: "json_object",
				},
			});

			responses.push(resp);
			await browser.close();
		}

		return responses;
	}
}
```

</TypeScriptExample>

You'll also need to add install the `@cloudflare/puppeteer` package and add the following to the wrangler configuration of your Agent:

<PackageManagers pkg="@cloudflare/puppeteer" dev />

<WranglerConfig>

```jsonc
{
	// ...
	"browser": {
		"binding": "MYBROWSER",
	},
	// ...
}
```

</WranglerConfig>

### Browserbase

You can also use [Browserbase](https://docs.browserbase.com/integrations/cloudflare/typescript) by using the Browserbase API directly from within your Agent.

Once you have your [Browserbase API key](https://docs.browserbase.com/integrations/cloudflare/typescript), you can add it to your Agent by creating a [secret](/workers/configuration/secrets/):

```sh
cd your-agent-project-folder
npx wrangler@latest secret put BROWSERBASE_API_KEY
```

```sh output
Enter a secret value: ******
Creating the secret for the Worker "agents-example"
Success! Uploaded secret BROWSERBASE_API_KEY
```

Install the `@cloudflare/puppeteer` package and use it from within your Agent to call the Browserbase API:

<PackageManagers pkg="@cloudflare/puppeteer" />

<TypeScriptExample>

```ts
interface Env {
	BROWSERBASE_API_KEY: string;
}

export class MyAgent extends Agent<Env> {
	constructor(env: Env) {
		super(env);
	}
}
```

</TypeScriptExample>

---

# Calling Agents

URL: https://developers.cloudflare.com/agents/api-reference/calling-agents/

import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";

Learn how to call your Agents from Workers, including how to create Agents on-the-fly, address them, and route requests to specific instances of an Agent.

### Calling your Agent

Agents are created on-the-fly and can serve multiple requests concurrently. Each Agent instance is isolated from other instances, can maintain its own state, and has a unique address.

<Render file="unique-agents" />

You can create and run an instance of an Agent directly from a Worker using either:

* The `routeAgentRequest` helper: this will automatically map requests to an individual Agent based on the `/agents/:agent/:name` URL pattern. The value of `:agent` will be the name of your Agent class converted to `kebab-case`, and the value of `:name` will be the name of the Agent instance you want to create or retrieve.
* `getAgentByName`, which will create a new Agent instance if none exists by that name, or retrieve a handle to an existing instance.

See the usage patterns in the following example:

<TypeScriptExample>

```ts
import { Agent, AgentNamespace, getAgentByName, routeAgentRequest } from 'agents';

interface Env {
	// Define your Agent on the environment here
	// Passing your Agent class as a TypeScript type parameter allows you to call
	// methods defined on your Agent.
	MyAgent: AgentNamespace<MyAgent>;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Routed addressing
		// Automatically routes HTTP requests and/or WebSocket connections to /agents/:agent/:name
		// Best for: connecting React apps directly to Agents using useAgent from agents/react
		return (await routeAgentRequest(request, env)) || Response.json({ msg: 'no agent here' }, { status: 404 });

		// Named addressing
		// Best for: convenience method for creating or retrieving an agent by name/ID.
		// Bringing your own routing, middleware and/or plugging into an existing
		// application or framework.
		let namedAgent = getAgentByName<Env, MyAgent>(env.MyAgent, 'my-unique-agent-id');
		// Pass the incoming request straight to your Agent
		let namedResp = (await namedAgent).fetch(request);
		return namedResp
	},
} satisfies ExportedHandler<Env>;

export class MyAgent extends Agent<Env> {
	// Your Agent implementation goes here
}
```
</TypeScriptExample>

:::note[Calling other Agents]

You can also call other Agents from within an Agent and build multi-Agent systems.

Calling other Agents uses the same APIs as calling into an Agent directly.

:::

### Calling methods on Agents

When using `getAgentByName`, you can pass both requests (including WebSocket) connections and call methods defined directly on the Agent itself using the native [JavaScript RPC](/workers/runtime-apis/rpc/) (JSRPC) API.

For example, once you have a handle (or "stub") to an unique instance of your Agent, you can call methods on it:

<TypeScriptExample>

```ts
import { Agent, AgentNamespace, getAgentByName } from 'agents';

interface Env {
	// Define your Agent on the environment here
	// Passing your Agent class as a TypeScript type parameter allows you to call
	// methods defined on your Agent.
	MyAgent: AgentNamespace<MyAgent>;
}

interface UserHistory {
	history: string[];
	lastUpdated: Date;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		let namedAgent = getAgentByName<Env, MyAgent>(env.MyAgent, 'my-unique-agent-id');
		// Call methods directly on the Agent, and pass native JavaScript objects
		let chatResponse = namedAgent.chat('Hello!');
		// No need to serialize/deserialize it from a HTTP request or WebSocket
		// message and back again
		let agentState = getState() // agentState is of type UserHistory
		return namedResp
	},
} satisfies ExportedHandler<Env>;

export class MyAgent extends Agent<Env, UserHistory> {
	// Your Agent implementation goes here
	async chat(prompt: string) {
		// call your favorite LLM
		return "result"
	}

	async getState() {
		// Return the Agent's state directly
		return this.state;
	}

	// Other methods as you see fit!
}
```
</TypeScriptExample>

When using TypeScript, ensure you pass your Agent class as a TypeScript type parameter to the AgentNamespace type so that types are correctly inferred:

```ts
interface Env {
	// Passing your Agent class as a TypeScript type parameter allows you to call
	// methods defined on your Agent.
	MyAgent: AgentNamespace<CodeReviewAgent>;
}

export class CodeReviewAgent extends Agent<Env, AgentState> {
	// Agent methods here
}
```

### Naming your Agents

When creating names for your Agents, think about what the Agent represents. A unique user? A team or company? A room or channel for collaboration?

A consistent approach to naming allows you to:

* direct incoming requests directly to the right Agent
* deterministically route new requests back to that Agent, no matter where the client is in the world.
* avoid having to rely on centralized session storage or external services for state management, since each Agent instance can maintain its own state.

For a given Agent definition (or 'namespace' in the code below), there can be millions (or tens of millions) of instances of that Agent, each handling their own requests, making calls to LLMs, and maintaining their own state.

For example, you might have an Agent for every user using your new AI-based code editor. In that case, you'd want to create Agents based on the user ID from your system, which would then allow that Agent to handle all requests for that user.

It also ensures that [state within the Agent](/agents/api-reference/store-and-sync-state/), including chat history, language preferences, model configuration and other context can associated specifically with that user, making it easier to manage state.

The example below shows how to create a unique agent Agent for each `userId` in a request:

<TypeScriptExample>

```ts
import { Agent, AgentNamespace, getAgentByName, routeAgentRequest } from 'agents';

interface Env {
	MyAgent: AgentNamespace<MyAgent>;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		let userId = new URL(request.url).searchParams.get('userId') || 'anonymous';
		// Use an identifier that allows you to route to requests, WebSockets or call methods on the Agent
		// You can also put authentication logic here - e.g. to only create or retrieve Agents for known users.
		let namedAgent = getAgentByName<Env, MyAgent>(env.MyAgent, 'my-unique-agent-id');
		return (await namedAgent).fetch(request);
	},
} satisfies ExportedHandler<Env>;

export class MyAgent extends Agent<Env> {
	// You can access the name of the agent via this.name in any method within
	// the Agent
	async onStartup() { console.log(`agent ${this.name} ready!`)}
}
```
</TypeScriptExample>

Replace `userId` with `teamName`, `channel`, `companyName` as fits your Agents goals - and/or configure authentication to ensure Agents are only created for known, authenticated users.

### Authenticating Agents

When building and deploying Agents using the Agents SDK, you will often want to authenticate clients before passing requests to an Agent in order to restrict who the Agent will call, authorize specific users for specific Agents, and/or to limit who can access administrative or debug APIs exposed by an Agent.

As best practices:

* Handle authentication in your Workers code, before you invoke your Agent.
* Use the built-in hooks when using the `routeAgentRequest` helper - `onBeforeConnect` and `onBeforeRequest`
* Use your preferred router (such as Hono) and authentication middleware or provider to apply custom authentication schemes before calling an Agent using other methods.

The `routeAgentRequest` helper documented earlier in this guide exposes two useful hooks (`onBeforeConnect`, `onBeforeRequest`) that allow you to apply custom logic before creating or retrieving an Agent:

<TypeScriptExample>

```ts
import { Agent, AgentNamespace, routeAgentRequest } from 'agents';

interface Env {
	MyAgent: AgentNamespace<MyAgent>;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Use the onBeforeConnect and onBeforeRequest hooks to authenticate clients
		// or run logic before handling a HTTP request or WebSocket.
		return (
			(await routeAgentRequest(request, env, {
				// Run logic before a WebSocket client connects
				onBeforeConnect: (request) => {
					// Your code/auth code here
					// You can return a Response here - e.g. a HTTP 403 Not Authorized -
					// which will stop further request processing and will NOT invoke the
					// Agent.
					// return Response.json({"error": "not authorized"}, { status: 403 })
				},
				// Run logic before a HTTP client clients
				onBeforeRequest: (request) => {
					// Your code/auth code here
					// Returning nothing will result in the call to the Agent continuing
				},
				// Prepend a prefix for how your Agents are named here
				prefix: 'name-prefix-here',
			})) || Response.json({ msg: 'no agent here' }, { status: 404 })
		);

	},
} satisfies ExportedHandler<Env>;
```
</TypeScriptExample>

If you are using `getAgentByName` or the underlying Durable Objects routing API, you should authenticate incoming requests or WebSocket connections before calling `getAgentByName`.

For example, if you are using [Hono](https://hono.dev/), you can authenticate in the middleware before calling an Agent and passing a request (or a WebSocket connection) to it:

<TypeScriptExample>

```ts
import { Agent, AgentNamespace, getAgentByName } from 'agents';
import { Hono } from 'hono';

const app = new Hono<{ Bindings: Env }>();

app.use('/code-review/*', async (c, next) => {
	// Perform auth here
	// e.g. validate a Bearer token, a JWT, use your preferred auth library
	// return Response.json({ msg: 'unauthorized' }, { status: 401 });
	await next(); // continue on if valid
});

app.get('/code-review/:id', async (c) => {
	const id = c.req.param('teamId');
	if (!id) return Response.json({ msg: 'missing id' }, { status: 400 });

	// Call the Agent, creating it with the name/identifier from the ":id" segment
	// of our URL
	const agent = await getAgentByName<Env, MyAgent>(c.env.MyAgent, id);

	// Pass the request to our Agent instance
	return await agent.fetch(c.req.raw);
});
```

</TypeScriptExample>

This ensures we only create Agents for authenticated users, and allows you to validate whether Agent names conform to your preferred naming scheme before instances are created.

### Next steps

* Review the [API documentation](/agents/api-reference/agents-api/) for the Agents class to learn how to define
* [Build a chat Agent](/agents/getting-started/build-a-chat-agent/) using the Agents SDK and deploy it to Workers.
* Learn more [using WebSockets](/agents/api-reference/websockets/) to build interactive Agents and stream data back from your Agent.
* [Orchestrate asynchronous workflows](/agents/api-reference/run-workflows) from your Agent by combining the Agents SDK and [Workflows](/workflows).

---

# Configuration

URL: https://developers.cloudflare.com/agents/api-reference/configuration/

import { MetaInfo, Render, Type, WranglerConfig } from "~/components";

An Agent is configured like any other Cloudflare Workers project, and uses [a wrangler configuration](/workers/wrangler/configuration/) file to define where your code is and what services (bindings) it will use.

### Project structure

The typical file structure for an Agent project created from `npm create cloudflare@latest agents-starter -- --template cloudflare/agents-starter` follows:

```sh
.
|-- package-lock.json
|-- package.json
|-- public
|   `-- index.html
|-- src
|   `-- index.ts // your Agent definition
|-- test
|   |-- index.spec.ts // your tests
|   `-- tsconfig.json
|-- tsconfig.json
|-- vitest.config.mts
|-- worker-configuration.d.ts
`-- wrangler.jsonc // your Workers & Agent configuration
```

### Example configuration

Below is a minimal `wrangler.jsonc` file that defines the configuration for an Agent, including the entry point, `durable_object` namespace, and code `migrations`:

<WranglerConfig>

```jsonc
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "agents-example",
	"main": "src/index.ts",
	"compatibility_date": "2025-02-23",
	"compatibility_flags": ["nodejs_compat"],
	"durable_objects": {
		"bindings": [
			{
				// Required:
				"name": "MyAgent", // How your Agent is called from your Worker
				"class_name": "MyAgent", // Must match the class name of the Agent in your code
				// Optional: set this if the Agent is defined in another Worker script
				"script_name": "the-other-worker"
			},
		],
	},
	"migrations": [
		{
			"tag": "v1",
			// Mandatory for the Agent to store state
			"new_sqlite_classes": ["MyAgent"],
		},
	],
	"observability": {
		"enabled": true,
	},
}
```

</WranglerConfig>

The configuration includes:

- A `main` field that points to the entry point of your Agent, which is typically a TypeScript (or JavaScript) file.
- A `durable_objects` field that defines the [Durable Object namespace](/durable-objects/reference/glossary/) that your Agents will run within.
- A `migrations` field that defines the code migrations that your Agent will use. This field is mandatory and must contain at least one migration. The `new_sqlite_classes` field is mandatory for the Agent to store state.

Agents must define these fields in their `wrangler.jsonc` (or `wrangler.toml`) config file.

---

# HTTP and Server-Sent Events

URL: https://developers.cloudflare.com/agents/api-reference/http-sse/

import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";

The Agents SDK allows you to handle HTTP requests and has native support for [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE). This allows you build applications that can push data to clients and avoid buffering.

### Handling HTTP requests

Agents can handle HTTP requests using the `onRequest` method, which is called whenever an HTTP request is received by the Agent instance. The method takes a `Request` object as a parameter and returns a `Response` object.

<TypeScriptExample>

```ts
class MyAgent extends Agent<Env, State> {
  // Handle HTTP requests coming to this Agent instance
  // Returns a Response object
  async onRequest(request: Request) {
    return new Response("Hello from Agent!");
  }

  async callAIModel(prompt: string) {
  	// Implement AI model call here
  }
}
```

</TypeScriptExample>

Review the [Agents API reference](/agents/api-reference/agents-api/) to learn more about the `Agent` class and its methods.

### Implementing Server-Sent Events

The Agents SDK support Server-Sent Events directly: you can use SSE to stream data back to the client over a long running connection. This avoids buffering large responses, which can both make your Agent feel slow, and forces you to buffer the entire response in memory.

When an Agent is deployed to Cloudflare Workers, there is no effective limit on the total time it takes to stream the response back: large AI model responses that take several minutes to reason and then respond will not be prematurely terminated.

Note that this does not mean the client can't potentially disconnect during the streaming process: you can account for this by either [writing to the Agent's stateful storage](/agents/api-reference/store-and-sync-state/) and/or [using WebSockets](/agents/api-reference/websockets/). Because you can always [route to the same Agent](/agents/api-reference/calling-agents/), you do not need to use a centralized session store to pick back up where you left off when a client disconnects.

The following example uses the AI SDK to generate text and stream it back to the client. It will automatically stream the response back to the client as the model generates it:

<TypeScriptExample>

```ts
import { Agent, AgentNamespace, getAgentByName, routeAgentRequest } from 'agents';
import { streamText } from 'ai';
import { createOpenAI, openai } from '@ai-sdk/openai';

interface Env {
	MyAgent: AgentNamespace<MyAgent>;
	OPENAI_API_KEY: string;
}

export class MyAgent extends Agent<Env> {
	async onRequest(request: Request) {
		// Test it via:
		// curl -d '{"prompt": "Write me a Cloudflare Worker"}' <url>
		let data = await request.json<{ prompt: string }>();
		let stream = await this.callAIModel(data.prompt);
		// This uses Server-Sent Events (SSE)
		return stream.toTextStreamResponse({
			headers: {
				'Content-Type': 'text/x-unknown',
				'content-encoding': 'identity',
				'transfer-encoding': 'chunked',
			},
		});
	}

	async callAIModel(prompt: string) {
		const openai = createOpenAI({
			apiKey: this.env.OPENAI_API_KEY,
		});

		return streamText({
			model: openai('gpt-4o'),
			prompt: prompt,
		});
	}
}

export default {
	async fetch(request: Request, env: Env) {
		let agentId = new URL(request.url).searchParams.get('agent-id') || '';
		const agent = await getAgentByName<Env, MyAgent>(env.MyAgent, agentId);
		return agent.fetch(request);
	},
};
```

</TypeScriptExample>

### WebSockets vs. Server-Sent Events

Both WebSockets and Server-Sent Events (SSE) enable real-time communication between clients and Agents. Agents built on the Agents SDK can expose both WebSocket and SSE endpoints directly.

* WebSockets provide full-duplex communication, allowing data to flow in both directions simultaneously. SSE only supports server-to-client communication, requiring additional HTTP requests if the client needs to send data back.
* WebSockets establish a single persistent connection that stays open for the duration of the session. SSE, being built on HTTP, may experience more overhead due to reconnection attempts and header transmission with each reconnection, especially when there is a lot of client-server communication.
* While SSE works well for simple streaming scenarios, WebSockets are better suited for applications requiring minutes or hours of connection time, as they maintain a more stable connection with built-in ping/pong mechanisms to keep connections alive.
* WebSockets use their own protocol (ws:// or wss://), separating them from HTTP after the initial handshake. This separation allows WebSockets to better handle binary data transmission and implement custom subprotocols for specialized use cases.

If you're unsure of which is better for your use-case, we recommend WebSockets. The [WebSockets API documentation](/agents/api-reference/websockets/) provides detailed information on how to use WebSockets with the Agents SDK.

### Next steps

* Review the [API documentation](/agents/api-reference/agents-api/) for the Agents class to learn how to define them.
* [Build a chat Agent](/agents/getting-started/build-a-chat-agent/) using the Agents SDK and deploy it to Workers.
* Learn more [using WebSockets](/agents/api-reference/websockets/) to build interactive Agents and stream data back from your Agent.
* [Orchestrate asynchronous workflows](/agents/api-reference/run-workflows) from your Agent by combining the Agents SDK and [Workflows](/workflows).

---

# Retrieval Augmented Generation

URL: https://developers.cloudflare.com/agents/api-reference/rag/

import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";

Agents can use Retrieval Augmented Generation (RAG) to retrieve relevant information and use it augment [calls to AI models](/agents/api-reference/using-ai-models/). Store a user's chat history to use as context for future conversations, summarize documents to bootstrap an Agent's knowledge base, and/or use data from your Agent's [web browsing](/agents/api-reference/browse-the-web/) tasks to enhance your Agent's capabilities.

You can use the Agent's own [SQL database](/agents/api-reference/store-and-sync-state) as the source of truth for your data and store embeddings in [Vectorize](/vectorize/) (or any other vector-enabled database) to allow your Agent to retrieve relevant information.

### Vector search

:::note

If you're brand-new to vector databases and Vectorize, visit the [Vectorize tutorial](/vectorize/get-started/intro/) to learn the basics, including how to create an index, insert data, and generate embeddings.

:::

You can query a vector index (or indexes) from any method on your Agent: any Vectorize index you attach is available on `this.env` within your Agent. If you've [associated metadata](/vectorize/best-practices/insert-vectors/#metadata) with your vectors that maps back to data stored in your Agent, you can then look up the data directly within your Agent using `this.sql`.

Here's an example of how to give an Agent retrieval capabilities:

<TypeScriptExample>

```ts
import { Agent } from "agents";

interface Env {
	AI: Ai;
	VECTOR_DB: Vectorize;
}

export class RAGAgent extends Agent<Env> {
	// Other methods on our Agent
	// ...
	//
	async queryKnowledge(userQuery: string) {
		// Turn a query into an embedding
		const queryVector = await this.env.AI.run('@cf/baai/bge-base-en-v1.5', {
			text: [userQuery],
		});

		// Retrieve results from our vector index
		let searchResults = await this.env.VECTOR_DB.query(queryVector.data[0], {
			topK: 10,
			returnMetadata: 'all',
		});

		let knowledge = [];
		for (const match of searchResults.matches) {
			console.log(match.metadata);
			knowledge.push(match.metadata);
		}

		// Use the metadata to re-associate the vector search results
		// with data in our Agent's SQL database
		let results = this.sql`SELECT * FROM knowledge WHERE id IN (${knowledge.map((k) => k.id)})`;

		// Return them
		return results;
	}
}
```

</TypeScriptExample>

You'll also need to connect your Agent to your vector indexes:

<WranglerConfig>

```jsonc
{
	// ...
  "vectorize": [
    {
      "binding": "VECTOR_DB",
      "index_name": "your-vectorize-index-name"
    }
  ]
  // ...
}
```

</WranglerConfig>

If you have multiple indexes you want to make available, you can provide an array of `vectorize` bindings.

#### Next steps

* Learn more on how to [combine Vectorize and Workers AI](/vectorize/get-started/embeddings/)
* Review the [Vectorize query API](/vectorize/reference/client-api/)
* Use [metadata filtering](/vectorize/reference/metadata-filtering/) to add context to your results

---

# API Reference

URL: https://developers.cloudflare.com/agents/api-reference/

import { DirectoryListing } from "~/components"

Learn more about what Agents can do, the `Agent` class, and the APIs that Agents expose:

<DirectoryListing />

---

# Run Workflows

URL: https://developers.cloudflare.com/agents/api-reference/run-workflows/

import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";

Agents can trigger asynchronous [Workflows](/workflows/), allowing your Agent to run complex, multi-step tasks in the background. This can include post-processing files that a user has uploaded, updating the embeddings in a [vector database](/vectorize/), and/or managing long-running user-lifecycle email or SMS notification workflows.

Because an Agent is just like a Worker script, it can create Workflows defined in the same project (script) as the Agent _or_ in a different project.

:::note[Agents vs. Workflows]

Agents and Workflows have some similarities: they can both run tasks asynchronously. For straightforward tasks that are linear or need to run to completion, a Workflow can be ideal: steps can be retried, they can be cancelled, and can act on events.

Agents do not have to run to completion: they can loop, branch and run forever, and they can also interact directly with users (over HTTP or WebSockets). An Agent can be used to trigger multiple Workflows as it runs, and can thus be used to co-ordinate and manage Workflows to achieve its goals.

:::

## Trigger a Workflow

An Agent can trigger one or more Workflows from within any method, whether from an incoming HTTP request, a WebSocket connection, on a delay or schedule, and/or from any other action the Agent takes.

Triggering a Workflow from an Agent is no different from [triggering a Workflow from a Worker script](/workflows/build/trigger-workflows/):

<TypeScriptExample>

```ts
interface Env {
	MY_WORKFLOW: Workflow;
	MyAgent: AgentNamespace<MyAgent>;
}

export class MyAgent extends Agent<Env> {
	async onRequest(request: Request) {
		let userId = request.headers.get("user-id");
		// Trigger a schedule that runs a Workflow
		// Pass it a payload
		let { taskId } = await this.schedule(300, "runWorkflow", { id: userId, flight: "DL264", date: "2025-02-23" });
	}

	async runWorkflow(data) {
		let instance = await env.MY_WORKFLOW.create({
			id: data.id,
			params: data,
		})

		// Schedule another task that checks the Workflow status every 5 minutes...
		await this.schedule("*/5 * * * *", "checkWorkflowStatus", { id: instance.id });
	}
}

export class MyWorkflow extends WorkflowEntrypoint<Env> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// Your Workflow code here
	}
}
```

</TypeScriptExample>

You'll also need to make sure your Agent [has a binding to your Workflow](/workflows/build/trigger-workflows/#workers-api-bindings) so that it can call it:

<WranglerConfig>

```jsonc
{
	// ...
	// Create a binding between your Agent and your Workflow
	"workflows": [
		{
			// Required:
			"name": "EMAIL_WORKFLOW",
			"class_name": "MyWorkflow",
			// Optional: set the script_name field if your Workflow is defined in a
			// different project from your Agent
			"script_name": "email-workflows"
		}
	 ],
	// ...
}
```

</WranglerConfig>

## Trigger a Workflow from another project

You can also call a Workflow that is defined in a different Workers script from your Agent by setting the `script_name` property in the `workflows` binding of your Agent:

<WranglerConfig>

```jsonc
{
		// Required:
		"name": "EMAIL_WORKFLOW",
		"class_name": "MyWorkflow",
		// Optional: set the script_name field if your Workflow is defined in a
		// different project from your Agent
		"script_name": "email-workflows"
}
```

</WranglerConfig>

Refer to the [cross-script calls](/workflows/build/workers-api/#cross-script-calls) section of the Workflows documentation for more examples.

---

# Schedule tasks

URL: https://developers.cloudflare.com/agents/api-reference/schedule-tasks/

import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";

An Agent can schedule tasks to be run in the future by calling `this.schedule(when, callback, data)`, where `when` can be a delay, a `Date`, or a cron string; `callback` the function name to call, and `data` is an object of data to pass to the function.

Scheduled tasks can do anything a request or message from a user can: make requests, query databases, send emails, read+write state: scheduled tasks can invoke any regular method on your Agent.

### Scheduling tasks

You can call `this.schedule` within any method on an Agent, and schedule tens-of-thousands of tasks per individual Agent:

<TypeScriptExample>

```ts
import { Agent } from "agents"

export class SchedulingAgent extends Agent {
	async onRequest(request) {
		// Handle an incoming request
		// Schedule a task 5 minutes from now
		// Calls the "checkFlights" method
		let { taskId } = await this.schedule(600, "checkFlights", { flight: "DL264", date: "2025-02-23" });
		return Response.json({ taskId });
	}

	async checkFlights(data) {
		// Invoked when our scheduled task runs
		// We can also call this.schedule here to schedule another task
	}
}
```
</TypeScriptExample>

:::caution

Tasks that set a callback for a method that does not exist will throw an exception: ensure that the method named in the `callback` argument of `this.schedule` exists on your `Agent` class.

:::

You can schedule tasks in multiple ways:

<TypeScriptExample>

```ts
// schedule a task to run in 10 seconds
let task = await this.schedule(10, "someTask", { message: "hello" });

// schedule a task to run at a specific date
let task = await this.schedule(new Date("2025-01-01"), "someTask", {});

// schedule a task to run every 10 seconds
let { id } = await this.schedule("*/10 * * * *", "someTask", { message: "hello" });

// schedule a task to run every 10 seconds, but only on Mondays
let task = await this.schedule("0 0 * * 1", "someTask", { message: "hello" });

// cancel a scheduled task
this.cancelSchedule(task.id);
```

</TypeScriptExample>

Calling `await this.schedule` returns a `Schedule`, which includes the task's randomly generated `id`. You can use this `id` to retrieve or cancel the task in the future. It also provides a `type` property that indicates the type of schedule, for example, one of `"scheduled" | "delayed" | "cron"`.

:::note[Maximum scheduled tasks]

Each task is mapped to a row in the Agent's underlying [SQLite database](/durable-objects/api/storage-api/), which means that each task can be up to 2 MB in size. The maximum number of tasks must be `(task_size * tasks) + all_other_state < maximum_database_size` (currently 1GB per Agent).

:::

### Managing scheduled tasks

You can get, cancel and filter across scheduled tasks within an Agent using the scheduling API:

<TypeScriptExample>

```ts
// Get a specific schedule by ID
// Returns undefined if the task does not exist
let task = await this.getSchedule(task.id)

// Get all scheduled tasks
// Returns an array of Schedule objects
let tasks = this.getSchedules();

// Cancel a task by its ID
// Returns true if the task was cancelled, false if it did not exist
await this.cancelSchedule(task.id);

// Filter for specific tasks
// e.g. all tasks starting in the next hour
let tasks = this.getSchedules({
	timeRange: {
		start: new Date(Date.now()),
		end: new Date(Date.now() + 60 * 60 * 1000),
	}
});
```

</TypeScriptExample>

---

# Store and sync state

URL: https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/

import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";

Every Agent has built-in state management capabilities, including built-in storage and synchronization between the Agent and frontend applications.

State within an Agent is:

* Persisted across Agent restarts: data is permanently stored within an Agent.
* Automatically serialized/deserialized: you can store any JSON-serializable data.
* Immediately consistent within the Agent: read your own writes.
* Thread-safe for concurrent updates
* Fast: state is colocated wherever the Agent is running. Reads and writes do not need to traverse the network.

Agent state is stored in a SQL database that is embedded within each individual Agent instance: you can interact with it using the higher-level `this.setState` API (recommended), which allows you to sync state and trigger events on state changes, or by directly querying the database with `this.sql`.

#### State API

Every Agent has built-in state management capabilities. You can set and update the Agent's state directly using `this.setState`:

<TypeScriptExample>

```ts
import { Agent } from "agents";

export class MyAgent extends Agent {
  // Update state in response to events
  async incrementCounter() {
    this.setState({
      ...this.state,
      counter: this.state.counter + 1,
    });
  }

  // Handle incoming messages
  async onMessage(message) {
    if (message.type === "update") {
      this.setState({
        ...this.state,
        ...message.data,
      });
    }
  }

  // Handle state updates
  onStateUpdate(state, source: "server" | Connection) {
    console.log("state updated", state);
  }
}
```

</TypeScriptExample>

If you're using TypeScript, you can also provide a type for your Agent's state by passing in a type as a [type parameter](https://www.typescriptlang.org/docs/handbook/2/generics.html#using-type-parameters-in-generic-constraints) as the _second_ type parameter to the `Agent` class definition.

<TypeScriptExample>

```ts
import { Agent } from "agents";

interface Env {}

// Define a type for your Agent's state
interface FlightRecord {
	id: string;
	departureIata: string;
	arrival: Date;
	arrivalIata: string;
	price: number;
}

// Pass in the type of your Agent's state
export class MyAgent extends Agent<Env, FlightRecord> {
  // This allows this.setState and the onStateUpdate method to
  // be typed:
 	async onStateUpdate(state: FlightRecord) {
  	console.log("state updated", state);
  }

  async someOtherMethod() {
  	this.setState({
  		...this.state,
  		price: this.state.price + 10,
  	});
  }
}
```

</TypeScriptExample>

### Set the initial state for an Agent

You can also set the initial state for an Agent via the `initialState` property on the `Agent` class:

<TypeScriptExample>

```ts
type State = {
  counter: number;
  text: string;
  color: string;
};

class MyAgent extends Agent<Env, State> {
	// Set a default, initial state
  initialState = {
    counter: 0,
    text: "",
    color: "#3B82F6",
  };

  doSomething() {
    console.log(this.state); // {counter: 0, text: "", color: "#3B82F6"}, if you haven't set the state yet
  }
}
```
</TypeScriptExample>

Any initial state is synced to clients connecting via [the `useAgent` hook](#synchronizing-state).

### Synchronizing state

Clients can connect to an Agent and stay synchronized with its state using the React hooks provided as part of `agents/react`.

A React application can call `useAgent` to connect to a named Agent over WebSockets at

<TypeScriptExample>

```ts
import { useState } from "react";
import { useAgent } from "agents/react";

function StateInterface() {
  const [state, setState] = useState({ counter: 0 });

  const agent = useAgent({
    agent: "thinking-agent",
    name: "my-agent",
    onStateUpdate: (newState) => setState(newState),
  });

  const increment = () => {
    agent.setState({ counter: state.counter + 1 });
  };

  return (
    <div>
      <div>Count: {state.counter}</div>
      <button onClick={increment}>Increment</button>
    </div>
  );
}
```

</TypeScriptExample>

The state synchronization system:

* Automatically syncs the Agent's state to all connected clients
* Handles client disconnections and reconnections gracefully
* Provides immediate local updates
* Supports multiple simultaneous client connections

Common use cases:

* Real-time collaborative features
* Multi-window/tab synchronization
* Live updates across multiple devices
* Maintaining consistent UI state across clients
* When new clients connect, they automatically receive the current state from the Agent, ensuring all clients start with the latest data.

### SQL API

Every individual Agent instance has its own SQL (SQLite) database that runs _within the same context_ as the Agent itself. This means that inserting or querying data within your Agent is effectively zero-latency: the Agent doesn't have to round-trip across a continent or the world to access its own data.

You can access the SQL API within any method on an Agent via `this.sql`. The SQL API accepts template literals, and

<TypeScriptExample>

```ts
export class MyAgent extends Agent<Env> {
	async onRequest(request: Request) {
		let userId = new URL(request.url).searchParams.get('userId');

		// 'users' is just an example here: you can create arbitrary tables and define your own schemas
		// within each Agent's database using SQL (SQLite syntax).
		let user = await this.sql`SELECT * FROM users WHERE id = ${userId}`
		return Response.json(user)
	}
}
```

</TypeScriptExample>

You can also supply a [TypeScript type argument](https://www.typescriptlang.org/docs/handbook/2/generics.html#using-type-parameters-in-generic-constraints) to the query, which will be used to infer the type of the result:

```ts
type User = {
	id: string;
	name: string;
	email: string;
};

export class MyAgent extends Agent<Env> {
	async onRequest(request: Request) {
		let userId = new URL(request.url).searchParams.get('userId');
		// Supply the type parameter to the query when calling this.sql
		// This assumes the results returns one or more User rows with "id", "name", and "email" columns
		const user = await this.sql<User>`SELECT * FROM users WHERE id = ${userId}`;
		return Response.json(user)
	}
}
```

You do not need to specify an array type (`User[]` or `Array<User>`) as `this.sql` will always return an array of the specified type.

Providing a type parameter does not validate that the result matches your type definition. In TypeScript, properties (fields) that do not exist or conform to the type you provided will be dropped. If you need to validate incoming events, we recommend a library such as [zod](https://zod.dev/) or your own validator logic.

:::note

Learn more about the zero-latency SQL storage that powers both Agents and Durable Objects [on our blog](https://blog.cloudflare.com/sqlite-in-durable-objects/).

:::

The SQL API exposed to an Agent is similar to the one [within Durable Objects](/durable-objects/api/storage-api/#sql-api): Durable Object SQL methods available on `this.ctx.storage.sql`. You can use the same SQL queries with the Agent's database, create tables, and query data, just as you would with Durable Objects or [D1](/d1/).

### Use Agent state as model context

You can combine the state and SQL APIs in your Agent with its ability to [call AI models](/agents/api-reference/using-ai-models/) to include historical context within your prompts to a model. Modern Large Language Models (LLMs) often have very large context windows (up to millions of tokens), which allows you to pull relevant context into your prompt directly.

For example, you can use an Agent's built-in SQL database to pull history, query a model with it, and append to that history ahead of the next call to the model:

<TypeScriptExample>

```ts
export class ReasoningAgent extends Agent<Env> {
	async callReasoningModel(prompt: Prompt) {
		let result = this.sql<History>`SELECT * FROM history WHERE user = ${prompt.userId} ORDER BY timestamp DESC LIMIT 1000`;
		let context = [];
		for await (const row of result) {
			context.push(row.entry);
		}

		const client = new OpenAI({
			apiKey: this.env.OPENAI_API_KEY,
		});

		// Combine user history with the current prompt
		const systemPrompt = prompt.system || 'You are a helpful assistant.';
		const userPrompt = `${prompt.user}\n\nUser history:\n${context.join('\n')}`;

		try {
			const completion = await client.chat.completions.create({
				model: this.env.MODEL || 'o3-mini',
				messages: [
					{ role: 'system', content: systemPrompt },
					{ role: 'user', content: userPrompt },
				],
				temperature: 0.7,
				max_tokens: 1000,
			});

			// Store the response in history
			this
				.sql`INSERT INTO history (timestamp, user, entry) VALUES (${new Date()}, ${prompt.userId}, ${completion.choices[0].message.content})`;

			return completion.choices[0].message.content;
		} catch (error) {
			console.error('Error calling reasoning model:', error);
			throw error;
		}
	}
}
```

</TypeScriptExample>

This works because each instance of an Agent has its _own_ database, the state stored in that database is private to that Agent: whether it's acting on behalf of a single user, a room or channel, or a deep research tool. By default, you don't have to manage contention or reach out over the network to a centralized database to retrieve and store state.

### Next steps

* Review the [API documentation](/agents/api-reference/agents-api/) for the Agents class to learn how to define them.
* [Build a chat Agent](/agents/getting-started/build-a-chat-agent/) using the Agents SDK and deploy it to Workers.
* Learn more [using WebSockets](/agents/api-reference/websockets/) to build interactive Agents and stream data back from your Agent.
* [Orchestrate asynchronous workflows](/agents/api-reference/run-workflows) from your Agent by combining the Agents SDK and [Workflows](/workflows).

---

# Using AI Models

URL: https://developers.cloudflare.com/agents/api-reference/using-ai-models/

import {
	AnchorHeading,
	MetaInfo,
	Render,
	Type,
	TypeScriptExample,
	WranglerConfig,
	PackageManagers,
} from "~/components";

Agents can communicate with AI models hosted on any provider, including:

- [Workers AI](/workers-ai/)
- The [AI SDK](https://sdk.vercel.ai/docs/ai-sdk-core/overview)
- [OpenAI](https://platform.openai.com/docs/quickstart?language=javascript)
- [Anthropic](https://docs.anthropic.com/en/api/client-sdks#typescript)
- [Google's Gemini](https://ai.google.dev/gemini-api/docs/openai)

You can also use the model routing features in [AI Gateway](/ai-gateway/) to route across providers, eval responses, and manage AI provider rate limits.

Because Agents are built on top of [Durable Objects](/durable-objects/), each Agent or chat session is associated with a stateful compute instance. Traditional serverless architectures often present challenges for persistent connections needed in real-time applications like chat.

A user can disconnect during a long-running response from a modern reasoning model (such as `o3-mini` or DeepSeek R1), or lose conversational context when refreshing the browser. Instead of relying on request-response patterns and managing an external database to track & store conversation state, state can be stored directly within the Agent. If a client disconnects, the Agent can write to its own distributed storage, and catch the client up as soon as it reconnects: even if it's hours or days later.

## Calling AI Models

You can call models from any method within an Agent, including from HTTP requests using the [`onRequest`](/agents/api-reference/agents-api/) handler, when a [scheduled task](/agents/api-reference/schedule-tasks/) runs, when handling a WebSocket message in the [`onMessage`](/agents/api-reference/websockets/) handler, or from any of your own methods.

Importantly, Agents can call AI models on their own — autonomously — and can handle long-running responses that can take minutes (or longer) to respond in full.

### Long-running model requests {/* long-running-model-requests */}

Modern [reasoning models](https://platform.openai.com/docs/guides/reasoning) or "thinking" model can take some time to both generate a response _and_ stream the response back to the client.

Instead of buffering the entire response, or risking the client disconnecting, you can stream the response back to the client by using the [WebSocket API](/agents/api-reference/websockets/).

<TypeScriptExample filename="src/index.ts">

```ts
import { Agent } from "agents";
import { OpenAI } from "openai";

export class MyAgent extends Agent<Env> {
	async onConnect(connection: Connection, ctx: ConnectionContext) {
		//
	}

	async onMessage(connection: Connection, message: WSMessage) {
		let msg = JSON.parse(message);
		// This can run as long as it needs to, and return as many messages as it needs to!
		await queryReasoningModel(connection, msg.prompt);
	}

	async queryReasoningModel(connection: Connection, userPrompt: string) {
		const client = new OpenAI({
			apiKey: this.env.OPENAI_API_KEY,
		});

		try {
			const stream = await client.chat.completions.create({
				model: this.env.MODEL || "o3-mini",
				messages: [{ role: "user", content: userPrompt }],
				stream: true,
			});

			// Stream responses back as WebSocket messages
			for await (const chunk of stream) {
				const content = chunk.choices[0]?.delta?.content || "";
				if (content) {
					connection.send(JSON.stringify({ type: "chunk", content }));
				}
			}

			// Send completion message
			connection.send(JSON.stringify({ type: "done" }));
		} catch (error) {
			connection.send(JSON.stringify({ type: "error", error: error }));
		}
	}
}
```

</TypeScriptExample>

You can also persist AI model responses back to [Agent's internal state](/agents/api-reference/store-and-sync-state/) by using the `this.setState` method. For example, if you run a [scheduled task](/agents/api-reference/schedule-tasks/), you can store the output of the task and read it later. Or, if a user disconnects, read the message history back and send it to the user when they reconnect.

### Workers AI

### Hosted models

You can use [any of the models available in Workers AI](/workers-ai/models/) within your Agent by [configuring a binding](/workers-ai/configuration/bindings/).

Workers AI supports streaming responses out-of-the-box by setting `stream: true`, and we strongly recommend using them to avoid buffering and delaying responses, especially for larger models or reasoning models that require more time to generate a response.

<TypeScriptExample filename="src/index.ts">

```ts
import { Agent } from "agents";

interface Env {
	AI: Ai;
}

export class MyAgent extends Agent<Env> {
	async onRequest(request: Request) {
		const response = await env.AI.run(
			"@cf/deepseek-ai/deepseek-r1-distill-qwen-32b",
			{
				prompt: "Build me a Cloudflare Worker that returns JSON.",
				stream: true, // Stream a response and don't block the client!
			},
		);

		// Return the stream
		return new Response(answer, {
			headers: { "content-type": "text/event-stream" },
		});
	}
}
```

</TypeScriptExample>

Your Wrangler configuration will need an `ai` binding added:

<WranglerConfig>

```toml
[ai]
binding = "AI"
```

</WranglerConfig>

### Model routing

You can also use the model routing features in [AI Gateway](/ai-gateway/) directly from an Agent by specifying a [`gateway` configuration](/ai-gateway/providers/workersai/) when calling the AI binding.

:::note

Model routing allows you to route requests to different AI models based on whether they are reachable, rate-limiting your client, and/or if you've exceeded your cost budget for a specific provider.

:::

<TypeScriptExample filename="src/index.ts">

```ts
import { Agent } from "agents";

interface Env {
	AI: Ai;
}

export class MyAgent extends Agent<Env> {
	async onRequest(request: Request) {
		const response = await env.AI.run(
			"@cf/deepseek-ai/deepseek-r1-distill-qwen-32b",
			{
				prompt: "Build me a Cloudflare Worker that returns JSON.",
			},
			{
				gateway: {
					id: "{gateway_id}", // Specify your AI Gateway ID here
					skipCache: false,
					cacheTtl: 3360,
				},
			},
		);

		return Response.json(response);
	}
}
```

</TypeScriptExample>

Your Wrangler configuration will need an `ai` binding added. This is shared across both Workers AI and AI Gateway.

<WranglerConfig>

```toml
[ai]
binding = "AI"
```

</WranglerConfig>

Visit the [AI Gateway documentation](/ai-gateway/) to learn how to configure a gateway and retrieve a gateway ID.

### AI SDK

The [AI SDK](https://sdk.vercel.ai/docs/introduction) provides a unified API for using AI models, including for text generation, tool calling, structured responses, image generation, and more.

To use the AI SDK, install the `ai` package and use it within your Agent. The example below shows how it use it to generate text on request, but you can use it from any method within your Agent, including WebSocket handlers, as part of a scheduled task, or even when the Agent is initialized.

<PackageManagers pkg="ai @ai-sdk/openai" />

<TypeScriptExample filename="src/index.ts">

```ts
import { Agent } from "agents";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

export class MyAgent extends Agent<Env> {
	async onRequest(request: Request): Promise<Response> {
		const { text } = await generateText({
			model: openai("o3-mini"),
			prompt: "Build me an AI agent on Cloudflare Workers",
		});

		return Response.json({ modelResponse: text });
	}
}
```

</TypeScriptExample>

### OpenAI compatible endpoints

Agents can call models across any service, including those that support the OpenAI API. For example, you can use the OpenAI SDK to use one of [Google's Gemini models](https://ai.google.dev/gemini-api/docs/openai#node.js) directly from your Agent.

Agents can stream responses back over HTTP using Server Sent Events (SSE) from within an `onRequest` handler, or by using the native [WebSockets](/agents/api-reference/websockets/) API in your Agent to responses back to a client, which is especially useful for larger models that can take over 30+ seconds to reply.

<TypeScriptExample filename="src/index.ts">

```ts
import { Agent } from "agents";
import { OpenAI } from "openai";

export class MyAgent extends Agent<Env> {
	async onRequest(request: Request): Promise<Response> {
		const openai = new OpenAI({
			apiKey: this.env.GEMINI_API_KEY,
			baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
		});

		// Create a TransformStream to handle streaming data
		let { readable, writable } = new TransformStream();
		let writer = writable.getWriter();
		const textEncoder = new TextEncoder();

		// Use ctx.waitUntil to run the async function in the background
		// so that it doesn't block the streaming response
		ctx.waitUntil(
			(async () => {
				const stream = await openai.chat.completions.create({
					model: "4o",
					messages: [
						{ role: "user", content: "Write me a Cloudflare Worker." },
					],
					stream: true,
				});

				// loop over the data as it is streamed and write to the writeable
				for await (const part of stream) {
					writer.write(
						textEncoder.encode(part.choices[0]?.delta?.content || ""),
					);
				}
				writer.close();
			})(),
		);

		// Return the readable stream back to the client
		return new Response(readable);
	}
}
```

</TypeScriptExample>

---

# Using WebSockets

URL: https://developers.cloudflare.com/agents/api-reference/websockets/

import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";

Users and clients can connect to an Agent directly over WebSockets, allowing long-running, bi-directional communication with your Agent as it operates.

To enable an Agent to accept WebSockets, define `onConnect` and `onMessage` methods on your Agent.

* `onConnect(connection: Connection, ctx: ConnectionContext)` is called when a client establishes a new WebSocket connection. The original HTTP request, including request headers, cookies, and the URL itself, are available on `ctx.request`.
* `onMessage(connection: Connection, message: WSMessage)` is called for each incoming WebSocket message. Messages are one of `ArrayBuffer | ArrayBufferView | string`, and you can send messages back to a client using `connection.send()`. You can distinguish between client connections by checking `connection.id`, which is unique for each connected client.

Here's an example of an Agent that echoes back any message it receives:

<TypeScriptExample>

```ts
import { Agent, Connection } from "agents";

export class ChatAgent extends Agent {
	async onConnect(connection: Connection, ctx: ConnectionContext) {
  	// Connections are automatically accepted by the SDK.
    // You can also explicitly close a connection here with connection.close()
    // Access the Request on ctx.request to inspect headers, cookies and the URL
  }

  async onMessage(connection: Connection, message: WSMessage) {
    // const response = await longRunningAITask(message)
    await connection.send(message)
  }
}
```

</TypeScriptExample>

### Connecting clients

The Agent framework includes a useful helper package for connecting directly to your Agent (or other Agents) from a client application. Import `agents/client`, create an instance of `AgentClient` and use it to connect to an instance of your Agent:

<TypeScriptExample>

```ts
import { AgentClient } from "agents/client";

const connection = new AgentClient({
  agent: "dialogue-agent",
  name: "insight-seeker",
});

connection.addEventListener("message", (event) => {
  console.log("Received:", event.data);
});

connection.send(
  JSON.stringify({
    type: "inquiry",
    content: "What patterns do you see?",
  })
);
```

</TypeScriptExample>

### React clients

React-based applications can import `agents/react` and use the `useAgent` hook to connect to an instance of an Agent directly:

<TypeScriptExample>

```ts
import { useAgent } from "agents/react";

function AgentInterface() {
  const connection = useAgent({
    agent: "dialogue-agent",
    name: "insight-seeker",
    onMessage: (message) => {
      console.log("Understanding received:", message.data);
    },
    onOpen: () => console.log("Connection established"),
    onClose: () => console.log("Connection closed"),
  });

  const inquire = () => {
    connection.send(
      JSON.stringify({
        type: "inquiry",
        content: "What insights have you gathered?",
      })
    );
  };

  return (
    <div className="agent-interface">
      <button onClick={inquire}>Seek Understanding</button>
    </div>
  );
}

```
</TypeScriptExample>

The `useAgent` hook automatically handles the lifecycle of the connection, ensuring that it is properly initialized and cleaned up when the component mounts and unmounts. You can also [combine `useAgent` with `useState`](/agents/api-reference/store-and-sync-state/) to automatically synchronize state across all clients connected to your Agent.

### Handling WebSocket events

Define `onError` and `onClose` methods on your Agent to explicitly handle WebSocket client errors and close events. Log errors, clean up state, and/or emit metrics:

<TypeScriptExample>

```ts
import { Agent, Connection } from "agents";

export class ChatAgent extends Agent {
 	// onConnect and onMessage methods
  // ...

  // WebSocket error and disconnection (close) handling.
  async onError(connection: Connection, error: unknown): Promise<void> {
		console.error(`WS error: ${error}`);
	}
	async onClose(connection: Connection, code: number, reason: string, wasClean: boolean): Promise<void> {
		console.log(`WS closed: ${code} - ${reason} - wasClean: ${wasClean}`);
		connection.close();
	}
}

```

</TypeScriptExample>

---

# Calling LLMs

URL: https://developers.cloudflare.com/agents/concepts/calling-llms/

import { Render } from "~/components";

### Understanding LLM providers and model types

Different LLM providers offer models optimized for specific types of tasks. When building AI systems, choosing the right model is crucial for both performance and cost efficiency.

#### Reasoning Models

Models like OpenAI's o1, Anthropic's Claude, and DeepSeek's R1 are particularly well-suited for complex reasoning tasks. These models excel at:

- Breaking down problems into steps
- Following complex instructions
- Maintaining context across long conversations
- Generating code and technical content

For example, when implementing a travel booking system, you might use a reasoning model to analyze travel requirements and generate appropriate booking strategies.

#### Instruction Models

Models like GPT-4 and Claude Instant are optimized for following straightforward instructions efficiently. They work well for:
- Content generation
- Simple classification tasks
- Basic question answering
- Text transformation

These models are often more cost-effective for straightforward tasks that do not require complex reasoning.

---

# Human in the Loop

URL: https://developers.cloudflare.com/agents/concepts/human-in-the-loop/

### What is Human-in-the-Loop?

Human-in-the-Loop (HITL) workflows integrate human judgment and oversight into automated processes. These workflows pause at critical points for human review, validation, or decision-making before proceeding. This approach combines the efficiency of automation with human expertise and oversight where it matters most.

![A human-in-the-loop diagram](~/assets/images/agents/human-in-the-loop.svg)

#### Understanding Human-in-the-Loop workflows

In a Human-in-the-Loop workflow, processes are not fully automated. Instead, they include designated checkpoints where human intervention is required. For example, in a travel booking system, a human may want to confirm the travel before an agent follows through with a transaction. The workflow manages this interaction, ensuring that:

1. The process pauses at appropriate review points
2. Human reviewers receive necessary context
3. The system maintains state during the review period
4. Review decisions are properly incorporated
5. The process continues once approval is received

### Best practices for Human-in-the-Loop workflows

#### Long-Term State Persistence

Human review processes do not operate on predictable timelines. A reviewer might need days or weeks to make a decision, especially for complex cases requiring additional investigation or multiple approvals. Your system needs to maintain perfect state consistency throughout this period, including:

- The original request and context
- All intermediate decisions and actions
- Any partial progress or temporary states
- Review history and feedback

:::note[Tip]
[Durable Objects](/durable-objects/) provide an ideal solution for managing state in Human-in-the-Loop workflows, offering persistent compute instances that maintain state for hours, weeks, or months.
:::

#### Continuous Improvement Through Evals

Human reviewers play a crucial role in evaluating and improving LLM performance. Implement a systematic evaluation process where human feedback is collected not just on the final output, but on the LLM's decision-making process. This can include:

- Decision Quality Assessment: Have reviewers evaluate the LLM's reasoning process and decision points, not just the final output.
- Edge Case Identification: Use human expertise to identify scenarios where the LLM's performance could be improved.
- Feedback Collection: Gather structured feedback that can be used to fine-tune the LLM or adjust the workflow. [AI Gateway](/ai-gateway/evaluations/add-human-feedback/) can be a useful tool for setting up an LLM feedback loop.

#### Error handling and recovery

Robust error handling is essential for maintaining workflow integrity. Your system should gracefully handle various failure scenarios, including reviewer unavailability, system outages, or conflicting reviews. Implement clear escalation paths for handling exceptional cases that fall outside normal parameters.

The system should maintain stability during paused states, ensuring that no work is lost even during extended review periods. Consider implementing automatic checkpointing that allows workflows to be resumed from the last stable state after any interruption.

---

# Concepts

URL: https://developers.cloudflare.com/agents/concepts/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Tools

URL: https://developers.cloudflare.com/agents/concepts/tools/

### What are tools?

Tools enable AI systems to interact with external services and perform actions. They provide a structured way for agents and workflows to invoke APIs, manipulate data, and integrate with external systems. Tools form the bridge between AI decision-making capabilities and real-world actions.

### Understanding tools

In an AI system, tools are typically implemented as function calls that the AI can use to accomplish specific tasks. For example, a travel booking agent might have tools for:

- Searching flight availability
- Checking hotel rates 
- Processing payments
- Sending confirmation emails

Each tool has a defined interface specifying its inputs, outputs, and expected behavior. This allows the AI system to understand when and how to use each tool appropriately.

### Common tool patterns

#### API integration tools

The most common type of tools are those that wrap external APIs. These tools handle the complexity of API authentication, request formatting, and response parsing, presenting a clean interface to the AI system.

#### Model Context Protocol (MCP)

The [Model Context Protocol](https://modelcontextprotocol.io/introduction) provides a standardized way to define and interact with tools. Think of it as an abstraction on top of APIs designed for LLMs to interact with external resources. MCP defines a consistent interface for:

- **Tool Discovery**: Systems can dynamically discover available tools
- **Parameter Validation**: Tools specify their input requirements using JSON Schema
- **Error Handling**: Standardized error reporting and recovery
- **State Management**: Tools can maintain state across invocations


#### Data processing tools

Tools that handle data transformation and analysis are essential for many AI workflows. These might include:

- CSV parsing and analysis
- Image processing
- Text extraction
- Data validation

---

# Agents

URL: https://developers.cloudflare.com/agents/concepts/what-are-agents/

import { Render } from "~/components";

### What are agents?

An agent is an AI system that can autonomously execute tasks by making decisions about tool usage and process flow. Unlike traditional automation that follows predefined paths, agents can dynamically adapt their approach based on context and intermediate results. Agents are also distinct from co-pilots (e.g. traditional chat applications) in that they can fully automate a task, as opposed to simply augmenting and extending human input. 

- **Agents** → non-linear, non-deterministic (can change from run to run)
- **Workflows** → linear, deterministic execution paths
- **Co-pilots** → augmentative AI assistance requiring human intervention

### Example: Booking vacations

If this is your first time working with, or interacting with agents, this example will illustrate how an agent works within a context like booking a vacation. If you are already familiar with the topic, read on. 

Imagine you're trying to book a vacation. You need to research flights, find hotels, check restaurant reviews, and keep track of your budget. 

#### Traditional workflow automation

A traditional automation system follows a predetermined sequence:

- Takes specific inputs (dates, location, budget)
- Calls predefined API endpoints in a fixed order
- Returns results based on hardcoded criteria
- Cannot adapt if unexpected situations arise

![Traditional workflow automation diagram](~/assets/images/agents/workflow-automation.svg)

#### AI Co-pilot

A co-pilot acts as an intelligent assistant that:

- Provides hotel and itinerary recommendations based on your preferences
- Can understand and respond to natural language queries
- Offers guidance and suggestions
- Requires human decision-making and action for execution

![A co-pilot diagram](~/assets/images/agents/co-pilot.svg)

#### Agent

An agent combines AI's ability to make judgements and call the relevant tools to execute the task. An agent's output will be nondeterministic given:

- Real-time availability and pricing changes
- Dynamic prioritization of constraints
- Ability to recover from failures
- Adaptive decision-making based on intermediate results

![An agent diagram](~/assets/images/agents/agent-workflow.svg)

An agents can dynamically generate an itinerary and execute on booking reservations, similarly to what you would expect from a travel agent. 

### Three primary components of agent systems:

- **Decision Engine**: Usually an LLM (Large Language Model) that determines action steps
- **Tool Integration**: APIs, functions, and services the agent can utilize
- **Memory System**: Maintains context and tracks task progress

#### How agents work

Agents operate in a continuous loop of:

1. **Observing** the current state or task
2. **Planning** what actions to take, using AI for reasoning
3. **Executing** those actions using available tools (often APIs or [MCPs](https://modelcontextprotocol.io/introduction))
4. **Learning** from the results (storing results in memory, updating task progress, and preparing for next iteration)

---

# Workflows

URL: https://developers.cloudflare.com/agents/concepts/workflows/

import { Render } from "~/components";

## What are workflows?

A workflow is the orchestration layer that coordinates how an agent's components work together. It defines the structured paths through which tasks are processed, tools are called, and results are managed. While agents make dynamic decisions about what to do, workflows provide the underlying framework that governs how those decisions are executed.

### Understanding workflows in agent systems

Think of a workflow like the operating procedures of a company. The company (agent) can make various decisions, but how those decisions get implemented follows established processes (workflows). For example, when you book a flight through a travel agent, they might make different decisions about which flights to recommend, but the process of actually booking the flight follows a fixed sequence of steps.

Let's examine a basic agent workflow:

### Core components of a workflow

A workflow typically consists of several key elements:

1. **Input Processing**
The workflow defines how inputs are received and validated before being processed by the agent. This includes standardizing formats, checking permissions, and ensuring all required information is present.
2. **Tool Integration**
Workflows manage how external tools and services are accessed. They handle authentication, rate limiting, error recovery, and ensuring tools are used in the correct sequence.
3. **State Management**
The workflow maintains the state of ongoing processes, tracking progress through multiple steps and ensuring consistency across operations.
4. **Output Handling**
Results from the agent's actions are processed according to defined rules, whether that means storing data, triggering notifications, or formatting responses.

---

# Getting started

URL: https://developers.cloudflare.com/agents/getting-started/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Testing your Agents

URL: https://developers.cloudflare.com/agents/getting-started/testing-your-agent/

import { Render, PackageManagers, WranglerConfig } from "~/components";

Because Agents run on Cloudflare Workers and Durable Objects, they can be tested using the same tools and techniques as Workers and Durable Objects.

## Writing and running tests

### Setup

:::note

The `agents-starter` template and new Cloudflare Workers projects already include the relevant `vitest` and `@cloudflare/vitest-pool-workers` packages, as well as a valid `vitest.config.js` file.

:::

Before you write your first test, install the necessary packages:

```sh
npm install vitest@~3.0.0 --save-dev --save-exact
npm install @cloudflare/vitest-pool-workers --save-dev
```

Ensure that your `vitest.config.js` file is identical to the following:

```js
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
	test: {
		poolOptions: {
			workers: {
				wrangler: { configPath: "./wrangler.toml" },
			},
		},
	},
});
```

### Add the Agent configuration

Add a `durableObjects` configuration to `vitest.config.js` with the name of your Agent class:

```js
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
	test: {
		poolOptions: {
			workers: {
				main: "./src/index.ts",
				miniflare: {
					durableObjects: {
						NAME: "MyAgent",
					},
				},
			},
		},
	},
});
```

### Write a test

:::note

Review the [Vitest documentation](https://vitest.dev/) for more information on testing, including the test API reference and advanced testing techniques.

:::

Tests use the `vitest` framework. A basic test suite for your Agent can validate how your Agent responds to requests, but can also unit test your Agent's methods and state.

```ts
import {
	env,
	createExecutionContext,
	waitOnExecutionContext,
	SELF,
} from "cloudflare:test";
import { describe, it, expect } from "vitest";
import worker from "../src";
import { Env } from "../src";

interface ProvidedEnv extends Env {}

describe("make a request to my Agent", () => {
	// Unit testing approach
	it("responds with state", async () => {
		// Provide a valid URL that your Worker can use to route to your Agent
		// If you are using routeAgentRequest, this will be /agent/:agent/:name
		const request = new Request<unknown, IncomingRequestCfProperties>(
			"http://example.com/agent/my-agent/agent-123",
		);
		const ctx = createExecutionContext();
		const response = await worker.fetch(request, env, ctx);
		await waitOnExecutionContext(ctx);
		expect(await response.text()).toMatchObject({ hello: "from your agent" });
	});

	it("also responds with state", async () => {
		const request = new Request("http://example.com/agent/my-agent/agent-123");
		const response = await SELF.fetch(request);
		expect(await response.text()).toMatchObject({ hello: "from your agent" });
	});
});
```

### Run tests

Running tests is done using the `vitest` CLI:

```sh
$ npm run test
# or run vitest directly
$ npx vitest
```

```sh output
  MyAgent
    ✓ should return a greeting (1 ms)

Test Files  1 passed (1)
```

Review the [documentation on testing](/workers/testing/vitest-integration/write-your-first-test/) for additional examples and test configuration.

## Running Agents locally

You can also run an Agent locally using the `wrangler` CLI:

```sh
$ npx wrangler dev
```

```sh output
Your Worker and resources are simulated locally via Miniflare. For more information, see: https://developers.cloudflare.com/workers/testing/local-development.

Your worker has access to the following bindings:
- Durable Objects:
  - MyAgent: MyAgent
  Starting local server...
[wrangler:inf] Ready on http://localhost:53645
```

This spins up a local development server that runs the same runtime as Cloudflare Workers, and allows you to iterate on your Agent's code and test it locally without deploying it.

Visit the [`wrangler dev`](https://developers.cloudflare.com/workers/wrangler/commands/#dev) docs to review the CLI flags and configuration options.

---

# Guides

URL: https://developers.cloudflare.com/agents/guides/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Build a Remote MCP server

URL: https://developers.cloudflare.com/agents/guides/remote-mcp-server/

import { Details, Render, PackageManagers } from "~/components";

## Deploy your first MCP server

This guide will show you how to deploy your own remote MCP server on Cloudflare, with two options:

- **Without authentication** — anyone can connect and use the server (no login required).
- **With [authentication and authorization](/agents/guides/remote-mcp-server/#add-authentication)** — users sign in before accessing tools, and you can control which tools an agent can call based on the user's permissions.

You can start by deploying a [public MCP server](https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-authless) without authentication, then add user authentication and scoped authorization later. If you already know your server will require authentication, you can skip ahead to the [next section](/agents/guides/remote-mcp-server/#add-authentication).

The button below will guide you through everything you need to do to deploy this [example MCP server](https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-authless) to your Cloudflare account:

[![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-authless)

Once deployed, this server will be live at your workers.dev subdomain (e.g. remote-mcp-server-authless.your-account.workers.dev/sse). You can connect to it immediately using the [AI Playground](https://playground.ai.cloudflare.com/) (a remote MCP client), [MCP inspector](https://github.com/modelcontextprotocol/inspector) or [other MCP clients](/agents/guides/remote-mcp-server/#connect-your-remote-mcp-server-to-claude-and-other-mcp-clients-via-a-local-proxy). Then, once you're ready, you can customize the MCP server and add your own [tools](/agents/model-context-protocol/tools/). 

If you're using the "Deploy to Cloudflare" button, a new git repository will be set up on your GitHub or GitLab account for your MCP server, configured to automatically deploy to Cloudflare each time you push a change or merge a pull request to the main branch of the repository. You can then clone this repository, [develop locally](/agents/guides/remote-mcp-server/#local-development), and start writing code and building.

### Set up and deploy your MCP server via CLI

Alternatively, you can use the command line as shown below to create a new MCP Server on your local machine.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"my-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless"}
/>

Now, you have the MCP server setup, with dependencies installed. Move into that project folder:

```sh
cd my-mcp-server
```

#### Local development

In the directory of your new project, run the following command to start the development server:

```sh
npm start
```

Your MCP server is now running on `http://localhost:8787/sse`.

In a new terminal, run the [MCP inspector](https://github.com/modelcontextprotocol/inspector). The MCP inspector is an interactive MCP client that allows you to connect to your MCP server and invoke tools from a web browser.

```sh
npx @modelcontextprotocol/inspector@latest
```

Open the MCP inspector in your web browser:

```sh
open http://localhost:5173
```

In the inspector, enter the URL of your MCP server, `http://localhost:8787/sse`, and click **Connect**. You should see the "List Tools" button, which will list the tools that your MCP server exposes.

![MCP inspector — authenticated](~/assets/images/agents/mcp-inspector-authenticated.png)

#### Deploy your MCP server

You can deploy your MCP server to Cloudflare using the following [Wrangler CLI command](/workers/wrangler) within the example project:

```sh
npx wrangler@latest deploy
```

If you have already [connected a git repository](/workers/ci-cd/builds/) to the Worker with your MCP server, you can deploy your MCP server by pushing a change or merging a pull request to the main branch of the repository.

After deploying, take the URL of your deployed MCP server, and enter it in the MCP inspector running on `http://localhost:5173`. You now have a remote MCP server, deployed to Cloudflare, that MCP clients can connect to.

### Connect your Remote MCP server to Claude and other MCP Clients via a local proxy

Now that your MCP server is running, you can use the [`mcp-remote` local proxy](https://www.npmjs.com/package/mcp-remote) to connect Claude Desktop or other MCP clients to it — even though these tools aren't yet _remote_ MCP clients, and don't support remote transport or authorization on the client side. This lets you test what an interaction with your MCP server will be like with a real MCP client.

Update your Claude Desktop configuration to point to the URL of your MCP server. You can use either the `localhost:8787/sse` URL, or the URL of your deployed MCP server:

```json
{
	"mcpServers": {
		"math": {
			"command": "npx",
			"args": [
				"mcp-remote",
				"https://your-worker-name.your-account.workers.dev/sse"
			]
		}
	}
}
```

Restart Claude Desktop after updating your config file to load the MCP Server. Once this is done, Claude will be able to make calls to your remote MCP server. You can test this by asking Claude to use one of your tools. For example: "Could you use the math tool to add 23 and 19?". Claude should invoke the tool and show the result generated by the MCP server.

Learn more about other ways of using remote MCP servers with MCP clients here in [this section](/agents/guides/test-remote-mcp-server).

## Add Authentication

Now that you’ve deployed a public MCP server, let’s walk through how to enable user authentication using OAuth.

The public server example you deployed earlier allows any client to connect and invoke tools without logging in. To add authentication, you’ll update your MCP server to act as an OAuth provider, handling secure login flows and issuing access tokens that MCP clients can use to make authenticated tool calls.

This is especially useful if users already need to log in to use your service. Once authentication is enabled, users can sign in with their existing account and grant their AI agent permission to interact with the tools exposed by your MCP server, using scoped permissions.

In this example, we use GitHub as an OAuth provider, but you can connect your MCP server with any [OAuth provider](/agents/model-context-protocol/authorization/#2-third-party-oauth-provider) that supports the OAuth 2.0 specification, including Google, Slack, [Stytch](/agents/model-context-protocol/authorization/#stytch), [Auth0](/agents/model-context-protocol/authorization/#stytch), [WorkOS](/agents/model-context-protocol/authorization/#stytch), and more.

### Step 1 — Create and deploy a new MCP server

Run the following command to create a new MCP server:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={
		"my-mcp-server-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth"
	}
/>

Now, you have the MCP server setup, with dependencies installed. Move into that project folder:

```sh
cd my-mcp-server-github-auth
```

Then, run the following command to deploy the MCP server:

```sh
npx wrangler@latest deploy
```

You'll notice that in the example MCP server, if you open `src/index.ts`, the primary difference is that the `defaultHandler` is set to the `GitHubHandler`:

```ts ins="OAuthProvider.GitHubHandler"
import GitHubHandler from "./github-handler";

export default new OAuthProvider({
	apiRoute: "/sse",
	apiHandler: MyMCP.Router,
	defaultHandler: GitHubHandler,
	authorizeEndpoint: "/authorize",
	tokenEndpoint: "/token",
	clientRegistrationEndpoint: "/register",
});
```

This will ensure that your users are redirected to GitHub to authenticate. To get this working though, you need to create OAuth client apps in the steps below.

### Step 2 — Create an OAuth App

You'll need to create two [GitHub OAuth Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) to use GitHub as an authentication provider for your MCP server — one for local development, and one for production.

#### First create a new OAuth App for local development

Navigate to [github.com/settings/developers](https://github.com/settings/developers) to create a new OAuth App with the following settings:

- **Application name**: `My MCP Server (local)`
- **Homepage URL**: `http://localhost:8787`
- **Authorization callback URL**: `http://localhost:8787/callback`

For the OAuth app you just created, add the client ID of the OAuth app as `GITHUB_CLIENT_ID` and generate a client secret, adding it as `GITHUB_CLIENT_SECRET` to a `.dev.vars` file in the root of your project, which [will be used to set secrets in local development](/workers/configuration/secrets/).

```sh
touch .dev.vars
echo 'GITHUB_CLIENT_ID="your-client-id"' >> .dev.vars
echo 'GITHUB_CLIENT_SECRET="your-client-secret"' >> .dev.vars
cat .dev.vars
```

#### Next, run your MCP server locally

Run the following command to start the development server:

```sh
npm start
```

Your MCP server is now running on `http://localhost:8787/sse`.

In a new terminal, run the [MCP inspector](https://github.com/modelcontextprotocol/inspector). The MCP inspector is an interactive MCP client that allows you to connect to your MCP server and invoke tools from a web browser.

```sh
npx @modelcontextprotocol/inspector@latest
```

Open the MCP inspector in your web browser:

```sh
open http://localhost:5173
```

In the inspector, enter the URL of your MCP server, `http://localhost:8787/sse`, and click **Connect**:

You should be redirected to a GitHub login or authorization page. After authorizing the MCP Client (the inspector) access to your GitHub account, you will be redirected back to the inspector. You should see the "List Tools" button, which will list the tools that your MCP server exposes.

#### Second — create a new OAuth App for production

You'll need to repeat these steps to create a new OAuth App for production.

Navigate to [github.com/settings/developers](https://github.com/settings/developers) to create a new OAuth App with the following settings:

- **Application name**: `My MCP Server (production)`
- **Homepage URL**: Enter the workers.dev URL of your deployed MCP server (ex: `worker-name.account-name.workers.dev`)
- **Authorization callback URL**: Enter the `/callback` path of the workers.dev URL of your deployed MCP server (ex: `worker-name.account-name.workers.dev/callback`)

For the OAuth app you just created, add the client ID and client secret, using Wrangler CLI:

```sh
wrangler secret put GITHUB_CLIENT_ID
```

```sh
wrangler secret put GITHUB_CLIENT_SECRET
```

#### Finally, connect to your MCP server

Now that you've added the ID and secret of your production OAuth app, you should now be able to connect to your MCP server running at `worker-name.account-name.workers.dev/sse` using the [AI Playground](https://playground.ai.cloudflare.com/), MCP inspector or ([other MCP clients](/agents/guides/remote-mcp-server/#connect-your-mcp-server-to-claude-and-other-mcp-clients)), and authenticate with GitHub.

## Next steps

- Add [tools](/agents/model-context-protocol/tools/) to your MCP server.
- Customize your MCP Server's [authentication and authorization](/agents/model-context-protocol/authorization/).

---

# Test a Remote MCP Server

URL: https://developers.cloudflare.com/agents/guides/test-remote-mcp-server/

import { Render } from "~/components";

Remote, authorized connections are an evolving part of the [Model Context Protocol (MCP) specification](https://spec.modelcontextprotocol.io/specification/draft/basic/authorization/). Not all MCP clients support remote connections yet.

This guide will show you options for how to start using your remote MCP server with MCP clients that support remote connections. If you haven't yet created and deployed a remote MCP server, you should follow the [Build a Remote MCP Server](/agents/guides/remote-mcp-server/) guide first.

## The Model Context Protocol (MCP) inspector

The [`@modelcontextprotocol/inspector` package](https://github.com/modelcontextprotocol/inspector) is a visual testing tool for MCP servers.

You can run it locally by running the following command:

```bash
npx @modelcontextprotocol/inspector
```

Then, enter the URL of your remote MCP server. You can use an MCP server running on your local machine on localhost, or you can use a remote MCP server running on Cloudflare.

![MCP inspector](~/assets/images/agents/mcp-inspector-enter-url.png)

Once you have authenticated, you will be redirected back to the inspector. You should see the "List Tools" button, which will list the tools that your MCP server exposes.

![MCP inspector — authenticated](~/assets/images/agents/mcp-inspector-authenticated.png)

## Connect your remote MCP server to Claude Desktop via a local proxy

Even though [Claude Desktop](https://claude.ai/download) doesn't yet support remote MCP clients, you can use the [`mcp-remote` local proxy](https://www.npmjs.com/package/mcp-remote) to connect it to your remote MCP server. This lets you to test what an interaction with your remote MCP server will be like with a real-world MCP client.

1. Open Claude Desktop and navigate to Settings -> Developer -> Edit Config. This opens the configuration file that controls which MCP servers Claude can access.
2. Replace the content with a configuration like this:

```json
{
	"mcpServers": {
		"math": {
			"command": "npx",
			"args": ["mcp-remote", "http://my-mcp-server.my-account.workers.dev/sse"]
		}
	}
}
```

This tells Claude to communicate with your MCP server running at `http://localhost:8787/sse`.

3. Save the file and restart Claude Desktop (command/ctrl + R). When Claude restarts, a browser window will open showing your OAuth login page. Complete the authorization flow to grant Claude access to your MCP server.

Once authenticated, you'll be able to see your tools by clicking the tools icon in the bottom right corner of Claude's interface.

## Connect your remote MCP server to Cursor

To connect [Cursor](https://www.cursor.com/) with your remote MCP server, choose `Type`: "Command" and in the `Command` field, combine the command and args fields into one (e.g.`npx mcp-remote https://your-worker-name.your-account.workers.dev/sse`).

## Connect your remote MCP server to Windsurf

You can connect your remote MCP server to [Windsurf](https://codeium.com/windsurf) by editing the [`mcp_config.json` file](https://docs.codeium.com/windsurf/mcp), and adding the following configuration:

```json
{
	"mcpServers": {
		"math": {
			"command": "npx",
			"args": ["mcp-remote", "http://my-mcp-server.my-account.workers.dev/sse"]
		}
	}
}
```

---

# Authorization

URL: https://developers.cloudflare.com/agents/model-context-protocol/authorization/

import { DirectoryListing } from "~/components";

When building a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server, you need both a way to allow users to login (authentication) and allow them to grant the MCP client access to resources on their account (authorization).

<diagram>

</diagram>

The Model Context Protocol uses [a subset of OAuth 2.1 for authorization](https://spec.modelcontextprotocol.io/specification/draft/basic/authorization/). OAuth allows your users to grant limited access to resources, without them having to share API keys or other credentials.

Cloudflare provides an [OAuth Provider Library](https://github.com/cloudflare/workers-oauth-provider) that implements the provider side of the OAuth 2.1 protocol, allowing you to easily add authorization to your MCP server.

You can use the OAuth Provider Library in three ways:

1. **Your Worker handles authorization itself.** Your MCP server, running on Cloudflare, handles the complete OAuth flow. ([Example](/agents/guides/remote-mcp-server/))
2. **Integrate directly with a third-party OAuth provider**, such as GitHub or Google.
3. **Integrate with your own OAuth provider**, including authorization-as-a-service providers you might already rely on, such as Stytch, Auth0, or WorkOS.

The following sections describe each of these options and link to runnable code examples for each.

## Authorization options

### (1) Your MCP Server handles authorization and authentication itself

Your MCP Server, using the [OAuth Provider Library](https://github.com/cloudflare/workers-oauth-provider), can handle the complete OAuth authorization flow, without any third-party involvement.

The [Workers OAuth Provider Library](https://github.com/cloudflare/workers-oauth-provider) is a Cloudflare Worker that implements a [`fetch()` handler](/workers/runtime-apis/handlers/fetch/), and handles incoming requests to your MCP server.

You provide your own handlers for your MCP Server's API, and authentication and authorization logic, and URI paths for the OAuth endpoints, as shown below:

```ts
export default new OAuthProvider({
	apiRoute: "/mcp",
	// Your MCP server:
	apiHandler: MyMCPServer.Router,
	// Your handler for authentication and authorization:
	defaultHandler: MyAuthHandler,
	authorizeEndpoint: "/authorize",
	tokenEndpoint: "/token",
	clientRegistrationEndpoint: "/register",
});
```

Refer to the [getting started example](/agents/guides/remote-mcp-server/) for a complete example of the `OAuthProvider` in use, with a mock authentication flow.

The authorization flow in this case works like this:

```mermaid
sequenceDiagram
    participant B as User-Agent (Browser)
    participant C as MCP Client
    participant M as MCP Server (your Worker)

    C->>M: MCP Request
    M->>C: HTTP 401 Unauthorized
    Note over C: Generate code_verifier and code_challenge
    C->>B: Open browser with authorization URL + code_challenge
    B->>M: GET /authorize
    Note over M: User logs in and authorizes
    M->>B: Redirect to callback URL with auth code
    B->>C: Callback with authorization code
    C->>M: Token Request with code + code_verifier
    M->>C: Access Token (+ Refresh Token)
    C->>M: MCP Request with Access Token
    Note over C,M: Begin standard MCP message exchange
```

Remember — [authentication is different from authorization](https://www.cloudflare.com/learning/access-management/authn-vs-authz/). Your MCP Server can handle authorization itself, while still relying on an external authentication service to first authenticate users. The [example](/agents/guides/remote-mcp-server) in getting started provides a mock authentication flow. You will need to implement your own authentication handler — either handling authentication yourself, or using an external authentication services.

### (2) Third-party OAuth Provider

The [OAuth Provider Library](https://github.com/cloudflare/workers-oauth-provider) can be configured to use a third-party OAuth provider, such as GitHub or Google. You can see a complete example of this in the [GitHub example](/agents/guides/remote-mcp-server/#add-authentication).

When you use a third-party OAuth provider, you must provide a handler to the `OAuthProvider` that implements the OAuth flow for the third-party provider.

```ts ins="defaultHandler: MyAuthHandler,"
import MyAuthHandler from "./auth-handler";

export default new OAuthProvider({
	apiRoute: "/mcp",
	// Your MCP server:
	apiHandler: MyMCPServer.Router,
	// Replace this handler with your own handler for authentication and authorization with the third-party provider:
	defaultHandler: MyAuthHandler,
	authorizeEndpoint: "/authorize",
	tokenEndpoint: "/token",
	clientRegistrationEndpoint: "/register",
});
```

Note that as [defined in the Model Context Protocol specification](https://spec.modelcontextprotocol.io/specification/draft/basic/authorization/#292-flow-description) when you use a third-party OAuth provider, the MCP Server (your Worker) generates and issues its own token to the MCP client:

```mermaid
sequenceDiagram
    participant B as User-Agent (Browser)
    participant C as MCP Client
    participant M as MCP Server (your Worker)
    participant T as Third-Party Auth Server

    C->>M: Initial OAuth Request
    M->>B: Redirect to Third-Party /authorize
    B->>T: Authorization Request
    Note over T: User authorizes
    T->>B: Redirect to MCP Server callback
    B->>M: Authorization code
    M->>T: Exchange code for token
    T->>M: Third-party access token
    Note over M: Generate bound MCP token
    M->>B: Redirect to MCP Client callback
    B->>C: MCP authorization code
    C->>M: Exchange code for token
    M->>C: MCP access token
```

Read the docs for the [Workers oAuth Provider Library](https://github.com/cloudflare/workers-oauth-provider) for more details.

### (3) Bring your own OAuth Provider

If your application already implements an OAuth Provider itself, or you use [Stytch](https://stytch.com/), [Auth0](https://auth0.com/), [WorkOS](https://workos.com/), or authorization-as-a-service provider, you can use this in the same way that you would use a third-party OAuth provider, described above in (2).

You can use the auth provider to:
- Allow users to authenticate to your MCP server through email, social logins, SSO (single sign-on), and MFA (multi-factor authentication).
- Define scopes and permissions that directly map to your MCP tools.
- Present users with a consent page corresponding with the requested permissions.
- Enforce the permissions so that agents can only invoke permitted tools.

#### Stytch
Get started with a [remote MCP server that uses Stytch](https://stytch.com/docs/guides/connected-apps/mcp-servers) to allow users to sign in with email, Google login or enterprise SSO and authorize their AI agent to view and manage their company's OKRs on their behalf. Stytch will handle restricting the scopes granted to the AI agent based on the user's role and permissions within their organization. When authorizing the MCP Client, each user will see a consent page that outlines the permissions that the agent is requesting that they are able to grant based on their role.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/ai/tree/main/demos/mcp-stytch-b2b-okr-manager)

For more consumer use cases, deploy a remote MCP server for a To Do app that uses Stytch for authentication and MCP client authorization. Users can sign in with email and immediately access the To Do lists associated with their account, and grant access to any AI assistant to help them manage their tasks.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/ai/tree/main/demos/mcp-stytch-consumer-todo-list)

#### Auth0
Get started with a remote MCP server that uses Auth0 to authenticate users through email, social logins, or enterprise SSO to interact with their todos and personal data through AI agents. The MCP server securely connects to API endpoints on behalf of users, showing exactly which resources the agent will be able to access once it gets consent from the user. In this implementation, access tokens are automatically refreshed during long running interactions.

To set it up, first deploy the protected API endpoint:

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-auth0/todos-api)

Then, deploy the MCP server that handles authentication through Auth0 and securely connects AI agents to your API endpoint.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-auth0/mcp-auth0-oidc)

#### WorkOS

Get started with a remote MCP server that uses WorkOS's AuthKit to authenticate users and manage the permissions granted to AI agents. In this example, the MCP server dynamically exposes tools based on the user's role and access rights. All authenticated users get access to the `add` tool, but only users who have been assigned the `image_generation` permission in WorkOS can grant the AI agent access to the image generation tool. This showcases how MCP servers can conditionally expose capabilities to AI agents based on the authenticated user's role and permission.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-authkit)

## Using Authentication Context in Your MCP Server

When a user authenticates to your MCP server through Cloudflare's OAuth Provider, their identity information and tokens are made available through the `props` parameter.

```js
export class MyMCP extends McpAgent<Env, unknown, AuthContext> {
  async init() {
    this.server.tool("userInfo", "Get user information", {}, async () => ({
      content: [{ type: "text", text: `Hello, ${this.props.claims.name || "user"}!` }],
    }));
  }
}
```

The authentication context can be used for:

- Accessing user-specific data by using the user ID (this.props.claims.sub) as a key
- Checking user permissions before performing operations
- Customizing responses based on user preferences or attributes
- Using authentication tokens to make requests to external services on behalf of the user
- Ensuring consistency when users interact with your application through different interfaces (dashboard, API, MCP server)

## Implementing Permission-Based Access for MCP Tools

You can implement fine-grained authorization controls for your MCP tools based on user permissions. This allows you to restrict access to certain tools based on the user's role or specific permissions.

```js
// Create a wrapper function to check permissions
function requirePermission(permission, handler) {
  return async (request, context) => {
    // Check if user has the required permission
    const userPermissions = context.props.permissions || [];
    if (!userPermissions.includes(permission)) {
      return {
        content: [{ type: "text", text: `Permission denied: requires ${permission}` }],
        status: 403
      };
    }
    
    // If permission check passes, execute the handler
    return handler(request, context);
  };
}

// Use the wrapper with your MCP tools
async init() {
  // Basic tools available to all authenticated users
  this.server.tool("basicTool", "Available to all users", {}, async () => {
    // Implementation for all users
  });
  
  // Protected tool using the permission wrapper
  this.server.tool(
    "adminAction",
    "Administrative action requiring special permission",
    { /* parameters */ },
    requirePermission("admin", async (req) => {
      // Only executes if user has "admin" permission
      return {
        content: [{ type: "text", text: "Admin action completed" }]
      };
    })
  );
  
  // Conditionally register tools based on user permissions
  if (this.props.permissions?.includes("special_feature")) {
    this.server.tool("specialTool", "Special feature", {}, async () => {
      // This tool only appears for users with the special_feature permission
    });
  }
}
```

Benefits: 
- Authorization check at the tool level ensures proper access control
- Allows you to define permission checks once and reuse them across tools
- Provides clear feedback to users when permission is denied
- Can choose to only present tools that the agent is able to call

## Next steps

- [Learn how to use the Workers OAuth Provider Library](https://github.com/cloudflare/workers-oauth-provider)
- Learn how to use a third-party OAuth provider, using the [GitHub](/agents/guides/remote-mcp-server/#add-authentication) example MCP server.

---

# Model Context Protocol (MCP)

URL: https://developers.cloudflare.com/agents/model-context-protocol/

You can build and deploy [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers on Cloudflare.

## What is the Model Context Protocol (MCP)?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that connects AI systems with external applications. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various accessories, MCP provides a standardized way to connect AI agents to different services.

### MCP Terminology

- **MCP Hosts**: AI assistants (like [Claude](http://claude.ai) or [Cursor](http://cursor.com)), AI agents, or applications that need to access external capabilities.
- **MCP Clients**: Clients embedded within the MCP hosts that connect to MCP servers and invoke tools. Each MCP client instance has a single connection to an MCP server.
- **MCP Servers**: Applications that expose [tools](/agents/model-context-protocol/tools/), [prompts](https://modelcontextprotocol.io/docs/concepts/prompts), and [resources](https://modelcontextprotocol.io/docs/concepts/resources) that MCP clients can use.

### Remote vs. local MCP connections

The MCP standard supports two modes of operation:

- **Remote MCP connections**: MCP clients connect to MCP servers over the Internet, establishing a [long-lived connection using HTTP and Server-Sent Events (SSE)](/agents/model-context-protocol/transport/), and authorizing the MCP client access to resources on the user's account using [OAuth](/agents/model-context-protocol/authorization/).
- **Local MCP connections**: MCP clients connect to MCP servers on the same machine, using [stdio](https://spec.modelcontextprotocol.io/specification/draft/basic/transports/#stdio) as a local transport method.

### Best Practices
- **Tool design**: Do not treat your MCP server as a wrapper around your full API schema. Instead, build tools that are optimized for specific user goals and reliable outcomes. Fewer, well-designed tools often outperform many granular ones, especially for agents with small context windows or tight latency budgets.
- **Scoped permissions**: Deploying several focused MCP servers, each with narrowly scoped permissions, reduces the risk of over-privileged access and makes it easier to manage and audit what each server is allowed to do.
- **Tool descriptions**: Detailed parameter descriptions help agents understand how to use your tools correctly — including what values are expected, how they affect behavior, and any important constraints. This reduces errors and improves reliability.
- **Evaluation tests**: Use evaluation tests ('evals') to measure the agent’s ability to use your tools correctly. Run these after any updates to your server or tool descriptions to catch regressions early and track improvements over time.

### Get Started

Go to the [Getting Started](/agents/guides/remote-mcp-server/) guide to learn how to build and deploy your first remote MCP server to Cloudflare.

---

# McpAgent — API Reference

URL: https://developers.cloudflare.com/agents/model-context-protocol/mcp-agent-api/

import { Render, TypeScriptExample } from "~/components";

When you build MCP Servers on Cloudflare, you extend the [`McpAgent` class](https://github.com/cloudflare/agents/blob/5881c5d23a7f4580600029f69307cfc94743e6b8/packages/agents/src/mcp.ts), from the Agents SDK, like this:

<TypeScriptExample>

```ts title="src/index.ts"
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export class MyMCP extends McpAgent {
  server = new McpServer({ name: "Demo", version: "1.0.0" });

  async init() {
    this.server.tool(
      "add",
      { a: z.number(), b: z.number() },
      async ({ a, b }) => ({
        content: [{ type: "text", text: String(a + b) }],
      }),
    );
  }
}
```

</TypeScriptExample>

This means that each instance of your MCP server has its own durable state, backed by a [Durable Object](/durable-objects/), with its own [SQL database](/agents/api-reference/store-and-sync-state).

Your MCP server doesn't necessarily have to be an Agent. You can build MCP servers that are stateless, and just add [tools](/agents/model-context-protocol/tools) to your MCP server using the `@modelcontextprotocol/typescript-sdk` package.

But if you want your MCP server to:

- remember previous tool calls, and responses it provided
- provide a game to the MCP client, remembering the state of the game board, previous moves, and the score
- cache the state of a previous external API call, so that subsequent tool calls can reuse it
- do anything that an Agent can do, but allow MCP clients to communicate with it

You can use the APIs below in order to do so.

#### Hibernation Support
`McpAgent` instances automatically support [WebSockets Hibernation](/durable-objects/best-practices/websockets/#websocket-hibernation-api), allowing stateful MCP servers to sleep during inactive periods while preserving their state. This means your agents only consume compute resources when actively processing requests, optimizing costs while maintaining the full context and conversation history.

Hibernation is enabled by default and requires no additional configuration.

#### Authentication & Authorization

The McpAgent class provides seamless integration with the [OAuth Provider Library](https://github.com/cloudflare/workers-oauth-provider) for [authentication and authorization](/agents/model-context-protocol/authorization/). 

When a user authenticates to your MCP server, their identity information and tokens are made available through the `props` parameter, allowing you to:

- access user-specific data
- check user permissions before performing operations
- customize responses based on user attributes
- use authentication tokens to make requests to external services on behalf of the user

### State synchronization APIs

The `McpAgent` class makes the following subset of methods from the [Agents SDK](/agents/api-reference/agents-api/) available:

- [`state`](/agents/api-reference/store-and-sync-state/)
- [`initialState`](/agents/api-reference/store-and-sync-state/#set-the-initial-state-for-an-agent)
- [`setState`](/agents/api-reference/store-and-sync-state/)
- [`onStateUpdate`](/agents/api-reference/store-and-sync-state/#synchronizing-state)
- [`sql`](/agents/api-reference/agents-api/#sql-api)

:::note[State resets after the session ends]
Currently, each client session is backed by an instance of the `McpAgent` class. This is handled automatically for you, as shown in the [getting started guide](/agents/guides/remote-mcp-server). This means that when the same client reconnects, they will start a new session, and the state will be reset.
:::

For example, the following code implements an MCP server that remembers a counter value, and updates the counter when the `add` tool is called:

<TypeScriptExample>

```ts title="src/index.ts"
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

type State = { counter: number };

export class MyMCP extends McpAgent<Env, State, {}> {
	server = new McpServer({
		name: "Demo",
		version: "1.0.0",
	});

	initialState: State = {
		counter: 1,
	};

	async init() {
		this.server.resource(`counter`, `mcp://resource/counter`, (uri) => {
			return {
				contents: [{ uri: uri.href, text: String(this.state.counter) }],
			};
		});

		this.server.tool(
			"add",
			"Add to the counter, stored in the MCP",
			{ a: z.number() },
			async ({ a }) => {
				this.setState({ ...this.state, counter: this.state.counter + a });

				return {
					content: [
						{
							type: "text",
							text: String(`Added ${a}, total is now ${this.state.counter}`),
						},
					],
				};
			},
		);
	}

	onStateUpdate(state: State) {
		console.log({ stateUpdate: state });
	}
}
```

</TypeScriptExample>

### Not yet supported APIs

The following APIs from the Agents SDK are not yet available on `McpAgent`:

- [WebSocket APIs](/agents/api-reference/websockets/) (`onMessage`, `onError`, `onClose`, `onConnect`)
- [Scheduling APIs](/agents/api-reference/schedule-tasks/) `this.schedule`

---

# Cloudflare's own MCP servers

URL: https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/

import { Render } from "~/components"

Cloudflare runs a catalog of managed remote MCP Servers which you can connect to using OAuth on clients like [Claude](https://modelcontextprotocol.io/quickstart/user), [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp), our own [AI Playground](https://playground.ai.cloudflare.com/) or any [SDK that supports MCP](https://github.com/cloudflare/agents/tree/main/packages/agents/src/mcp).

These MCP servers allow your MCP Client to read configurations from your account, process information, make suggestions based on data, and even make those suggested changes for you. All of these actions can happen across Cloudflare's many services including application development, security and performance.

| Server Name                                                    | Description                                                                                     | Server URL                                     |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [Documentation server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize)               | Get up to date reference information on Cloudflare                                              | `https://docs.mcp.cloudflare.com/sse`          |
| [Workers Bindings server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/workers-bindings)          | Build Workers applications with storage, AI, and compute primitives                             | `https://bindings.mcp.cloudflare.com/sse`      |
| [Workers Builds server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/workers-builds)              | Get insights and manage your Cloudflare Workers Builds                                          | `https://builds.mcp.cloudflare.com/sse`        |
| [Observability server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/workers-observability)        | Debug and get insight into your application's logs and analytics                                | `https://observability.mcp.cloudflare.com/sse` |
| [Radar server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/radar)                                | Get global Internet traffic insights, trends, URL scans, and other utilities                    | `https://radar.mcp.cloudflare.com/sse`         |
| [Container server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/sandbox-container)                | Spin up a sandbox development environment                                                       | `https://containers.mcp.cloudflare.com/sse`    |
| [Browser rendering server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/browser-rendering)        | Fetch web pages, convert them to markdown and take screenshots                                  | `https://browser.mcp.cloudflare.com/sse`       |
| [Logpush server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/logpush)                            | Get quick summaries for Logpush job health                                                      | `https://logs.mcp.cloudflare.com/sse`          |
| [AI Gateway server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/ai-gateway)                      | Search your logs, get details about the prompts and responses                                   | `https://ai-gateway.mcp.cloudflare.com/sse`    |
| [AutoRAG server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/autorag)                            | List and search documents on your AutoRAGs                                                      | `https://autorag.mcp.cloudflare.com/sse`       |
| [Audit Logs server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/auditlogs)                       | Query audit logs and generate reports for review                                                | `https://auditlogs.mcp.cloudflare.com/sse`     |
| [DNS Analytics server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/dns-analytics)                | Optimize DNS performance and debug issues based on current set up                               | `https://dns-analytics.mcp.cloudflare.com/sse` |
| [Digital Experience Monitoring server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/dex-analysis) | Get quick insight on critical applications for your organization                                | `https://dex.mcp.cloudflare.com/sse`           |
| [Cloudflare One CASB server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/cloudflare-one-casb)    | Quickly identify any security misconfigurations for SaaS applications to safeguard users & data | `https://casb.mcp.cloudflare.com/sse`          |
| [GraphQL server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/graphql/)                           | Get analytics data using Cloudflare’s GraphQL API                                               | `https://graphql.mcp.cloudflare.com/sse`       |

Check our [GitHub page](https://github.com/cloudflare/mcp-server-cloudflare) to know how to use Cloudflare's remote MCP servers with different MCP clients.

---

# Tools

URL: https://developers.cloudflare.com/agents/model-context-protocol/tools/

import { Render, TypeScriptExample } from "~/components";

Model Context Protocol (MCP) tools are functions that a [MCP Server](/agents/model-context-protocol) provides and MCP clients can call.

When you build MCP Servers with the `@cloudflare/model-context-protocol` package, you can define tools the [same way as shown in the `@modelcontextprotocol/typescript-sdk` package's examples](https://github.com/modelcontextprotocol/typescript-sdk?tab=readme-ov-file#tools).

For example, the following code from [this example MCP server](https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-server) defines a simple MCP server that adds two numbers together:

<TypeScriptExample>
```ts title="src/index.ts"
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
import { McpAgent } from "agents/mcp";

export class MyMCP extends McpAgent {
	server = new McpServer({ name: "Demo", version: "1.0.0" });
	async init() {
		this.server.tool(
			"add",
			{ a: z.number(), b: z.number() },
			async ({ a, b }) => ({
				content: [{ type: "text", text: String(a + b) }],
			}),
		);
	}
}
```
</TypeScriptExample>

---

# Transport

URL: https://developers.cloudflare.com/agents/model-context-protocol/transport/

import { Render } from "~/components";
import { TabItem, Tabs } from "~/components";

The Model Context Protocol (MCP) specification defines three standard [transport mechanisms](https://spec.modelcontextprotocol.io/specification/draft/basic/transports/) for communication between clients and servers:

1. **stdio, communication over standard in and standard out** — designed for local MCP connections.
2. **Server-Sent Events (SSE)** — Currently supported by most remote MCP clients, but is expected to be replaced by Streamable HTTP over time. It requires two endpoints: one for sending requests, another for receiving streamed responses.
3. **Streamable HTTP** — New transport method [introduced](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) in March 2025. It simplifies the communication by using a single HTTP endpoint for bidirectional messaging. It is currently gaining adoption among remote MCP clients, but it is expected to become the standard transport in the future.

MCP servers built with the [Agents SDK](/agents) can support both remote transport methods (SSE and Streamable HTTP), with the [`McpAgent` class](https://github.com/cloudflare/agents/blob/2f82f51784f4e27292249747b5fbeeef94305552/packages/agents/src/mcp.ts) automatically handling the transport configuration. 

## Implementing remote MCP transport

If you're building a new MCP server or upgrading an existing one on Cloudflare, we recommend supporting both remote transport methods (SSE and Streamable HTTP) concurrently to ensure compatibility with all MCP clients.

#### Get started quickly
You can use the "Deploy to Cloudflare" button to create a remote MCP server that automatically supports both SSE and Streamable HTTP transport methods.

[![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-authless)

#### Remote MCP server (without authentication)
If you're manually configuring your MCP server, here's how to use the `McpAgent` class to handle both transport methods:

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const { pathname } = new URL(request.url);
    
    if (pathname.startsWith('/sse')) {
      return MyMcpAgent.serveSSE('/sse').fetch(request, env, ctx);
    }
    
    if (pathname.startsWith('/mcp')) {
      return MyMcpAgent.serve('/mcp').fetch(request, env, ctx);
    }
  },
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext): Response | Promise<Response> {
    const { pathname } = new URL(request.url);
    
    if (pathname.startsWith('/sse')) {
      return MyMcpAgent.serveSSE('/sse').fetch(request, env, ctx);
    }
    
    if (pathname.startsWith('/mcp')) {
      return MyMcpAgent.serve('/mcp').fetch(request, env, ctx);
    }
    
    // Handle case where no path matches
    return new Response('Not found', { status: 404 });
  },
};
```
 </TabItem>
<TabItem label="Hono" icon="seti:typescript">
```ts
const app = new Hono()

app.mount('/sse', MyMCP.serveSSE('/sse').fetch, { replaceRequest: false })
app.mount('/mcp', MyMCP.serve('/mcp').fetch, { replaceRequest: false )

export default app
```
</TabItem> </Tabs>

#### MCP Server with Authentication
If your MCP server implements authentication & authorization using the [Workers OAuth Provider](https://github.com/cloudflare/workers-oauth-provider) Library, then you can configure it to support both transport methods using the `apiHandlers` property.

```js
export default new OAuthProvider({
  apiHandlers: {
    '/sse': MyMCP.serveSSE('/sse'),
    '/mcp': MyMCP.serve('/mcp'),
  },
  // ... other OAuth configuration
})
```

### Upgrading an Existing Remote MCP Server
If you've already built a remote MCP server using the Cloudflare Agents SDK, make the following changes to support the new Streamable HTTP transport while maintaining compatibility with remote MCP clients using SSE:
- Use `MyMcpAgent.serveSSE('/sse')` for the existing SSE transport. Previously, this would have been `MyMcpAgent.mount('/sse')`, which has been kept as an alias.
- Add a new path with `MyMcpAgent.serve('/mcp')` to support the new Streamable HTTP transport.

If you have an MCP server with authentication/authorization using the Workers OAuth Provider, [update the configuration](/agents/model-context-protocol/transport/#mcp-server-with-authentication) to use the `apiHandlers` property, which replaces `apiRoute` and `apiHandler`.

:::note
To use apiHandlers, update to @cloudflare/workers-oauth-provider v0.0.4 or later.
:::

With these few changes, your MCP server will support both transport methods, making it compatible with both existing and new clients.

### Testing with MCP Clients
While most MCP clients have not yet adopted the new Streamable HTTP transport, you can start testing it today using [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), an adapter that lets MCP clients that otherwise only support local connections work with remote MCP servers.

Follow [this guide](/agents/guides/test-remote-mcp-server/) for instructions on how to connect to your remote MCP server from Claude Desktop, Cursor, Windsurf, and other local MCP clients, using the [`mcp-remote` local proxy](https://www.npmjs.com/package/mcp-remote).

---

# Platform

URL: https://developers.cloudflare.com/agents/platform/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Limits

URL: https://developers.cloudflare.com/agents/platform/limits/

import { Render } from "~/components"

Limits that apply to authoring, deploying, and running Agents are detailed below.

Many limits are inherited from those applied to Workers scripts and/or Durable Objects, and are detailed in the [Workers limits](/workers/platform/limits/) documentation.

| Feature                                   | Limit         			    |
| ----------------------------------------- | ----------------------- |
| Max concurrent (running) Agents per account	| Tens of millions+ [^1]
| Max definitions per account         | ~250,000+ [^2]
| Max state stored per unique Agent | 1 GB |
| Max compute time per Agent | 30 seconds (refreshed per HTTP request / incoming WebSocket message) [^3] |
| Duration (wall clock) per step [^3]       | Unlimited (for example, waiting on a database call or an LLM response) |

---

[^1]: Yes, really. You can have tens of millions of Agents running concurrently, as each Agent is mapped to a [unique Durable Object](/durable-objects/what-are-durable-objects/) (actor).
[^2]: You can deploy up to [500 scripts per account](/workers/platform/limits/), but each script (project) can define multiple Agents. Each deployed script can be up to 10 MB on the [Workers Paid Plan](/workers/platform/pricing/#workers)
[^3]: Compute (CPU) time per Agent is limited to 30 seconds, but this is refreshed when an Agent receives a new HTTP request, runs a [scheduled task](/agents/api-reference/schedule-tasks/), or an incoming WebSocket message.

<Render file="limits_increase" product="workers" />

---

# Authentication

URL: https://developers.cloudflare.com/ai-gateway/configuration/authentication/

Using an Authenticated Gateway in AI Gateway adds security by requiring a valid authorization token for each request. This feature is especially useful when storing logs, as it prevents unauthorized access and protects against invalid requests that can inflate log storage usage and make it harder to find the data you need. With Authenticated Gateway enabled, only requests with the correct token are processed.

:::note
We recommend enabling Authenticated Gateway when opting to store logs with AI Gateway.

If Authenticated Gateway is enabled but a request does not include the required `cf-aig-authorization` header, the request will fail. This setting ensures that only verified requests pass through the gateway. To bypass the need for the `cf-aig-authorization` header, make sure to disable Authenticated Gateway.
:::

## Setting up Authenticated Gateway using the Dashboard

1. Go to the Settings for the specific gateway you want to enable authentication for.
2. Select **Create authentication token** to generate a custom token with the required `Run` permissions. Be sure to securely save this token, as it will not be displayed again.
3. Include the `cf-aig-authorization` header with your API token in each request for this gateway.
4. Return to the settings page and toggle on Authenticated Gateway.

## Example requests with OpenAI

```bash
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header 'cf-aig-authorization: Bearer {CF_AIG_TOKEN}' \
  --header 'Authorization: Bearer OPENAI_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "What is Cloudflare?"}]}'
```

Using the OpenAI SDK:

```javascript
import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: process.env.OPENAI_API_KEY,
	baseURL: "https://gateway.ai.cloudflare.com/v1/account-id/gateway/openai",
	defaultHeaders: {
		"cf-aig-authorization": `Bearer {token}`,
	},
});
```

## Example requests with the Vercel AI SDK

```javascript
import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
	baseURL: "https://gateway.ai.cloudflare.com/v1/account-id/gateway/openai",
	headers: {
		"cf-aig-authorization": `Bearer {token}`,
	},
});
```

## Expected behavior

The following table outlines gateway behavior based on the authentication settings and header status:

| Authentication Setting | Header Info    | Gateway State           | Response                                   |
| ---------------------- | -------------- | ----------------------- | ------------------------------------------ |
| On                     | Header present | Authenticated gateway   | Request succeeds                           |
| On                     | No header      | Error                   | Request fails due to missing authorization |
| Off                    | Header present | Unauthenticated gateway | Request succeeds                           |
| Off                    | No header      | Unauthenticated gateway | Request succeeds                           |

---

# Caching

URL: https://developers.cloudflare.com/ai-gateway/configuration/caching/

import { TabItem, Tabs } from "~/components";

AI Gateway can cache responses from your AI model providers, serving them directly from Cloudflare's cache for identical requests.

## Benefits of Using Caching

- **Reduced Latency:** Serve responses faster to your users by avoiding a round trip to the origin AI provider for repeated requests.
- **Cost Savings:** Minimize the number of paid requests made to your AI provider, especially for frequently accessed or non-dynamic content.
- **Increased Throughput:** Offload repetitive requests from your AI provider, allowing it to handle unique requests more efficiently.

:::note

Currently caching is supported only for text and image responses, and it applies only to identical requests.

This configuration benefits use cases with limited prompt options. For example, a support bot that asks "How can I help you?" and lets the user select an answer from a limited set of options works well with the current caching configuration.
We plan on adding semantic search for caching in the future to improve cache hit rates.
:::

## Default configuration

<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">

To set the default caching configuration in the dashboard:

1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Select **AI** > **AI Gateway**.
3. Select **Settings**.
4. Enable **Cache Responses**.
5. Change the default caching to whatever value you prefer.

</TabItem> <TabItem label="API">

To set the default caching configuration using the API:

1. [Create an API token](/fundamentals/api/get-started/create-token/) with the following permissions:

- `AI Gateway - Read`
- `AI Gateway - Edit`

2. Get your [Account ID](/fundamentals/account/find-account-and-zone-ids/).
3. Using that API token and Account ID, send a [`POST` request](/api/resources/ai_gateway/methods/create/) to create a new Gateway and include a value for the `cache_ttl`.

</TabItem> </Tabs>

This caching behavior will be uniformly applied to all requests that support caching. If you need to modify the cache settings for specific requests, you have the flexibility to override this setting on a per-request basis.

To check whether a response comes from cache or not, **cf-aig-cache-status** will be designated as `HIT` or `MISS`.

## Per-request caching

While your gateway's default cache settings provide a good baseline, you might need more granular control. These situations could be data freshness, content with varying lifespans, or dynamic or personalized responses.

To address these needs, AI Gateway allows you to override default cache behaviors on a per-request basis using specific HTTP headers. This gives you the precision to optimize caching for individual API calls.

The following headers allow you to define this per-request cache behavior:

:::note

The following headers have been updated to new names, though the old headers will still function. We recommend updating to the new headers to ensure future compatibility:

`cf-cache-ttl` is now `cf-aig-cache-ttl`

`cf-skip-cache` is now `cf-aig-skip-cache`

:::

### Skip cache (cf-aig-skip-cache)

Skip cache refers to bypassing the cache and fetching the request directly from the original provider, without utilizing any cached copy.

You can use the header **cf-aig-skip-cache** to bypass the cached version of the request.

As an example, when submitting a request to OpenAI, include the header in the following manner:

```bash title="Request skipping the cache"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-skip-cache: true' \
  --data ' {
   		 "model": "gpt-4o-mini",
   		 "messages": [
   			 {
   				 "role": "user",
   				 "content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
   			 }
   		 ]
   	 }
'
```

### Cache TTL (cf-aig-cache-ttl)

Cache TTL, or Time To Live, is the duration a cached request remains valid before it expires and is refreshed from the original source. You can use **cf-aig-cache-ttl** to set the desired caching duration in seconds. The minimum TTL is 60 seconds and the maximum TTL is one month.

For example, if you set a TTL of one hour, it means that a request is kept in the cache for an hour. Within that hour, an identical request will be served from the cache instead of the original API. After an hour, the cache expires and the request will go to the original API for a fresh response, and that response will repopulate the cache for the next hour.

As an example, when submitting a request to OpenAI, include the header in the following manner:

```bash title="Request to be cached for an hour"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-cache-ttl: 3600' \
  --data ' {
   		 "model": "gpt-4o-mini",
   		 "messages": [
   			 {
   				 "role": "user",
   				 "content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
   			 }
   		 ]
   	 }
'
```

### Custom cache key (cf-aig-cache-key)

Custom cache keys let you override the default cache key in order to precisely set the cacheability setting for any resource. To override the default cache key, you can use the header **cf-aig-cache-key**.

When you use the **cf-aig-cache-key** header for the first time, you will receive a response from the provider. Subsequent requests with the same header will return the cached response. If the **cf-aig-cache-ttl** header is used, responses will be cached according to the specified Cache Time To Live. Otherwise, responses will be cached according to the cache settings in the dashboard. If caching is not enabled for the gateway, responses will be cached for 5 minutes by default.

As an example, when submitting a request to OpenAI, include the header in the following manner:

```bash title="Request with custom cache key"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header 'Authorization: Bearer {openai_token}' \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-cache-key: responseA' \
  --data ' {
   		 "model": "gpt-4o-mini",
   		 "messages": [
   			 {
   				 "role": "user",
   				 "content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
   			 }
   		 ]
   	 }
'
```

:::caution[AI Gateway caching behavior]
Cache in AI Gateway is volatile. If two identical requests are sent simultaneously, the first request may not cache in time for the second request to use it, which may result in the second request retrieving data from the original source.
:::

---

# Custom costs

URL: https://developers.cloudflare.com/ai-gateway/configuration/custom-costs/

import { TabItem, Tabs } from "~/components";

AI Gateway allows you to set custom costs at the request level. By using this feature, the cost metrics can accurately reflect your unique pricing, overriding the default or public model costs.

:::note[Note]

Custom costs will only apply to requests that pass tokens in their response. Requests without token information will not have costs calculated.

:::

## Custom cost

To add custom costs to your API requests, use the `cf-aig-custom-cost` header. This header enables you to specify the cost per token for both input (tokens sent) and output (tokens received).

- **per_token_in**: The negotiated input token cost (per token).
- **per_token_out**: The negotiated output token cost (per token).

There is no limit to the number of decimal places you can include, ensuring precise cost calculations, regardless of how small the values are.

Custom costs will appear in the logs with an underline, making it easy to identify when custom pricing has been applied.

In this example, if you have a negotiated price of $1 per million input tokens and $2 per million output tokens, include the `cf-aig-custom-cost` header as shown below.

```bash title="Request with custom cost"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-custom-cost: {"per_token_in":0.000001,"per_token_out":0.000002}' \
  --data ' {
        "model": "gpt-4o-mini",
        "messages": [
          {
            "role": "user",
            "content": "When is Cloudflare’s Birthday Week?"
          }
        ]
      }'
```

:::note

If a response is served from cache (cache hit), the cost is always `0`, even if you specified a custom cost. Custom costs only apply when the request reaches the model provider.
:::

---

# Custom metadata

URL: https://developers.cloudflare.com/ai-gateway/configuration/custom-metadata/

Custom metadata in AI Gateway allows you to tag requests with user IDs or other identifiers, enabling better tracking and analysis of your requests. Metadata values can be strings, numbers, or booleans, and will appear in your logs, making it easy to search and filter through your data.

## Key Features

* **Custom Tagging**: Add user IDs, team names, test indicators, and other relevant information to your requests.
* **Enhanced Logging**: Metadata appears in your logs, allowing for detailed inspection and troubleshooting.
* **Search and Filter**: Use metadata to efficiently search and filter through logged requests.

:::note


AI Gateway allows you to pass up to five custom metadata entries per request. If more than five entries are provided, only the first five will be saved; additional entries will be ignored. Ensure your custom metadata is limited to five entries to avoid unprocessed or lost data.

:::

## Supported Metadata Types

* String
* Number
* Boolean

:::note


Objects are not supported as metadata values.


:::

## Implementations

### Using cURL

To include custom metadata in your request using cURL:

```bash
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header 'Authorization: Bearer {api_token}' \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-metadata: {"team": "AI", "user": 12345, "test":true}' \
  --data '{"model": "gpt-4o", "messages": [{"role": "user", "content": "What should I eat for lunch?"}]}'
```

### Using SDK

To include custom metadata in your request using the OpenAI SDK:

```javascript
import OpenAI from "openai";

export default {
 async fetch(request, env, ctx) {
   const openai = new OpenAI({
     apiKey: env.OPENAI_API_KEY,
     baseURL: "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai",
   });

   try {
     const chatCompletion = await openai.chat.completions.create(
       {
         model: "gpt-4o",
         messages: [{ role: "user", content: "What should I eat for lunch?" }],
         max_tokens: 50,
       },
       {
         headers: {
           "cf-aig-metadata": JSON.stringify({
             user: "JaneDoe",
             team: 12345,
             test: true
           }),
         },
       }
     );

     const response = chatCompletion.choices[0].message;
     return new Response(JSON.stringify(response));
   } catch (e) {
     console.log(e);
     return new Response(e);
   }
 },
};
```

### Using Binding

To include custom metadata in your request using [Bindings](/workers/runtime-apis/bindings/):

```javascript
export default {
 async fetch(request, env, ctx) {
   const aiResp = await env.AI.run(
       '@cf/mistral/mistral-7b-instruct-v0.1',
       { prompt: 'What should I eat for lunch?' },
       { gateway: { id: 'gateway_id', metadata: { "team": "AI", "user": 12345, "test": true} } }
   );

   return new Response(aiResp);
 },
};
```

---

# Fallbacks

URL: https://developers.cloudflare.com/ai-gateway/configuration/fallbacks/

import { Render } from "~/components";

Specify model or provider fallbacks with your [Universal endpoint](/ai-gateway/universal/) to handle request failures and ensure reliability.

Cloudflare can trigger your fallback provider in response to [request errors](#request-failures) or [predetermined request timeouts](/ai-gateway/configuration/request-handling#request-timeouts). The [response header `cf-aig-step`](#response-headercf-aig-step) indicates which step successfully processed the request.

## Request failures

By default, Cloudflare triggers your fallback if a model request returns an error.

### Example

In the following example, a request first goes to the [Workers AI](/workers-ai/) Inference API. If the request fails, it falls back to OpenAI. The response header `cf-aig-step` indicates which provider successfully processed the request.

1. Sends a request to Workers AI Inference API.
2. If that request fails, proceeds to OpenAI.

```mermaid
graph TD
    A[AI Gateway] --> B[Request to Workers AI Inference API]
    B -->|Success| C[Return Response]
    B -->|Failure| D[Request to OpenAI API]
    D --> E[Return Response]
```

<br />

You can add as many fallbacks as you need, just by adding another object in the array.

<Render file="universal-gateway-example" />

## Response header(cf-aig-step)

When using the [Universal endpoint](/ai-gateway/universal/) with fallbacks, the response header `cf-aig-step` indicates which model successfully processed the request by returning the step number. This header provides visibility into whether a fallback was triggered and which model ultimately processed the response.

- `cf-aig-step:0` – The first (primary) model was used successfully.
- `cf-aig-step:1` – The request fell back to the second model.
- `cf-aig-step:2` – The request fell back to the third model.
- Subsequent steps – Each fallback increments the step number by 1.

---

# Configuration

URL: https://developers.cloudflare.com/ai-gateway/configuration/

import { DirectoryListing } from "~/components";

Configure your AI Gateway with multiple options and customizations.

<DirectoryListing />

---

# Rate limiting

URL: https://developers.cloudflare.com/ai-gateway/configuration/rate-limiting/

import { TabItem, Tabs } from "~/components";

Rate limiting controls the traffic that reaches your application, which prevents expensive bills and suspicious activity.

## Parameters

You can define rate limits as the number of requests that get sent in a specific time frame. For example, you can limit your application to 100 requests per 60 seconds.

You can also select if you would like a **fixed** or **sliding** rate limiting technique. With rate limiting, we allow a certain number of requests within a window of time. For example, if it is a fixed rate, the window is based on time, so there would be no more than `x` requests in a ten minute window. If it is a sliding rate, there would be no more than `x` requests in the last ten minutes.

To illustrate this, let us say you had a limit of ten requests per ten minutes, starting at 12:00. So the fixed window is 12:00-12:10, 12:10-12:20, and so on. If you sent ten requests at 12:09 and ten requests at 12:11, all 20 requests would be successful in a fixed window strategy. However, they would fail in a sliding window strategy since there were more than ten requests in the last ten minutes.

## Handling rate limits

When your requests exceed the allowed rate, you will encounter rate limiting. This means the server will respond with a `429 Too Many Requests` status code and your request will not be processed.

## Default configuration

<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">

To set the default rate limiting configuration in the dashboard:

1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Go to **AI** > **AI Gateway**.
3. Go to **Settings**.
4. Enable **Rate-limiting**.
5. Adjust the rate, time period, and rate limiting method as desired.

</TabItem> <TabItem label="API">

To set the default rate limiting configuration using the API:

1. [Create an API token](/fundamentals/api/get-started/create-token/) with the following permissions:

- `AI Gateway - Read`
- `AI Gateway - Edit`

2. Get your [Account ID](/fundamentals/account/find-account-and-zone-ids/).
3. Using that API token and Account ID, send a [`POST` request](/api/resources/ai_gateway/methods/create/) to create a new Gateway and include a value for the `rate_limiting_interval`, `rate_limiting_limit`, and `rate_limiting_technique`.

</TabItem> </Tabs>

This rate limiting behavior will be uniformly applied to all requests for that gateway.

---

# Request handling

URL: https://developers.cloudflare.com/ai-gateway/configuration/request-handling/

import { Render, Aside } from "~/components";

Your AI gateway supports different strategies for handling requests to providers, which allows you to manage AI interactions effectively and ensure your applications remain responsive and reliable.

## Request timeouts

A request timeout allows you to trigger fallbacks or a retry if a provider takes too long to respond.

These timeouts help:

- Improve user experience, by preventing users from waiting too long for a response
- Proactively handle errors, by detecting unresponsive providers and triggering a fallback option

Request timeouts can be set on a Universal Endpoint or directly on a request to any provider.

### Definitions

A timeout is set in milliseconds. Additionally, the timeout is based on when the first part of the response comes back. As long as the first part of the response returns within the specified timeframe - such as when streaming a response - your gateway will wait for the response.

### Configuration

#### Universal Endpoint

If set on a [Universal Endpoint](/ai-gateway/universal/), a request timeout specifies the timeout duration for requests and triggers a fallback.

For a Universal Endpoint, configure the timeout value by setting a `requestTimeout` property within the provider-specific `config` object. Each provider can have a different `requestTimeout` value for granular customization.

```bash title="Provider-level config" {11-13} collapse={15-48}
curl 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}' \
	--header 'Content-Type: application/json' \
	--data '[
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type": "application/json"
        },
        "config": {
            "requestTimeout": 1000
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        }
    },
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct-fast",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type": "application/json"
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        },
				"config": {
            "requestTimeout": 3000
        },
    }
]'
```

#### Direct provider

If set on a [provider](/ai-gateway/providers/) request, request timeout specifies the timeout duration for a request and - if exceeded - returns an error.

For a provider-specific endpoint, configure the timeout value by adding a `cf-aig-request-timeout` header.

```bash title="Provider-specific endpoint example" {4}
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/workers-ai/@cf/meta/llama-3.1-8b-instruct \
 --header 'Authorization: Bearer {cf_api_token}' \
 --header 'Content-Type: application/json' \
 --header 'cf-aig-request-timeout: 5000'
 --data '{"prompt": "What is Cloudflare?"}'
```

---

## Request retries

AI Gateway also supports automatic retries for failed requests, with a maximum of five retry attempts.

This feature improves your application's resiliency, ensuring you can recover from temporary issues without manual intervention.

Request timeouts can be set on a Universal Endpoint or directly on a request to any provider.

### Definitions

With request retries, you can adjust a combination of three properties:

- Number of attempts (maximum of 5 tries)
- How long before retrying (in milliseconds, maximum of 5 seconds)
- Backoff method (constant, linear, or exponential)

On the final retry attempt, your gateway will wait until the request completes, regardless of how long it takes.

### Configuration

#### Universal endpoint

If set on a [Universal Endpoint](/ai-gateway/universal/), a request retry will automatically retry failed requests up to five times before triggering any configured fallbacks.

For a Universal Endpoint, configure the retry settings with the following properties in the provider-specific `config`:

```json
config:{
	maxAttempts?: number;
	retryDelay?: number;
	backoff?: "constant" | "linear" | "exponential";
}
```

As with the [request timeout](/ai-gateway/configuration/request-handling/#universal-endpoint), each provider can have a different retry settings for granular customization.

```bash title="Provider-level config" {11-15} collapse={16-55}
curl 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}' \
	--header 'Content-Type: application/json' \
	--data '[
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type": "application/json"
        },
        "config": {
            "maxAttempts": 2,
						"retryDelay": 1000,
						"backoff": "constant"
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        }
    },
    {
        "provider": "workers-ai",
        "endpoint": "@cf/meta/llama-3.1-8b-instruct-fast",
        "headers": {
            "Authorization": "Bearer {cloudflare_token}",
            "Content-Type": "application/json"
        },
        "query": {
            "messages": [
                {
                    "role": "system",
                    "content": "You are a friendly assistant"
                },
                {
                    "role": "user",
                    "content": "What is Cloudflare?"
                }
            ]
        },
				"config": {
            "maxAttempts": 4,
						"retryDelay": 1000,
						"backoff": "exponential"
        },
    }
]'
```

#### Direct provider

If set on a [provider](/ai-gateway/universal/) request, a request retry will automatically retry failed requests up to five times. On the final retry attempt, your gateway will wait until the request completes, regardless of how long it takes.

For a provider-specific endpoint, configure the retry settings by adding different header values:

- `cf-aig-max-attempts` (number)
- `cf-aig-retry-delay` (number)
- `cf-aig-backoff` ("constant" | "linear" | "exponential)

---

# Manage gateways

URL: https://developers.cloudflare.com/ai-gateway/configuration/manage-gateway/

import { Render } from "~/components"

You have several different options for managing an AI Gateway.

## Create gateway

<Render file="create-gateway" />

## Edit gateway

<Render file="edit-gateway" />

:::note


For more details about what settings are available for editing, refer to [Configuration](/ai-gateway/configuration/).


:::

## Delete gateway

Deleting your gateway is permanent and can not be undone.

<Render file="delete-gateway" />

---

# Guardrails

URL: https://developers.cloudflare.com/ai-gateway/guardrails/

import { CardGrid, LinkTitleCard, YouTube } from "~/components";

Guardrails help you deploy AI applications safely by intercepting and evaluating both user prompts and model responses for harmful content. Acting as a proxy between your application and [model providers](/ai-gateway/providers/) (such as OpenAI, Anthropic, DeepSeek, and others), AI Gateway's Guardrails ensure a consistent and secure experience across your entire AI ecosystem.

Guardrails proactively monitor interactions between users and AI models, giving you:

- **Consistent moderation**: Uniform moderation layer that works across models and providers.
- **Enhanced safety and user trust**: Proactively protect users from harmful or inappropriate interactions.
- **Flexibility and control over allowed content**: Specify which categories to monitor and choose between flagging or outright blocking.
- **Auditing and compliance capabilities**: Receive updates on evolving regulatory requirements with logs of user prompts, model responses, and enforced guardrails.

## Video demo

<YouTube id="Its1H0jTxrQ" />

## How Guardrails work

AI Gateway inspects all interactions in real time by evaluating content against predefined safety parameters. Guardrails work by:

1. Intercepting interactions:
   AI Gateway proxies requests and responses, sitting between the user and the AI model.

2. Inspecting content:

   - User prompts: AI Gateway checks prompts against safety parameters (for example, violence, hate, or sexual content). Based on your settings, prompts can be flagged or blocked before reaching the model.
   - Model responses: Once processed, the AI model response is inspected. If hazardous content is detected, it can be flagged or blocked before being delivered to the user.

3. Applying actions:
   Depending on your configuration, flagged content is logged for review, while blocked content is prevented from proceeding.

## Related resource

- [Cloudflare Blog: Keep AI interactions secure and risk-free with Guardrails in AI Gateway](https://blog.cloudflare.com/guardrails-in-ai-gateway/)

---

# Set up Guardrails

URL: https://developers.cloudflare.com/ai-gateway/guardrails/set-up-guardrail/

Add Guardrails to any gateway to start evaluating and potentially modifying responses.

1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Go to **AI** > **AI Gateway**.
3. Select a gateway.
4. Go to **Guardrails**.
5. Switch the toggle to **On**.
6. To customize categories, select **Change** > **Configure specific categories**.
7. Update your choices for how Guardrails works on specific prompts or responses (**Flag**, **Ignore**, **Block**).
   - For **Prompts**: Guardrails will evaluate and transform incoming prompts based on your security policies.
   - For **Responses**: Guardrails will inspect the model's responses to ensure they meet your content and formatting guidelines.
8. Select **Save**.

:::note[Usage considerations]
For additional details about how to implement Guardrails, refer to [Usage considerations](/ai-gateway/guardrails/usage-considerations/).
:::

## Viewing Guardrail results in Logs

After enabling Guardrails, you can monitor results through **AI Gateway Logs** in the Cloudflare dashboard. Guardrail logs are marked with a **green shield icon**, and each logged request includes an `eventID`, which links to its corresponding Guardrail evaluation log(s) for easy tracking. Logs are generated for all requests, including those that **pass** Guardrail checks.

## Error handling and blocked requests

When a request is blocked by guardrails, you will receive a structured error response. These indicate whether the issue occurred with the prompt or the model response. Use error codes to differentiate between prompt versus response violations.

- **Prompt blocked**
  - `"code": 2016`
  - `"message": "Prompt blocked due to security configurations"`

- **Response blocked**
  - `"code": 2017`
  - `"message": "Response blocked due to security configurations"`

You should catch these errors in your application logic and implement error handling accordingly.

For example, when using [Workers AI with a binding](/ai-gateway/integrations/aig-workers-ai-binding/):

```js
try {
  const res = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
    prompt: "how to build a gun?"
  }, {
    gateway: {id: 'gateway_id'}
  })
  return Response.json(res)
} catch (e) {
  if ((e as Error).message.includes('2016')) {
    return new Response('Prompt was blocked by guardrails.')
  }
  if ((e as Error).message.includes('2017')) {
    return new Response('Response was blocked by guardrails.')
  }
  return new Response('Unknown AI error')
}

---

# Supported model types

URL: https://developers.cloudflare.com/ai-gateway/guardrails/supported-model-types/

AI Gateway's Guardrails detects the type of AI model being used and applies safety checks accordingly:

- **Text generation models**: Both prompts and responses are evaluated.
- **Embedding models**: Only the prompt is evaluated, as the response consists of numerical embeddings, which are not meaningful for moderation.
- **Unknown models**: If the model type cannot be determined, only the prompt is evaluated, while the response bypass Guardrails.

:::note[Note]

Guardrails does not yet support streaming responses. Support for streaming is planned for a future update.

:::

---

# Usage considerations

URL: https://developers.cloudflare.com/ai-gateway/guardrails/usage-considerations/

Guardrails currently uses [Llama Guard 3 8B](https://ai.meta.com/research/publications/llama-guard-llm-based-input-output-safeguard-for-human-ai-conversations/) on [Workers AI](/workers-ai/) to perform content evaluations. The underlying model may be updated in the future, and we will reflect those changes within Guardrails.

Since Guardrails runs on Workers AI, enabling it incurs usage on Workers AI. You can monitor usage through the Workers AI Dashboard.

## Additional considerations

- **Model availability**: If at least one hazard category is set to `block`, but AI Gateway is unable to receive a response from Workers AI, the request will be blocked. Conversely, if a hazard category is set to `flag` and AI Gateway cannot obtain a response from Workers AI, the request will proceed without evaluation. This approach prioritizes availability, allowing requests to continue even when content evaluation is not possible.
- **Latency impact**: Enabling Guardrails adds some latency. Enabling Guardrails introduces additional latency to requests. Typically, evaluations using Llama Guard 3 8B on Workers AI add approximately 500 milliseconds per request. However, larger requests may experience increased latency, though this increase is not linear. Consider this when balancing safety and performance.
- **Handling long content**: When evaluating long prompts or responses, Guardrails automatically segments the content into smaller chunks, processing each through separate Guardrail requests. This approach ensures comprehensive moderation but may result in increased latency for longer inputs.
- **Supported languages**: Llama Guard 3.3 8B supports content safety classification in the following languages: English, French, German, Hindi, Italian, Portuguese, Spanish, and Thai.
- **Streaming support**: Streaming is not supported when using Guardrails.

:::note

Llama Guard is provided as-is without any representations, warranties, or guarantees. Any rules or examples contained in blogs, developer docs, or other reference materials are provided for informational purposes only. You acknowledge and understand that you are responsible for the results and outcomes of your use of AI Gateway.

:::

---

# Add Human Feedback using API

URL: https://developers.cloudflare.com/ai-gateway/evaluations/add-human-feedback-api/

This guide will walk you through the steps of adding human feedback to an AI Gateway request using the Cloudflare API. You will learn how to retrieve the relevant request logs, and submit feedback using the API.

If you prefer to add human feedback via the dashboard, refer to [Add Human Feedback](/ai-gateway/evaluations/add-human-feedback/).

## 1. Create an API Token

1. [Create an API token](/fundamentals/api/get-started/create-token/) with the following permissions:

- `AI Gateway - Read`
- `AI Gateway - Edit`

2. Get your [Account ID](/fundamentals/account/find-account-and-zone-ids/).
3. Using that API token and Account ID, send a [`POST` request](/api/resources/ai_gateway/methods/create/) to the Cloudflare API.

## 2. Using the API Token

Once you have the token, you can use it in API requests by adding it to the authorization header as a bearer token. Here is an example of how to use it in a request:

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/logs" \
--header "Authorization: Bearer {your_api_token}"
```

In the request above:

- Replace `{account_id}` and `{gateway_id}` with your specific Cloudflare account and gateway details.
- Replace `{your_api_token}` with the API token you just created.

## 3. Retrieve the `cf-aig-log-id`

The `cf-aig-log-id` is a unique identifier for the specific log entry to which you want to add feedback. Below are two methods to obtain this identifier.

### Method 1: Locate the `cf-aig-log-id` in the request response

This method allows you to directly find the `cf-aig-log-id` within the header of the response returned by the AI Gateway. This is the most straightforward approach if you have access to the original API response.

The steps below outline how to do this.

1. **Make a Request to the AI Gateway**: This could be a request your application sends to the AI Gateway. Once the request is made, the response will contain various pieces of metadata.
2. **Check the Response Headers**: The response will include a header named `cf-aig-log-id`. This is the identifier you will need to submit feedback.

In the example below, the `cf-aig-log-id` is `01JADMCQQQBWH3NXZ5GCRN98DP`.

```json
{
	"status": "success",
	"headers": {
		"cf-aig-log-id": "01JADMCQQQBWH3NXZ5GCRN98DP"
	},
	"data": {
		"response": "Sample response data"
	}
}
```

### Method 2: Retrieve the `cf-aig-log-id` via API (GET request)

If you do not have the `cf-aig-log-id` in the response body or you need to access it after the fact, you are able to retrieve it by querying the logs using the [Cloudflare API](/api/resources/ai_gateway/subresources/logs/methods/list/).

The steps below outline how to do this.

1. **Send a GET Request to Retrieve Logs**: You can query the AI Gateway logs for a specific time frame or for a specific request. The request will return a list of logs, each containing its own `id`.
   Here is an example request:

```bash
GET https://api.cloudflare.com/client/v4/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/logs
```

Replace `{account_id}` and `{gateway_id}` with your specific account and gateway details.

2. **Search for the Relevant Log**: In the response from the GET request, locate the specific log entry for which you would like to submit feedback. Each log entry will include the `id`.

In the example below, the `id` is `01JADMCQQQBWH3NXZ5GCRN98DP`.

```json
{
	"result": [
		{
			"id": "01JADMCQQQBWH3NXZ5GCRN98DP",
			"cached": true,
			"created_at": "2019-08-24T14:15:22Z",
			"custom_cost": true,
			"duration": 0,
			"id": "string",
			"metadata": "string",
			"model": "string",
			"model_type": "string",
			"path": "string",
			"provider": "string",
			"request_content_type": "string",
			"request_type": "string",
			"response_content_type": "string",
			"status_code": 0,
			"step": 0,
			"success": true,
			"tokens_in": 0,
			"tokens_out": 0
		}
	],
	"result_info": {
		"count": 0,
		"max_cost": 0,
		"max_duration": 0,
		"max_tokens_in": 0,
		"max_tokens_out": 0,
		"max_total_tokens": 0,
		"min_cost": 0,
		"min_duration": 0,
		"min_tokens_in": 0,
		"min_tokens_out": 0,
		"min_total_tokens": 0,
		"page": 0,
		"per_page": 0,
		"total_count": 0
	},
	"success": true
}
```

### Method 3: Retrieve the `cf-aig-log-id` via a binding

You can also retrieve the `cf-aig-log-id` using a binding, which streamlines the process. Here's how to retrieve the log ID directly:

```js
const resp = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
		prompt: 'tell me a joke'
}, {
		gateway: {
				id: 'my_gateway_id'
		}
})

const myLogId = env.AI.aiGatewayLogId
```

:::note[Note:]


The `aiGatewayLogId` property, will only hold the last inference call log id.


:::

## 4. Submit feedback via PATCH request

Once you have both the API token and the `cf-aig-log-id`, you can send a PATCH request to submit feedback. Use the following URL format, replacing the `{account_id}`, `{gateway_id}`, and `{log_id}` with your specific details:

```bash
PATCH https://api.cloudflare.com/client/v4/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/logs/{log_id}
```

Add the following in the request body to submit positive feedback:

```json
{
	"feedback": 1
}
```

Add the following in the request body to submit negative feedback:

```json
{
	"feedback": -1
}
```

## 5. Verify the feedback submission

You can verify the feedback submission in two ways:

- **Through the [Cloudflare dashboard ](https://dash.cloudflare.com)**: check the updated feedback on the AI Gateway interface.
- **Through the API**: Send another GET request to retrieve the updated log entry and confirm the feedback has been recorded.

---

# Add human feedback using Worker Bindings

URL: https://developers.cloudflare.com/ai-gateway/evaluations/add-human-feedback-bindings/

This guide explains how to provide human feedback for AI Gateway evaluations using Worker bindings.

## 1. Run an AI Evaluation

Start by sending a prompt to the AI model through your AI Gateway.

```javascript
const resp = await env.AI.run(
	"@cf/meta/llama-3.1-8b-instruct",
	{
		prompt: "tell me a joke",
	},
	{
		gateway: {
			id: "my-gateway",
		},
	},
);

const myLogId = env.AI.aiGatewayLogId;
```

Let the user interact with or evaluate the AI response. This interaction will inform the feedback you send back to the AI Gateway.

## 2. Send Human Feedback

Use the [`patchLog()`](/ai-gateway/integrations/worker-binding-methods/#31-patchlog-send-feedback) method to provide feedback for the AI evaluation.

```javascript
await env.AI.gateway("my-gateway").patchLog(myLogId, {
	feedback: 1, // all fields are optional; set values that fit your use case
	score: 100,
	metadata: {
		user: "123", // Optional metadata to provide additional context
	},
});
```

## Feedback parameters explanation

- `feedback`: is either `-1` for negative or `1` to positive, `0` is considered not evaluated.
- `score`: A number between 0 and 100.
- `metadata`: An object containing additional contextual information.

### patchLog: Send Feedback

The `patchLog` method allows you to send feedback, score, and metadata for a specific log ID. All object properties are optional, so you can include any combination of the parameters:

```javascript
gateway.patchLog("my-log-id", {
	feedback: 1,
	score: 100,
	metadata: {
		user: "123",
	},
});
```

Returns: `Promise<void>` (Make sure to `await` the request.)

---

# Add Human Feedback using Dashboard

URL: https://developers.cloudflare.com/ai-gateway/evaluations/add-human-feedback/

Human feedback is a valuable metric to assess the performance of your AI models. By incorporating human feedback, you can gain deeper insights into how the model's responses are perceived and how well it performs from a user-centric perspective. This feedback can then be used in evaluations to calculate performance metrics, driving optimization and ultimately enhancing the reliability, accuracy, and efficiency of your AI application.

Human feedback measures the performance of your dataset based on direct human input. The metric is calculated as the percentage of positive feedback (thumbs up) given on logs, which are annotated in the Logs tab of the Cloudflare dashboard. This feedback helps refine model performance by considering real-world evaluations of its output.

This tutorial will guide you through the process of adding human feedback to your evaluations in AI Gateway using the [Cloudflare dashboard](https://dash.cloudflare.com/).

On the next guide, you can [learn how to add human feedback via the API](/ai-gateway/evaluations/add-human-feedback-api/).

## 1. Log in to the dashboard

1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Go to **AI** > **AI Gateway**.

## 2. Access the Logs tab

1. Go to **Logs**.
2. The Logs tab displays all logs associated with your datasets. These logs show key information, including:
   - Timestamp: When the interaction occurred.
   - Status: Whether the request was successful, cached, or failed.
   - Model: The model used in the request.
   - Tokens: The number of tokens consumed by the response.
   - Cost: The cost based on token usage.
   - Duration: The time taken to complete the response.
   - Feedback: Where you can provide human feedback on each log.

## 3. Provide human feedback

1. Click on the log entry you want to review. This expands the log, allowing you to see more detailed information.
2. In the expanded log, you can view additional details such as:
   - The user prompt.
   - The model response.
   - HTTP response details.
   - Endpoint information.
3. You will see two icons:
   - Thumbs up: Indicates positive feedback.
   - Thumbs down: Indicates negative feedback.
4. Click either the thumbs up or thumbs down icon based on how you rate the model response for that particular log entry.

## 4. Evaluate human feedback

After providing feedback on your logs, it becomes a part of the evaluation process.

When you run an evaluation (as outlined in the [Set Up Evaluations](/ai-gateway/evaluations/set-up-evaluations/) guide), the human feedback metric will be calculated based on the percentage of logs that received thumbs-up feedback.

:::note[Note]

You need to select human feedback as an evaluator to receive its metrics.

:::

## 5. Review results

After running the evaluation, review the results on the Evaluations tab.
You will be able to see the performance of the model based on cost, speed, and now human feedback, represented as the percentage of positive feedback (thumbs up).

The human feedback score is displayed as a percentage, showing the distribution of positively rated responses from the database.

For more information on running evaluations, refer to the documentation [Set Up Evaluations](/ai-gateway/evaluations/set-up-evaluations/).

---

# Evaluations

URL: https://developers.cloudflare.com/ai-gateway/evaluations/

Understanding your application's performance is essential for optimization. Developers often have different priorities, and finding the optimal solution involves balancing key factors such as cost, latency, and accuracy. Some prioritize low-latency responses, while others focus on accuracy or cost-efficiency.

AI Gateway's Evaluations provide the data needed to make informed decisions on how to optimize your AI application. Whether it is adjusting the model, provider, or prompt, this feature delivers insights into key metrics around performance, speed, and cost. It empowers developers to better understand their application's behavior, ensuring improved accuracy, reliability, and customer satisfaction.

Evaluations use datasets which are collections of logs stored for analysis. You can create datasets by applying filters in the Logs tab, which help narrow down specific logs for evaluation.

Our first step toward comprehensive AI evaluations starts with human feedback (currently in open beta). We will continue to build and expand AI Gateway with additional evaluators.

[Learn how to set up an evaluation](/ai-gateway/evaluations/set-up-evaluations/) including creating datasets, selecting evaluators, and running the evaluation process.

---

# Set up Evaluations

URL: https://developers.cloudflare.com/ai-gateway/evaluations/set-up-evaluations/

This guide walks you through the process of setting up an evaluation in AI Gateway. These steps are done in the [Cloudflare dashboard](https://dash.cloudflare.com/).

## 1. Select or create a dataset

Datasets are collections of logs stored for analysis that can be used in an evaluation. You can create datasets by applying filters in the Logs tab. Datasets will update automatically based on the set filters.

### Set up a dataset from the Logs tab

1. Apply filters to narrow down your logs. Filter options include provider, number of tokens, request status, and more.
2. Select **Create Dataset** to store the filtered logs for future analysis.

You can manage datasets by selecting **Manage datasets** from the Logs tab.

:::note[Note]

Please keep in mind that datasets currently use `AND` joins, so there can only be one item per filter (for example, one model or one provider). Future updates will allow more flexibility in dataset creation.

:::

### List of available filters

| Filter category | Filter options                                               | Filter by description                     |
| --------------- | ------------------------------------------------------------ | ----------------------------------------- |
| Status          | error, status                                                | error type or status.                     |
| Cache           | cached, not cached                                           | based on whether they were cached or not. |
| Provider        | specific providers                                           | the selected AI provider.                 |
| AI Models       | specific models                                              | the selected AI model.                    |
| Cost            | less than, greater than                                      | cost, specifying a threshold.             |
| Request type    | Universal, Workers AI Binding, WebSockets                    | the type of request.                      |
| Tokens          | Total tokens, Tokens In, Tokens Out                          | token count (less than or greater than).  |
| Duration        | less than, greater than                                      | request duration.                         |
| Feedback        | equals, does not equal (thumbs up, thumbs down, no feedback) | feedback type.                            |
| Metadata Key    | equals, does not equal                                       | specific metadata keys.                   |
| Metadata Value  | equals, does not equal                                       | specific metadata values.                 |
| Log ID          | equals, does not equal                                       | a specific Log ID.                        |
| Event ID        | equals, does not equal                                       | a specific Event ID.                      |

## 2. Select evaluators

After creating a dataset, choose the evaluation parameters:

- Cost: Calculates the average cost of inference requests within the dataset (only for requests with [cost data](/ai-gateway/observability/costs/)).
- Speed: Calculates the average duration of inference requests within the dataset.
- Performance:
  - Human feedback: measures performance based on human feedback, calculated by the % of thumbs up on the logs, annotated from the Logs tab.

:::note[Note]

Additional evaluators will be introduced in future updates to expand performance analysis capabilities.

:::

## 3. Name, review, and run the evaluation

1. Create a unique name for your evaluation to reference it in the dashboard.
2. Review the selected dataset and evaluators.
3. Select **Run** to start the process.

## 4. Review and analyze results

Evaluation results will appear in the Evaluations tab. The results show the status of the evaluation (for example, in progress, completed, or error). Metrics for the selected evaluators will be displayed, excluding any logs with missing fields. You will also see the number of logs used to calculate each metric.

While datasets automatically update based on filters, evaluations do not. You will have to create a new evaluation if you want to evaluate new logs.

Use these insights to optimize based on your application's priorities. Based on the results, you may choose to:

- Change the model or [provider](/ai-gateway/providers/)
- Adjust your prompts
- Explore further optimizations, such as setting up [Retrieval Augmented Generation (RAG)](/reference-architecture/diagrams/ai/ai-rag/)

---

# Workers AI

URL: https://developers.cloudflare.com/ai-gateway/integrations/aig-workers-ai-binding/

import { Render, PackageManagers, WranglerConfig } from "~/components";

This guide will walk you through setting up and deploying a Workers AI project. You will use [Workers](/workers/), an AI Gateway binding, and a large language model (LLM), to deploy your first AI-powered application on the Cloudflare global network.

## Prerequisites

<Render file="prereqs" product="workers" />

## 1. Create a Worker Project

You will create a new Worker project using the create-Cloudflare CLI (C3). C3 is a command-line tool designed to help you set up and deploy new applications to Cloudflare.

Create a new project named `hello-ai` by running:

<PackageManagers type="create" pkg="cloudflare@latest" args={"hello-ai"} />

Running `npm create cloudflare@latest` will prompt you to install the create-cloudflare package and lead you through setup. C3 will also install [Wrangler](/workers/wrangler/), the Cloudflare Developer Platform CLI.

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

This will create a new `hello-ai` directory. Your new `hello-ai` directory will include:

- A "Hello World" Worker at `src/index.ts`.
- A [Wrangler configuration file](/workers/wrangler/configuration/)

Go to your application directory:

```bash
cd hello-ai
```

## 2. Connect your Worker to Workers AI

You must create an AI binding for your Worker to connect to Workers AI. Bindings allow your Workers to interact with resources, like Workers AI, on the Cloudflare Developer Platform.

To bind Workers AI to your Worker, add the following to the end of your [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml title="wrangler.toml"
[ai]
binding = "AI"
```

</WranglerConfig>

Your binding is [available in your Worker code](/workers/reference/migrate-to-module-workers/#bindings-in-es-modules-format) on [`env.AI`](/workers/runtime-apis/handlers/fetch/).

You will need to have your `gateway id` for the next step. You can learn [how to create an AI Gateway in this tutorial](/ai-gateway/get-started/).

## 3. Run an inference task containing AI Gateway in your Worker

You are now ready to run an inference task in your Worker. In this case, you will use an LLM, [`llama-3.1-8b-instruct-fast`](/workers-ai/models/llama-3.1-8b-instruct-fast/), to answer a question. Your gateway ID is found on the dashboard.

Update the `index.ts` file in your `hello-ai` application directory with the following code:

```typescript title="src/index.ts" {78-81}
export interface Env {
	// If you set another name in the [Wrangler configuration file](/workers/wrangler/configuration/) as the value for 'binding',
	// replace "AI" with the variable name you defined.
	AI: Ai;
}

export default {
	async fetch(request, env): Promise<Response> {
		// Specify the gateway label and other options here
		const response = await env.AI.run(
			"@cf/meta/llama-3.1-8b-instruct-fast",
			{
				prompt: "What is the origin of the phrase Hello, World",
			},
			{
				gateway: {
					id: "GATEWAYID", // Use your gateway label here
					skipCache: true, // Optional: Skip cache if needed
				},
			},
		);

		// Return the AI response as a JSON object
		return new Response(JSON.stringify(response), {
			headers: { "Content-Type": "application/json" },
		});
	},
} satisfies ExportedHandler<Env>;
```

Up to this point, you have created an AI binding for your Worker and configured your Worker to be able to execute the Llama 3.1 model. You can now test your project locally before you deploy globally.

## 4. Develop locally with Wrangler

While in your project directory, test Workers AI locally by running [`wrangler dev`](/workers/wrangler/commands/#dev):

```bash
npx wrangler dev
```

<Render file="ai-local-usage-charges" product="workers" />

You will be prompted to log in after you run `wrangler dev`. When you run `npx wrangler dev`, Wrangler will give you a URL (most likely `localhost:8787`) to review your Worker. After you go to the URL Wrangler provides, you will see a message that resembles the following example:

````json
{
  "response": "A fascinating question!\n\nThe phrase \"Hello, World!\" originates from a simple computer program written in the early days of programming. It is often attributed to Brian Kernighan, a Canadian computer scientist and a pioneer in the field of computer programming.\n\nIn the early 1970s, Kernighan, along with his colleague Dennis Ritchie, were working on the C programming language. They wanted to create a simple program that would output a message to the screen to demonstrate the basic structure of a program. They chose the phrase \"Hello, World!\" because it was a simple and recognizable message that would illustrate how a program could print text to the screen.\n\nThe exact code was written in the 5th edition of Kernighan and Ritchie's book \"The C Programming Language,\" published in 1988. The code, literally known as \"Hello, World!\" is as follows:\n\n```
main()
{
  printf(\"Hello, World!\");
}
```\n\nThis code is still often used as a starting point for learning programming languages, as it demonstrates how to output a simple message to the console.\n\nThe phrase \"Hello, World!\" has since become a catch-all phrase to indicate the start of a new program or a small test program, and is widely used in computer science and programming education.\n\nSincerely, I'm glad I could help clarify the origin of this iconic phrase for you!"
}
````

## 5. Deploy your AI Worker

Before deploying your AI Worker globally, log in with your Cloudflare account by running:

```bash
npx wrangler login
```

You will be directed to a web page asking you to log in to the Cloudflare dashboard. After you have logged in, you will be asked if Wrangler can make changes to your Cloudflare account. Scroll down and select **Allow** to continue.

Finally, deploy your Worker to make your project accessible on the Internet. To deploy your Worker, run:

```bash
npx wrangler deploy
```

Once deployed, your Worker will be available at a URL like:

```bash
https://hello-ai.<YOUR_SUBDOMAIN>.workers.dev
```

Your Worker will be deployed to your custom [`workers.dev`](/workers/configuration/routing/workers-dev/) subdomain. You can now visit the URL to run your AI Worker.

By completing this tutorial, you have created a Worker, connected it to Workers AI through an AI Gateway binding, and successfully ran an inference task using the Llama 3.1 model.

---

# Vercel AI SDK

URL: https://developers.cloudflare.com/ai-gateway/integrations/vercel-ai-sdk/

The [Vercel AI SDK](https://sdk.vercel.ai/) is a TypeScript library for building AI applications. The SDK supports many different AI providers, tools for streaming completions, and more.

To use Cloudflare AI Gateway inside of the AI SDK, you can configure a custom "Gateway URL" for most supported providers. Below are a few examples of how it works.

## Examples

### OpenAI

If you're using the `openai` provider in AI SDK, you can create a customized setup with `createOpenAI`, passing your OpenAI-compatible AI Gateway URL:

```typescript
import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
	baseURL: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai`,
});
```

### Anthropic

If you're using the `anthropic` provider in AI SDK, you can create a customized setup with `createAnthropic`, passing your Anthropic-compatible AI Gateway URL:

```typescript
import { createAnthropic } from "@ai-sdk/anthropic";

const anthropic = createAnthropic({
	baseURL: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/anthropic`,
});
```

### Google AI Studio

If you're using the Google AI Studio provider in AI SDK, you need to append `/v1beta` to your Google AI Studio-compatible AI Gateway URL to avoid errors. The `/v1beta` path is required because Google AI Studio's API includes this in its endpoint structure, and the AI SDK sets the model name separately. This ensures compatibility with Google's API versioning.

```typescript
import { createGoogleGenerativeAI } from "@ai-sdk/google";

const google = createGoogleGenerativeAI({
	baseURL: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-ai-studio/v1beta`,
});
```

### Retrieve `log id` from AI SDK

You can access the AI Gateway `log id` from the response headers when invoking the SDK.

```typescript
const result = await generateText({
	model: anthropic("claude-3-sonnet-20240229"),
	messages: [],
});
console.log(result.response.headers["cf-aig-log-id"]);
```

### Other providers

For other providers that are not listed above, you can follow a similar pattern by creating a custom instance for any AI provider, and passing your AI Gateway URL. For help finding your provider-specific AI Gateway URL, refer to the [Supported providers page](/ai-gateway/providers).

---

# AI Gateway Binding Methods

URL: https://developers.cloudflare.com/ai-gateway/integrations/worker-binding-methods/

import { Render, PackageManagers } from "~/components";

This guide provides an overview of how to use the latest Cloudflare Workers AI Gateway binding methods. You will learn how to set up an AI Gateway binding, access new methods, and integrate them into your Workers.

## 1. Add an AI Binding to your Worker

To connect your Worker to Workers AI, add the following to your [Wrangler configuration file](/workers/wrangler/configuration/):

import { WranglerConfig } from "~/components";

<WranglerConfig>

```toml title="wrangler.toml"
[ai]
binding = "AI"
```

</WranglerConfig>

This configuration sets up the AI binding accessible in your Worker code as `env.AI`.

<Render file="wrangler-typegen" product="workers" />

## 2. Basic Usage with Workers AI + Gateway

To perform an inference task using Workers AI and an AI Gateway, you can use the following code:

```typescript title="src/index.ts"
const resp = await env.AI.run(
	"@cf/meta/llama-3.1-8b-instruct",
	{
		prompt: "tell me a joke",
	},
	{
		gateway: {
			id: "my-gateway",
		},
	},
);
```

Additionally, you can access the latest request log ID with:

```typescript
const myLogId = env.AI.aiGatewayLogId;
```

## 3. Access the Gateway Binding

You can access your AI Gateway binding using the following code:

```typescript
const gateway = env.AI.gateway("my-gateway");
```

Once you have the gateway instance, you can use the following methods:

### 3.1. `patchLog`: Send Feedback

The `patchLog` method allows you to send feedback, score, and metadata for a specific log ID. All object properties are optional, so you can include any combination of the parameters:

```typescript
gateway.patchLog("my-log-id", {
	feedback: 1,
	score: 100,
	metadata: {
		user: "123",
	},
});
```

- **Returns**: `Promise<void>` (Make sure to `await` the request.)
- **Example Use Case**: Update a log entry with user feedback or additional metadata.

### 3.2. `getLog`: Read Log Details

The `getLog` method retrieves details of a specific log ID. It returns an object of type `Promise<AiGatewayLog>`. If this type is missing, ensure you have run [`wrangler types`](/workers/languages/typescript/#generate-types).

```typescript
const log = await gateway.getLog("my-log-id");
```

- **Returns**: `Promise<AiGatewayLog>`
- **Example Use Case**: Retrieve log information for debugging or analytics.

### 3.3. `getUrl`: Get Gateway URLs

The `getUrl` method allows you to retrieve the base URL for your AI Gateway, optionally specifying a provider to get the provider-specific endpoint.

```typescript
// Get the base gateway URL
const baseUrl = await gateway.getUrl();
// Output: https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/

// Get a provider-specific URL
const openaiUrl = await gateway.getUrl("openai");
// Output: https://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/openai
```

- **Parameters**: Optional `provider` (string or `AIGatewayProviders` enum)
- **Returns**: `Promise<string>`
- **Example Use Case**: Dynamically construct URLs for direct API calls or debugging configurations.

#### SDK Integration Examples

The `getUrl` method is particularly useful for integrating with popular AI SDKs:

**OpenAI SDK:**

```typescript
import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: "my api key", // defaults to process.env["OPENAI_API_KEY"]
	baseURL: await env.AI.gateway("my-gateway").getUrl("openai"),
});
```

**Vercel AI SDK with OpenAI:**

```typescript
import { createOpenAI } from "@ai-sdk/openai";

const openai = createOpenAI({
	baseURL: await env.AI.gateway("my-gateway").getUrl("openai"),
});
```

**Vercel AI SDK with Anthropic:**

```typescript
import { createAnthropic } from "@ai-sdk/anthropic";

const anthropic = createAnthropic({
	baseURL: await env.AI.gateway("my-gateway").getUrl("anthropic"),
});
```

### 3.4. `run`: Universal Requests

The `run` method allows you to execute universal requests. Users can pass either a single universal request object or an array of them. This method supports all AI Gateway providers.

Refer to the [Universal endpoint documentation](/ai-gateway/universal/) for details about the available inputs.

```typescript
const resp = await gateway.run({
	provider: "workers-ai",
	endpoint: "@cf/meta/llama-3.1-8b-instruct",
	headers: {
		authorization: "Bearer my-api-token",
	},
	query: {
		prompt: "tell me a joke",
	},
});
```

- **Returns**: `Promise<Response>`
- **Example Use Case**: Perform a [universal request](/ai-gateway/universal/) to any supported provider.

## Conclusion

With these AI Gateway binding methods, you can now:

- Send feedback and update metadata with `patchLog`.
- Retrieve detailed log information using `getLog`.
- Get gateway URLs for direct API access with `getUrl`, making it easy to integrate with popular AI SDKs.
- Execute universal requests to any AI Gateway provider with `run`.

These methods offer greater flexibility and control over your AI integrations, empowering you to build more sophisticated applications on the Cloudflare Workers platform.

---

# Analytics

URL: https://developers.cloudflare.com/ai-gateway/observability/analytics/

import { Render, TabItem, Tabs } from "~/components";

Your AI Gateway dashboard shows metrics on requests, tokens, caching, errors, and cost. You can filter these metrics by time.
These analytics help you understand traffic patterns, token consumption, and
potential issues across AI providers. You can
view the following analytics:

- **Requests**: Track the total number of requests processed by AI Gateway.
- **Token Usage**: Analyze token consumption across requests, giving insight into usage patterns.
- **Costs**: Gain visibility into the costs associated with using different AI providers, allowing you to track spending, manage budgets, and optimize resources.
- **Errors**: Monitor the number of errors across the gateway, helping to identify and troubleshoot issues.
- **Cached Responses**: View the percentage of responses served from cache, which can help reduce costs and improve speed.

## View analytics

<Tabs> <TabItem label="Dashboard">

<Render file="analytics-dashboard" />

</TabItem> <TabItem label="graphql">

You can use GraphQL to query your usage data outside of the AI Gateway dashboard. See the example query below. You will need to use your Cloudflare token when making the request, and change `{account_id}` to match your account tag.

```bash title="Request"
curl https://api.cloudflare.com/client/v4/graphql \
  --header 'Authorization: Bearer TOKEN \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "query{\n  viewer {\n	accounts(filter: { accountTag: \"{account_id}\" }) {\n	requests: aiGatewayRequestsAdaptiveGroups(\n    	limit: $limit\n    	filter: { datetimeHour_geq: $start, datetimeHour_leq: $end }\n    	orderBy: [datetimeMinute_ASC]\n  	) {\n    	count,\n    	dimensions {\n        	model,\n        	provider,\n        	gateway,\n        	ts: datetimeMinute\n    	}\n    	\n  	}\n    	\n	}\n  }\n}",
    "variables": {
   	 "limit": 1000,
   	 "start": "2023-09-01T10:00:00.000Z",
   	 "end": "2023-09-30T10:00:00.000Z",
   	 "orderBy": "date_ASC"
    }
}'
```

</TabItem> </Tabs>

---

# Costs

URL: https://developers.cloudflare.com/ai-gateway/observability/costs/

Cost metrics are only available for endpoints where the models return token data and the model name in their responses.

## Track costs across AI providers

AI Gateway makes it easier to monitor and estimate token based costs across all your AI providers. This can help you:

- Understand and compare usage costs between providers.
- Monitor trends and estimate spend using consistent metrics.
- Apply custom pricing logic to match negotiated rates.

:::note[Note]

The cost metric is an **estimation** based on the number of tokens sent and received in requests. While this metric can help you monitor and predict cost trends, refer to your provider's dashboard for the most **accurate** cost details.

:::

:::caution[Caution]

Providers may introduce new models or change their pricing. If you notice outdated cost data or are using a model not yet supported by our cost tracking, please [submit a request](https://forms.gle/8kRa73wRnvq7bxL48)

:::

## Custom costs

AI Gateway allows users to set custom costs when operating under special pricing agreements or negotiated rates. Custom costs can be applied at the request level, and when applied, they will override the default or public model costs.
For more information on configuration of custom costs, please visit the [Custom Costs](/ai-gateway/configuration/custom-costs/) configuration page.

---

# Observability

URL: https://developers.cloudflare.com/ai-gateway/observability/

import { DirectoryListing } from "~/components";

Observability is the practice of instrumenting systems to collect metrics, and logs enabling better monitoring, troubleshooting, and optimization of applications.

<DirectoryListing />

---

# Anthropic

URL: https://developers.cloudflare.com/ai-gateway/providers/anthropic/

import { Render } from "~/components";

[Anthropic](https://www.anthropic.com/) helps build reliable, interpretable, and steerable AI systems.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/anthropic
```

## Prerequisites

When making requests to Anthropic, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active Anthropic API token.
- The name of the Anthropic model you want to use.

## Examples

### cURL

```bash title="Example fetch request"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/anthropic/v1/messages \
 --header 'x-api-key: {anthropic_api_key}' \
 --header 'anthropic-version: 2023-06-01' \
 --header 'Content-Type: application/json' \
 --data  '{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is Cloudflare?"}
    ]
  }'
```

### Use Anthropic SDK with JavaScript

If you are using the `@anthropic-ai/sdk`, you can set your endpoint like this:

```js title="JavaScript"
import Anthropic from "@anthropic-ai/sdk";

const apiKey = env.ANTHROPIC_API_KEY;
const accountId = "{account_id}";
const gatewayId = "{gateway_id}";
const baseURL = `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/anthropic`;

const anthropic = new Anthropic({
	apiKey,
	baseURL,
});

const model = "claude-3-opus-20240229";
const messages = [{ role: "user", content: "What is Cloudflare?" }];
const maxTokens = 1024;

const message = await anthropic.messages.create({
	model,
	messages,
	max_tokens: maxTokens,
});
```

<Render
	file="chat-completions-providers"
	product="ai-gateway"
	params={{
		name: "Anthropic",
		jsonexample: `
{
	"model": "anthropic/{model}"
}`

    }}

/>

---

# Azure OpenAI

URL: https://developers.cloudflare.com/ai-gateway/providers/azureopenai/

[Azure OpenAI](https://azure.microsoft.com/en-gb/products/ai-services/openai-service/) allows you apply natural language algorithms on your data.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/azure-openai/{resource_name}/{deployment_name}
```

## Prerequisites

When making requests to Azure OpenAI, you will need:

- AI Gateway account ID
- AI Gateway gateway name
- Azure OpenAI API key
- Azure OpenAI resource name
- Azure OpenAI deployment name (aka model name)

## URL structure

Your new base URL will use the data above in this structure: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/azure-openai/{resource_name}/{deployment_name}`. Then, you can append your endpoint and api-version at the end of the base URL, like `.../chat/completions?api-version=2023-05-15`.

## Examples

### cURL

```bash title="Example fetch request"
curl 'https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/azure-openai/{resource_name}/{deployment_name}/chat/completions?api-version=2023-05-15' \
  --header 'Content-Type: application/json' \
  --header 'api-key: {azure_api_key}' \
  --data '{
  "messages": [
    {
      "role": "user",
      "content": "What is Cloudflare?"
    }
  ]
}'
```

### Use `openai-node` with JavaScript

If you are using the `openai-node` library, you can set your endpoint like this:

```js title="JavaScript"
import OpenAI from "openai";

const resource = "xxx";
const model = "xxx";
const apiVersion = "xxx";
const apiKey = env.AZURE_OPENAI_API_KEY;
const accountId = "{account_id}";
const gatewayId = "{gateway_id}";
const baseURL = `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/azure-openai/${resource}/${model}`;

const azure_openai = new OpenAI({
	apiKey,
	baseURL,
	defaultQuery: { "api-version": apiVersion },
	defaultHeaders: { "api-key": apiKey },
});
```

---

# Amazon Bedrock

URL: https://developers.cloudflare.com/ai-gateway/providers/bedrock/

[Amazon Bedrock](https://aws.amazon.com/bedrock/) allows you to build and scale generative AI applications with foundation models.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/aws-bedrock`
```

## Prerequisites

When making requests to Amazon Bedrock, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active Amazon Bedrock API token.
- The name of the Amazon Bedrock model you want to use.

## Make a request

When making requests to Amazon Bedrock, replace `https://bedrock-runtime.us-east-1.amazonaws.com/` in the URL you're currently using with `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/aws-bedrock/bedrock-runtime/us-east-1/`, then add the model you want to run at the end of the URL.

With Bedrock, you will need to sign the URL before you make requests to AI Gateway. You can try using the [`aws4fetch`](https://github.com/mhart/aws4fetch) SDK.

## Examples

### Use `aws4fetch` SDK with TypeScript

```typescript
import { AwsClient } from "aws4fetch";

interface Env {
	accessKey: string;
	secretAccessKey: string;
}

export default {
	async fetch(
		request: Request,
		env: Env,
		ctx: ExecutionContext,
	): Promise<Response> {
		// replace with your configuration
		const cfAccountId = "{account_id}";
		const gatewayName = "{gateway_id}";
		const region = "us-east-1";

		// added as secrets (https://developers.cloudflare.com/workers/configuration/secrets/)
		const accessKey = env.accessKey;
		const secretKey = env.secretAccessKey;

		const awsClient = new AwsClient({
			accessKeyId: accessKey,
			secretAccessKey: secretKey,
			region: region,
			service: "bedrock",
		});

		const requestBodyString = JSON.stringify({
			inputText: "What does ethereal mean?",
		});

		const stockUrl = new URL(
			`https://bedrock-runtime.${region}.amazonaws.com/model/amazon.titan-embed-text-v1/invoke`,
		);

		const headers = {
			"Content-Type": "application/json",
		};

		// sign the original request
		const presignedRequest = await awsClient.sign(stockUrl.toString(), {
			method: "POST",
			headers: headers,
			body: requestBodyString,
		});

		// Gateway Url
		const gatewayUrl = new URL(
			`https://gateway.ai.cloudflare.com/v1/${cfAccountId}/${gatewayName}/aws-bedrock/bedrock-runtime/${region}/model/amazon.titan-embed-text-v1/invoke`,
		);

		// make the request through the gateway url
		const response = await fetch(gatewayUrl, {
			method: "POST",
			headers: presignedRequest.headers,
			body: requestBodyString,
		});

		if (
			response.ok &&
			response.headers.get("content-type")?.includes("application/json")
		) {
			const data = await response.json();
			return new Response(JSON.stringify(data));
		}

		return new Response("Invalid response", { status: 500 });
	},
};
```

---

# Cartesia

URL: https://developers.cloudflare.com/ai-gateway/providers/cartesia/

[Cartesia](https://docs.cartesia.ai/) provides advanced text-to-speech services with customizable voice models.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/cartesia
```

## URL Structure

When making requests to Cartesia, replace `https://api.cartesia.ai/v1` in the URL you are currently using with `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/cartesia`.

## Prerequisites

When making requests to Cartesia, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active Cartesia API token.
- The model ID and voice ID for the Cartesia voice model you want to use.

## Example

### cURL

```bash title="Request"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/cartesia/tts/bytes \
  --header 'Content-Type: application/json' \
  --header 'Cartesia-Version: 2024-06-10' \
  --header 'X-API-Key: {cartesia_api_token}' \
  --data '{
    "transcript": "Welcome to Cloudflare - AI Gateway!",
    "model_id": "sonic-english",
    "voice": {
        "mode": "id",
        "id": "694f9389-aac1-45b6-b726-9d9369183238"
    },
    "output_format": {
        "container": "wav",
        "encoding": "pcm_f32le",
        "sample_rate": 44100
    }
}
```

---

# Cerebras

URL: https://developers.cloudflare.com/ai-gateway/providers/cerebras/

import { Render } from "~/components";

[Cerebras](https://inference-docs.cerebras.ai/) offers developers a low-latency solution for AI model inference.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/cerebras-ai
```

## Prerequisites

When making requests to Cerebras, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active Cerebras API token.
- The name of the Cerebras model you want to use.

## Examples

### cURL

```bash title="Example fetch request"
curl https://gateway.ai.cloudflare.com/v1/ACCOUNT_TAG/GATEWAY/cerebras/chat/completions \
 --header 'content-type: application/json' \
 --header 'Authorization: Bearer CEREBRAS_TOKEN' \
 --data '{
    "model": "llama3.1-8b",
    "messages": [
        {
            "role": "user",
            "content": "What is Cloudflare?"
        }
    ]
}'
```

<Render
	file="chat-completions-providers"
	product="ai-gateway"
	params={{
		name: "Cerebras",
		jsonexample: `
{
	"model": "cerebras/{model}"
}`

    }}

/>

---

# Cohere

URL: https://developers.cloudflare.com/ai-gateway/providers/cohere/

import { Render } from "~/components";

[Cohere](https://cohere.com/) build AI models designed to solve real-world business challenges.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/cohere
```

## URL structure

When making requests to [Cohere](https://cohere.com/), replace `https://api.cohere.ai/v1` in the URL you're currently using with `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/cohere`.

## Prerequisites

When making requests to Cohere, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active Cohere API token.
- The name of the Cohere model you want to use.

## Examples

### cURL

```bash title="Request"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/cohere/v1/chat \
  --header 'Authorization: Token {cohere_api_token}' \
  --header 'Content-Type: application/json' \
  --data '{
  "chat_history": [
    {"role": "USER", "message": "Who discovered gravity?"},
    {"role": "CHATBOT", "message": "The man who is widely credited with discovering gravity is Sir Isaac Newton"}
  ],
  "message": "What year was he born?",
  "connectors": [{"id": "web-search"}]
}'
```

### Use Cohere SDK with Python

If using the [`cohere-python-sdk`](https://github.com/cohere-ai/cohere-python), set your endpoint like this:

```js title="Python"

import cohere
import os

api_key = os.getenv('API_KEY')
account_id = '{account_id}'
gateway_id = '{gateway_id}'
base_url = f"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/cohere/v1"

co = cohere.Client(
  api_key=api_key,
  base_url=base_url,
)

message = "hello world!"
model = "command-r-plus"

chat = co.chat(
  message=message,
  model=model
)

print(chat)

```

<Render
	file="chat-completions-providers"
	product="ai-gateway"
	params={{
		name: "Cohere",
		jsonexample: `
{
	"model": "cohere/{model}"
}`

    }}

/>

---

# DeepSeek

URL: https://developers.cloudflare.com/ai-gateway/providers/deepseek/

import { Render } from "~/components";

[DeepSeek](https://www.deepseek.com/) helps you build quickly with DeepSeek's advanced AI models.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/deepseek
```

## Prerequisites

When making requests to DeepSeek, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active DeepSeek AI API token.
- The name of the DeepSeek AI model you want to use.

## URL structure

Your new base URL will use the data above in this structure:

`https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/deepseek/`.

You can then append the endpoint you want to hit, for example: `chat/completions`.

So your final URL will come together as:

`https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/deepseek/chat/completions`.

## Examples

### cURL

```bash title="Example fetch request"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/deepseek/chat/completions \
 --header 'content-type: application/json' \
 --header 'Authorization: Bearer DEEPSEEK_TOKEN' \
 --data '{
    "model": "deepseek-chat",
    "messages": [
        {
            "role": "user",
            "content": "What is Cloudflare?"
        }
    ]
}'
```

### Use DeepSeek with JavaScript

If you are using the OpenAI SDK, you can set your endpoint like this:

```js title="JavaScript"
import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: env.DEEPSEEK_TOKEN,
	baseURL:
		"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/deepseek",
});

try {
	const chatCompletion = await openai.chat.completions.create({
		model: "deepseek-chat",
		messages: [{ role: "user", content: "What is Cloudflare?" }],
	});

	const response = chatCompletion.choices[0].message;

	return new Response(JSON.stringify(response));
} catch (e) {
	return new Response(e);
}
```

<Render
	file="chat-completions-providers"
	product="ai-gateway"
	params={{
		name: "DeepSeek",
		jsonexample: `
{
	"model": "deepseek/{model}"
}`

    }}

/>

---

# ElevenLabs

URL: https://developers.cloudflare.com/ai-gateway/providers/elevenlabs/

[ElevenLabs](https://elevenlabs.io/) offers advanced text-to-speech services, enabling high-quality voice synthesis in multiple languages.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/elevenlabs
```

## Prerequisites

When making requests to ElevenLabs, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active ElevenLabs API token.
- The model ID of the ElevenLabs voice model you want to use.

## Example

### cURL

```bash title="Request"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/elevenlabs/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb?output_format=mp3_44100_128 \
  --header 'Content-Type: application/json' \
  --header 'xi-api-key: {elevenlabs_api_token}' \
  --data '{
    "text": "Welcome to Cloudflare - AI Gateway!",
    "model_id": "eleven_multilingual_v2"
}'
```

---

# Google AI Studio

URL: https://developers.cloudflare.com/ai-gateway/providers/google-ai-studio/

import { Render } from "~/components";

[Google AI Studio](https://ai.google.dev/aistudio) helps you build quickly with Google Gemini models.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-ai-studio
```

## Prerequisites

When making requests to Google AI Studio, you will need:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active Google AI Studio API token.
- The name of the Google AI Studio model you want to use.

## URL structure

Your new base URL will use the data above in this structure: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-ai-studio/`.

Then you can append the endpoint you want to hit, for example: `v1/models/{model}:{generative_ai_rest_resource}`

So your final URL will come together as: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-ai-studio/v1/models/{model}:{generative_ai_rest_resource}`.

## Examples

### cURL

```bash title="Example fetch request"
curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_name}/google-ai-studio/v1/models/gemini-1.0-pro:generateContent" \
 --header 'content-type: application/json' \
 --header 'x-goog-api-key: {google_studio_api_key}' \
 --data '{
      "contents": [
          {
            "role":"user",
            "parts": [
              {"text":"What is Cloudflare?"}
            ]
          }
        ]
      }'
```

### Use `@google/generative-ai` with JavaScript

If you are using the `@google/generative-ai` package, you can set your endpoint like this:

```js title="JavaScript example"
import { GoogleGenerativeAI } from "@google/generative-ai";

const api_token = env.GOOGLE_AI_STUDIO_TOKEN;
const account_id = "";
const gateway_name = "";

const genAI = new GoogleGenerativeAI(api_token);
const model = genAI.getGenerativeModel(
	{ model: "gemini-1.5-flash" },
	{
		baseUrl: `https://gateway.ai.cloudflare.com/v1/${account_id}/${gateway_name}/google-ai-studio`,
	},
);

await model.generateContent(["What is Cloudflare?"]);
```

<Render
	file="chat-completions-providers"
	product="ai-gateway"
	params={{
		name: "Google AI Studio",
		jsonexample: `
{
	"model": "google-ai-studio/{model}"
}`

    }}

/>

---

# Grok

URL: https://developers.cloudflare.com/ai-gateway/providers/grok/

import { Render } from "~/components";

[Grok](https://docs.x.ai/docs#getting-started) is a general purpose model that can be used for a variety of tasks, including generating and understanding text, code, and function calling.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/grok
```

## URL structure

When making requests to [Grok](https://docs.x.ai/docs#getting-started), replace `https://api.x.ai/v1` in the URL you are currently using with `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/grok`.

## Prerequisites

When making requests to Grok, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active Grok API token.
- The name of the Grok model you want to use.

## Examples

### cURL

```bash title="Request"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/grok/v1/chat/completions \
  --header 'content-type: application/json' \
  --header 'Authorization: Bearer {grok_api_token}' \
  --data '{
    "model": "grok-beta",
    "messages": [
        {
            "role": "user",
            "content": "What is Cloudflare?"
        }
    ]
}'
```

### Use OpenAI SDK with JavaScript

If you are using the OpenAI SDK with JavaScript, you can set your endpoint like this:

```js title="JavaScript"
import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: "<api key>",
	baseURL:
		"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/grok",
});

const completion = await openai.chat.completions.create({
	model: "grok-beta",
	messages: [
		{
			role: "system",
			content:
				"You are Grok, a chatbot inspired by the Hitchhiker's Guide to the Galaxy.",
		},
		{
			role: "user",
			content: "What is the meaning of life, the universe, and everything?",
		},
	],
});

console.log(completion.choices[0].message);
```

### Use OpenAI SDK with Python

If you are using the OpenAI SDK with Python, you can set your endpoint like this:

```python title="Python"
import os
from openai import OpenAI

XAI_API_KEY = os.getenv("XAI_API_KEY")
client = OpenAI(
    api_key=XAI_API_KEY,
    base_url="https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/grok",
)

completion = client.chat.completions.create(
    model="grok-beta",
    messages=[
        {"role": "system", "content": "You are Grok, a chatbot inspired by the Hitchhiker's Guide to the Galaxy."},
        {"role": "user", "content": "What is the meaning of life, the universe, and everything?"},
    ],
)

print(completion.choices[0].message)
```

### Use Anthropic SDK with JavaScript

If you are using the Anthropic SDK with JavaScript, you can set your endpoint like this:

```js title="JavaScript"
import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
	apiKey: "<api key>",
	baseURL:
		"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/grok",
});

const msg = await anthropic.messages.create({
	model: "grok-beta",
	max_tokens: 128,
	system:
		"You are Grok, a chatbot inspired by the Hitchhiker's Guide to the Galaxy.",
	messages: [
		{
			role: "user",
			content: "What is the meaning of life, the universe, and everything?",
		},
	],
});

console.log(msg);
```

### Use Anthropic SDK with Python

If you are using the Anthropic SDK with Python, you can set your endpoint like this:

```python title="Python"
import os
from anthropic import Anthropic

XAI_API_KEY = os.getenv("XAI_API_KEY")
client = Anthropic(
    api_key=XAI_API_KEY,
    base_url="https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/grok",
)

message = client.messages.create(
    model="grok-beta",
    max_tokens=128,
    system="You are Grok, a chatbot inspired by the Hitchhiker's Guide to the Galaxy.",
    messages=[
        {
            "role": "user",
            "content": "What is the meaning of life, the universe, and everything?",
        },
    ],
)

print(message.content)
```

<Render
	file="chat-completions-providers"
	product="ai-gateway"
	params={{
		name: "Grok",
		jsonexample: `
{
	"model": "grok/{model}"
}`

    }}

/>

---

# Groq

URL: https://developers.cloudflare.com/ai-gateway/providers/groq/

import { Render } from "~/components";

[Groq](https://groq.com/) delivers high-speed processing and low-latency performance.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/groq
```

## URL structure

When making requests to [Groq](https://groq.com/), replace `https://api.groq.com/openai/v1` in the URL you're currently using with `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/groq`.

## Prerequisites

When making requests to Groq, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active Groq API token.
- The name of the Groq model you want to use.

## Examples

### cURL

```bash title="Example fetch request"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/groq/chat/completions \
  --header 'Authorization: Bearer {groq_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ],
    "model": "llama3-8b-8192"
}'
```

### Use Groq SDK with JavaScript

If using the [`groq-sdk`](https://www.npmjs.com/package/groq-sdk), set your endpoint like this:

```js title="JavaScript"
import Groq from "groq-sdk";

const apiKey = env.GROQ_API_KEY;
const accountId = "{account_id}";
const gatewayId = "{gateway_id}";
const baseURL = `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/groq`;

const groq = new Groq({
	apiKey,
	baseURL,
});

const messages = [{ role: "user", content: "What is Cloudflare?" }];
const model = "llama3-8b-8192";

const chatCompletion = await groq.chat.completions.create({
	messages,
	model,
});
```

<Render
	file="chat-completions-providers"
	product="ai-gateway"
	params={{
		name: "Groq",
		jsonexample: `
{
	"model": "groq/{model}"
}`

    }}

/>

---

# Model providers

URL: https://developers.cloudflare.com/ai-gateway/providers/

Here is a quick list of the providers we support:

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# HuggingFace

URL: https://developers.cloudflare.com/ai-gateway/providers/huggingface/

[HuggingFace](https://huggingface.co/) helps users build, deploy and train machine learning models.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/huggingface
```

## URL structure

When making requests to HuggingFace Inference API, replace `https://api-inference.huggingface.co/models/` in the URL you're currently using with `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/huggingface`. Note that the model you're trying to access should come right after, for example `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/huggingface/bigcode/starcoder`.

## Prerequisites

When making requests to HuggingFace, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active HuggingFace API token.
- The name of the HuggingFace model you want to use.

## Examples

### cURL

```bash title="Request"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/huggingface/bigcode/starcoder \
  --header 'Authorization: Bearer {hf_api_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "inputs": "console.log"
}'
```

### Use HuggingFace.js library with JavaScript

If you are using the HuggingFace.js library, you can set your inference endpoint like this:

```js title="JavaScript"
import { HfInferenceEndpoint } from "@huggingface/inference";

const accountId = "{account_id}";
const gatewayId = "{gateway_id}";
const model = "gpt2";
const baseURL = `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/huggingface/${model}`;
const apiToken = env.HF_API_TOKEN;

const hf = new HfInferenceEndpoint(baseURL, apiToken);
```

---

# Mistral AI

URL: https://developers.cloudflare.com/ai-gateway/providers/mistral/

import { Render } from "~/components";

[Mistral AI](https://mistral.ai) helps you build quickly with Mistral's advanced AI models.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/mistral
```

## Prerequisites

When making requests to the Mistral AI, you will need:

- AI Gateway Account ID
- AI Gateway gateway name
- Mistral AI API token
- Mistral AI model name

## URL structure

Your new base URL will use the data above in this structure: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/mistral/`.

Then you can append the endpoint you want to hit, for example: `v1/chat/completions`

So your final URL will come together as: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/mistral/v1/chat/completions`.

## Examples

### cURL

```bash title="Example fetch request"
curl -X POST https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/mistral/v1/chat/completions \
 --header 'content-type: application/json' \
 --header 'Authorization: Bearer MISTRAL_TOKEN' \
 --data '{
    "model": "mistral-large-latest",
    "messages": [
        {
            "role": "user",
            "content": "What is Cloudflare?"
        }
    ]
}'
```

### Use `@mistralai/mistralai` package with JavaScript

If you are using the `@mistralai/mistralai` package, you can set your endpoint like this:

```js title="JavaScript example"
import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({
	apiKey: MISTRAL_TOKEN,
	serverURL: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/mistral`,
});

await client.chat.create({
	model: "mistral-large-latest",
	messages: [
		{
			role: "user",
			content: "What is Cloudflare?",
		},
	],
});
```

<Render
	file="chat-completions-providers"
	product="ai-gateway"
	params={{
		name: "Mistral",
		jsonexample: `
{
	"model": "mistral/{model}"
}`

    }}

/>

---

# OpenAI

URL: https://developers.cloudflare.com/ai-gateway/providers/openai/

[OpenAI](https://openai.com/about/) helps you build with ChatGPT.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai
```

### Chat completions endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
```

### Responses endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/responses \
```

## URL structure

When making requests to OpenAI, replace `https://api.openai.com/v1` in the URL you are currently using with `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai`.

## Prerequisites

When making requests to OpenAI, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active OpenAI API token.
- The name of the OpenAI model you want to use.

## Chat completions endpoint

### cURL example

```bash
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
--header 'Authorization: Bearer {openai_token}' \
--header 'Content-Type: application/json' \
--data '{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": "What is Cloudflare?"
    }
  ]
}'
```

### JavaScript SDK example

```js
import OpenAI from "openai";

const apiKey = "my api key"; // or process.env["OPENAI_API_KEY"]
const accountId = "{account_id}";
const gatewayId = "{gateway_id}";
const baseURL = `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`;

const openai = new OpenAI({
	apiKey,
	baseURL,
});

try {
	const model = "gpt-3.5-turbo-0613";
	const messages = [{ role: "user", content: "What is a neuron?" }];
	const maxTokens = 100;
	const chatCompletion = await openai.chat.completions.create({
		model,
		messages,
		max_tokens: maxTokens,
	});
	const response = chatCompletion.choices[0].message;
	console.log(response);
} catch (e) {
	console.error(e);
}
```

## OpenAI Responses endpoint

### cURL example

```bash
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/responses \
--header 'Authorization: Bearer {openai_token}' \
--header 'Content-Type: application/json' \
--data '{
  "model": "gpt-4.1",
  "input": [
    {
      "role": "user",
      "content": "Write a one-sentence bedtime story about a unicorn."
    }
  ]
}'
```

### JavaScript SDK example

```js
import OpenAI from "openai";

const apiKey = "my api key"; // or process.env["OPENAI_API_KEY"]
const accountId = "{account_id}";
const gatewayId = "{gateway_id}";
const baseURL = `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`;

const openai = new OpenAI({
	apiKey,
	baseURL,
});

try {
	const model = "gpt-4.1";
	const input = [
		{
			role: "user",
			content: "Write a one-sentence bedtime story about a unicorn.",
		},
	];
	const response = await openai.responses.create({
		model,
		input,
	});
	console.log(response.output_text);
} catch (e) {
	console.error(e);
}
```

---

# OpenRouter

URL: https://developers.cloudflare.com/ai-gateway/providers/openrouter/

[OpenRouter](https://openrouter.ai/) is a platform that provides a unified interface for accessing and using large language models (LLMs).

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openrouter
```

## URL structure

When making requests to [OpenRouter](https://openrouter.ai/), replace `https://openrouter.ai/api/v1/chat/completions` in the URL you are currently using with `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openrouter`.

## Prerequisites

When making requests to OpenRouter, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active OpenRouter API token or a token from the original model provider.
- The name of the OpenRouter model you want to use.

## Examples

### cURL

```bash title="Request"
curl -X POST https://gateway.ai.cloudflare.com/v1/ACCOUNT_TAG/GATEWAY/openrouter/v1/chat/completions \
 --header 'content-type: application/json' \
 --header 'Authorization: Bearer OPENROUTER_TOKEN' \
 --data '{
    "model": "openai/gpt-3.5-turbo",
    "messages": [
        {
            "role": "user",
            "content": "What is Cloudflare?"
        }
    ]
}'

```

### Use OpenAI SDK with JavaScript

If you are using the OpenAI SDK with JavaScript, you can set your endpoint like this:

```js title="JavaScript"
import OpenAI from "openai";

const openai = new OpenAI({
	apiKey: env.OPENROUTER_TOKEN,
	baseURL:
		"https://gateway.ai.cloudflare.com/v1/ACCOUNT_TAG/GATEWAY/openrouter",
});

try {
	const chatCompletion = await openai.chat.completions.create({
		model: "openai/gpt-3.5-turbo",
		messages: [{ role: "user", content: "What is Cloudflare?" }],
	});

	const response = chatCompletion.choices[0].message;

	return new Response(JSON.stringify(response));
} catch (e) {
	return new Response(e);
}
```

---

# Perplexity

URL: https://developers.cloudflare.com/ai-gateway/providers/perplexity/

import { Render } from "~/components";

[Perplexity](https://www.perplexity.ai/) is an AI powered answer engine.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/perplexity-ai
```

## Prerequisites

When making requests to Perplexity, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active Perplexity API token.
- The name of the Perplexity model you want to use.

## Examples

### cURL

```bash title="Example fetch request"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/perplexity-ai/chat/completions \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer {perplexity_token}' \
     --data '{
      "model": "mistral-7b-instruct",
      "messages": [
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ]
    }'
```

### Use Perplexity through OpenAI SDK with JavaScript

Perplexity does not have their own SDK, but they have compatibility with the OpenAI SDK. You can use the OpenAI SDK to make a Perplexity call through AI Gateway as follows:

```js title="JavaScript"
import OpenAI from "openai";

const apiKey = env.PERPLEXITY_API_KEY;
const accountId = "{account_id}";
const gatewayId = "{gateway_id}";
const baseURL = `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/perplexity-ai`;

const perplexity = new OpenAI({
	apiKey,
	baseURL,
});

const model = "mistral-7b-instruct";
const messages = [{ role: "user", content: "What is Cloudflare?" }];
const maxTokens = 20;

const chatCompletion = await perplexity.chat.completions.create({
	model,
	messages,
	max_tokens: maxTokens,
});
```

<Render
	file="chat-completions-providers"
	product="ai-gateway"
	params={{
		name: "Perplexity",
		jsonexample: `
{
	"model": "perplexity/{model}"
}`

    }}

/>

---

# Replicate

URL: https://developers.cloudflare.com/ai-gateway/providers/replicate/

[Replicate](https://replicate.com/) runs and fine tunes open-source models.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/replicate
```

## URL structure

When making requests to Replicate, replace `https://api.replicate.com/v1` in the URL you're currently using with `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/replicate`.

## Prerequisites

When making requests to Replicate, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active Replicate API token.
- The name of the Replicate model you want to use.

## Example

### cURL

```bash title="Request"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/replicate/predictions \
  --header 'Authorization: Token {replicate_api_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "input":
      {
        "prompt": "What is Cloudflare?"
      }
    }'
```

---

# Google Vertex AI

URL: https://developers.cloudflare.com/ai-gateway/providers/vertex/

[Google Vertex AI](https://cloud.google.com/vertex-ai) enables developers to easily build and deploy enterprise ready generative AI experiences.

Below is a quick guide on how to set your Google Cloud Account:

1. Google Cloud Platform (GCP) Account

   - Sign up for a [GCP account](https://cloud.google.com/vertex-ai). New users may be eligible for credits (valid for 90 days).

2. Enable the Vertex AI API

   - Navigate to [Enable Vertex AI API](https://console.cloud.google.com/marketplace/product/google/aiplatform.googleapis.com) and activate the API for your project.

3. Apply for access to desired models.

## Endpoint

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai
```

## Prerequisites

When making requests to Google Vertex, you will need:

- AI Gateway account tag
- AI Gateway gateway name
- Google Vertex API key
- Google Vertex Project Name
- Google Vertex Region (for example, us-east4)
- Google Vertex model

## URL structure

Your new base URL will use the data above in this structure: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}`.

Then you can append the endpoint you want to hit, for example: `/publishers/google/models/{model}:{generative_ai_rest_resource}`

So your final URL will come together as: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-1.0-pro-001:generateContent`

## Example

### cURL

```bash title="Example fetch request"
curl "https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-vertex-ai/v1/projects/{project_name}/locations/{region}/publishers/google/models/gemini-1.0-pro-001:generateContent" \
    -H "Authorization: Bearer {vertex_api_key}" \
    -H 'Content-Type: application/json' \
    -d '{
        "contents": {
          "role": "user",
          "parts": [
            {
              "text": "Tell me more about Cloudflare"
            }
          ]
        }'

```

---

# Workers AI

URL: https://developers.cloudflare.com/ai-gateway/providers/workersai/

import { Render } from "~/components";

Use AI Gateway for analytics, caching, and security on requests to [Workers AI](/workers-ai/). Workers AI integrates seamlessly with AI Gateway, allowing you to execute AI inference via API requests or through an environment binding for Workers scripts. The binding simplifies the process by routing requests through your AI Gateway with minimal setup.

## Prerequisites

When making requests to Workers AI, ensure you have the following:

- Your AI Gateway Account ID.
- Your AI Gateway gateway name.
- An active Workers AI API token.
- The name of the Workers AI model you want to use.

## REST API

To interact with a REST API, update the URL used for your request:

- **Previous**:

```txt
https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/{model_id}
```

- **New**:

```txt
https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/workers-ai/{model_id}
```

For these parameters:

- `{account_id}` is your Cloudflare [account ID](/workers-ai/get-started/rest-api/#1-get-api-token-and-account-id).
- `{gateway_id}` refers to the name of your existing [AI Gateway](/ai-gateway/get-started/#create-gateway).
- `{model_id}` refers to the model ID of the [Workers AI model](/workers-ai/models/).

## Examples

First, generate an [API token](/fundamentals/api/get-started/create-token/) with `Workers AI Read` access and use it in your request.

```bash title="Request to Workers AI llama model"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/workers-ai/@cf/meta/llama-3.1-8b-instruct \
 --header 'Authorization: Bearer {cf_api_token}' \
 --header 'Content-Type: application/json' \
 --data '{"prompt": "What is Cloudflare?"}'
```

```bash title="Request to Workers AI text classification model"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/workers-ai/@cf/huggingface/distilbert-sst-2-int8 \
  --header 'Authorization: Bearer {cf_api_token}' \
  --header 'Content-Type: application/json' \
  --data '{ "text": "Cloudflare docs are amazing!" }'
```

### OpenAI compatible endpoints

<Render file="openai-compatibility" product="workers-ai" /> <br />

```bash title="Request to OpenAI compatible endpoint"
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/workers-ai/v1/chat/completions \
 --header 'Authorization: Bearer {cf_api_token}' \
 --header 'Content-Type: application/json' \
 --data '{
      "model": "@cf/meta/llama-3.1-8b-instruct",
      "messages": [
        {
          "role": "user",
          "content": "What is Cloudflare?"
        }
      ]
    }
'
```

## Workers Binding

You can integrate Workers AI with AI Gateway using an environment binding. To include an AI Gateway within your Worker, add the gateway as an object in your Workers AI request.

```ts
export interface Env {
	AI: Ai;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const response = await env.AI.run(
			"@cf/meta/llama-3.1-8b-instruct",
			{
				prompt: "Why should you use Cloudflare for your AI inference?",
			},
			{
				gateway: {
					id: "{gateway_id}",
					skipCache: false,
					cacheTtl: 3360,
				},
			},
		);
		return new Response(JSON.stringify(response));
	},
} satisfies ExportedHandler<Env>;
```

For a detailed step-by-step guide on integrating Workers AI with AI Gateway using a binding, see [Integrations in AI Gateway](/ai-gateway/integrations/aig-workers-ai-binding/).

Workers AI supports the following parameters for AI gateways:

- `id` string
  - Name of your existing [AI Gateway](/ai-gateway/get-started/#create-gateway). Must be in the same account as your Worker.
- `skipCache` boolean(default: false)
  - Controls whether the request should [skip the cache](/ai-gateway/configuration/caching/#skip-cache-cf-aig-skip-cache).
- `cacheTtl` number
  - Controls the [Cache TTL](/ai-gateway/configuration/caching/#cache-ttl-cf-aig-cache-ttl).

<Render
	file="chat-completions-providers"
	product="ai-gateway"
	params={{
		name: "Workers AI",
		jsonexample: `
{
	"model": "workers-ai/{model}"
}`

    }}

/>

---

# Audit logs

URL: https://developers.cloudflare.com/ai-gateway/reference/audit-logs/

[Audit logs](/fundamentals/account/account-security/review-audit-logs/) provide a comprehensive summary of changes made within your Cloudflare account, including those made to gateways in AI Gateway. This functionality is available on all plan types, free of charge, and is enabled by default.

## Viewing Audit Logs

To view audit logs for AI Gateway:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Go to **Manage Account** > **Audit Log**.

For more information on how to access and use audit logs, refer to [review audit logs documentation](/fundamentals/account/account-security/review-audit-logs/).

## Logged Operations

The following configuration actions are logged:

| Operation       | Description                      |
| --------------- | -------------------------------- |
| gateway created | Creation of a new gateway.       |
| gateway deleted | Deletion of an existing gateway. |
| gateway updated | Edit of an existing gateway.     |

## Example Log Entry

Below is an example of an audit log entry showing the creation of a new gateway:

```json
{
 "action": {
     "info": "gateway created",
     "result": true,
     "type": "create"
 },
 "actor": {
     "email": "<ACTOR_EMAIL>",
     "id": "3f7b730e625b975bc1231234cfbec091",
     "ip": "fe32:43ed:12b5:526::1d2:13",
     "type": "user"
 },
 "id": "5eaeb6be-1234-406a-87ab-1971adc1234c",
 "interface": "UI",
 "metadata": {},
 "newValue": "",
 "newValueJson": {
     "cache_invalidate_on_update": false,
     "cache_ttl": 0,
     "collect_logs": true,
     "id": "test",
     "rate_limiting_interval": 0,
     "rate_limiting_limit": 0,
     "rate_limiting_technique": "fixed"
 },
 "oldValue": "",
 "oldValueJson": {},
 "owner": {
     "id": "1234d848c0b9e484dfc37ec392b5fa8a"
 },
 "resource": {
     "id": "89303df8-1234-4cfa-a0f8-0bd848e831ca",
     "type": "ai_gateway.gateway"
 },
 "when": "2024-07-17T14:06:11.425Z"
}
```

---

# Platform

URL: https://developers.cloudflare.com/ai-gateway/reference/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Limits

URL: https://developers.cloudflare.com/ai-gateway/reference/limits/

import { Render } from "~/components";

The following limits apply to gateway configurations, logs, and related features in Cloudflare's platform.

| Feature                                                          | Limit                               |
| ---------------------------------------------------------------- | ----------------------------------- |
| [Cacheable request size](/ai-gateway/configuration/caching/)     | 25 MB per request                   |
| [Cache TTL](/ai-gateway/configuration/caching/#cache-ttl-cf-aig-cache-ttl)     | 1 month               |
| [Custom metadata](/ai-gateway/configuration/custom-metadata/)    | 5 entries per request               |
| [Datasets](/ai-gateway/evaluations/set-up-evaluations/)          | 10 per gateway                      |
| Gateways free plan                                               | 10 per account                      |
| Gateways paid plan                                               | 20 per account                      |
| Gateway name length                                              | 64 characters                       |
| Log storage rate limit                                           | 500 logs per second per gateway     |
| Logs stored [paid plan](/ai-gateway/reference/pricing/)          | 10 million per gateway <sup>1</sup> |
| Logs stored [free plan](/ai-gateway/reference/pricing/)          | 100,000 per account <sup>2</sup>    |
| [Log size stored](/ai-gateway/observability/logging/)            | 10 MB per log <sup>3</sup>          |
| [Logpush jobs](/ai-gateway/observability/logging/logpush/)       | 4 per account                       |
| [Logpush size limit](/ai-gateway/observability/logging/logpush/) | 1MB per log                         |

<sup>1</sup> If you have reached 10 million logs stored per gateway, new logs
will stop being saved. To continue saving logs, you must delete older logs in
that gateway to free up space or create a new gateway. Refer to [Auto Log
Cleanup](/ai-gateway/observability/logging/#auto-log-cleanup) for more details
on how to automatically delete logs.

<sup>2</sup> If you have reached 100,000 logs stored per account, across all
gateways, new logs will stop being saved. To continue saving logs, you must
delete older logs. Refer to [Auto Log
Cleanup](/ai-gateway/observability/logging/#auto-log-cleanup) for more details
on how to automatically delete logs.

<sup>3</sup> Logs larger than 10 MB will not be stored.

<Render file="limits-increase" product="ai-gateway" />

---

# Pricing

URL: https://developers.cloudflare.com/ai-gateway/reference/pricing/

AI Gateway is available to use on all plans.

AI Gateway's core features available today are offered for free, and all it takes is a Cloudflare account and one line of code to [get started](/ai-gateway/get-started/). Core features include: dashboard analytics, caching, and rate limiting.

We will continue to build and expand AI Gateway. Some new features may be additional core features that will be free while others may be part of a premium plan. We will announce these as they become available.

You can monitor your usage in the AI Gateway dashboard.

## Persistent logs

:::note[Note]

Billing for persistent logs has not yet started. Users on paid plans can store logs beyond the included volume of 200,000 logs stored a month without being charged during this period. (Users on the free plan remain limited to the 100,000 logs cap for their plan.) We will provide plenty of advanced notice before charging begins for persistent log storage.

:::

Persistent logs are available on all plans, with a free allocation for both free and paid plans. Charges for additional logs beyond those limits are based on the number of logs stored per month.

### Free allocation and overage pricing

| Plan         | Free logs stored   | Overage pricing                      |
| ------------ | ------------------ | ------------------------------------ |
| Workers Free | 100,000 logs total | N/A - Upgrade to Workers Paid        |
| Workers Paid | 200,000 logs total | $8 per 100,000 logs stored per month |

Allocations are based on the total logs stored across all gateways. For guidance on managing or deleting logs, please see our [documentation](/ai-gateway/observability/logging).

For example, if you are a Workers Paid plan user storing 300,000 logs, you will be charged for the excess 100,000 logs (300,000 total logs - 200,000 free logs), resulting in an $8/month charge.

## Logpush

Logpush is only available on the Workers Paid plan.

|          | Paid plan                          |
| -------- | ---------------------------------- |
| Requests | 10 million / month, +$0.05/million |

## Fine print

Prices subject to change. If you are an Enterprise customer, reach out to your account team to confirm pricing details.

---

# Create your first AI Gateway using Workers AI

URL: https://developers.cloudflare.com/ai-gateway/tutorials/create-first-aig-workers/

import { Render } from "~/components";

This tutorial guides you through creating your first AI Gateway using Workers AI on the Cloudflare dashboard. The intended audience is beginners who are new to AI Gateway and Workers AI. Creating an AI Gateway enables the user to efficiently manage and secure AI requests, allowing them to utilize AI models for tasks such as content generation, data processing, or predictive analysis with enhanced control and performance.

## Sign up and log in

1. **Sign up**: If you do not have a Cloudflare account, [sign up](https://cloudflare.com/sign-up).
2. **Log in**: Access the Cloudflare dashboard by logging in to the [Cloudflare dashboard](https://dash.cloudflare.com/login).

## Create gateway

Then, create a new AI Gateway.

<Render file="create-gateway" />

## Connect Your AI Provider

1. In the AI Gateway section, select the gateway you created.
2. Select **Workers AI** as your provider to set up an endpoint specific to Workers AI.
   You will receive an endpoint URL for sending requests.

## Configure Your Workers AI

1. Go to **AI** > **Workers AI** in the Cloudflare dashboard.
2. Select **Use REST API** and follow the steps to create and copy the API token and Account ID.
3. **Send Requests to Workers AI**: Use the provided API endpoint. For example, you can run a model via the API using a curl command. Replace `{account_id}`, `{gateway_id}` and `{cf_api_token}` with your actual account ID and API token:

   ```bash
   curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/workers-ai/@cf/meta/llama-3.1-8b-instruct \
   --header 'Authorization: Bearer {cf_api_token}' \
   --header 'Content-Type: application/json' \
   --data '{"prompt": "What is Cloudflare?"}'
   ```

The expected output would be similar to :

```bash
{"result":{"response":"I'd be happy to explain what Cloudflare is.\n\nCloudflare is a cloud-based service that provides a range of features to help protect and improve the performance, security, and reliability of websites, applications, and other online services. Think of it as a shield for your online presence!\n\nHere are some of the key things Cloudflare does:\n\n1. **Content Delivery Network (CDN)**: Cloudflare has a network of servers all over the world. When you visit a website that uses Cloudflare, your request is sent to the nearest server, which caches a copy of the website's content. This reduces the time it takes for the content to load, making your browsing experience faster.\n2. **DDoS Protection**: Cloudflare protects against Distributed Denial-of-Service (DDoS) attacks. This happens when a website is overwhelmed with traffic from multiple sources to make it unavailable. Cloudflare filters out this traffic, ensuring your site remains accessible.\n3. **Firewall**: Cloudflare acts as an additional layer of security, filtering out malicious traffic and hacking attempts, such as SQL injection or cross-site scripting (XSS) attacks.\n4. **SSL Encryption**: Cloudflare offers free SSL encryption, which secure sensitive information (like passwords, credit card numbers, and browsing data) with an HTTPS connection (the \"S\" stands for Secure).\n5. **Bot Protection**: Cloudflare has an AI-driven system that identifies and blocks bots trying to exploit vulnerabilities or scrape your content.\n6. **Analytics**: Cloudflare provides insights into website traffic, helping you understand your audience and make informed decisions.\n7. **Cybersecurity**: Cloudflare offers advanced security features, such as intrusion protection, DNS filtering, and Web Application Firewall (WAF) protection.\n\nOverall, Cloudflare helps protect against cyber threats, improves website performance, and enhances security for online businesses, bloggers, and individuals who need to establish a strong online presence.\n\nWould you like to know more about a specific aspect of Cloudflare?"},"success":true,"errors":[],"messages":[]}%
```

## View Analytics

Monitor your AI Gateway to view usage metrics.

1. Go to **AI** > **AI Gateway** in the dashboard.
2. Select your gateway to view metrics such as request counts, token usage, caching efficiency, errors, and estimated costs. You can also turn on additional configurations like logging and rate limiting.

## Optional - Next steps

To build more with Workers, refer to [Tutorials](/workers/tutorials/).

If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on [Discord](https://discord.cloudflare.com) to connect with other developers and the Cloudflare team.

---

# Tutorials

URL: https://developers.cloudflare.com/ai-gateway/tutorials/

import { GlossaryTooltip, ListTutorials, YouTubeVideos } from "~/components";

View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with AI Gateway.

## Docs

<ListTutorials />

## Videos

<YouTubeVideos products={["AI Gateway"]} />

---

# Deploy a Worker that connects to OpenAI via AI Gateway

URL: https://developers.cloudflare.com/ai-gateway/tutorials/deploy-aig-worker/

import { Render, PackageManagers } from "~/components";

In this tutorial, you will learn how to deploy a Worker that makes calls to OpenAI through AI Gateway. AI Gateway helps you better observe and control your AI applications with more analytics, caching, rate limiting, and logging.

This tutorial uses the most recent v4 OpenAI node library, an update released in August 2023.

## Before you start

All of the tutorials assume you have already completed the [Get started guide](/workers/get-started/guide/), which gets you set up with a Cloudflare Workers account, [C3](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare), and [Wrangler](/workers/wrangler/install-and-update/).

## 1. Create an AI Gateway and OpenAI API key

On the AI Gateway page in the Cloudflare dashboard, create a new AI Gateway by clicking the plus button on the top right. You should be able to name the gateway as well as the endpoint. Click on the API Endpoints button to copy the endpoint. You can choose from provider-specific endpoints such as OpenAI, HuggingFace, and Replicate. Or you can use the universal endpoint that accepts a specific schema and supports model fallback and retries.

For this tutorial, we will be using the OpenAI provider-specific endpoint, so select OpenAI in the dropdown and copy the new endpoint.

You will also need an OpenAI account and API key for this tutorial. If you do not have one, create a new OpenAI account and create an API key to continue with this tutorial. Make sure to store your API key somewhere safe so you can use it later.

## 2. Create a new Worker

Create a Worker project in the command line:

<PackageManagers type="create" pkg="cloudflare@latest" args={"openai-aig"} />

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Go to your new open Worker project:

```sh title="Open your new project directory"
cd openai-aig
```

Inside of your new openai-aig directory, find and open the `src/index.js` file. You will configure this file for most of the tutorial.

Initially, your generated `index.js` file should look like this:

```js
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello World!");
	},
};
```

## 3. Configure OpenAI in your Worker

With your Worker project created, we can learn how to make your first request to OpenAI. You will use the OpenAI node library to interact with the OpenAI API. Install the OpenAI node library with `npm`:

<PackageManagers pkg="openai" />

In your `src/index.js` file, add the import for `openai` above `export default`:

```js
import OpenAI from "openai";
```

Within your `fetch` function, set up the configuration and instantiate your `OpenAIApi` client with the AI Gateway endpoint you created:

```js null {5-8}
import OpenAI from "openai";

export default {
	async fetch(request, env, ctx) {
		const openai = new OpenAI({
			apiKey: env.OPENAI_API_KEY,
			baseURL:
				"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai", // paste your AI Gateway endpoint here
		});
	},
};
```

To make this work, you need to use [`wrangler secret put`](/workers/wrangler/commands/#put) to set your `OPENAI_API_KEY`. This will save the API key to your environment so your Worker can access it when deployed. This key is the API key you created earlier in the OpenAI dashboard:

<PackageManagers type="exec" pkg="wrangler" args="secret put OPENAI_API_KEY" />

To make this work in local development, create a new file `.dev.vars` in your Worker project and add this line. Make sure to replace `OPENAI_API_KEY` with your own OpenAI API key:

```txt title="Save your API key locally"
OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY_HERE>"
```

## 4. Make an OpenAI request

Now we can make a request to the OpenAI [Chat Completions API](https://platform.openai.com/docs/guides/gpt/chat-completions-api).

You can specify what model you'd like, the role and prompt, as well as the max number of tokens you want in your total request.

```js null {10-22}
import OpenAI from "openai";

export default {
	async fetch(request, env, ctx) {
		const openai = new OpenAI({
			apiKey: env.OPENAI_API_KEY,
			baseURL:
				"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai",
		});

		try {
			const chatCompletion = await openai.chat.completions.create({
				model: "gpt-4o-mini",
				messages: [{ role: "user", content: "What is a neuron?" }],
				max_tokens: 100,
			});

			const response = chatCompletion.choices[0].message;

			return new Response(JSON.stringify(response));
		} catch (e) {
			return new Response(e);
		}
	},
};
```

## 5. Deploy your Worker application

To deploy your application, run the `npx wrangler deploy` command to deploy your Worker application:

<PackageManagers type="exec" pkg="wrangler" args="deploy" />

You can now preview your Worker at \<YOUR_WORKER>.\<YOUR_SUBDOMAIN>.workers.dev.

## 6. Review your AI Gateway

When you go to AI Gateway in your Cloudflare dashboard, you should see your recent request being logged. You can also [tweak your settings](/ai-gateway/configuration/) to manage your logs, caching, and rate limiting settings.

---

# WebSockets API

URL: https://developers.cloudflare.com/ai-gateway/websockets-api/

The AI Gateway WebSockets API provides a persistent connection for AI interactions, eliminating repeated handshakes and reducing latency. This API is divided into two categories:

- **Realtime APIs** - Designed for AI providers that offer low-latency, multimodal interactions over WebSockets.
- **Non-Realtime APIs** - Supports standard WebSocket communication for AI providers, including those that do not natively support WebSockets.

## When to use WebSockets

WebSockets are long-lived TCP connections that enable bi-directional, real-time and non realtime communication between client and server. Unlike HTTP connections, which require repeated handshakes for each request, WebSockets maintain the connection, supporting continuous data exchange with reduced overhead. WebSockets are ideal for applications needing low-latency, real-time data, such as voice assistants.

## Key benefits

- **Reduced overhead**: Avoid overhead of repeated handshakes and TLS negotiations by maintaining a single, persistent connection.
- **Provider compatibility**: Works with all AI providers in AI Gateway. Even if your chosen provider does not support WebSockets, Cloudflare handles it for you, managing the requests to your preferred AI provider.

## Key differences

| Feature                 | Realtime APIs                                                                                                           | Non-Realtime APIs                                                                                |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| **Purpose**             | Enables real-time, multimodal AI interactions for providers that offer dedicated WebSocket endpoints.                   | Supports WebSocket-based AI interactions with providers that do not natively support WebSockets. |
| **Use Case**            | Streaming responses for voice, video, and live interactions.                                                            | Text-based queries and responses, such as LLM requests.                                          |
| **AI Provider Support** | [Limited to providers offering real-time WebSocket APIs.](/ai-gateway/websockets-api/realtime-api/#supported-providers) | [All AI providers in AI Gateway.](/ai-gateway/providers/)                                        |
| **Streaming Support**   | Providers natively support real-time data streaming.                                                                    | AI Gateway handles streaming via WebSockets.                                                     |

For details on implementation, refer to the next sections:

- [Realtime WebSockets API](/ai-gateway/websockets-api/realtime-api/)
- [Non-Realtime WebSockets API](/ai-gateway/websockets-api/non-realtime-api/)

---

# Non-realtime WebSockets API

URL: https://developers.cloudflare.com/ai-gateway/websockets-api/non-realtime-api/

The Non-realtime WebSockets API allows you to establish persistent connections for AI requests without requiring repeated handshakes. This approach is ideal for applications that do not require real-time interactions but still benefit from reduced latency and continuous communication.

## Set up WebSockets API

1. Generate an AI Gateway token with appropriate AI Gateway Run and opt in to using an authenticated gateway.
2. Modify your Universal Endpoint URL by replacing `https://` with `wss://` to initiate a WebSocket connection:
   ```
   wss://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}
   ```
3. Open a WebSocket connection authenticated with a Cloudflare token with the AI Gateway Run permission.

:::note
Alternatively, we also support authentication via the `sec-websocket-protocol` header if you are using a browser WebSocket.
:::

## Example request

```javascript
import WebSocket from "ws";

const ws = new WebSocket(
	"wss://gateway.ai.cloudflare.com/v1/my-account-id/my-gateway/",
	{
		headers: {
			"cf-aig-authorization": "Bearer AI_GATEWAY_TOKEN",
		},
	},
);

ws.send(
	JSON.stringify({
		type: "universal.create",
		request: {
			eventId: "my-request",
			provider: "workers-ai",
			endpoint: "@cf/meta/llama-3.1-8b-instruct",
			headers: {
				Authorization: "Bearer WORKERS_AI_TOKEN",
				"Content-Type": "application/json",
			},
			query: {
				prompt: "tell me a joke",
			},
		},
	}),
);

ws.on("message", function incoming(message) {
	console.log(message.toString());
});
```

## Example response

```json
{
	"type": "universal.created",
	"metadata": {
		"cacheStatus": "MISS",
		"eventId": "my-request",
		"logId": "01JC3R94FRD97JBCBX3S0ZAXKW",
		"step": "0",
		"contentType": "application/json"
	},
	"response": {
		"result": {
			"response": "Why was the math book sad? Because it had too many problems. Would you like to hear another one?"
		},
		"success": true,
		"errors": [],
		"messages": []
	}
}
```

## Example streaming request

For streaming requests, AI Gateway sends an initial message with request metadata indicating the stream is starting:

```json
{
	"type": "universal.created",
	"metadata": {
		"cacheStatus": "MISS",
		"eventId": "my-request",
		"logId": "01JC40RB3NGBE5XFRZGBN07572",
		"step": "0",
		"contentType": "text/event-stream"
	}
}
```

After this initial message, all streaming chunks are relayed in real-time to the WebSocket connection as they arrive from the inference provider. Only the `eventId` field is included in the metadata for these streaming chunks. The `eventId` allows AI Gateway to include a client-defined ID with each message, even in a streaming WebSocket environment.

```json
{
	"type": "universal.stream",
	"metadata": {
		"eventId": "my-request"
	},
	"response": {
		"response": "would"
	}
}
```

Once all chunks for a request have been streamed, AI Gateway sends a final message to signal the completion of the request. For added flexibility, this message includes all the metadata again, even though it was initially provided at the start of the streaming process.

```json
{
	"type": "universal.done",
	"metadata": {
		"cacheStatus": "MISS",
		"eventId": "my-request",
		"logId": "01JC40RB3NGBE5XFRZGBN07572",
		"step": "0",
		"contentType": "text/event-stream"
	}
}
```

---

# Realtime WebSockets API

URL: https://developers.cloudflare.com/ai-gateway/websockets-api/realtime-api/

Some AI providers support real-time, low-latency interactions over WebSockets. AI Gateway allows seamless integration with these APIs, supporting multimodal interactions such as text, audio, and video.

## Supported Providers

- [OpenAI](https://platform.openai.com/docs/guides/realtime-websocket)
- [Google AI Studio](https://ai.google.dev/gemini-api/docs/multimodal-live)
- [Cartesia](https://docs.cartesia.ai/api-reference/tts/tts)
- [ElevenLabs](https://elevenlabs.io/docs/conversational-ai/api-reference/conversational-ai/websocket)

## Authentication

For real-time WebSockets, authentication can be done using:

- Headers (for non-browser environments)
- `sec-websocket-protocol` (for browsers)

## Examples

### OpenAI

```javascript
import WebSocket from "ws";

const url =
	"wss://gateway.ai.cloudflare.com/v1/<account_id>/<gateway>/openai?model=gpt-4o-realtime-preview-2024-12-17";
const ws = new WebSocket(url, {
	headers: {
		"cf-aig-authorization": process.env.CLOUDFLARE_API_KEY,
		Authorization: "Bearer " + process.env.OPENAI_API_KEY,
		"OpenAI-Beta": "realtime=v1",
	},
});

ws.on("open", () => console.log("Connected to server."));
ws.on("message", (message) => console.log(JSON.parse(message.toString())));

ws.send(
	JSON.stringify({
		type: "response.create",
		response: { modalities: ["text"], instructions: "Tell me a joke" },
	}),
);
```

### Google AI Studio

```javascript
const ws = new WebSocket(
	"wss://gateway.ai.cloudflare.com/v1/<account_id>/<gateway>/google?api_key=<google_api_key>",
	["cf-aig-authorization.<cloudflare_token>"],
);

ws.on("open", () => console.log("Connected to server."));
ws.on("message", (message) => console.log(message.data));

ws.send(
	JSON.stringify({
		setup: {
			model: "models/gemini-2.0-flash-exp",
			generationConfig: { responseModalities: ["TEXT"] },
		},
	}),
);
```

### Cartesia

```javascript
const ws = new WebSocket(
	"wss://gateway.ai.cloudflare.com/v1/<account_id>/<gateway>/cartesia?cartesia_version=2024-06-10&api_key=<cartesia_api_key>",
	["cf-aig-authorization.<cloudflare_token>"],
);

ws.on("open", function open() {
	console.log("Connected to server.");
});

ws.on("message", function incoming(message) {
	console.log(message.data);
});

ws.send(
	JSON.stringify({
		model_id: "sonic",
		transcript: "Hello, world! I'm generating audio on ",
		voice: { mode: "id", id: "a0e99841-438c-4a64-b679-ae501e7d6091" },
		language: "en",
		context_id: "happy-monkeys-fly",
		output_format: {
			container: "raw",
			encoding: "pcm_s16le",
			sample_rate: 8000,
		},
		add_timestamps: true,
		continue: true,
	}),
);
```

### ElevenLabs

```javascript
const ws = new WebSocket(
	"wss://gateway.ai.cloudflare.com/v1/<account_id>/<gateway>/elevenlabs?agent_id=<elevenlabs_agent_id>",
	[
		"xi-api-key.<elevenlabs_api_key>",
		"cf-aig-authorization.<cloudflare_token>",
	],
);

ws.on("open", function open() {
	console.log("Connected to server.");
});

ws.on("message", function incoming(message) {
	console.log(message.data);
});

ws.send(
	JSON.stringify({
		text: "This is a sample text ",
		voice_settings: { stability: 0.8, similarity_boost: 0.8 },
		generation_config: { chunk_length_schedule: [120, 160, 250, 290] },
	}),
);
```

---

# Get started

URL: https://developers.cloudflare.com/analytics/analytics-engine/get-started/

import { DirectoryListing, WranglerConfig } from "~/components"

## 1. Name your dataset and add it to your Worker

Add the following to your [Wrangler configuration file](/workers/wrangler/configuration/) to create a [binding](/workers/runtime-apis/bindings/) to a Workers Analytics Engine dataset. A dataset is like a table in SQL: the rows and columns should have consistent meaning.

<WranglerConfig>

```toml
[[analytics_engine_datasets]]
binding = "<BINDING_NAME>"
dataset = "<DATASET_NAME>"
```

</WranglerConfig>

## 2. Write data points from your Worker

You can write data points to your Worker by calling the `writeDataPoint()` method that is exposed on the binding that you just created.

```js
async fetch(request, env) {
  env.WEATHER.writeDataPoint({
    'blobs': ["Seattle", "USA", "pro_sensor_9000"], // City, State
    'doubles': [25, 0.5],
    'indexes': ["a3cd45"]
  });
  return new Response("OK!");
}
```

:::note

You do not need to await `writeDataPoint()` — it will return immediately, and the Workers runtime handles writing your data in the background.
:::

A data point is a structured event that consists of:

* **Blobs** (strings) — The dimensions used for grouping and filtering. Sometimes called labels in other metrics systems.
* **Doubles** (numbers) — The numeric values that you want to record in your data point.
* **Indexes** — (strings) — Used as a [sampling](/analytics/analytics-engine/sql-api/#sampling) key.

In the example above, suppose you are collecting air quality samples. Each data point written represents a reading from your weather sensor. The blobs define city, state, and sensor model — the dimensions you want to be able to filter queries on later. The doubles define the numeric temperature and air pressure readings. And the index is the ID of your customer. You may want to include [context about the incoming request](/workers/runtime-apis/request/), such as geolocation, to add additional data to your datapoint.

Currently, the `writeDataPoint()` API accepts ordered arrays of values. This means that you must provide fields in a consistent order. While the `indexes` field accepts an array, you currently must only provide a single index. If you attempt to provide multiple indexes, your data point will not be recorded.

## 3. Query data using the SQL API

You can query the data you have written in two ways:

* [**SQL API**](/analytics/analytics-engine/sql-api) — Best for writing your own queries and integrating with external tools like Grafana.
* [**GraphQL API**](/analytics/graphql-api/) — This is the same API that powers the Cloudflare dashboard.

For the purpose of this example, we will use the SQL API.

### Create an API token

Create an [API Token](https://dash.cloudflare.com/profile/api-tokens) that has the `Account Analytics Read` permission.

### Write your first query

The following query returns the top 10 cities that had the highest average humidity readings when the temperature was above zero:

```sql
SELECT
  blob1 AS city,
  SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity
FROM WEATHER
WHERE double1 > 0
GROUP BY city
ORDER BY avg_humidity DESC
LIMIT 10
```

:::note

We are using a custom averaging function to take [sampling](/analytics/analytics-engine/sql-api/#sampling) into account.
:::

You can run this query by making an HTTP request to the SQL API:

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SELECT blob1 AS city, SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity FROM WEATHER WHERE double1 > 0 GROUP BY city ORDER BY avg_humidity DESC LIMIT 10"
```

Refer to the [Workers Analytics Engine SQL Reference](/analytics/analytics-engine/sql-reference/) for a full list of supported SQL functionality.

### Working with time series data

Workers Analytics Engine is optimized for powering time series analytics that can be visualized using tools like Grafana. Every event written from the runtime is automatically populated with a `timestamp` field. It is expected that most time series will round, and then `GROUP BY` the `timestamp`. For example:

```sql
SELECT
  intDiv(toUInt32(timestamp), 300) * 300 AS t,
  blob1 AS city,
  SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity
FROM WEATHER
WHERE
  timestamp >= NOW() - INTERVAL '1' DAY
  AND double1 > 0
GROUP BY t, city
ORDER BY t, avg_humidity DESC
```

This query first rounds the `timestamp` field to the nearest five minutes. Then, it groups by that field and city and calculates the average humidity in each city for a five minute period.

Refer to [Querying Workers Analytics Engine from Grafana](/analytics/analytics-engine/grafana/) for more details on how to create efficient Grafana queries against Workers Analytics Engine.

## Further reading

<DirectoryListing
folder="analytics/analytics-engine"
/>

---

# Querying from Grafana

URL: https://developers.cloudflare.com/analytics/analytics-engine/grafana/

Workers Analytics Engine is optimized for powering time series analytics that can be visualized using tools like Grafana. Every event written from the runtime is automatically populated with a `timestamp` field.

## Grafana plugin setup

We recommend the use of the [Altinity plugin for Clickhouse](https://grafana.com/grafana/plugins/vertamedia-clickhouse-datasource/) for querying Workers Analytics Engine from Grafana.

Configure the plugin as follows:

* URL: `https://api.cloudflare.com/client/v4/accounts/<account_id>/analytics_engine/sql`. Replace `<account_id>` with your 32 character account ID (available in the Cloudflare dashboard).
* Leave all auth settings off.
* Add a custom header with a name of `Authorization` and value set to `Bearer <token>`. Replace `<token>` with suitable API token string (refer to the [SQL API docs](/analytics/analytics-engine/sql-api/#authentication) for more information on this).
* No other options need to be set.

## Querying timeseries data

For use in a dashboard, you usually want to aggregate some metric per time interval. This can be achieved by rounding and then grouping by the `timestamp` field. The following query rounds and groups in this way, and then computes an average across each time interval whilst taking into account [sampling](/analytics/analytics-engine/sql-api/#sampling).

```sql
SELECT
    intDiv(toUInt32(timestamp), 60) * 60 AS t,
    blob1 AS label,
    SUM(_sample_interval * double1) / SUM(_sample_interval) AS average_metric
FROM dataset_name
WHERE 
    timestamp <= NOW() 
    AND timestamp > NOW() - INTERVAL '1' DAY
GROUP BY blob1, t
ORDER BY t
```

The Altinity plugin provides some useful macros that can simplify writing queries of this type. The macros require setting `Column:DateTime` to `timestamp` in the query builder, then they can be used like this:

```sql
SELECT
    $timeSeries AS t,
    blob1 AS label,
    SUM(_sample_interval * double1) / SUM(_sample_interval) AS average_metric
FROM dataset_name
WHERE $timeFilter
GROUP BY blob1, t
ORDER BY t
```

This query will automatically adjust the rounding time depending on the zoom level and filter to the correct time range that is currently being displayed.

---

# Workers Analytics Engine

URL: https://developers.cloudflare.com/analytics/analytics-engine/

import { LinkButton } from "~/components"

Workers Analytics Engine provides unlimited-cardinality analytics at scale, via [a built-in API](/analytics/analytics-engine/get-started/) to write data points from Workers, and a [SQL API](/analytics/analytics-engine/sql-api/) to query that data.

You can use Workers Analytics Engine to:

* Expose custom analytics to your own customers
* Build usage-based billing systems
* Understand the health of your service on a per-customer or per-user basis
* Add instrumentation to frequently called code paths, without impacting performance or overwhelming external analytics systems with events

 <LinkButton variant="primary" href="/analytics/analytics-engine/get-started/">Get started</LinkButton>

---

# Pricing

URL: https://developers.cloudflare.com/analytics/analytics-engine/pricing/

Workers Analytics Engine is priced based on two metrics — data points written, and read queries.

| Plan             | Data points written                                                  | Read queries                                                 |
| ---------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ |
| **Workers Paid** | 10 million included per month <br /> (+$0.25 per additional million) | 1 million included per month (+$1.00 per additional million) |
| **Workers Free** | 100,000 included per day                                             | 10,000 included per day                                      |

:::note[Pricing availability]

Currently, you will not be billed for your use of Workers Analytics Engine. Pricing information here is shared in advance, so that you can estimate what your costs will be once Cloudflare starts billing for usage in the coming months.

If you are an Enterprise customer, contact your account team for information about Workers Analytics Engine pricing and billing. 
:::

### Data points written

Every time you call [`writeDataPoint()`](/analytics/analytics-engine/get-started/#2-write-data-points-from-your-worker) in a Worker, this counts as one data point written.

Each data point written costs the same amount. There is no extra cost to add dimensions or cardinality, and no additional cost for writing more data in a single data point.

### Read queries

Every time you post to Workers Analytics Engine's [SQL API](/analytics/analytics-engine/sql-api/), this counts as one read query.

Each read query costs the same amount. There is no extra cost for more or less complex queries, and no extra cost for reading only a few rows of data versus many rows of data.

---

# Limits

URL: https://developers.cloudflare.com/analytics/analytics-engine/limits/

The following limits apply to Workers Analytics Engine:

* Analytics Engine will accept up to twenty blobs, twenty doubles, and one index per call to `writeDataPoint`.
* The total size of all blobs in a request must not exceed **16 KB**. The 16 KB size limit for the blobs field applies to **each individual data point**, regardless of how many are included in a single request using writeDataPoints().
* Each index must not be more than 96 bytes.
* You can write a maximum of 25 data points per Worker invocation (client HTTP request). Each call to `writeDataPoint` counts towards this limit.

## Data retention

Data written to Workers Analytics Engine is stored for three months.

Interested in longer retention periods? Join the `#analytics-engine` channel in the [Cloudflare Developers Discord](https://discord.cloudflare.com/) and tell us more about what you are building.

---

# Sampling with WAE

URL: https://developers.cloudflare.com/analytics/analytics-engine/sampling/

Workers Analytics Engine offers the ability to write an extensive amount of data and retrieve it quickly, at minimal or no cost. To facilitate writing large amounts of data at a reasonable cost, Workers Analytics Engine employs weighted adaptive [sampling](https://en.wikipedia.org/wiki/Sampling_\(statistics\)).

When utilizing sampling, you do not need every single data point to answer questions about a dataset. For a sufficiently large dataset, the [necessary sample size](https://select-statistics.co.uk/blog/importance-effect-sample-size/) does not depend on the size of the original population. Necessary sample size depends on the variance of your measure, the size of the subgroups you analyze, and how accurate your estimate must be.

The implication for Analytics Engine is that we can compress very large datasets into many fewer observations, yet still answer most queries with very high accuracy. This enables us to offer an analytics service that can measure very high rates of usage, with unbounded cardinality, at a low and predictable price.

At a high level, the way sampling works is:

1. At write time, we sample if data points are written too quickly into one index.
2. We sample again at query time if the query is too complex.

In the following sections, you will learn:

* [How sampling works](/analytics/analytics-engine/sampling/#how-sampling-works).
* [How to read sampled data](/analytics/analytics-engine/sampling/#how-to-read-sampled-data).
* [How is data sampled](/analytics/analytics-engine/sampling/#how-is-data-sampled).
* [How Adaptive Bit Rate Sampling works](/analytics/analytics-engine/sampling/#adaptive-bit-rate-sampling-at-read-time).
* [How to pick your index such that your data is sampled in a usable way](/analytics/analytics-engine/sampling/#how-to-select-an-index).

## How sampling works

Cloudflare's data sampling is similar to how online mapping services like Google Maps render maps at different zoom levels. When viewing satellite imagery of a whole continent, the mapping service provides appropriately sized images based on the user's screen and Internet speed.

![The image on the left shows a satellite view from OpenStreetMap. On the right, the same image is zoomed in. In these two images, each pixel represents the same area; however the image on the right has many fewer pixels.](~/assets/images/analytics/zoom-less-pixels.png)

Each pixel on the map represents a large area, such as several square kilometers. If a user tries to zoom in using a screenshot, the resulting image would be blurry. Instead, the mapping service selects higher-resolution images when a user zooms in on a specific city. The total number of pixels remains relatively constant, but each pixel now represents a smaller area, like a few square meters.

![Now the image on the right is of a much higher resolution. Each pixel represents a much smaller area; however, the total number of pixels in both images is roughly the same.](~/assets/images/analytics/zoom-more-pixels.png)

The key point is that the map's quality does not solely depend on the resolution or the area represented by each pixel. It is determined by the total number of pixels used to render the final view.

There are similarities between the how a mapping services handles resolution and Cloudflare Analytics delivers analytics using adaptive samples:

* **How data is stored**:
  * **Mapping service**: Imagery stored at different resolutions.
  * **Cloudflare Analytics**: Events stored at different sample rates.
* **How data is displayed to user**:
  * **Mapping service**: The total number of pixels is \~constant for a given screen size, regardless of the area selected.
  * **Cloudflare Analytics**: A similar number of events are read for each query, regardless of the size of the dataset or length of time selected.
* **How a resolution is selected**:
  * **Mapping service**: The area represented by each pixel will depend on the size of the map being rendered. In a more zoomed out map, each pixel will represent a larger area.
  * **Cloudflare Analytics**: The sample interval of each event in the result depends on the size of the underlying dataset and length of time selected. For a query over a large dataset or long length of time, each sampled event may stand in for many similar events.

## How to read sampled data

To effectively write queries and analyze the data, it is helpful to first learn how sampled data is read in Workers Analytics Engine.

In Workers Analytics Engine, every event is recorded with the `_sample_interval` field. The sample interval is the inverse of the sample rate. For example, if a one percent (1%) sample rate is applied, the `sample_interval` will be set to `100`.

Using the mapping example in simple terms, the sample interval represents the "number of unsampled data points" (kilometers or meters) that a given sampled data point (pixel) represents.

The sample interval is a property associated with each individual row stored in Workers Analytics Engine. Due to the implementation of equitable sampling, the sample interval can vary for each row. As a result, when querying the data, you need to consider the sample interval field. Simply multiplying the query result by a constant sampling factor is not sufficient.

Here are some examples of how to express some common queries over sampled data.

| Use case                           | Example without sampling | Example with sampling                                   |
| ---------------------------------- | ------------------------ | ------------------------------------------------------- |
| Count events in a dataset          | `count()`                | `sum(_sample_interval)`                                 |
| Sum a quantity, for example, bytes | `sum(bytes)`             | `sum(bytes * _sample_interval)`                         |
| Average a quantity                 | `avg(bytes)`             | `sum(bytes * _sample_interval) / sum(_sample_interval)` |
| Compute quantiles                  | `quantile(0.50)(bytes)`  | `quantileWeighted(0.50)(bytes, _sample_interval)`       |

Note that the accuracy of results is not determined by the sample interval, similar to the mapping analogy mentioned earlier. A high sample interval can still provide precise results. Instead, accuracy depends on the total number of data points queried and their distribution.

## How is data sampled

To determine the sample interval for each event, note that most analytics have some important type of subgroup that must be analyzed with accurate results. For example, you may want to analyze user usage or traffic to specific hostnames. Analytics Engine users can define these groups by populating the `index` field when writing an event. This allows for more targeted and precise analysis within the specified groups.

The next observation is that these index values likely have a very different number of events written to them. In fact, the usage of most web services follows a [Pareto distribution](https://en.wikipedia.org/wiki/Pareto_distribution), meaning that the top few users will account for the vast majority of the usage. Pareto distributions are common and look like this:

![In this graphic, each bar represents a user; the height of the bar is their total usage.](~/assets/images/analytics/total-usage.png)

If we took a [simple random sample](https://en.wikipedia.org/wiki/Simple_random_sample) of one percent (1%) of this data, and we applied that to the whole population, you may be able to track your largest customers accurately — but you would lose visibility into what your smaller customers are doing:

![The same graphic as above, but now based on a 1% sample of the data.](~/assets/images/analytics/sample-data.png)

Notice that the larger bars look more or less unchanged, and yet they are still quite accurate. But as you analyze smaller customers, results get [quantized](https://en.wikipedia.org/wiki/Quantization_\(signal_processing\)) and may even be rounded to 0 entirely.

This shows that while a one percent (1%) or even smaller sample of a large population may be sufficient, we may need to store a larger proportion of events for a small population to get accurate results.

We do this through a technique called equitable sampling. This means that we will equalize the number of events we store for each unique index value. For relatively uncommon index values, we may write all of the data points that we get via `writeDataPoint()`.  But if you write lots of data points to a single index value, we will start to sample.

Here is the same distribution, but now with (a simulation of) equitable sampling applied:

![This graphic shows the same population, but with equitable sampling.](~/assets/images/analytics/equitable-sampling.png)

You may notice that this graphic is very similar to the first graph. However, it only requires `<10%` of the data to be stored overall. The sample rate is actually much lower than `10%` for the larger series (that is, we store larger sample intervals), but the sample rate is higher for the smaller series.

Refer back to the mapping analogy above. Regardless of the map area shown, the total number of pixels in the map stays constant. Similarly, we always want to store a similar number of data points for each index value. However, the resolution of the map — how much area is represented by each pixel — will change based on the area being shown. Similarly here, the amount of data represented by each stored data point will vary, based on the total number of data points in the index.

## Adaptive Bit Rate Sampling at Read Time

Equitable sampling ensures that an equal amount of data is maintained for each index within a specific time frame. However, queries can vary significantly in the duration of time they target. Some queries may only require a 10-minute data snapshot, while others might need to analyze data spanning 10 weeks — a period which is 10,000 times longer.

To address this issue, we employ a method called [adaptive bit rate](https://blog.cloudflare.com/explaining-cloudflares-abr-analytics/) (ABR). With ABR, queries that cover longer time ranges will retrieve data from a higher sample interval, allowing them to be completed within a fixed time limit. In simpler terms, just as screen size or bandwidth is a fixed resource in our mapping analogy, the time required to complete a query is also fixed. Therefore, irrespective of the volume of data involved, we need to limit the total number of rows scanned to provide an answer to the query. This helps to ensure fairness: regardless of the size of the underlying dataset being queried, we ensure that all queries receive an equivalent share of the available computing time.

To achieve this, we store the data in multiple resolutions (that is, with different levels of detail, for instance, 100%, 10%, 1%) derived from the equitably sampled data. At query time, we select the most suitable data resolution to read based on the query's complexity. The query's complexity is determined by the number of rows to be retrieved and the probability of the query completing within a specified time limit of N seconds. By dynamically selecting the appropriate resolution, we optimize the query performance and ensure it stays within the allotted time budget.

ABR offers a significant advantage by enabling us to consistently provide query results within a fixed query budget, regardless of the data size or time span involved. This sets it apart from systems that struggle with timeouts, errors, or high costs when dealing with extensive datasets.

## How to select an index

In order to get accurate results with sampled data, select an appropriate value to use as your index. The index should match how users will query and view data. For example, if users frequently view data based on a specific device or hostname, it is recommended to incorporate those attributes into your index.

The index has the following properties, which are important to consider when choosing an index:

* Get accurate summary statistics about your entire dataset, across all index values.
* Get an accurate count of the number of unique values of your index.
* Get accurate summary statistics (for example, count, sum) within a particular index value.
* See the `Top N` values of specific fields that are not in your index.
* Filter on most fields.
* Run other aggregations like quantiles.

Some limitations and trade-offs to consider are:

* You may not be able to get accurate unique counts of fields that are not in your index.
  * For example, if you index on `hostname`, you may not be able to count the number of unique URLs.
* You may not be able to observe very rare values of fields not in the index.
  * For example, a particular URL for a hostname, if you index on host and have millions of unique URLs.
* You may not be able to run accurate queries across multiple indices at once.
  * For example, you may only be able to query for one host at a time (or all of them) and expect accurate results.
* There is no guarantee you can retrieve any one individual record.
* You cannot necessarily reconstruct exact sequences of events.

It is not recommended to write a unique index value on every row (like a UUID) for most use cases. While this will make it possible to retrieve individual data points very quickly, it will slow down most queries for aggregations and time series.

Refer to the Workers Analytics Engine FAQs, for common question about [Sampling](/analytics/faq/wae-faqs/#sampling).

---

# SQL API

URL: https://developers.cloudflare.com/analytics/analytics-engine/sql-api/

The Workers Analytics Engine SQL API is an HTTP API that allows executing SQL queries against your Workers Analytics Engine datasets.

The API is hosted at `https://api.cloudflare.com/client/v4/accounts/<account_id>/analytics_engine/sql`.

## Authentication

Authentication is done via bearer token. An `Authorization: Bearer <token>` header must be supplied with every request to the API.

Use the dashboard to create a token with permission to read analytics data on your account:

1. Visit the [API tokens](https://dash.cloudflare.com/profile/api-tokens) page in the Cloudflare dashboard.
2. Select **Create Token**.
3. Select **Create Custom Token**.
4. Complete the **Create Custom Token** form as follows:
   * Give your token a descriptive name.
   * For **Permissions** select *Account* | *Account Analytics* | *Read*
   * Optionally configure account and IP restrictions and TTL.
   * Submit and confirm the form to create the token.
5. Make a note of the token string.

## Querying the API

Submit the query text in the body of a `POST` request to the API address. The format of the data returned can be selected using the [`FORMAT` option](/analytics/analytics-engine/sql-reference/#format-clause) in your query.

You can use cURL to test the API as follows, replacing the `<account_id>` with your 32 character account ID (available in the dashboard) and the `<token>` with the token string you generated above.

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SELECT 'Hello Workers Analytics Engine' AS message"
```

If you have already published some data, you might try executing the following to confirm that the dataset has been created in the DB.

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SHOW TABLES"
```

Refer to the Workers Analytics Engine [SQL reference](/analytics/analytics-engine/sql-reference/), for the full supported query syntax.

## Table structure

A new table will automatically be created for each dataset once you start writing events to it from your worker.

The table will have the following columns:

| Name                         | Type     | Description                                                                                                                                                                                                                                          |
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dataset                      | string   | This column will contain the dataset name in every row.                                                                                                                                                                                              |
| timestamp                    | DateTime | The timestamp at which the event was logged in your worker.                                                                                                                                                                                          |
| \_sample\_interval           | integer  | In case that the data has been sampled, this column indicates what the sample rate is for this row (that is, how many rows of the original data are represented by this row). Refer to the [sampling](#sampling) section below for more information. |
| index1                       | string   | The index value that was logged with the event. The value in this column is used as the key for sampling.                                                                                                                                            |
| blob1<br/>...<br/>blob20     | string   | The blob values that were logged with the event.                                                                                                                                                                                                     |
| double1<br/>...<br/>double20 | double   | The double values that were logged with the event.                                                                                                                                                                                                   |

## Sampling

At very high volumes of data, Analytics Engine will downsample data in order to be able to maintain performance. Sampling can occur on write and on read.
Sampling is based on the index of your dataset so that only indexes that receive large numbers of events will be sampled. For example, if your worker serves multiple customers, you might consider making customer ID the index field. This would mean that if one customer starts making a high rate of requests then events from that customer could be sampled while other customers data remains unsampled.

We have tested this system of sampling over a number of years at Cloudflare and it has enabled us to scale our web analytics systems to very high throughput, while still providing statistically meaningful results irrespective of the amount of traffic a website receives.

The rate at which the data is sampled is exposed via the `_sample_interval` column. This means that if you are doing statistical analysis of your data, you may need to take this column into account. For example:

| Original query                 | Query taking into account sampling                                        |
| ------------------------------ | ------------------------------------------------------------------------- |
| `SELECT COUNT() FROM ... `     | `SELECT SUM(_sample_interval) FROM ...`                                   |
| `SELECT SUM(double1) FROM ...` | `SELECT SUM(_sample_interval * double1) FROM ...`                         |
| `SELECT AVG(double1) FROM ...` | `SELECT SUM(_sample_interval * double1) / SUM(_sample_interval) FROM ...` |

Additionally, the [QUANTILEWEIGHTED function](/analytics/analytics-engine/sql-reference/#quantileweighted) is designed to be used with sample interval as the third argument.

## Example queries

### Select data with column aliases

Column aliases can be used in queries to give names to the blobs and doubles in your dataset:

```sql
SELECT
    timestamp,
    blob1 AS location_id,
    double1 AS inside_temp,
    double2 AS outside_temp
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '1' DAY
```

### Aggregation taking into account sample interval

Calculate number of readings taken at each location in the last 7 days. In this case, we are grouping by the index field so an exact count can be calculated even in the case that the data has been sampled:

```sql
SELECT
    index1 AS location_id,
    SUM(_sample_interval) AS n_readings
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '7' DAY
GROUP BY index1
```

Calculate the average temperature over the last 7 days at each location. Sample interval is taken into account:

```sql
SELECT
    index1 AS location_id,
    SUM(_sample_interval * double1) / SUM(_sample_interval) AS average_temp
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '7' DAY
GROUP BY index1
```

---

# Querying from a Worker

URL: https://developers.cloudflare.com/analytics/analytics-engine/worker-querying/

import { WranglerConfig } from "~/components";

If you want to access Analytics Engine data from within a Worker you can use `fetch` to access the SQL API. The API can return JSON data that is easy to interact with in JavaScript.

## Authentication

In order that your Worker can authenticate with the API you will need your account ID and an API token.

- Your 32 character account ID can be obtained from the Cloudflare dashboard.
- An API token can also be generated in the dashboard. Refer to the [SQL API docs](/analytics/analytics-engine/sql-api/#authentication) for more information on this.

We recommend storing the account ID as an environment variable and the API token as a secret in your worker. This can be done through the dashboard or through Wrangler. Refer to the [Workers documentation](/workers/configuration/environment-variables/) for more details on this.

## Querying

Use the JavaScript `fetch` API as follows to execute a query:

```js
const query = "SELECT * FROM my_dataset";
const API = `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/analytics_engine/sql`;
const response = await fetch(API, {
	method: "POST",
	headers: {
		Authorization: `Bearer ${env.API_TOKEN}`,
	},
	body: query,
});
const responseJSON = await response.json();
```

The data will be returned in the format described in the [FORMAT section of the API docs](/analytics/analytics-engine/sql-reference/#json) allowing you to extract meta information about the names and types of returned columns in addition to the data itself and a row count.

## Example Worker

The following is a sample Worker which executes a query against a dataset of weather readings and displays minimum and maximum values for each city.

### Environment variable setup

First the environment variables are set up with the account ID and API token.

The account ID is set in the [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
[vars]
ACCOUNT_ID = "<account_id>"
```

</WranglerConfig>

The API_TOKEN can be set as a secret, using the wrangler command line tool, by running the following and entering your token string:

```sh
npx wrangler secret put API_TOKEN
```

### Worker script

The worker script itself executes a query and formats the result:

```js
export default {
	async fetch(request, env) {
		// This worker only responds to requests at the root.
		if (new URL(request.url).pathname != "/") {
			return new Response("Not found", { status: 404 });
		}

		// SQL string to be executed.
		const query = `
            SELECT
                blob1 AS city,
                max(double1) as max_temp,
                min(double1) as min_temp
            FROM weather
            WHERE timestamp > NOW() - INTERVAL '1' DAY
            GROUP BY city
            ORDER BY city`;

		// Build the API endpoint URL and make a POST request with the query string
		const API = `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/analytics_engine/sql`;
		const queryResponse = await fetch(API, {
			method: "POST",
			headers: {
				Authorization: `Bearer ${env.API_TOKEN}`,
			},
			body: query,
		});

		// The API will return a 200 status code if the query succeeded.
		// In case of failure we log the error message and return a failure message.
		if (queryResponse.status != 200) {
			console.error("Error querying:", await queryResponse.text());
			return new Response("An error occurred!", { status: 500 });
		}

		// Read the JSON data from the query response and render the data as HTML.
		const queryJSON = await queryResponse.json();
		return new Response(renderResponse(queryJSON.data), {
			headers: { "content-type": "text/html" },
		});
	},
};

// renderCity renders a table row as HTML from a data row.
function renderCity(row) {
	return `<tr><td>${row.city}</td><td>${row.min_temp}</td><td>${row.max_temp}</td></tr>`;
}

// renderResponse renders a simple HTML table of results.
function renderResponse(data) {
	return `<!DOCTYPE html>
<html>
    <body>
        <table>
            <tr><th>City</th><th>Min Temp</th><th>Max Temp</th></tr>
            ${data.map(renderCity).join("\n")}
        </table>
    </body>
<html>`;
}
```

---

# SQL Reference

URL: https://developers.cloudflare.com/analytics/analytics-engine/sql-reference/

## SHOW TABLES statement

`SHOW TABLES` can be used to list the tables on your account. The table name is the name you specified as `dataset` when configuring the workers binding (refer to [Get started with Workers Analytics Engine](/analytics/analytics-engine/get-started/), for more information). The table is automatically created when you write event data in your worker.

```sql
SHOW TABLES
[FORMAT <format>]
```

Refer to [FORMAT clause](#format-clause) for the available `FORMAT` options.

## SHOW TIMEZONES statement

`SHOW TIMEZONES` can be used to list all of the timezones supported by the SQL API. Most common timezones are supported.

```sql
SHOW TIMEZONES
[FORMAT <format>]
```

## SHOW TIMEZONE statement

`SHOW TIMEZONE` responds with the current default timezone in use by SQL API. This should always be `Etc/UTC`.

```sql
SHOW TIMEZONE
[FORMAT <format>]
```

## SELECT statement

`SELECT` is used to query tables.

Usage:

```sql
SELECT <expression_list>
[FROM <table>|(<subquery>)]
[WHERE <expression>]
[GROUP BY <expression>, ...]
[ORDER BY <expression_list>]
[LIMIT <n>|ALL]
[FORMAT <format>]
```

Below you can find the syntax of each clause. Refer to the [SQL API docs](/analytics/analytics-engine/sql-api/) for some example queries.

### SELECT clause

The `SELECT` clause specifies the list of columns to be included in the result.
Columns can be aliased using the `AS` keyword.

Usage:

```sql
SELECT <expression> [AS <alias>], ...
```

Examples:

```sql
-- return the named columns
SELECT blob2, double3

-- return all columns
SELECT *

-- alias columns to more descriptive names
SELECT
    blob2 AS probe_name,
    double3 AS temperature
```

Additionally, expressions using supported [functions](#supported-functions) and [operators](#supported-operators) can be used in place of column names:

```sql
SELECT
    blob2 AS probe_name,
    double3 AS temp_c,
    double3*1.8+32 AS temp_f -- compute a value

SELECT
    blob2 AS probe_name,
    if(double3 <= 0, 'FREEZING', 'NOT FREEZING') AS description -- use of functions

SELECT
    blob2 AS probe_name,
    avg(double3) AS avg_temp -- aggregation function
```

### FROM clause

`FROM` is used to specify the source of the data for the query.

Usage:

```sql
FROM <table_name>|(subquery)
```

Examples:

```sql
-- query data written to a workers dataset called "temperatures"
FROM temperatures

-- use a subquery to manipulate the table
FROM (
    SELECT
        blob1 AS probe_name,
        count() as num_readings
    FROM
        temperatures
    GROUP BY
        probe_name
)
```

Note that queries can only operate on a single table. `UNION`, `JOIN` etc. are not currently supported.

### WHERE clause

`WHERE` is used to filter the rows returned by a query.

Usage:

```sql
WHERE <condition>
```

`<condition>` can be any expression that evaluates to a boolean.

[Comparison operators](#comparison-operators) can be used to compare values and [boolean operators](#boolean-operators) can be used to combine conditions.

Expressions containing [functions](#supported-functions) and [operators](#supported-operators) are supported.

Examples:

```sql
-- simple comparisons
WHERE blob1 = 'test'
WHERE double1 = 4

-- inequalities
WHERE double1 > 4

-- use of operators (see below for supported operator list)
WHERE double1 + double2 > 4
WHERE blob1 = 'test1' OR blob2 = 'test2'

-- expression using inequalities, functions and operators
WHERE if(unit = 'f', (temp-32)/1.8, temp) <= 0
```

### GROUP BY clause

When using aggregate functions, `GROUP BY` specifies the groups over which the aggregation is run.

Usage:

```sql
GROUP BY <expression>, ...
```

For example. If you had a table of temperature readings:

```sql
-- return the average temperature for each probe
SELECT
    blob1 AS probe_name,
    avg(double1) AS average_temp
FROM temperature_readings
GROUP BY probe_name
```

In the usual case the `<expression>` can just be a column name but it is also possible to supply a complex expression here. Multiple expressions or column names can be supplied separated by commas.

### ORDER BY clause

`ORDER BY` can be used to control the order in which rows are returned.

Usage:

```sql
ORDER BY <expression> [ASC|DESC], ...
```

`<expression>` can just be a column name.

`ASC` or `DESC` determines if the ordering is ascending or descending. `ASC` is the default, and can be omitted.

Examples:

```sql
-- order by double2 then double3, both in ascending order
ORDER BY double2, double3

-- order by double2 in ascending order then double3 is descending order
ORDER BY double2, double3 DESC
```

### LIMIT clause

`LIMIT` specifies a maximum number of rows to return.

Usage:

```sql
LIMIT <n>|ALL
```

Supply the maximum number of rows to return or `ALL` for no restriction.

For example:

```sql
LIMIT 10 -- return at most 10 rows
```

### FORMAT clause

`FORMAT` controls how to the returned data is encoded.

Usage:

```sql
FORMAT [JSON|JSONEachRow|TabSeparated]
```

If no format clause is included then the default format of `JSON` will be used.

Override the default by setting a format. For example:

```sql
FORMAT JSONEachRow
```

The following formats are supported:

#### JSON

Data is returned as a single JSON object with schema data included:

```json
{
    "meta": [
        {
            "name": "<column 1 name>",
            "type": "<column 1 type>"
        },
        {
            "name": "<column 2 name>",
            "type": "<column 2 type>"
        },
        ...
    ],
    "data": [
        {
            "<column 1 name>": "<column 1 value>",
            "<column 2 name>": "<column 2 value>",
            ...
        },
        {
            "<column 1 name>": "<column 1 value>",
            "<column 2 name>": "<column 2 value>",
            ...
        },
        ...
    ],
    "rows": 10
}
```

#### JSONEachRow

Data is returned with a separate JSON object per row. Rows are newline separated and there is no header line or schema data:

```json
{"<column 1 name>": "<column 1 value>", "<column 2 name>": "<column 2 value>"}
{"<column 1 name>": "<column 1 value>", "<column 2 name>": "<column 2 value>"}
...
```

#### TabSeparated

Data is returned with newline separated rows. Columns are separated with tabs. There is no header.

```txt
column 1 value  column 2 value
column 1 value  column 2 value
...
```

## Supported functions

:::note

Note that function names are not case-sensitive, they can be used both in uppercase or in lowercase. 
:::

### count

Usage:

```sql
count()
count(DISTINCT column_name)
```

Count is an aggregation function that returns the number of rows in each group or results set.

Count can also be used to count the number of distinct (unique) values in each column:

Example:

```sql
-- return the total number of rows
count()
-- return the number of different values in the column
count(DISTINCT column_name)
```

### sum

Usage:

```sql
sum([DISTINCT] column_name)
```

Sum is an aggregation function that returns the sum of column values across all rows in each group or results set. Sum also supports `DISTINCT`, but in this case it will only sum the unique values in the column.

Example:

```sql
-- return the total cost of all items
sum(item_cost)
-- return the total of all unique item costs
sum(DISTINCT item_cost)
```

### avg

Usage:

```sql
avg([DISTINCT] column_name)
```

Avg is an aggregation function that returns the mean of column values across all rows in each group or results set. Avg also supports `DISTINCT`, but in this case it will only average the unique values in the column.

Example:

```sql
-- return the mean item cost
avg(item_cost)
-- return the mean of unique item costs
avg(DISTINCT item_cost)
```

### min

Usage:

```sql
min(column_name)
```

Min is an aggregation function that returns the minimum value of a column across all rows.

Example:

```sql
-- return the minimum item cost
min(item_cost)
```

### max

Usage:

```sql
max(column_name)
```

Max is an aggregation function that returns the maximum value of a column across all rows.

Example:

```sql
-- return the maximum item cost
max(item_cost)
```

### quantileWeighted

Usage:

```sql
quantileWeighted(q, column_name, weight_column_name)
```

`quantileWeighted` is an aggregation function that returns the value at the q<sup>th</sup> quantile in the named column across all rows in each group or results set. Each row will be weighted by the value in `weight_column_name`. Typically this would be `_sample_interval` (refer to [how sampling works](/analytics/analytics-engine/sql-api/#sampling), for more information).

Example:

```sql
-- estimate the median value of <double1>
quantileWeighted(0.5, double1, _sample_interval)

-- in a table of query times, estimate the 95th centile query time
quantileWeighted(0.95, query_time, _sample_interval)
```

### if

Usage:

```sql
if(<condition>, <true_expression>, <false_expression>)
```

Returns `<true_expression>` if `<condition>` evaluates to true, else returns `<false_expression>`.

Example:

```sql
if(temp > 20, 'It is warm', 'Bring a jumper')
```

### intDiv

Usage:

```sql
intDiv(a, b)
```

Divide a by b, rounding the answer down to the nearest whole number.

### toUInt32

Usage:

```sql
toUInt32(<expression>)
```

Converts any numeric expression, or expression resulting in a string representation of a decimal, into an unsigned 32 bit integer.

Behaviour for negative numbers is undefined.

### length

Usage:

```sql
length({string})
```

Returns the length of a string. This function is UTF-8 compatible.

Examples:

```sql
SELECT length('a string') AS s;
SELECT length(blob1) AS s FROM your_dataset;
```

### isEmpty

Usage:

```sql
isEmpty({string})
```

Returns a boolean saying whether the string was empty. This computation can also be done as a binary operation: `{string} = ''`.

Examples:

```sql
SELECT isEmpty('a string') AS b;
SELECT isEmpty(blob1) AS b FROM your_dataset;
```

### toLower

Usage:

```sql
toLower({string})
```

Returns the string converted to lowercase. This function is Unicode compatible. This may not be perfect for all languages and users with stringent needs, should do the operation in their own code.

Examples:

```sql
SELECT toLower('STRING TO DOWNCASE') AS s;
SELECT toLower(blob1) AS s FROM your_dataset;
```

### toUpper

Usage:

```sql
toUpper({string})
```

Returns the string converted to uppercase. This function is Unicode compatible. The results may not be perfect for all languages and users with strict needs. These users should do the operation in their own code.

Examples:

```sql
SELECT toUpper('string to uppercase') AS s;
SELECT toUpper(blob1) AS s FROM your_dataset;
```

### startsWith

Usage:

```sql
startsWith({string}, {string})
```

Returns a boolean of whether the first string has the second string at its start.

Examples:

```sql
SELECT startsWith('prefix ...', 'prefix') AS b;
SELECT startsWith(blob1, 'prefix') AS b FROM your_dataset;
```

### endsWith

Usage:

```sql
endsWith({string}, {string})
```

Returns a boolean of whether the first string contains the second string at its end.

Examples:

```sql
SELECT endsWith('prefix suffix', 'suffix') AS b;
SELECT endsWith(blob1, 'suffix') AS b FROM your_dataset;
```

### position

Usage:

```sql
position({needle:string} IN {haystack:string})
```

Returns the position of one string, `needle`, in another, `haystack`. In SQL, indexes are usually 1-based. That means that position returns `1` if your needle is at the start of the haystack. It only returns `0` if your string is not found.

Examples:

```sql
SELECT position(':' IN 'hello: world') AS p;
SELECT position(':' IN blob1) AS p FROM your_dataset;
```

### substring

Usage:

```sql
substring({string}, {offset:integer}[. {length:integer}])
```

Extracts part of a string, starting at the Unicode code point indicated by the offset and returning the number of code points requested by the length. As previously mentioned, in SQL, indexes are usually 1-based. That means that the offset provided to substring should be at least `1`.

Examples:

```sql
SELECT substring('hello world', 6) AS s;
SELECT substring('hello: world', 1, position(':' IN 'hello: world')-1) AS s;
```

### format

Usage:

```sql
format({string}[, ...])
```

This function supports formatting strings, integers, floats, datetimes, intervals, etc, except `NULL`. The function does not support literal `{` and `}` characters in the format string.

Examples:

```sql
SELECT format('blob1: {}', blob1) AS s FROM dataset;
```

See also: [formatDateTime](#formatdatetime)

### toDateTime

Usage:

```sql
toDateTime(<expression>[, 'timezone string'])
```

`toDateTime` converts an expression to a datetime. This function does not support ISO 8601-style timezones; if your time is not in UTC then you must provide the timezone using the second optional argument.

Examples:

```sql
-- double1 contains a unix timestamp in seconds
toDateTime(double1)

-- blob1 contains an datetime in the format 'YYYY-MM-DD hh:mm:ss'
toDateTime(blob1)

-- literal values:
toDateTime(355924804) -- unix timestamp
toDateTime('355924804') -- string containing unix timestamp
toDateTime('1981-04-12 12:00:04') -- string with datetime in 'YYYY-MM-DD hh:mm:ss' format

-- interpret a date relative to New York time
toDateTime('2022-12-01 16:17:00', 'America/New_York')
```

### now

Usage:

```sql
now()
```

Returns the current time as a DateTime.

### toUnixTimestamp

Usage:

```sql
toUnixTimestamp(<datetime>)
```

`toUnixTimestamp` converts a datetime into an integer unix timestamp.

Examples:

```sql
-- get the current unix timestamp
toUnixTimestamp(now())
```

### formatDateTime

Usage:

```sql
formatDateTime(<datetime expression>, <format string>[, <timezone string>])
```

`formatDateTime` prints a datetime as a string according to a provided format string. See
[ClickHouse's docs](https://clickhouse.com/docs/en/sql-reference/functions/date-time-functions/#formatdatetime)
for a list of supported formatting options.

Examples:

```sql
-- prints the current YYYY-MM-DD in UTC
formatDateTime(now(), '%Y-%m-%d')

-- prints YYYY-MM-DD in the datetime's timezone
formatDateTime(<a datetime with a timezone>, '%Y-%m-%d')
formatDateTime(toDateTime('2022-12-01 16:17:00', 'America/New_York'), '%Y-%m-%d')

-- prints YYYY-MM-DD in UTC
formatDateTime(<a datetime with a timezone>, '%Y-%m-%d', 'Etc/UTC')
formatDateTime(toDateTime('2022-12-01 16:17:00', 'America/New_York'), '%Y-%m-%d', 'Etc/UTC')
```

### toStartOfInterval

Usage:

```sql
toStartOfInterval(<datetime>, INTERVAL '<n>' <unit>[, <timezone string>])
```

`toStartOfInterval` rounds down a datetime to the nearest offset of a provided interval. This can
be useful for grouping data into equal-sized time ranges.

Examples:

```sql
-- round the current time down to the nearest 15 minutes
toStartOfInterval(now(), INTERVAL '15' MINUTE)

-- round a timestamp down to the day
toStartOfInterval(timestamp, INTERVAL '1' DAY)

-- count the number of datapoints filed in each hourly window
SELECT
  toStartOfInterval(timestamp, INTERVAL '1' HOUR) AS hour,
  sum(_sample_interval) AS count
FROM your_dataset
GROUP BY hour
ORDER BY hour ASC
```

### extract

Usage:

```sql
extract(<time unit> from <datetime>)
```

`extract` returns an integer number of time units from a datetime. It supports
`YEAR`, `MONTH`, `DAY`, `HOUR`, `MINUTE` and `SECOND`.

Examples:

```sql
-- extract the number of seconds from a timestamp (returns 15 in this example)
extract(SECOND from toDateTime('2022-06-06 11:30:15'))
```

## Supported operators

The following operators are supported:

### Arithmetic operators

| Operator | Description    |
| -------- | -------------- |
| `+`      | addition       |
| `-`      | subtraction    |
| `*`      | multiplication |
| `/`      | division       |
| `%`      | modulus        |

### Comparison operators

| Operator     | Description                                                                                                   |
| ------------ | ------------------------------------------------------------------------------------------------------------- |
| `=`          | equals                                                                                                        |
| `<`          | less than                                                                                                     |
| `>`          | greater than                                                                                                  |
| `<=`         | less than or equal to                                                                                         |
| `>=`         | greater than or equal to                                                                                      |
| `<>` or `!=` | not equal                                                                                                     |
| `IN`         | true if the preceding expression's value is in the list<br/>`column IN ('a', 'list', 'of', 'values')`         |
| `NOT IN`     | true if the preceding expression's value is not in the list<br/>`column NOT IN ('a', 'list', 'of', 'values')` |

We also support the `BETWEEN` operator for checking a value is in an inclusive range: `a [NOT] BETWEEN b AND c`.

### Boolean operators

| Operator | Description                                                          |
| -------- | -------------------------------------------------------------------- |
| `AND`    | boolean "AND" (true if both sides are true)                          |
| `OR`     | boolean "OR" (true if either side or both sides are true)            |
| `NOT`    | boolean "NOT" (true if following expression is false and visa-versa) |

### Unary operators

| Operator | Description                            |
| -------- | -------------------------------------- |
| `-`      | negation operator (for example, `-42`) |

## Literals

| Type          | Syntax                                                                                                   |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| integer       | `42`, `-42`                                                                                              |
| double        | `4.2`, `-4.2`                                                                                            |
| string        | `'so long and thanks for all the fish'`                                                                  |
| boolean       | `true` or `false`                                                                                        |
| time interval | `INTERVAL '42' DAY`<br/>Intervals of `YEAR`, `MONTH`, `DAY`, `HOUR`, `MINUTE` and `SECOND` are supported |

---

# How AutoRAG works

URL: https://developers.cloudflare.com/autorag/concepts/how-autorag-works/

AutoRAG sets up and manages your RAG pipeline for you. It connects the tools needed for indexing, retrieval, and generation, and keeps everything up to date by syncing with your data with the index regularly. Once set up, AutoRAG indexes your content in the background and responds to queries in real time.

AutoRAG consists of two core processes:

- **Indexing:** An asynchronous background process that monitors your data source for changes and converts your data into vectors for search.
- **Querying:** A synchronous process triggered by user queries. It retrieves the most relevant content and generates context-aware responses.

## How indexing works

Indexing begins automatically when you create an AutoRAG instance and connect a data source.

Here is what happens during indexing:

1. **Data ingestion:** AutoRAG reads from your connected data source.
2. **Markdown conversion:** AutoRAG uses [Workers AI’s Markdown Conversion](/workers-ai/features/markdown-conversion/) to convert [supported data types](/autorag/configuration/data-source/) into structured Markdown. This ensures consistency across diverse file types. For images, Workers AI is used to perform object detection followed by vision-to-language transformation to convert images into Markdown text.
3. **Chunking:** The extracted text is [chunked](/autorag/configuration/chunking/) into smaller pieces to improve retrieval granularity.
4. **Embedding:** Each chunk is embedded using Workers AI’s embedding model to transform the content into vectors.
5. **Vector storage:** The resulting vectors, along with metadata like file name, are stored in a the [Vectorize](/vectorize/) database created on your Cloudflare account.

After the initial data set is indexed, AutoRAG will regularly check for updates in your data source (e.g. additions, updates, or deletes) and index changes to ensure your vector database is up to date.

![Indexing](~/assets/images/autorag/indexing.png)

## How querying works

Once indexing is complete, AutoRAG is ready to respond to end-user queries in real time.

Here is how the querying pipeline works:

1. **Receive query from AutoRAG API:** The query workflow begins when you send a request to either the AutoRAG’s [AI Search](/autorag/usage/rest-api/#ai-search) or [Search](/autorag/usage/rest-api/#search) endpoints.
2. **Query rewriting (optional):** AutoRAG provides the option to [rewrite the input query](/autorag/configuration/query-rewriting/) using one of Workers AI’s LLMs to improve retrieval quality by transforming the original query into a more effective search query.
3. **Embedding the query:** The rewritten (or original) query is transformed into a vector via the same embedding model used to embed your data so that it can be compared against your vectorized data to find the most relevant matches.
4. **Querying Vectorize index:** The query vector is [queried](/vectorize/best-practices/query-vectors/) against stored vectors in the associated Vectorize database for your AutoRAG.
5. **Content retrieval:** Vectorize returns the metadata of the most relevant chunks, and the original content is retrieved from the R2 bucket. If you are using the Search endpoint, the content is returned at this point.
6. **Response generation:** If you are using the AI Search endpoint, then a text-generation model from Workers AI is used to generate a response using the retrieved content and the original user’s query, combined via a [system prompt](/autorag/configuration/system-prompt/). The context-aware response from the model is returned.

![Querying](~/assets/images/autorag/querying.png)

---

# Concepts

URL: https://developers.cloudflare.com/autorag/concepts/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# What is RAG

URL: https://developers.cloudflare.com/autorag/concepts/what-is-rag/

Retrieval-Augmented Generation (RAG) is a way to use your own data with a large language model (LLM). Instead of relying only on what the model was trained on, RAG searches for relevant information from your data source and uses it to help answer questions.

## How RAG works

Here’s a simplified overview of the RAG pipeline:

1. **Indexing:** Your content (e.g. docs, wikis, product information) is split into smaller chunks and converted into vectors using an embedding model. These vectors are stored in a vector database.
2. **Retrieval:** When a user asks a question, it’s also embedded into a vector and used to find the most relevant chunks from the vector database.
3. **Generation:** The retrieved content and the user’s original question are combined into a single prompt. An LLM uses that prompt to generate a response.

The resulting response should be accurate, relevant, and based on your own data.

![What is RAG](~/assets/images/autorag/RAG.png)

:::note[How does AutoRAG work]
To learn more details about how AutoRAG uses RAG under the hood, reference [How AutoRAG works](/autorag/concepts/how-autorag-works/).
:::

## Why use RAG?

RAG lets you bring your own data into LLM generation without retraining or fine-tuning a model. It improves both accuracy and trust by retrieving relevant content at query time and using that as the basis for a response.

Benefits of using RAG:

- **Accurate and current answers:** Responses are based on your latest content, not outdated training data.
- **Control over information sources:** You define the knowledge base so answers come from content you trust.
- **Fewer hallucinations:** Responses are grounded in real, retrieved data, reducing made-up or misleading answers.
- **No model training required:** You can get high-quality results without building or fine-tuning your own LLM which can be time consuming and costly.

RAG is ideal for building AI-powered apps like:

- AI assistants for internal knowledge
- Support chatbots connected to your latest content
- Enterprise search across documentation and files

---

# Similarity cache

URL: https://developers.cloudflare.com/autorag/configuration/cache/

Similarity-based caching in AutoRAG lets you serve responses from Cloudflare’s cache for queries that are similar to previous requests, rather than creating new, unique responses for every request. This speeds up response times and cuts costs by reusing answers for questions that are close in meaning.

## How It Works

Unlike with basic caching, which creates a new response with every request, this is what happens when a request is received using similarity-based caching:

1. AutoRAG checks if a _similar_ prompt (based on your chosen threshold) has been answered before.
2. If a match is found, it returns the cached response instantly.
3. If no match is found, it generates a new response and caches it.

To see if a response came from the cache, check the `cf-aig-cache-status` header: `HIT` for cached and `MISS` for new.

## What to consider when using similarity cache

Consider these behaviors when using similarity caching:

- **Volatile Cache**: If two similar requests hit at the same time, the first might not cache in time for the second to use it, resulting in a `MISS`.
- **30-Day Cache**: Cached responses last 30 days, then expire automatically. No custom durations for now.
- **Data Dependency**: Cached responses are tied to specific document chunks. If those chunks change or get deleted, the cache clears to keep answers fresh.

## How similarity matching works

AutoRAG’s similarity cache uses **MinHash and Locality-Sensitive Hashing (LSH)** to find and reuse responses for prompts that are worded similarly.

Here’s how it works when a new prompt comes in:

1. The prompt is split into small overlapping chunks of words (called shingles), like “what’s the” or “the weather.”
2. These shingles are turned into a “fingerprint” using MinHash. The more overlap two prompts have, the more similar their fingerprints will be.
3. Fingerprints are placed into LSH buckets, which help AutoRAG quickly find similar prompts without comparing every single one.
4. If a past prompt in the same bucket is similar enough (based on your configured threshold), AutoRAG reuses its cached response.

## Choosing a threshold

The similarity threshold decides how close two prompts need to be to reuse a cached response. Here are the available thresholds:

| Threshold        | Description                 | Example Match                                                                   |
| ---------------- | --------------------------- | ------------------------------------------------------------------------------- |
| Exact            | Near-identical matches only | "What’s the weather like today?" matches with "What is the weather like today?" |
| Strong (default) | High semantic similarity    | "What’s the weather like today?" matches with "How’s the weather today?"        |
| Broad            | Moderate match, more hits   | "What’s the weather like today?" matches with "Tell me today’s weather"         |
| Loose            | Low similarity, max reuse   | "What’s the weather like today?" matches with "Give me the forecast"            |

Test these values to see which works best with your [RAG application](/autorag/).

---

# Chunking

URL: https://developers.cloudflare.com/autorag/configuration/chunking/

Chunking is the process of splitting large data into smaller segments before embedding them for search. AutoRAG uses **recursive chunking**, which breaks your content at natural boundaries (like paragraphs or sentences), and then further splits it if the chunks are too large.

## What is recursive chunking

Recursive chunking tries to keep chunks meaningful by:

- **Splitting at natural boundaries:** like paragraphs, then sentences.
- **Checking the size:** if a chunk is too long (based on token count), it’s split again into smaller parts.

This way, chunks are easy to embed and retrieve, without cutting off thoughts mid-sentence.

## Chunking controls

AutoRAG exposes two parameters to help you control chunking behavior:

- **Chunk size**: The number of tokens per chunk.
  - Minimum: `64`
  - Maximum: `512`
- **Chunk overlap**: The percentage of overlapping tokens between adjacent chunks.
  - Minimum: `0%`
  - Maximum: `30%`

These settings apply during the indexing step, before your data is embedded and stored in Vectorize.

## Choosing chunk size and overlap

Chunking affects both how your content is retrieved and how much context is passed into the generation model. Try out this external [chunk visualizer tool](https://huggingface.co/spaces/m-ric/chunk_visualizer) to help understand how different chunk settings could look.

For chunk size, consider how:

- **Smaller chunks** create more precise vector matches, but may split relevant ideas across multiple chunks.
- **Larger chunks** retain more context, but may dilute relevance and reduce retrieval precision.

For chunk overlap, consider how:

- **More overlap** helps preserve continuity across boundaries, especially in flowing or narrative content.
- **Less overlap** reduces indexing time and cost, but can miss context if key terms are split between chunks.

### Additional considerations:

- **Vector index size:** Smaller chunk sizes produce more chunks and more total vectors. Refer to the [Vectorize limits](/vectorize/platform/limits/) to ensure your configuration stays within the maximum allowed vectors per index.
- **Generation model context window:** Generation models have a limited context window that must fit all retrieved chunks (`topK` × `chunk size`), the user query, and the model’s output. Be careful with large chunks or high topK values to avoid context overflows.
- **Cost and performance:** Larger chunks and higher topK settings result in more tokens passed to the model, which can increase latency and cost. You can monitor this usage in [AI Gateway](/ai-gateway/).

---

# Data source

URL: https://developers.cloudflare.com/autorag/configuration/data-source/

import { Render } from "~/components";

AutoRAG currently supports Cloudflare R2 as the data source for storing your knowledge base. To get started, [configure an R2 bucket](/r2/get-started/) containing your data.

AutoRAG will automatically scan and process supported files stored in that bucket. Files that are unsupported or exceed the size limit will be skipped during indexing and logged as errors.

## File limits

AutoRAG has different file size limits depending on the file type:

- **Plain text files:** Up to **4 MB**
- **Rich format files:** Up to **4 MB**

Files that exceed these limits will not be indexed and will show up in the error logs.

## File types

AutoRAG can ingest a variety of different file types to power your RAG. The following plain text files and rich format files are supported.

### Plain text file types

AutoRAG supports the following plain text file types:

| Format     | File extensions                                                                | Mime Type                                                             |
| ---------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| Text       | `.txt`, `.rst`                                                                 | `text/plain`                                                          |
| Log        | `.log`                                                                         | `text/plain`                                                          |
| Config     | `.ini`, `.conf`, `.env`, `.properties`, `.gitignore`, `.editorconfig`, `.toml` | `text/plain`, `text/toml`                                             |
| Markdown   | `.markdown`, `.md`, `.mdx`                                                     | `text/markdown`                                                       |
| LaTeX      | `.tex`, `.latex`                                                               | `application/x-tex`, `application/x-latex`                            |
| Script     | `.sh`, `.bat` , `.ps1`                                                         | `application/x-sh` , `application/x-msdos-batch`, `text/x-powershell` |
| SGML       | `.sgml`                                                                        | `text/sgml`                                                           |
| JSON       | `.json`                                                                        | `application/json`                                                    |
| YAML       | `.yaml`, `.yml`                                                                | `application/x-yaml`                                                  |
| CSS        | `.css`                                                                         | `text/css`                                                            |
| JavaScript | `.js`                                                                          | `application/javascript`                                              |
| PHP        | `.php`                                                                         | `application/x-httpd-php`                                             |
| Python     | `.py`                                                                          | `text/x-python`                                                       |
| Ruby       | `.rb`                                                                          | `text/x-ruby`                                                         |
| Java       | `.java`                                                                        | `text/x-java-source`                                                  |
| C          | `.c`                                                                           | `text/x-c`                                                            |
| C++        | `.cpp`, `.cxx`                                                                 | `text/x-c++`                                                          |
| C Header   | `.h`, `.hpp`                                                                   | `text/x-c-header`                                                     |
| Go         | `.go`                                                                          | `text/x-go`                                                           |
| Rust       | `.rs`                                                                          | `text/rust`                                                           |
| Swift      | `.swift`                                                                       | `text/swift`                                                          |
| Dart       | `.dart`                                                                        | `text/dart`                                                           |

### Rich format file types

AutoRAG uses [Markdown Conversion](/workers-ai/features/markdown-conversion/) to convert rich format files to markdown. The following table lists the supported formats that will be converted to Markdown:

<Render file="markdown-conversion-support" product="workers-ai" />

---

# Configuration

URL: https://developers.cloudflare.com/autorag/configuration/

import { MetaInfo, Type } from "~/components";

When creating an AutoRAG instance, you can customize how your RAG pipeline ingests, processes, and responds to data using a set of configuration options. Some settings can be updated after the instance is created, while others are fixed at creation time.

The table below lists all available configuration options:

| Configuration                                                                | Editable after creation | Description                                                                                |
| ---------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
| [Data source](/autorag/configuration/data-source/)                           | no                      | The source where your knowledge base is stored                                             |
| [Chunk size](/autorag/configuration/chunking/)                               | yes                     | Number of tokens per chunk                                                                 |
| [Chunk overlap](/autorag/configuration/chunking/)                            | yes                     | Number of overlapping tokens between chunks                                                |
| [Embedding model](/autorag/configuration/models/)                            | no                      | Model used to generate vector embeddings                                                   |
| [Query rewrite](/autorag/configuration/query-rewriting/)                     | yes                     | Enable or disable query rewriting before retrieval                                         |
| [Query rewrite model](/autorag/configuration/models/)                        | yes                     | Model used for query rewriting                                                             |
| [Query rewrite system prompt](/autorag/configuration/system-prompt/)         | yes                     | Custom system prompt to guide query rewriting behavior                                     |
| [Match threshold](/autorag/configuration/retrieval-configuration/)           | yes                     | Minimum similarity score required for a vector match                                       |
| [Maximum number of results](/autorag/configuration/retrieval-configuration/) | yes                     | Maximum number of vector matches returned (`top_k`)                                        |
| [Generation model](/autorag/configuration/models/)                           | yes                     | Model used to generate the final response                                                  |
| [Generation system prompt](/autorag/configuration/system-prompt/)            | yes                     | Custom system prompt to guide response generation                                          |
| [Similarity caching](/autorag/configuration/cache/)                          | yes                     | Enable or disable caching of responses for similar (not just exact) prompts                |
| [Similarity caching threshold](/autorag/configuration/cache/)                | yes                     | Controls how similar a new prompt must be to a previous one to reuse its cached response   |
| [AI Gateway](/ai-gateway)                                                    | yes                     | AI Gateway for monitoring and controlling model usage                                      |
| AutoRAG name                                                                 | no                      | Name of your AutoRAG instance                                                              |
| Service API token                                                            | yes                     | API token granted to AutoRAG to give it permission to configure resources on your account. |

:::note[API token]
The Service API token is different from the AutoRAG API token that you can make to interact with your AutoRAG. The Service API token is only used by AutoRAG to get permissions to configure resources on your account.
:::

---

# Indexing

URL: https://developers.cloudflare.com/autorag/configuration/indexing/

AutoRAG automatically indexes your data into vector embeddings optimized for semantic search. Once a data source is connected, indexing runs continuously in the background to keep your knowledge base fresh and queryable.

## Jobs

AutoRAG automatically monitors your data source for updates and reindexes your content **every 4 hours**. During each cycle, only new or modified files are reprocessed to keep your Vectorize index up to date.

## Controls

You can control indexing behavior through the following actions on the dashboard:

- **Sync Index**: Force AutoRAG to scan your data source for new or modified files and initiate an indexing job to update the associated Vectorize index. A new indexing job can be initiated every 5 minutes.
- **Pause Indexing**: Temporarily stop all scheduled indexing checks and reprocessing. Useful for debugging or freezing your knowledge base.

## Performance

AutoRAG processes files in parallel for efficient indexing. The total time to index depends on the number and type of files in your data source.

Factors that affect performance include:

- Total number of files and their sizes
- File formats (for example, images take longer than plain text)
- Latency of Workers AI models used for embedding and image processing

## Best practices

To ensure smooth and reliable indexing:

- Make sure your files are within the [**size limit**](/autorag/platform/limits-pricing/#limits) and in a supported format to avoid being skipped.
- Keep your Service API token valid to prevent indexing failures.
- Regularly clean up outdated or unnecessary content in your knowledge base to avoid hitting [Vectorize index limits](/vectorize/platform/limits/).

---

# Models

URL: https://developers.cloudflare.com/autorag/configuration/models/

AutoRAG uses models at multiple steps of the RAG pipeline. You can configure which models are used, or let AutoRAG automatically select defaults optimized for general use.

## Models used

AutoRAG leverages Workers AI models in the following stages:

- **Image to markdown conversion (if images are in data source)**: Converts image content to Markdown using object detection and captioning models.
- **Embedding**: Transforms your documents and queries into vector representations for semantic search.
- **Query rewriting (optional)**: Reformulates the user’s query to improve retrieval accuracy.
- **Generation**: Produces the final response from retrieved context.

## Model providers

AutoRAG currently only supports [Workers AI](/workers-ai/) as the model provider. Usage of models through AutoRAG contributes to your Workers AI usage and is billed as part of your account.

If you have connected your project to [AI Gateway](/ai-gateway), all model calls triggered by AutoRAG can be tracked in AI Gateway. This gives you full visibility into inputs, outputs, latency, and usage patterns.

## Choosing a model

When configuring your AutoRAG instance, you can specify the exact model to use for each step of embedding, rewriting, and generation. You can find available models that can be used with AutoRAG in the **Settings** of your AutoRAG.

:::note
AutoRAG supports a subset of Workers AI models that have been selected to provide the best experience for RAG.
:::

### Smart default

If you choose **Smart Default** in your model selection, then AutoRAG will select a Cloudflare recommended model. These defaults may change over time as Cloudflare evaluates and updates model choices. You can switch to explicit model configuration at any time by visiting **Settings**.

### Per-request generation model override

While the generation model can be set globally at the AutoRAG instance level, you can also override it on a per-request basis in the [AI Search API](/autorag/usage/rest-api/#ai-search). This is useful if your [RAG application](/autorag/) requires dynamic selection of generation models based on context or user preferences.

---

# Metadata

URL: https://developers.cloudflare.com/autorag/configuration/metadata/

import { FileTree } from "~/components"

Use metadata to filter documents before retrieval and provide context to guide AI responses. This page covers how to apply filters and attach optional context metadata to your files.

## Metadata filtering
Metadata filtering narrows down search results based on metadata, so only relevant content is retrieved. The filter narrows down results prior to retrieval, so that you only query the scope of documents that matter.

Here is an example of metadata filtering using [Workers Binding](/autorag/usage/workers-binding/) but it can be easily adapted to use the [REST API](/autorag/usage/rest-api/) instead.

```js
const answer = await env.AI.autorag("my-autorag").search({
	query: "How do I train a llama to deliver coffee?",
	filters: {
		type: "and",
		filters: [
			{
				type: "eq",
				key: "folder",
				value: "llama/logistics/",
			},
			{
				type: "gte",
				key: "timestamp",
				value: "1735689600000", // unix timestamp for 2025-01-01
			},
		],
	},
});
```

### Metadata attributes

| Attribute |  Description | Example |
| --- | --- | --- |
| `filename` | The name of the file. | `dog.png` or `animals/mammals/cat.png` |
| `folder` | The folder or prefix to the object. | For the object `animals/mammals/cat.png`, the folder is `animals/mammals/` |
| `timestamp` | The timestamp for when the object was last modified. Comparisons are supported using a 13-digit Unix timestamp (milliseconds), but values will be rounded down to 10 digits (seconds). | The timestamp `2025-01-01 00:00:00.999 UTC` is `1735689600999` and it will be rounded down to `1735689600000`, corresponding to `2025-01-01 00:00:00 UTC` |

### Filter schema

You can create simple comparison filters or an array of comparison filters using a compound filter.

#### Comparison filter

You can compare a metadata attribute (for example, `folder` or `timestamp`) with a target value using a comparison filter.

```js
filters: {
  type: "operator",
  key: "metadata_attribute",
  value: "target_value"
}
```

The available operators for the comparison are:

| Operator | Description               |
| -------- | ------------------------- |
| `eq`     | Equals                    |
| `ne`     | Not equals                |
| `gt`     | Greater than              |
| `gte`    | Greater than or equals to |
| `lt`     | Less than                 |
| `lte`    | Less than or equals to    |

#### Compound filter

You can use a compound filter to combine multiple comparison filters with a logical operator.

```js
filters: {
  type: "compound_operator",
  filters: [...]
}
```

The available compound operators are: `and`, `or`.

Note the following limitations with the compound operators:

- No nesting combinations of `and`'s and `or`'s, meaning you can only pick 1 `and` or 1 `or`.
- When using `or`:
  - Only the `eq` operator is allowed.
  - All conditions must filter on the **same key** (for example, all on `folder`)

#### "Starts with" filter for folders

You can use "starts with" filtering on the `folder` metadata attribute to search for all files and subfolders within a specific path.

For example, consider this file structure:

<FileTree>
- customer-a
  - profile.md
  - contracts
    - property
      - contract-1.pdf
</FileTree>

If you were to filter using an `eq` (equals) operator with `value: "customer-a/"`, it would only match files directly within that folder, like `profile.md`. It would not include files in subfolders like `customer-a/contracts/`.

To recursively filter for all items starting with the path `customer-a/`, you can use the following compound filter:

```js
filters: {
    type: "and",
    filters: [
      {
        type: "gt",
        key: "folder",
        value: "customer-a//",
      },
      {
        type: "lte",
        key: "folder",
        value: "customer-a/z",
      },
    ],
  },
```

This filter identifies paths starting with `customer-a/` by using:

- The `and` condition to combine the effects of the `gt` and `lte` conditions.
- The `gt` condition to include paths greater than the `/` ASCII character.
- The `lte` condition to include paths less than and including the lower case `z` ASCII character.

Together, these conditions effectively select paths that begin with the provided path value.

## Add `context` field to guide AI Search
You can optionally include a custom metadata field named `context` when uploading an object to your R2 bucket.

The `context` field is attached to each chunk and passed to the LLM during an `/ai-search` query. It does not affect retrieval but helps the LLM interpret and frame the answer.

The field can be used for providing document summaries, source links, or custom instructions without modifying the file content.

You can add [custom metadata](/r2/api/workers/workers-api-reference/#r2putoptions) to an object in the `/PUT` operation when uploading the object to your R2 bucket. For example if you are using the [Workers binding with R2](/r2/api/workers/workers-api-usage/):

```javascript
await env.MY_BUCKET.put("cat.png", file, {
  customMetadata: {
    context: "This is a picture of Joe's cat. His name is Max."
  }
});
```

During `/ai-search`, this context appears in the response under `attributes.file.context`, and is included in the data passed to the LLM for generating a response.

## Response

You can see the metadata attributes of your retrieved data in the response under the property `attributes` for each retrieved chunk. For example:

```js
"data": [
  {
    "file_id": "llama001",
    "filename": "llama/logistics/llama-logistics.md",
    "score": 0.45,
    "attributes": {
      "timestamp": 1735689600000,   // unix timestamp for 2025-01-01
      "folder": "llama/logistics/",
      "file": {
        "url": "www.llamasarethebest.com/logistics"
        "context": "This file contains information about how llamas can logistically deliver coffee."
      }
    },
    "content": [
      {
        "id": "llama001",
        "type": "text",
        "text": "Llamas can carry 3 drinks max."
      }
    ]
  }
]
```

---

# Retrieval configuration

URL: https://developers.cloudflare.com/autorag/configuration/retrieval-configuration/

AutoRAG allows you to configure how content is retrieved from your vector index and used to generate a final response. Two options control this behavior:

- **Match threshold**: Minimum similarity score required for a vector match to be considered relevant.
- **Maximum number of results**: Maximum number of top-matching results to return (`top_k`).

AutoRAG uses the [`query()`](/vectorize/best-practices/query-vectors/) method from [Vectorize](/vectorize/) to perform semantic search. This function compares the embedded query vector against the stored vectors in your index and returns the most similar results.

## Match threshold

The `match_threshold` sets the minimum similarity score (for example, cosine similarity) that a document chunk must meet to be included in the results. Threshold values range from `0` to `1`.

- A higher threshold means stricter filtering, returning only highly similar matches.
- A lower threshold allows broader matches, increasing recall but possibly reducing precision.

## Maximum number of results

This setting controls the number of top-matching chunks returned by Vectorize after filtering by similarity score. It corresponds to the `topK` parameter in `query()`. The maximum allowed value is 50.

- Use a higher value if you want to synthesize across multiple documents. However, providing more input to the model can increase latency and cost.
- Use a lower value if you prefer concise answers with minimal context.

## How they work together

AutoRAG's retrieval step follows this sequence:

1. Your query is embedded using the configured Workers AI model.
2. `query()` is called to search the Vectorize index, with `topK` set to the `maximum_number_of_results`.
3. Results are filtered using the `match_threshold`.
4. The filtered results are passed into the generation step as context.

If no results meet the threshold, AutoRAG will not generate a response.

## Configuration

These values can be configured at the AutoRAG instance level or overridden on a per-request basis using the [REST API](/autorag/usage/rest-api/) or the [Workers Binding](/autorag/usage/workers-binding/).

Use the parameters `match_threshold` and `max_num_results` to customize retrieval behavior per request.

---

# Query rewriting

URL: https://developers.cloudflare.com/autorag/configuration/query-rewriting/

Query rewriting is an optional step in the AutoRAG pipeline that improves retrieval quality by transforming the original user query into a more effective search query.

Instead of embedding the raw user input directly, AutoRAG can use a large language model (LLM) to rewrite the query based on a system prompt. The rewritten query is then used to perform the vector search.

## Why use query rewriting?

The wording of a user’s question may not match how your documents are written. Query rewriting helps bridge this gap by:

- Rephrasing informal or vague queries into precise, information-dense terms
- Adding synonyms or related keywords
- Removing filler words or irrelevant details
- Incorporating domain-specific terminology

This leads to more relevant vector matches which improves the accuracy of the final generated response.

## Example

**Original query:** `how do i make this work when my api call keeps failing?`

**Rewritten query:** `API call failure troubleshooting authentication headers rate limiting network timeout 500 error`

In this example, the original query is conversational and vague. The rewritten version extracts the core problem (API call failure) and expands it with relevant technical terms and likely causes. These terms are much more likely to appear in documentation or logs, improving semantic matching during vector search.

## How it works

If query rewriting is enabled, AutoRAG performs the following:

1. Sends the **original user query** and the **query rewrite system prompt** to the configured LLM
2. Receives the **rewritten query** from the model
3. Embeds the rewritten query using the selected embedding model
4. Performs vector search in your AutoRAG’s Vectorize index

For details on how to guide model behavior during this step, see the [system prompt](/autorag/configuration/system-prompt/) documentation.

---

# Bring your own generation model

URL: https://developers.cloudflare.com/autorag/how-to/bring-your-own-generation-model/

import {
	Badge,
	Description,
	Render,
	TabItem,
	Tabs,
	WranglerConfig,
	MetaInfo,
	Type,
} from "~/components";

When using `AI Search`, AutoRAG leverages a Workers AI model to generate the response. If you want to use a model outside of Workers AI, you can use AutoRAG for search while leveraging a model outside of Workers AI to generate responses.

Here is an example of how you can use an OpenAI model to generate your responses. This example uses [Workers Binding](/autorag/usage/workers-binding/), but can be easily adapted to use the [REST API](/autorag/usage/rest-api/) instead.

```ts
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

export interface Env {
	AI: Ai;
	OPENAI_API_KEY: string;
}

export default {
	async fetch(request, env): Promise<Response> {
		// Parse incoming url
		const url = new URL(request.url);

		// Get the user query or default to a predefined one
		const userQuery =
			url.searchParams.get("query") ??
			"How do I train a llama to deliver coffee?";

		// Search for documents in AutoRAG
		const searchResult = await env.AI.autorag("my-rag").search({
			query: userQuery,
		});

		if (searchResult.data.length === 0) {
			// No matching documents
			return Response.json({ text: `No data found for query "${userQuery}"` });
		}

		// Join all document chunks into a single string
		const chunks = searchResult.data
			.map((item) => {
				const data = item.content
					.map((content) => {
						return content.text;
					})
					.join("\n\n");

				return `<file name="${item.filename}">${data}</file>`;
			})
			.join("\n\n");

		// Send the user query + matched documents to openai for answer
		const generateResult = await generateText({
			model: openai("gpt-4o-mini"),
			messages: [
				{
					role: "system",
					content:
						"You are a helpful assistant and your task is to answer the user question using the provided files.",
				},
				{ role: "user", content: chunks },
				{ role: "user", content: userQuery },
			],
		});

		// Return the generated answer
		return Response.json({ text: generateResult.text });
	},
} satisfies ExportedHandler<Env>;
```

---

# System prompt

URL: https://developers.cloudflare.com/autorag/configuration/system-prompt/

System prompts allow you to guide the behavior of the text-generation models used by AutoRAG at query time. AutoRAG supports system prompt configuration in two steps:

- **Query rewriting**: Reformulates the original user query to improve semantic retrieval. A system prompt can guide how the model interprets and rewrites the query.
- **Generation**: Generates the final response from retrieved context. A system prompt can help define how the model should format, filter, or prioritize information when constructing the answer.

## What is a system prompt?

A system prompt is a special instruction sent to a large language model (LLM) that guides how it behaves during inference. The system prompt defines the model's role, context, or rules it should follow.

System prompts are particularly useful for:

- Enforcing specific response formats
- Constraining behavior (for example, it only responds based on the provided content)
- Applying domain-specific tone or terminology
- Encouraging consistent, high-quality output

## How to set your system prompt

The system prompt for your AutoRAG can be set after it has been created by:

1. Navigating to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/ai/autorag), and go to AI > AutoRAG
2. Select your AutoRAG
3. Go to Settings page and find the System prompt setting for either Query rewrite or Generation

### Default system prompt

When configuring your AutoRAG instance, you can provide your own system prompts. If you do not provide a system prompt, AutoRAG will use the **default system prompt** provided by Cloudflare.

You can view the effective system prompt used for any AutoRAG's model call through AI Gateway logs, where model inputs and outputs are recorded.

:::note
The default system prompt can change and evolve over time to improve performance and quality.
:::

## Query rewriting system prompt

If query rewriting is enabled, you can provide a custom system prompt to control how the model rewrites user queries. In this step, the model receives:

- The query rewrite system prompt
- The original user query

The model outputs a rewritten query optimized for semantic retrieval.

### Example

```text
You are a search query optimizer for vector database searches. Your task is to reformulate user queries into more effective search terms.

Given a user's search query, you must:
1. Identify the core concepts and intent
2. Add relevant synonyms and related terms
3. Remove irrelevant filler words
4. Structure the query to emphasize key terms
5. Include technical or domain-specific terminology if applicable

Provide only the optimized search query without any explanations, greetings, or additional commentary.

Example input: "how to fix a bike tire that's gone flat"
Example output: "bicycle tire repair puncture fix patch inflate maintenance flat tire inner tube replacement"

Constraints:
- Output only the enhanced search terms
- Keep focus on searchable concepts
- Include both specific and general related terms
- Maintain all important meaning from original query
```

## Generation system prompt

If you are using the AI Search API endpoint, you can use the system prompt to influence how the LLM responds to the final user query using the retrieved results. At this step, the model receives:

- The user's original query
- Retrieved document chunks (with metadata)
- The generation system prompt

The model uses these inputs to generate a context-aware response.

### Example

```
You are a helpful AI assistant specialized in answering questions using retrieved documents.
Your task is to provide accurate, relevant answers based on the matched content provided.
For each query, you will receive:
User's question/query
A set of matched documents, each containing:
  - File name
  - File content

You should:
1. Analyze the relevance of matched documents
2. Synthesize information from multiple sources when applicable
3. Acknowledge if the available documents don't fully answer the query
4. Format the response in a way that maximizes readability, in Markdown format

Answer only with direct reply to the user question, be concise, omit everything which is not directly relevant, focus on answering the question directly and do not redirect the user to read the content.

If the available documents don't contain enough information to fully answer the query, explicitly state this and provide an answer based on what is available.

Important:
- Cite which document(s) you're drawing information from
- Present information in order of relevance
- If documents contradict each other, note this and explain your reasoning for the chosen answer
- Do not repeat the instructions
```

---

# How to

URL: https://developers.cloudflare.com/autorag/how-to/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Create multitenancy

URL: https://developers.cloudflare.com/autorag/how-to/multitenancy/

import { FileTree } from "~/components"

AutoRAG supports multitenancy by letting you segment content by tenant, so each user, customer, or workspace can only access their own data. This is typically done by organizing documents into per-tenant folders and applying [metadata filters](/autorag/configuration/metadata/) at query time.

## 1. Organize Content by Tenant

When uploading files to R2, structure your content by tenant using unique folder paths.

Example folder structure:

<FileTree>
- customer-a
  - logs/
  - contracts/
- customer-b
  - contracts/
</FileTree>

When indexing, AutoRAG will automatically store the folder path as metadata under the `folder` attribute. It is recommended to enforce folder separation during upload or indexing to prevent accidental data access across tenants.

## 2. Search Using Folder Filters

To ensure a tenant only retrieves their own documents, apply a `folder` filter when performing a search.

Example using [Workers Binding](/autorag/usage/workers-binding/):

```js
const response = await env.AI.autorag("my-autorag").search({
	query: "When did I sign my agreement contract?",
	filters: {
		type: "eq",
		key: "folder",
		value: `customer-a/contracts/`,
	},
});
```

To filter across multiple folders, or to add date-based filtering, you can use a compound filter with an array of [comparison filters](/autorag/configuration/metadata/#compound-filter).

## Tip: Use "Starts with" filter

While an `eq` filter targets files at the specific folder, you'll often want to retrieve all documents belonging to a tenant regardless if there are files in its subfolders. For example, all files in `customer-a/` with a structure like:

<FileTree>
- customer-a
  - profile.md
  - contracts
    - property
      - contract-1.pdf
</FileTree>

To achieve this [starts with](/autorag/configuration/metadata/#starts-with-filter-for-folders) behavior, use a compound filter like:

```js
filters: {
    type: "and",
    filters: [
      {
        type: "gt",
        key: "folder",
        value: "customer-a//",
      },
      {
        type: "lte",
        key: "folder",
        value: "customer-a/z",
      },
    ],
  },
```

This filter identifies paths starting with `customer-a/` by using:

- The `and` condition to combine the effects of the `gt` and `lte` conditions.
- The `gt` condition to include paths greater than the `/` ASCII character.
- The `lte` condition to include paths less than and including the lower case `z` ASCII character.

This filter captures both files `profile.md` and `contract-1.pdf`.

---

# Create a simple search engine

URL: https://developers.cloudflare.com/autorag/how-to/simple-search-engine/

By using the `search` method, you can implement a simple but fast search engine. This example uses [Workers Binding](/autorag/usage/workers-binding/), but can be easily adapted to use the [REST API](/autorag/usage/rest-api/) instead.

To replicate this example remember to:

- Disable `rewrite_query`, as you want to match the original user query
- Configure your AutoRAG to have small chunk sizes, usually 256 tokens is enough

```ts
export interface Env {
	AI: Ai;
}

export default {
	async fetch(request, env): Promise<Response> {
		const url = new URL(request.url);
		const userQuery =
			url.searchParams.get("query") ??
			"How do I train a llama to deliver coffee?";
		const searchResult = await env.AI.autorag("my-rag").search({
			query: userQuery,
			rewrite_query: false,
		});

		return Response.json({
			files: searchResult.data.map((obj) => obj.filename),
		});
	},
} satisfies ExportedHandler<Env>;
```

---

# Platform

URL: https://developers.cloudflare.com/autorag/platform/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Limits & pricing

URL: https://developers.cloudflare.com/autorag/platform/limits-pricing/

## Pricing

During the open beta, AutoRAG is **free to enable**. When you create an AutoRAG instance, it provisions and runs on top of Cloudflare services in your account. These resources are **billed as part of your Cloudflare usage**, and includes:

| Service & Pricing                                | Description                                                                               |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| [**R2**](/r2/pricing/)                           | Stores your source data                                                                   |
| [**Vectorize**](/vectorize/platform/pricing/)    | Stores vector embeddings and powers semantic search                                       |
| [**Workers AI**](/workers-ai/platform/pricing/)  | Handles image-to-Markdown conversion, embedding, query rewriting, and response generation |
| [**AI Gateway**](/ai-gateway/reference/pricing/) | Monitors and controls model usage                                                         |

For more information about how each resource is used within AutoRAG, reference [How AutoRAG works](/autorag/concepts/how-autorag-works/).

## Limits

The following limits currently apply to AutoRAG during the open beta:

| Limit                             | Value                                                                                                                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Max AutoRAG instances per account | 10                                                                                                                                                                |
| Max files per AutoRAG             | 100,000                                                                                                                                                           |
| Max file size                     | 4 MB |

These limits are subject to change as AutoRAG evolves beyond open beta.

---

# Release note

URL: https://developers.cloudflare.com/autorag/platform/release-note/

import { ProductReleaseNotes } from "~/components";

This release notes section covers regular updates and minor fixes. For major feature releases or significant updates, see the [changelog](/changelog).

{/* <!-- Actual content lives in /src/content/release-notes/autorag.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Build a RAG from your website

URL: https://developers.cloudflare.com/autorag/tutorial/brower-rendering-autorag-tutorial/

AutoRAG is designed to work out of the box with data in R2 buckets. But what if your content lives on a website or needs to be rendered dynamically?

In this tutorial, we’ll walk through how to:

1. Render your website using Cloudflare's Browser Rendering API
2. Store the rendered HTML in R2
3. Connect it to AutoRAG for querying

## Step 1. Create a Worker to fetch webpages and upload into R2

We’ll create a Cloudflare Worker that uses Puppeteer to visit your URL, render it, and store the full HTML in your R2 bucket. If you already have an R2 bucket with content you’d like to build a RAG for then you can skip this step.

1. Create a new Worker project named `browser-r2-worker` by running:

```bash
npm create cloudflare@latest -- browser-r2-worker
```

For setup, select the following options:

- For _What would you like to start with_?, choose `Hello World example`.
- For _Which template would you like to use_?, choose `Worker only`.
- For _Which language do you want to use_?, choose `TypeScript`.
- For _Do you want to use git for version control_?, choose `Yes`.
- For _Do you want to deploy your application_?, choose `No` (we will be making some changes before deploying).

2. Install `@cloudflare/puppeteer`, which allows you to control the Browser Rendering instance:

```bash
npm i @cloudflare/puppeteer
```

3. Create a new R2 bucket named `html-bucket` by running:

```bash
npx wrangler r2 bucket create html-bucket
```

4. Add the following configurations to your Wrangler configuration file so your Worker can use browser rendering and your new R2 bucket:

```jsonc
{
	"compatibility_flags": ["nodejs_compat"],
	"browser": {
		"binding": "MY_BROWSER",
	},
	"r2_buckets": [
		{
			"binding": "HTML_BUCKET",
			"bucket_name": "html-bucket",
		},
	],
}
```

5. Replace the contents of `src/index.ts` with the following skeleton script:

```typescript
import puppeteer from "@cloudflare/puppeteer";

// Define our environment bindings
interface Env {
	MY_BROWSER: any;
	HTML_BUCKET: R2Bucket;
}

// Define request body structure
interface RequestBody {
	url: string;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		// Only accept POST requests
		if (request.method !== "POST") {
			return new Response("Please send a POST request with a target URL", {
				status: 405,
			});
		}

		// Get URL from request body
		const body = (await request.json()) as RequestBody;
		// Note: Only use this parser for websites you own
		const targetUrl = new URL(body.url);

		// Launch browser and create new page
		const browser = await puppeteer.launch(env.MY_BROWSER);
		const page = await browser.newPage();

		// Navigate to the page and fetch its html
		await page.goto(targetUrl.href);
		const htmlPage = await page.content();

		// Create filename and store in R2
		const key = targetUrl.hostname + "_" + Date.now() + ".html";
		await env.HTML_BUCKET.put(key, htmlPage);

		// Close browser
		await browser.close();

		// Return success response
		return new Response(
			JSON.stringify({
				success: true,
				message: "Page rendered and stored successfully",
				key: key,
			}),
			{
				headers: { "Content-Type": "application/json" },
			},
		);
	},
} satisfies ExportedHandler<Env>;
```

6. Once the code is ready, you can deploy it to your Cloudflare account by running:

```bash
npx wrangler deploy
```

7. To test your Worker, you can use the following cURL request to fetch the HTML file of a page. In this example we are fetching this page to upload into the `html-bucket` bucket:

```bash
curl -X POST https://browser-r2-worker.<YOUR_SUBDOMAIN>.workers.dev \
-H "Content-Type: application/json" \
-d '{"url": "https://developers.cloudflare.com/autorag/tutorial/brower-rendering-autorag-tutorial/"}'
```

## Step 2. Create your AutoRAG and monitor the indexing

Now that you have created your R2 bucket and filled it with your content that you’d like to query from, you are ready to create an AutoRAG instance:

1. In your [Cloudflare Dashboard](https://dash.cloudflare.com/?to=/:account/ai/autorag), navigate to AI > AutoRAG
2. Select Create AutoRAG and complete the setup process:
   1. Select the **R2 bucket** which contains your knowledge base, in this case, select the `html-bucket`.
   2. Select an **embedding model** used to convert your data to vector representation. It is recommended to use the Default.
   3. Select an **LLM** to use to generate your responses. It is recommended to use the Default.
   4. Select or create an **AI Gateway** to monitor and control your model usage.
   5. **Name** your AutoRAG as `my-rag`
   6. Select or create a **Service API** token to grant AutoRAG access to create and access resources in your account.
3. Select Create to spin up your AutoRAG.

Once you’ve created your AutoRAG, it will automatically create a Vectorize database in your account and begin indexing the data.

You can view the progress of your indexing job in the Overview page of your AutoRAG.

![AutoRAG Overview page](~/assets/images/autorag/tutorial-indexing-page.png)

## Step 3. Test and add to your application

Once AutoRAG finishes indexing your content, you’re ready to start asking it questions. You can open up your AutoRAG instance, navigate to the Playground tab, and ask a question based on your uploaded content, like “What is AutoRAG?”.

Once you’re happy with the results in the Playground, you can integrate AutoRAG directly into the application that you are building. If you are using a Worker to build your [RAG application](/autorag/), then you can use the AI binding to directly call your AutoRAG:

```jsonc
{
	"ai": {
		"binding": "AI",
	},
}
```

Then, query your AutoRAG instance from your Worker code by calling the `aiSearch()` method.

```javascript
const answer = await env.AI.autorag("my-rag").aiSearch({
	query: "What is AutoRAG?",
});
```

For more information on how to add AutoRAG into your application, go to your AutoRAG then navigate to Use AutoRAG for more instructions.

---

# Usage

URL: https://developers.cloudflare.com/autorag/usage/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# REST API

URL: https://developers.cloudflare.com/autorag/usage/rest-api/

import {
	Badge,
	Description,
	Render,
	TabItem,
	Tabs,
	WranglerConfig,
	MetaInfo,
	Type,
} from "~/components";

This guide will instruct you through how to use the AutoRAG REST API to make a query to your AutoRAG.

## Prerequisite: Get AutoRAG API token

You need an API token with the `AutoRAG - Read` and `AutoRAG Edit` permissions to use the REST API. To create a new token:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **AI** > **AutoRAG** and select your AutoRAG.
3. Select **Use AutoRAG** then select **API**.
4. Select **Create an API Token**.
5. Review the prefilled information then select **Create API Token**.
6. Select **Copy API Token** and save that value for future use.

## AI Search

This REST API searches for relevant results from your data source and generates a response using the model and the retrieved relevant context:

```bash

curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/autorag/rags/{AUTORAG_NAME}/ai-search \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {API_TOKEN}" \
-d '{
	"query": "How do I train a llama to deliver coffee?",
	"model": @cf/meta/llama-3.3-70b-instruct-sd,
	"rewrite_query": false,
	"max_num_results": 10,
	"ranking_options": {
		"score_threshold": 0.3
	},
	"stream": true,
}'

```

:::note

You can get your `ACCOUNT_ID` by navigating to [Workers & Pages on the dashboard](/fundamentals/account/find-account-and-zone-ids/#find-account-id-workers-and-pages).

:::

### Parameters

<Render file="ai-search-api-params" product="autorag" />

### Response

This is the response structure without `stream` enabled.

<Render file="ai-search-response" product="autorag" />

## Search

This REST API searches for results from your data source and returns the relevant results:

```bash

curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/autorag/rags/{AUTORAG_NAME}/search \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {API_TOKEN}" \
-d '{
	"query": "How do I train a llama to deliver coffee?",
	"rewrite_query": true,
	"max_num_results": 10,
	"ranking_options": {
		"score_threshold": 0.3
	},
}'

```

:::note

You can get your `ACCOUNT_ID` by navigating to Workers & Pages on the dashboard, and copying the Account ID under Account Details.

:::

### Parameters

<Render file="search-api-params" product="autorag" />

### Response

<Render file="search-response" product="autorag" />

---

# Tutorial

URL: https://developers.cloudflare.com/autorag/tutorial/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Workers Binding

URL: https://developers.cloudflare.com/autorag/usage/workers-binding/

import {
	Badge,
	Description,
	Render,
	TabItem,
	Tabs,
	WranglerConfig,
	MetaInfo,
	Type,
} from "~/components";

Cloudflare’s serverless platform allows you to run code at the edge to build full-stack applications with [Workers](/workers/). A [binding](/workers/runtime-apis/bindings/) enables your Worker or Pages Function to interact with resources on the Cloudflare Developer Platform.

To use your AutoRAG with Workers or Pages, create an AI binding either in the Cloudflare dashboard (refer to [AI bindings](/pages/functions/bindings/#workers-ai) for instructions), or you can update your [Wrangler file](/workers/wrangler/configuration/). To bind AutoRAG to your Worker, add the following to your Wrangler file:

<WranglerConfig>

```toml
[ai]
binding = "AI" # i.e. available in your Worker on env.AI
```

</WranglerConfig>

## `aiSearch()`

This method searches for relevant results from your data source and generates a response using your default model and the retrieved context, for an AutoRAG named `my-autorag`:

```js
const answer = await env.AI.autorag("my-autorag").aiSearch({
	query: "How do I train a llama to deliver coffee?",
	model: "@cf/meta/llama-3.3-70b-instruct-sd",
	rewrite_query: true,
	max_num_results: 2,
	ranking_options: {
		score_threshold: 0.3,
	},
	stream: true,
});
```

### Parameters

<Render file="ai-search-api-params" product="autorag" />

### Response

This is the response structure without `stream` enabled.

```sh output
{
    "object": "vector_store.search_results.page",
    "search_query": "How do I train a llama to deliver coffee?",
    "response": "To train a llama to deliver coffee:\n\n1. **Build trust** — Llamas appreciate patience (and decaf).\n2. **Know limits** — Max 3 cups per llama, per `llama-logistics.md`.\n3. **Use voice commands** — Start with \"Espresso Express!\"\n4.",
    "data": [
      {
        "file_id": "llama001",
        "filename": "llama/logistics/llama-logistics.md",
        "score": 0.45,
        "attributes": {
          "modified_date": 1735689600000,   // unix timestamp for 2025-01-01
          "folder": "llama/logistics/",
        },
        "content": [
          {
            "id": "llama001",
            "type": "text",
            "text": "Llamas can carry 3 drinks max."
          }
        ]
      },
      {
        "file_id": "llama042",
        "filename": "llama/llama-commands.md",
        "score": 0.4,
        "attributes": {
          "modified_date": 1735689600000,   // unix timestamp for 2025-01-01
          "folder": "llama/",
        },
        "content": [
          {
            "id": "llama042",
            "type": "text",
            "text": "Start with basic commands like 'Espresso Express!' Llamas love alliteration."
          }
        ]
      },
    ],
    "has_more": false,
    "next_page": null
}

```

## `search()`

This method searches for results from your corpus and returns the relevant results, for the AutoRAG instance named `my-autorag`:

```js
const answer = await env.AI.autorag("my-autorag").search({
	query: "How do I train a llama to deliver coffee?",
	rewrite_query: true,
	max_num_results: 2,
	ranking_options: {
		score_threshold: 0.3,
	},
});
```

### Parameters

<Render file="search-api-params" product="autorag" />

### Response

```sh output
{
    "object": "vector_store.search_results.page",
    "search_query": "How do I train a llama to deliver coffee?",
    "data": [
      {
        "file_id": "llama001",
        "filename": "llama/logistics/llama-logistics.md",
        "score": 0.45,
        "attributes": {
          "modified_date": 1735689600000,   // unix timestamp for 2025-01-01
          "folder": "llama/logistics/",
        },
        "content": [
          {
            "id": "llama001",
            "type": "text",
            "text": "Llamas can carry 3 drinks max."
          }
        ]
      },
      {
        "file_id": "llama042",
        "filename": "llama/llama-commands.md",
        "score": 0.4,
        "attributes": {
          "modified_date": 1735689600000,   // unix timestamp for 2025-01-01
          "folder": "llama/",
        },
        "content": [
          {
            "id": "llama042",
            "type": "text",
            "text": "Start with basic commands like 'Espresso Express!' Llamas love alliteration."
          }
        ]
      },
    ],
    "has_more": false,
    "next_page": null
}

```

## Local development

Local development is supported by proxying requests to your deployed AutoRAG instance. When running in local mode, your application forwards queries to the configured remote AutoRAG instance and returns the generated responses as if they were served locally.

---

# How To

URL: https://developers.cloudflare.com/browser-rendering/how-to/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Use browser rendering with AI

URL: https://developers.cloudflare.com/browser-rendering/how-to/ai/

import { Aside, WranglerConfig } from "~/components";

The ability to browse websites can be crucial when building workflows with AI. Here, we provide an example where we use Browser Rendering to visit
`https://labs.apnic.net/` and then, using a machine learning model available in [Workers AI](/workers-ai/), extract the first post as JSON with a specified schema.

## Prerequisites

1. Use the `create-cloudflare` CLI to generate a new Hello World Cloudflare Worker script:

```sh
npm create cloudflare@latest -- browser-worker
```

2. Install `@cloudflare/puppeteer`, which allows you to control the Browser Rendering instance:

```sh
npm i @cloudflare/puppeteer
```

2. Install `zod` so we can define our output format and `zod-to-json-schema` so we can convert it into a JSON schema format:

```sh
npm i zod
npm i zod-to-json-schema
```

3. Activate the nodejs compatibility flag and add your Browser Rendering binding to your new Wrangler configuration:

<WranglerConfig>
```toml
compatibility_flags = [ "nodejs_compat" ]
```
</WranglerConfig>

<WranglerConfig>
```toml
[browser]
binding = "MY_BROWSER"
```
</WranglerConfig>

4.  In order to use [Workers AI](/workers-ai/), you need to get your [Account ID and API token](/workers-ai/get-started/rest-api/#1-get-api-token-and-account-id).
Once you have those, create a [`.dev.vars`](/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) file and set them there:

```
ACCOUNT_ID=
API_TOKEN=
```

We use `.dev.vars` here since it's only for local development, otherwise you'd use [Secrets](/workers/configuration/secrets/).

## Load the page using Browser Rendering

In the code below, we launch a browser using `await puppeteer.launch(env.MY_BROWSER)`, extract the rendered text and close the browser.
Then, with the user prompt, the desired output schema and the rendered text, prepare a prompt to send to the LLM.

Replace the contents of `src/index.ts` with the following skeleton script:

```ts
import { z } from "zod";
import puppeteer from "@cloudflare/puppeteer";
import zodToJsonSchema from "zod-to-json-schema";

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname != "/") {
      return new Response("Not found");
    }

    // Your prompt and site to scrape
    const userPrompt = "Extract the first post only.";
    const targetUrl = "https://labs.apnic.net/";

    // Launch browser
    const browser = await puppeteer.launch(env.MY_BROWSER);
    const page = await browser.newPage();
    await page.goto(targetUrl);

    // Get website text
    const renderedText = await page.evaluate(() => {
      // @ts-ignore js code to run in the browser context
      const body = document.querySelector("body");
      return body ? body.innerText : "";
    });
    // Close browser since we no longer need it
    await browser.close();

    // define your desired json schema
    const outputSchema = zodToJsonSchema(
      z.object({ title: z.string(), url: z.string(), date: z.string() })
    );

    // Example prompt
    const prompt = `
    You are a sophisticated web scraper. You are given the user data extraction goal and the JSON schema for the output data format.
    Your task is to extract the requested information from the text and output it in the specified JSON schema format:

        ${JSON.stringify(outputSchema)}

    DO NOT include anything else besides the JSON output, no markdown, no plaintext, just JSON.

    User Data Extraction Goal: ${userPrompt}

    Text extracted from the webpage: ${renderedText}`;

    // TODO call llm
    //const result = await getLLMResult(env, prompt, outputSchema);
    //return Response.json(result);
  }

} satisfies ExportedHandler<Env>;
```

## Call an LLM

Having the webpage text, the user's goal and output schema, we can now use an LLM to transform it to JSON according to the user's request.
The example below uses `@hf/thebloke/deepseek-coder-6.7b-instruct-awq` but other [models](/workers-ai/models/) or services like OpenAI, could be used with minimal changes:

```ts
async function getLLMResult(env, prompt: string, schema?: any) {
  const model = "@hf/thebloke/deepseek-coder-6.7b-instruct-awq"
  const requestBody = {
    messages: [{
      role: "user",
      content: prompt
    }],
  };
  const aiUrl = `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/ai/run/${model}`

  const response = await fetch(aiUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${env.API_TOKEN}`,
    },
    body: JSON.stringify(requestBody),
  });
  if (!response.ok) {
    console.log(JSON.stringify(await response.text(), null, 2));
    throw new Error(`LLM call failed ${aiUrl} ${response.status}`);
  }

  // process response
  const data = await response.json();
  const text = data.result.response || '';
  const value = (text.match(/```(?:json)?\s*([\s\S]*?)\s*```/) || [null, text])[1];
  try {
    return JSON.parse(value);
  } catch(e) {
    console.error(`${e} . Response: ${value}`)
  }
}
```

If you want to use Browser Rendering with OpenAI instead you'd just need to change the `aiUrl` endpoint and `requestBody` (or check out the [llm-scraper-worker](https://www.npmjs.com/package/llm-scraper-worker) package).

## Conclusion

The full Worker script now looks as follows:

```ts
import { z } from "zod";
import puppeteer from "@cloudflare/puppeteer";
import zodToJsonSchema from "zod-to-json-schema";

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname != "/") {
      return new Response("Not found");
    }

    // Your prompt and site to scrape
    const userPrompt = "Extract the first post only.";
    const targetUrl = "https://labs.apnic.net/";

    // Launch browser
    const browser = await puppeteer.launch(env.MY_BROWSER);
    const page = await browser.newPage();
    await page.goto(targetUrl);

    // Get website text
    const renderedText = await page.evaluate(() => {
      // @ts-ignore js code to run in the browser context
      const body = document.querySelector("body");
      return body ? body.innerText : "";
    });
    // Close browser since we no longer need it
    await browser.close();

    // define your desired json schema
    const outputSchema = zodToJsonSchema(
      z.object({ title: z.string(), url: z.string(), date: z.string() })
    );

    // Example prompt
    const prompt = `
    You are a sophisticated web scraper. You are given the user data extraction goal and the JSON schema for the output data format.
    Your task is to extract the requested information from the text and output it in the specified JSON schema format:

        ${JSON.stringify(outputSchema)}

    DO NOT include anything else besides the JSON output, no markdown, no plaintext, just JSON.

    User Data Extraction Goal: ${userPrompt}

    Text extracted from the webpage: ${renderedText}`;

    // call llm
    const result = await getLLMResult(env, prompt, outputSchema);
    return Response.json(result);
  }

} satisfies ExportedHandler<Env>;


async function getLLMResult(env, prompt: string, schema?: any) {
  const model = "@hf/thebloke/deepseek-coder-6.7b-instruct-awq"
  const requestBody = {
    messages: [{
      role: "user",
      content: prompt
    }],
  };
  const aiUrl = `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/ai/run/${model}`

  const response = await fetch(aiUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${env.API_TOKEN}`,
    },
    body: JSON.stringify(requestBody),
  });
  if (!response.ok) {
    console.log(JSON.stringify(await response.text(), null, 2));
    throw new Error(`LLM call failed ${aiUrl} ${response.status}`);
  }

  // process response
  const data = await response.json() as { result: { response: string }};
  const text = data.result.response || '';
  const value = (text.match(/```(?:json)?\s*([\s\S]*?)\s*```/) || [null, text])[1];
  try {
    return JSON.parse(value);
  } catch(e) {
    console.error(`${e} . Response: ${value}`)
  }
}
```

You can run this script to test it using Wrangler's `--remote` flag:

```sh
npx wrangler dev --remote
```

With your script now running, you can go to `http://localhost:8787/` and should see something like the following:

```json
{
  "title": "IP Addresses in 2024",
  "url": "http://example.com/ip-addresses-in-2024",
  "date": "11 Jan 2025"
}
```

For more complex websites or prompts, you might need a better model. Check out the latest models in [Workers AI](/workers-ai/models/).

---

# Generate PDFs Using HTML and CSS

URL: https://developers.cloudflare.com/browser-rendering/how-to/pdf-generation/

import { Aside, WranglerConfig, PackageManagers } from "~/components";

As seen in [this Workers bindings guide](/browser-rendering/workers-bindings/screenshots/), Browser Rendering can be used to generate screenshots for any given URL. Alongside screenshots, you can also generate full PDF documents for a given webpage, and can also provide the webpage markup and style ourselves.

## Prerequisites

1. Use the `create-cloudflare` CLI to generate a new Hello World Cloudflare Worker script:

<PackageManagers type="create" pkg="cloudflare@latest" args="browser-worker" />

2. Install `@cloudflare/puppeteer`, which allows you to control the Browser Rendering instance:

<PackageManagers pkg="@cloudflare/puppeteer" dev />

3. Add your Browser Rendering binding to your new Wrangler configuration:

<WranglerConfig>

```toml title="wrangler.toml"
browser = { binding = "BROWSER" }
```

</WranglerConfig>

4. Replace the contents of `src/index.ts` (or `src/index.js` for JavaScript projects) with the following skeleton script:

```ts
import puppeteer from "@cloudflare/puppeteer";

const generateDocument = (name: string) => {};

export default {
	async fetch(request, env) {
		const { searchParams } = new URL(request.url);
		let name = searchParams.get("name");

		if (!name) {
			return new Response("Please provide a name using the ?name= parameter");
		}

		const browser = await puppeteer.launch(env.BROWSER);
		const page = await browser.newPage();

		// Step 1: Define HTML and CSS
		const document = generateDocument(name);

		// Step 2: Send HTML and CSS to our browser
		await page.setContent(document);

		// Step 3: Generate and return PDF

		return new Response();
	},
};
```

## 1. Define HTML and CSS

Rather than using Browser Rendering to navigate to a user-provided URL, manually generate a webpage, then provide that webpage to the Browser Rendering instance. This allows you to render any design you want.

:::note
You can generate your HTML or CSS using any method you like. This example uses string interpolation, but the method is also fully compatible with web frameworks capable of rendering HTML on Workers such as React, Remix, and Vue.
:::

For this example, we are going to take in user-provided content (via a '?name=' parameter), and have that name output in the final PDF document.

To start, fill out your `generateDocument` function with the following:

```ts
const generateDocument = (name: string) => {
	return `
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <style>
      html,
      body,
      #container {
        width: 100%;
        height: 100%;
        margin: 0;
      }
      body {
        font-family: Baskerville, Georgia, Times, serif;
        background-color: #f7f1dc;
      }
      strong {
        color: #5c594f;
        font-size: 128px;
        margin: 32px 0 48px 0;
      }
      em {
        font-size: 24px;
      }
      #container {
        flex-direction: column;
        display: flex;
        align-items: center;
        justify-content: center;
        text-align: center;
      }
    </style>
  </head>

  <body>
    <div id="container">
      <em>This is to certify that</em>
      <strong>${name}</strong>
      <em>has rendered a PDF using Cloudflare Workers</em>
    </div>
  </body>
</html>
`;
};
```

This example HTML document should render a beige background imitating a certificate showing that the user-provided name has successfully rendered a PDF using Cloudflare Workers.

:::note
It is usually best to avoid directly interpolating user-provided content into an image or PDF renderer in production applications. To render contents like an invoice, it would be best to validate the data input and fetch the data yourself using tools like [D1](/d1/) or [Workers KV](/kv/).
:::

## 2. Load HTML and CSS Into Browser

Now that you have your fully styled HTML document, you can take the contents and send it to your browser instance. Create an empty page to store this document as follows:

```ts
const browser = await puppeteer.launch(env.BROWSER);
const page = await browser.newPage();
```

The [`page.setContent()`](https://github.com/cloudflare/puppeteer/blob/main/docs/api/puppeteer.page.setcontent.md) function can then be used to set the page's HTML contents from a string, so you can pass in your created document directly like so:

```ts
await page.setContent(document);
```

## 3. Generate and Return PDF

With your Browser Rendering instance now rendering your provided HTML and CSS, you can use the [`page.pdf()`](https://github.com/cloudflare/puppeteer/blob/main/docs/api/puppeteer.page.pdf.md) command to generate a PDF file and return it to the client.

```ts
let pdf = page.pdf({ printBackground: true });
```

The `page.pdf()` call supports a [number of options](https://github.com/cloudflare/puppeteer/blob/main/docs/api/puppeteer.pdfoptions.md), including setting the dimensions of the generated PDF to a specific paper size, setting specific margins, and allowing fully-transparent backgrounds. For now, you are only overriding the `printBackground` option to allow your `body` background styles to show up.

Now that you have your PDF data, return it to the client in the `Response` with an `application/pdf` content type:

```ts
return new Response(pdf, {
	headers: {
		"content-type": "application/pdf",
	},
});
```

## Conclusion

The full Worker script now looks as follows:

```ts
import puppeteer from "@cloudflare/puppeteer";

const generateDocument = (name: string) => {
	return `
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <style>
	  html, body, #container {
		width: 100%;
	    height: 100%;
		margin: 0;
	  }
      body {
        font-family: Baskerville, Georgia, Times, serif;
        background-color: #f7f1dc;
      }
      strong {
        color: #5c594f;
		font-size: 128px;
		margin: 32px 0 48px 0;
      }
	  em {
		font-size: 24px;
	  }
      #container {
		flex-direction: column;
        display: flex;
        align-items: center;
        justify-content: center;
		text-align: center
      }
    </style>
  </head>

  <body>
    <div id="container">
		<em>This is to certify that</em>
		<strong>${name}</strong>
		<em>has rendered a PDF using Cloudflare Workers</em>
	</div>
  </body>
</html>
`;
};

export default {
	async fetch(request, env) {
		const { searchParams } = new URL(request.url);
		let name = searchParams.get("name");

		if (!name) {
			return new Response("Please provide a name using the ?name= parameter");
		}

		const browser = await puppeteer.launch(env.BROWSER);
		const page = await browser.newPage();

		// Step 1: Define HTML and CSS
		const document = generateDocument(name);

		// // Step 2: Send HTML and CSS to our browser
		await page.setContent(document);

		// // Step 3: Generate and return PDF
		const pdf = await page.pdf({ printBackground: true });

		// Close browser since we no longer need it
		await browser.close();

		return new Response(pdf, {
			headers: {
				"content-type": "application/pdf",
			},
		});
	},
};
```

You can run this script to test it using Wrangler’s `--remote` flag:

<PackageManagers type="exec" pkg="wrangler" args="dev --remote" />

With your script now running, you can pass in a `?name` parameter to the local URL (such as `http://localhost:8787/?name=Harley`) and should see the following:

![A screenshot of a generated PDF, with the author's name shown in a mock certificate.](~/assets/images/browser-rendering/pdf-generation.png).

---

Dynamically generating PDF documents solves a number of common use-cases, from invoicing customers to archiving documents to creating dynamic certificates (as seen in the simple example here).

---

# Browser close reasons

URL: https://developers.cloudflare.com/browser-rendering/platform/browser-close-reasons/

A browser session may close for a variety of reasons, occasionally due to connection errors or errors in the headless browser instance. As a best practice, wrap `puppeteer.connect` or `puppeteer.launch` in a [`try/catch`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) statement.

The reason that a browser closed can be found on the Browser Rendering Dashboard in the [logs tab](https://dash.cloudflare.com/?to=/:account/workers/browser-renderingl/logs). When Cloudflare begins charging for the Browser Rendering API, we will not charge when errors are due to underlying Browser Rendering infrastructure.

| Reasons a session may end                            |
| ---------------------------------------------------- |
| User opens and closes browser normally.              |
| Browser is idle for 60 seconds.                      |
| Chromium instance crashes.                           |
| Error connecting with the client, server, or Worker. |
| Browser session is evicted.                          |

---

# Platform

URL: https://developers.cloudflare.com/browser-rendering/platform/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Limits

URL: https://developers.cloudflare.com/browser-rendering/platform/limits/

import { Render, Plan } from "~/components";

<Plan type="workers-all" />

## Workers Free

Users on the [Workers Free plan](/workers/platform/pricing/) are limited to **10 minutes of browser rendering usage per day**.

To increase this limit, you’ll need to [upgrade to a Workers Paid plan](/workers/platform/pricing).

| Feature                                | Limit           |
| -------------------------------------- | --------------- |
| Concurrent browsers per account (Workers Bindings only)        | 3 per account   |
| New browser instances per minute (Workers Bindings only)      | 3 per minute    |
| Browser timeout                        | 60 seconds [^2] |
| Total requests per min (REST API only) | 6 per minute    |

## Workers Paid

<Render file="limits-increase" product="browser-rendering" />

| Feature                                | Limit               |
| -------------------------------------- | ------------------- |
| Concurrent browsers per account (Workers Bindings only)        | 10 per account [^1] |
| New browser instances per minute (Workers Bindings only)       | 10 per minute [^1]  |
| Browser timeout                        | 60 seconds [^2][^1] |
| Total requests per min (REST API only) | 60 per minute       |

[^1]: Contact our team to request increases to this limit.

[^2]: By default, a browser instance gets killed if it does not get any [devtools](https://chromedevtools.github.io/devtools-protocol/) command for 60 seconds, freeing one instance. Users can optionally increase this by using the `keep_alive` [option](/browser-rendering/platform/puppeteer/#keep-alive). `browser.close()` releases the browser instance.

## Note on concurrency

While the limits above define the maximum number of concurrent browser sessions per account, in practice you may not need to hit these limits. Browser sessions close automatically—by default, after 60 seconds of inactivity or upon task completion—so if each session finishes its work before a new request comes in, the effective concurrency is lower. This means that most workflows do not require very high concurrent browser limits.

## Pricing

Browser Rendering service is currently available at no cost up to the limits specified above **until billing begins**. Pricing to be announced and we will provide advance notice before any billing begins.

---

# Playwright MCP

URL: https://developers.cloudflare.com/browser-rendering/platform/playwright-mcp/

import {
	Render,
	WranglerConfig,
	TabItem,
	Tabs,
	PackageManagers,
} from "~/components";

[`@cloudflare/playwright-mcp`](https://github.com/cloudflare/playwright-mcp) is a [Playwright MCP](https://github.com/microsoft/playwright-mcp) server fork that provides browser automation capabilities using Playwright and Browser Rendering.

This server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models. Its key features are:

* Fast and lightweight. Uses Playwright's accessibility tree, not pixel-based input.
* LLM-friendly. No vision models needed, operates purely on structured data.
* Deterministic tool application. Avoids ambiguity common with screenshot-based approaches.

## Deploying

Follow these steps to deploy `@cloudflare/playwright-mcp`:

1. Install the Playwright MCP [npm package](https://www.npmjs.com/package/@cloudflare/playwright-mcp).

<PackageManagers pkg="@cloudflare/playwright-mcp" dev />

2. Make sure you have the [browser rendering](/browser-rendering/) and [durable object](/durable-objects/) bindings and [migrations](/durable-objects/reference/durable-objects-migrations/) in your wrangler configuration file.

<WranglerConfig>

```toml
name = "playwright-mcp-example"
main = "src/index.ts"
compatibility_date = "2025-03-10"
compatibility_flags = ["nodejs_compat"]

[browser]
binding = "BROWSER"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["PlaywrightMCP"]

[[durable_objects.bindings]]
name = "MCP_OBJECT"
class_name = "PlaywrightMCP"
```

</WranglerConfig>

3. Edit the code.

```ts title="src/index.ts"
import { env } from 'cloudflare:workers';
import { createMcpAgent } from '@cloudflare/playwright-mcp';

export const PlaywrightMCP = createMcpAgent(env.BROWSER);
export default PlaywrightMCP.mount('/sse');
```

4. Deploy the server.

```bash
npx wrangler deploy
```

The server is now available at `https://[my-mcp-url].workers.dev/sse` and you can use it with any MCP client.

Alternatively, use [Deploy to Cloudflare](/workers/platform/deploy-buttons/):

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/playwright-mcp/tree/main/cloudflare/example)

Check our [GitHub page](https://github.com/cloudflare/playwright-mcp) for more information on how to build and deploy Playwright MCP.

## Using Playwright MCP

![alt text](~/assets/images/browser-rendering/playground-ai-screenshot.png)

[Cloudflare AI Playground](https://playground.ai.cloudflare.com/) is a great way to test MCP servers using LLM models available in Workers AI.

- Navigate to https://playground.ai.cloudflare.com/
- Ensure that the model is set to `llama-3.3-70b-instruct-fp8-fast`
- In **MCP Servers**, set **URL** to `https://[my-mcp-url].workers.dev/sse`
- Click **Connect**
- Status should update to **Connected** and it should list 23 available tools

You can now start to interact with the model, and it will run necessary the tools to accomplish what was requested.

:::note

For best results, give simple instructions consisting of one single action, e.g. "Create a new todo entry", "Go to cloudflare site", "Take a screenshot"

:::

Try this sequence of instructions to see Playwright MCP in action:

1. "Go to demo.playwright.dev/todomvc"
2. "Create some todo entry"
3. "Nice. Now create a todo in parrot style"
4. "And create another todo in Yoda style"
5. "Take a screenshot"

You can also use other MCP clients like [Claude Desktop](https://github.com/cloudflare/playwright-mcp/blob/main/cloudflare/example/README.md#use-with-claude-desktop).

Check our [GitHub page](https://github.com/cloudflare/playwright-mcp) for more examples and MCP client configuration options and our developer documentation on how to [build Agents on Cloudflare](/agents/).

---

# Playwright (beta)

URL: https://developers.cloudflare.com/browser-rendering/platform/playwright/

import {
	Render,
	WranglerConfig,
	TabItem,
	Tabs,
	PackageManagers,
} from "~/components";

[Playwright](https://playwright.dev/) is an open-source package developed by Microsoft that can do browser automation tasks; it is commonly used to write frontend tests, create screenshots, or crawl pages.

The Workers team forked a [version of Playwright](https://github.com/cloudflare/playwright) that was modified to be compatible with [Cloudflare Workers](/workers/) and [Browser Rendering](/browser-rendering/).

Our version is open sourced and can be found in [Cloudflare's fork of Playwright](https://github.com/cloudflare/playwright). The npm package can be installed from [npmjs](https://www.npmjs.com/) as [@cloudflare/playwright](https://www.npmjs.com/package/@cloudflare/playwright):

<PackageManagers pkg="@cloudflare/playwright" dev />

## Use Playwright in a Worker

Make sure you have the [browser binding](/browser-rendering/platform/wrangler/#bindings) configured in your `wrangler.toml` file:

<WranglerConfig>

```toml
name = "cloudflare-playwright-example"
main = "src/index.ts"
workers_dev = true
compatibility_flags = ["nodejs_compat_v2"]
compatibility_date = "2025-03-05"
upload_source_maps = true

[dev]
port = 9000

[browser]
binding = "MYBROWSER"
```

</WranglerConfig>

Install the npm package:

<PackageManagers pkg="@cloudflare/playwright" dev />

Let's look at some examples of how to use Playwright:

### Take a screenshot

Using browser automation to take screenshots of web pages is a common use case. This script tells the browser to navigate to https://demo.playwright.dev/todomvc, create some items, take a screenshot of the page, and return the image in the response.

```ts
import { launch, type BrowserWorker } from "@cloudflare/playwright";

interface Env {
	MYBROWSER: BrowserWorker;
}

export default {
	async fetch(request: Request, env: Env) {
		const browser = await launch(env.MYBROWSER);
		const page = await browser.newPage();

		await page.goto("https://demo.playwright.dev/todomvc");

		const TODO_ITEMS = [
			"buy some cheese",
			"feed the cat",
			"book a doctors appointment",
		];

		const newTodo = page.getByPlaceholder("What needs to be done?");
		for (const item of TODO_ITEMS) {
			await newTodo.fill(item);
			await newTodo.press("Enter");
		}

		const img = await page.screenshot();
		await browser.close();

		return new Response(img, {
			headers: {
				"Content-Type": "image/png",
			},
		});
	},
};
```

### Trace

A Playwright trace is a detailed log of your workflow execution that captures information like user clicks and navigation actions, screenshots of the page, and any console messages generated and used for debugging. Developers can take a `trace.zip` file and either open it [locally](https://playwright.dev/docs/trace-viewer#opening-the-trace) or upload it to the [Playwright Trace Viewer](https://trace.playwright.dev/), a GUI tool that helps you explore the data.

Here's an example of a worker generating a trace file:

```ts
import { launch, type BrowserWorker } from "@cloudflare/playwright";
import fs from "@cloudflare/playwright/fs";

interface Env {
	MYBROWSER: BrowserWorker;
}

export default {
	async fetch(request: Request, env: Env) {
		const browser = await launch(env.MYBROWSER);
		const page = await browser.newPage();

		// Start tracing before navigating to the page
		await page.context().tracing.start({ screenshots: true, snapshots: true });

		await page.goto("https://demo.playwright.dev/todomvc");

		const TODO_ITEMS = [
			"buy some cheese",
			"feed the cat",
			"book a doctors appointment",
		];

		const newTodo = page.getByPlaceholder("What needs to be done?");
		for (const item of TODO_ITEMS) {
			await newTodo.fill(item);
			await newTodo.press("Enter");
		}

		// Stop tracing and save the trace to a zip file
		await page.context().tracing.stop({ path: "trace.zip" });
		await browser.close();
		const file = await fs.promises.readFile("trace.zip");

		return new Response(file, {
			status: 200,
			headers: {
				"Content-Type": "application/zip",
			},
		});
	},
};
```

### Assertions

One of the most common use cases for using Playwright is software testing. Playwright includes test assertion features in its APIs; refer to [Assertions](https://playwright.dev/docs/test-assertions) in the Playwright documentation for details. Here's an example of a Worker doing `expect()` test assertions of the [todomvc](https://demo.playwright.dev/todomvc) demo page:

```ts
import { launch, type BrowserWorker } from "@cloudflare/playwright";
import { expect } from "@cloudflare/playwright/test";

interface Env {
	MYBROWSER: BrowserWorker;
}

export default {
	async fetch(request: Request, env: Env) {
		const browser = await launch(env.MYBROWSER);
		const page = await browser.newPage();

		await page.goto("https://demo.playwright.dev/todomvc");

		const TODO_ITEMS = [
			"buy some cheese",
			"feed the cat",
			"book a doctors appointment",
		];

		const newTodo = page.getByPlaceholder("What needs to be done?");
		for (const item of TODO_ITEMS) {
			await newTodo.fill(item);
			await newTodo.press("Enter");
		}

		await expect(page.getByTestId("todo-title")).toHaveCount(TODO_ITEMS.length);

		await Promise.all(
			TODO_ITEMS.map((value, index) =>
				expect(page.getByTestId("todo-title").nth(index)).toHaveText(value),
			),
		);
	},
};
```

### Keep Alive

If users omit the `browser.close()` statement, the browser instance will stay open, ready to be connected to again and [re-used](/browser-rendering/workers-bindings/reuse-sessions/) but it will, by default, close automatically after 1 minute of inactivity. Users can optionally extend this idle time up to 10 minutes, by using the `keep_alive` option, set in milliseconds:

```js
const browser = await playwright.launch(env.MYBROWSER, { keep_alive: 600000 });
```

Using the above, the browser will stay open for up to 10 minutes, even if inactive.

## Session management

In order to facilitate browser session management, we have extended the Playwright API with new methods:

### List open sessions

`playwright.sessions()` lists the current running sessions. It will return an output similar to this:

```json
[
	{
		"connectionId": "2a2246fa-e234-4dc1-8433-87e6cee80145",
		"connectionStartTime": 1711621704607,
		"sessionId": "478f4d7d-e943-40f6-a414-837d3736a1dc",
		"startTime": 1711621703708
	},
	{
		"sessionId": "565e05fb-4d2a-402b-869b-5b65b1381db7",
		"startTime": 1711621703808
	}
]
```

Notice that the session `478f4d7d-e943-40f6-a414-837d3736a1dc` has an active worker connection (`connectionId=2a2246fa-e234-4dc1-8433-87e6cee80145`), while session `565e05fb-4d2a-402b-869b-5b65b1381db7` is free. While a connection is active, no other workers may connect to that session.

### List recent sessions

`playwright.history()` lists recent sessions, both open and closed. It is useful to get a sense of your current usage.

```json
[
	{
		"closeReason": 2,
		"closeReasonText": "BrowserIdle",
		"endTime": 1711621769485,
		"sessionId": "478f4d7d-e943-40f6-a414-837d3736a1dc",
		"startTime": 1711621703708
	},
	{
		"closeReason": 1,
		"closeReasonText": "NormalClosure",
		"endTime": 1711123501771,
		"sessionId": "2be00a21-9fb6-4bb2-9861-8cd48e40e771",
		"startTime": 1711123430918
	}
]
```

Session `2be00a21-9fb6-4bb2-9861-8cd48e40e771` was closed explicitly with `browser.close()` by the client, while session `478f4d7d-e943-40f6-a414-837d3736a1dc` was closed due to reaching the maximum idle time (check [limits](/browser-rendering/platform/limits/)).

You should also be able to access this information in the dashboard, albeit with a slight delay.

### Active limits

`playwright.limits()` lists your active limits:

```json
{
	"activeSessions": [
		{ "id": "478f4d7d-e943-40f6-a414-837d3736a1dc" },
		{ "id": "565e05fb-4d2a-402b-869b-5b65b1381db7" }
	],
	"allowedBrowserAcquisitions": 1,
	"maxConcurrentSessions": 2,
	"timeUntilNextAllowedBrowserAcquisition": 0
}
```

- `activeSessions` lists the IDs of the current open sessions
- `maxConcurrentSessions` defines how many browsers can be open at the same time
- `allowedBrowserAcquisitions` specifies if a new browser session can be opened according to the rate [limits](/browser-rendering/platform/limits/) in place
- `timeUntilNextAllowedBrowserAcquisition` defines the waiting period before a new browser can be launched.

## Playwright API

The full Playwright API can be found at the [Playwright API documentation](https://playwright.dev/docs/api/class-playwright).

Note that `@cloudflare/playwright` is in beta. The following capabilities are not yet fully supported, but we’re actively working on them:

- [API Testing](https://playwright.dev/docs/api-testing)
- [Playwright Test](https://playwright.dev/docs/test-configuration) except [Assertions](https://playwright.dev/docs/test-assertions)
- [Components](https://playwright.dev/docs/test-components)
- [Firefox](https://playwright.dev/docs/api/class-playwright#playwright-firefox), [Android](https://playwright.dev/docs/api/class-android) and [Electron](https://playwright.dev/docs/api/class-electron), as well as different versions of Chrome
- [Network](https://playwright.dev/docs/next/network#network)
- [Videos](https://playwright.dev/docs/next/videos)

This is **not an exhaustive list** — expect rapid changes as we work toward broader parity with the original feature set. You can also check [latest test results](https://playwright-full-test-report.pages.dev/) for a granular up to date list of the features that are fully supported.

---

# Pricing

URL: https://developers.cloudflare.com/browser-rendering/platform/pricing/

Browser Rendering service is currently available at no cost up to the [limits](/browser-rendering/platform/limits/) specified until billing begins. Pricing to be announced and we will provide advance notice before any billing begins.

---

# Puppeteer

URL: https://developers.cloudflare.com/browser-rendering/platform/puppeteer/

import { TabItem, Tabs, PackageManagers } from "~/components";

[Puppeteer](https://pptr.dev/) is one of the most popular libraries that abstract the lower-level DevTools protocol from developers and provides a high-level API that you can use to easily instrument Chrome/Chromium and automate browsing sessions. Puppeteer is used for tasks like creating screenshots, crawling pages, and testing web applications.

Puppeteer typically connects to a local Chrome or Chromium browser using the DevTools port. Refer to the [Puppeteer API documentation on the `Puppeteer.connect()` method](https://pptr.dev/api/puppeteer.puppeteer.connect) for more information.

The Workers team forked a version of Puppeteer and patched it to connect to the Workers Browser Rendering API instead. After connecting, the developers can then use the full [Puppeteer API](https://github.com/cloudflare/puppeteer/blob/main/docs/api/index.md) as they would on a standard setup.

Our version is open sourced and can be found in [Cloudflare's fork of Puppeteer](https://github.com/cloudflare/puppeteer). The npm can be installed from [npmjs](https://www.npmjs.com/) as [@cloudflare/puppeteer](https://www.npmjs.com/package/@cloudflare/puppeteer):

<PackageManagers pkg="@cloudflare/puppeteer" dev />

## Use Puppeteer in a Worker

Once the [browser binding](/browser-rendering/platform/wrangler/#bindings) is configured and the `@cloudflare/puppeteer` library is installed, Puppeteer can be used in a Worker:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import puppeteer from "@cloudflare/puppeteer";

export default {
	async fetch(request, env) {
		const browser = await puppeteer.launch(env.MYBROWSER);
		const page = await browser.newPage();
		await page.goto("https://example.com");
		const metrics = await page.metrics();
		await browser.close();
		return Response.json(metrics);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import puppeteer from "@cloudflare/puppeteer";

interface Env {
	MYBROWSER: Fetcher;
}

export default {
	async fetch(request, env): Promise<Response> {
		const browser = await puppeteer.launch(env.MYBROWSER);
		const page = await browser.newPage();
		await page.goto("https://example.com");
		const metrics = await page.metrics();
		await browser.close();
		return Response.json(metrics);
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

This script [launches](https://pptr.dev/api/puppeteer.puppeteernode.launch) the `env.MYBROWSER` browser, opens a [new page](https://pptr.dev/api/puppeteer.browser.newpage), [goes to](https://pptr.dev/api/puppeteer.page.goto) [https://example.com/](https://example.com/), gets the page load [metrics](https://pptr.dev/api/puppeteer.page.metrics), [closes](https://pptr.dev/api/puppeteer.browser.close) the browser and prints metrics in JSON.

### Keep Alive

If users omit the `browser.close()` statement, it will stay open, ready to be connected to again and [re-used](/browser-rendering/workers-bindings/reuse-sessions/) but it will, by default, close automatically after 1 minute of inactivity. Users can optionally extend this idle time up to 10 minutes, by using the `keep_alive` option, set in milliseconds:

```js
const browser = await puppeteer.launch(env.MYBROWSER, { keep_alive: 600000 });
```

Using the above, the browser will stay open for up to 10 minutes, even if inactive.

## Session management

In order to facilitate browser session management, we've added new methods to `puppeteer`:

### List open sessions

`puppeteer.sessions()` lists the current running sessions. It will return an output similar to this:

```json
[
	{
		"connectionId": "2a2246fa-e234-4dc1-8433-87e6cee80145",
		"connectionStartTime": 1711621704607,
		"sessionId": "478f4d7d-e943-40f6-a414-837d3736a1dc",
		"startTime": 1711621703708
	},
	{
		"sessionId": "565e05fb-4d2a-402b-869b-5b65b1381db7",
		"startTime": 1711621703808
	}
]
```

Notice that the session `478f4d7d-e943-40f6-a414-837d3736a1dc` has an active worker connection (`connectionId=2a2246fa-e234-4dc1-8433-87e6cee80145`), while session `565e05fb-4d2a-402b-869b-5b65b1381db7` is free. While a connection is active, no other workers may connect to that session.

### List recent sessions

`puppeteer.history()` lists recent sessions, both open and closed. It's useful to get a sense of your current usage.

```json
[
	{
		"closeReason": 2,
		"closeReasonText": "BrowserIdle",
		"endTime": 1711621769485,
		"sessionId": "478f4d7d-e943-40f6-a414-837d3736a1dc",
		"startTime": 1711621703708
	},
	{
		"closeReason": 1,
		"closeReasonText": "NormalClosure",
		"endTime": 1711123501771,
		"sessionId": "2be00a21-9fb6-4bb2-9861-8cd48e40e771",
		"startTime": 1711123430918
	}
]
```

Session `2be00a21-9fb6-4bb2-9861-8cd48e40e771` was closed explicitly with `browser.close()` by the client, while session `478f4d7d-e943-40f6-a414-837d3736a1dc` was closed due to reaching the maximum idle time (check [limits](/browser-rendering/platform/limits/)).

You should also be able to access this information in the dashboard, albeit with a slight delay.

### Active limits

`puppeteer.limits()` lists your active limits:

```json
{
	"activeSessions": [
		"478f4d7d-e943-40f6-a414-837d3736a1dc",
		"565e05fb-4d2a-402b-869b-5b65b1381db7"
	],
	"allowedBrowserAcquisitions": 1,
	"maxConcurrentSessions": 2,
	"timeUntilNextAllowedBrowserAcquisition": 0
}
```

- `activeSessions` lists the IDs of the current open sessions
- `maxConcurrentSessions` defines how many browsers can be open at the same time
- `allowedBrowserAcquisitions` specifies if a new browser session can be opened according to the rate [limits](/browser-rendering/platform/limits/) in place
- `timeUntilNextAllowedBrowserAcquisition` defines the waiting period before a new browser can be launched.

## Puppeteer API

The full Puppeteer API can be found in the [Cloudflare's fork of Puppeteer](https://github.com/cloudflare/puppeteer/blob/main/docs/api/index.md).

---

# Automatic request headers

URL: https://developers.cloudflare.com/browser-rendering/reference/automatic-request-headers/

When using the [REST API](/browser-rendering/rest-api/) to fetch content via Browser Rendering, Cloudflare adds the following headers to outbound requests made to the target URL:

| Header               | Description                                                                         |
| -------------------- | ----------------------------------------------------------------------------------- |
| `cf-biso-request-id` | A unique identifier for the Browser Rendering request                               |
| `cf-biso-devtools`   | A flag indicating the request originated from Cloudflare's rendering infrastructure |

:::note[Note]

These headers are unique to Browser Rendering and are automatically included and cannot be removed or overridden (such as via `setExtraHTTPHeaders`). They are intended to ensure transparency, allowing destination servers to identify traffic as coming from Cloudflare Browser Rendering.

:::

---

# Wrangler

URL: https://developers.cloudflare.com/browser-rendering/platform/wrangler/

import { Render, WranglerConfig } from "~/components"

[Wrangler](/workers/wrangler/) is a command-line tool for building with Cloudflare developer products.

Use Wrangler to deploy projects that use the Workers Browser Rendering API.

## Install

To install Wrangler, refer to [Install and Update Wrangler](/workers/wrangler/install-and-update/).

## Bindings

[Bindings](/workers/runtime-apis/bindings/) allow your Workers to interact with resources on the Cloudflare developer platform. A browser binding will provide your Worker with an authenticated endpoint to interact with a dedicated Chromium browser instance.

To deploy a Browser Rendering Worker, you must declare a [browser binding](/workers/runtime-apis/bindings/) in your Worker's Wrangler configuration file.

<Render file="nodejs-compat-howto" product="workers" />

<WranglerConfig>

```toml
# Top-level configuration
name = "browser-rendering"
main = "src/index.ts"
workers_dev = true
compatibility_flags = ["nodejs_compat_v2"]

browser = { binding = "MYBROWSER" }
```

</WranglerConfig>

After the binding is declared, access the DevTools endpoint using `env.MYBROWSER` in your Worker code:

```javascript
const browser = await puppeteer.launch(env.MYBROWSER);
```

Run [`npx wrangler dev --remote`](/workers/wrangler/commands/#dev) to test your Worker remotely before deploying to Cloudflare's global network. Local mode support does not exist for Browser Rendering so `--remote` is required. To deploy, run [`npx wrangler deploy`](/workers/wrangler/commands/#deploy).

---

# Reference

URL: https://developers.cloudflare.com/browser-rendering/reference/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Deploy a Browser Rendering Worker with Durable Objects

URL: https://developers.cloudflare.com/browser-rendering/workers-bindings/browser-rendering-with-do/

import { Render, PackageManagers, WranglerConfig } from "~/components";

By following this guide, you will create a Worker that uses the Browser Rendering API along with [Durable Objects](/durable-objects/) to take screenshots from web pages and store them in [R2](/r2/).

Using Durable Objects to persist browser sessions improves performance by eliminating the time that it takes to spin up a new browser session. Since Durable Objects re-uses sessions, it reduces the number of concurrent sessions needed.

<Render file="prereqs" product="workers" />

## 1. Create a Worker project

[Cloudflare Workers](/workers/) provides a serverless execution environment that allows you to create new applications or augment existing ones without configuring or maintaining infrastructure. Your Worker application is a container to interact with a headless browser to do actions, such as taking screenshots.

Create a new Worker project named `browser-worker` by running:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"browser-worker"}
/>

## 2. Install Puppeteer

In your `browser-worker` directory, install Cloudflare’s [fork of Puppeteer](/browser-rendering/platform/puppeteer/):

<PackageManagers pkg="@cloudflare/puppeteer" dev />

## 3. Create a R2 bucket

Create two R2 buckets, one for production, and one for development.

Note that bucket names must be lowercase and can only contain dashes.

```sh
wrangler r2 bucket create screenshots
wrangler r2 bucket create screenshots-test
```

To check that your buckets were created, run:

```sh
wrangler r2 bucket list
```

After running the `list` command, you will see all bucket names, including the ones you have just created.

## 4. Configure your Wrangler configuration file

Configure your `browser-worker` project's [Wrangler configuration file](/workers/wrangler/configuration/) by adding a browser [binding](/workers/runtime-apis/bindings/) and a [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). Browser bindings allow for communication between a Worker and a headless browser which allows you to do actions such as taking a screenshot, generating a PDF and more.

Update your Wrangler configuration file with the Browser Rendering API binding, the R2 bucket you created and a Durable Object:

<WranglerConfig>

```toml
name = "rendering-api-demo"
main = "src/index.js"
compatibility_date = "2023-09-04"
compatibility_flags = [ "nodejs_compat"]
account_id = "<ACCOUNT_ID>"


# Browser Rendering API binding
browser = { binding = "MYBROWSER" }

# Bind an R2 Bucket
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "screenshots"
preview_bucket_name = "screenshots-test"

# Binding to a Durable Object
[[durable_objects.bindings]]
name = "BROWSER"
class_name = "Browser"

[[migrations]]
tag = "v1" # Should be unique for each entry
new_sqlite_classes = ["Browser"] # Array of new classes

```

</WranglerConfig>

## 5. Code

The code below uses Durable Object to instantiate a browser using Puppeteer. It then opens a series of web pages with different resolutions, takes a screenshot of each, and uploads it to R2.

The Durable Object keeps a browser session open for 60 seconds after last use. If a browser session is open, any requests will re-use the existing session rather than creating a new one. Update your Worker code by copy and pasting the following:

```js
import puppeteer from "@cloudflare/puppeteer";

export default {
	async fetch(request, env) {
		let id = env.BROWSER.idFromName("browser");
		let obj = env.BROWSER.get(id);

		// Send a request to the Durable Object, then await its response.
		let resp = await obj.fetch(request.url);

		return resp;
	},
};

const KEEP_BROWSER_ALIVE_IN_SECONDS = 60;

export class Browser {
	constructor(state, env) {
		this.state = state;
		this.env = env;
		this.keptAliveInSeconds = 0;
		this.storage = this.state.storage;
	}

	async fetch(request) {
		// screen resolutions to test out
		const width = [1920, 1366, 1536, 360, 414];
		const height = [1080, 768, 864, 640, 896];

		// use the current date and time to create a folder structure for R2
		const nowDate = new Date();
		var coeff = 1000 * 60 * 5;
		var roundedDate = new Date(
			Math.round(nowDate.getTime() / coeff) * coeff,
		).toString();
		var folder = roundedDate.split(" GMT")[0];

		//if there's a browser session open, re-use it
		if (!this.browser || !this.browser.isConnected()) {
			console.log(`Browser DO: Starting new instance`);
			try {
				this.browser = await puppeteer.launch(this.env.MYBROWSER);
			} catch (e) {
				console.log(
					`Browser DO: Could not start browser instance. Error: ${e}`,
				);
			}
		}

		// Reset keptAlive after each call to the DO
		this.keptAliveInSeconds = 0;

		const page = await this.browser.newPage();

		// take screenshots of each screen size
		for (let i = 0; i < width.length; i++) {
			await page.setViewport({ width: width[i], height: height[i] });
			await page.goto("https://workers.cloudflare.com/");
			const fileName = "screenshot_" + width[i] + "x" + height[i];
			const sc = await page.screenshot();

			await this.env.BUCKET.put(folder + "/" + fileName + ".jpg", sc);
		}

		// Close tab when there is no more work to be done on the page
		await page.close();

		// Reset keptAlive after performing tasks to the DO.
		this.keptAliveInSeconds = 0;

		// set the first alarm to keep DO alive
		let currentAlarm = await this.storage.getAlarm();
		if (currentAlarm == null) {
			console.log(`Browser DO: setting alarm`);
			const TEN_SECONDS = 10 * 1000;
			await this.storage.setAlarm(Date.now() + TEN_SECONDS);
		}

		return new Response("success");
	}

	async alarm() {
		this.keptAliveInSeconds += 10;

		// Extend browser DO life
		if (this.keptAliveInSeconds < KEEP_BROWSER_ALIVE_IN_SECONDS) {
			console.log(
				`Browser DO: has been kept alive for ${this.keptAliveInSeconds} seconds. Extending lifespan.`,
			);
			await this.storage.setAlarm(Date.now() + 10 * 1000);
			// You could ensure the ws connection is kept alive by requesting something
			// or just let it close automatically when there  is no work to be done
			// for example, `await this.browser.version()`
		} else {
			console.log(
				`Browser DO: exceeded life of ${KEEP_BROWSER_ALIVE_IN_SECONDS}s.`,
			);
			if (this.browser) {
				console.log(`Closing browser.`);
				await this.browser.close();
			}
		}
	}
}
```

## 6. Test

Run [`npx wrangler dev --remote`](/workers/wrangler/commands/#dev) to test your Worker remotely before deploying to Cloudflare's global network. Local mode support does not exist for Browser Rendering so `--remote` is required.

## 7. Deploy

Run [`npx wrangler deploy`](/workers/wrangler/commands/#deploy) to deploy your Worker to the Cloudflare global network.

## Related resources

- Other [Puppeteer examples](https://github.com/cloudflare/puppeteer/tree/main/examples)
- Get started with [Durable Objects](/durable-objects/get-started/)
- [Using R2 from Workers](/r2/api/workers/workers-api-usage/)

---

# Reuse sessions

URL: https://developers.cloudflare.com/browser-rendering/workers-bindings/reuse-sessions/

import { Render, PackageManagers, WranglerConfig } from "~/components";

The best way to improve the performance of your browser rendering Worker is to reuse sessions. One way to do that is via [Durable Objects](/browser-rendering/workers-bindings/browser-rendering-with-do/), which allows you to keep a long running connection from a Worker to a browser. Another way is to keep the browser open after you've finished with it, and connect to that session each time you have a new request.

In short, this entails using `browser.disconnect()` instead of `browser.close()`, and, if there are available sessions, using `puppeteer.connect(env.MY_BROWSER, sessionID)` instead of launching a new browser session.

## 1. Create a Worker project

[Cloudflare Workers](/workers/) provides a serverless execution environment that allows you to create new applications or augment existing ones without configuring or maintaining infrastructure. Your Worker application is a container to interact with a headless browser to do actions, such as taking screenshots.

Create a new Worker project named `browser-worker` by running:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"browser-worker"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

## 2. Install Puppeteer

In your `browser-worker` directory, install Cloudflare's [fork of Puppeteer](/browser-rendering/platform/puppeteer/):

<PackageManagers pkg="@cloudflare/puppeteer" dev />

## 3. Configure the [Wrangler configuration file](/workers/wrangler/configuration/)

<WranglerConfig>

```toml
name = "browser-worker"
main = "src/index.ts"
compatibility_date = "2023-03-14"
compatibility_flags = [ "nodejs_compat" ]

browser = { binding = "MYBROWSER" }

```

</WranglerConfig>

## 4. Code

The script below starts by fetching the current running sessions. If there are any that don't already have a worker connection, it picks a random session ID and attempts to connect (`puppeteer.connect(..)`) to it. If that fails or there were no running sessions to start with, it launches a new browser session (`puppeteer.launch(..)`). Then, it goes to the website and fetches the dom. Once that's done, it disconnects (`browser.disconnect()`), making the connection available to other workers.

Take into account that if the browser is idle, i.e. does not get any command, for more than the current [limit](/browser-rendering/platform/limits/), it will close automatically, so you must have enough requests per minute to keep it alive.

```ts
import puppeteer from "@cloudflare/puppeteer";

interface Env {
	MYBROWSER: Fetcher;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		let reqUrl = url.searchParams.get("url") || "https://example.com";
		reqUrl = new URL(reqUrl).toString(); // normalize

		// Pick random session from open sessions
		let sessionId = await this.getRandomSession(env.MYBROWSER);
		let browser, launched;
		if (sessionId) {
			try {
				browser = await puppeteer.connect(env.MYBROWSER, sessionId);
			} catch (e) {
				// another worker may have connected first
				console.log(`Failed to connect to ${sessionId}. Error ${e}`);
			}
		}
		if (!browser) {
			// No open sessions, launch new session
			browser = await puppeteer.launch(env.MYBROWSER);
			launched = true;
		}

		sessionId = browser.sessionId(); // get current session id

		// Do your work here
		const page = await browser.newPage();
		const response = await page.goto(reqUrl);
		const html = await response!.text();

		// All work done, so free connection (IMPORTANT!)
		browser.disconnect();

		return new Response(
			`${launched ? "Launched" : "Connected to"} ${sessionId} \n-----\n` + html,
			{
				headers: {
					"content-type": "text/plain",
				},
			},
		);
	},

	// Pick random free session
	// Other custom logic could be used instead
	async getRandomSession(endpoint: puppeteer.BrowserWorker): Promise<string> {
		const sessions: puppeteer.ActiveSession[] =
			await puppeteer.sessions(endpoint);
		console.log(`Sessions: ${JSON.stringify(sessions)}`);
		const sessionsIds = sessions
			.filter((v) => {
				return !v.connectionId; // remove sessions with workers connected to them
			})
			.map((v) => {
				return v.sessionId;
			});
		if (sessionsIds.length === 0) {
			return;
		}

		const sessionId =
			sessionsIds[Math.floor(Math.random() * sessionsIds.length)];

		return sessionId!;
	},
};
```

Besides `puppeteer.sessions()`, we have added other methods to facilitate [Session Management](/browser-rendering/platform/puppeteer/#session-management).

## 5. Test

Run [`npx wrangler dev --remote`](/workers/wrangler/commands/#dev) to test your Worker remotely before deploying to Cloudflare's global network. Local mode support does not exist for Browser Rendering so `--remote` is required.

To test go to the following URL:

`<LOCAL_HOST_URL>/?url=https://example.com`

## 6. Deploy

Run `npx wrangler deploy` to deploy your Worker to the Cloudflare global network and then to go to the following URL:

`<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/?url=https://example.com`

---

# Workers Bindings

URL: https://developers.cloudflare.com/browser-rendering/workers-bindings/

import { DirectoryListing } from "~/components";

Workers Bindings allow you to execute advanced browser rendering scripts within Cloudflare Workers. They provide developers the flexibility to automate and control complex workflows and browser interactions. The following options are available for browser rendering tasks:

<DirectoryListing />

Use Workers Bindings when you need advanced browser automation, custom workflows, or complex interactions beyond basic rendering. For quick, one-off tasks like capturing screenshots or extracting HTML, the [REST API](/browser-rendering/rest-api/) is the simpler choice.

---

# Deploy a Browser Rendering Worker

URL: https://developers.cloudflare.com/browser-rendering/workers-bindings/screenshots/

import {
	Render,
	TabItem,
	Tabs,
	PackageManagers,
	WranglerConfig,
} from "~/components";

By following this guide, you will create a Worker that uses the Browser Rendering API to take screenshots from web pages. This is a common use case for browser automation.

<Render file="prereqs" product="workers" />

## 1. Create a Worker project

[Cloudflare Workers](/workers/) provides a serverless execution environment that allows you to create new applications or augment existing ones without configuring or maintaining infrastructure. Your Worker application is a container to interact with a headless browser to do actions, such as taking screenshots.

Create a new Worker project named `browser-worker` by running:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"browser-worker"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript / TypeScript",
	}}
/>

## 2. Install Puppeteer

In your `browser-worker` directory, install Cloudflare’s [fork of Puppeteer](/browser-rendering/platform/puppeteer/):

<PackageManagers pkg="@cloudflare/puppeteer" dev />

## 3. Create a KV namespace

Browser Rendering can be used with other developer products. You might need a [relational database](/d1/), an [R2 bucket](/r2/) to archive your crawled pages and assets, a [Durable Object](/durable-objects/) to keep your browser instance alive and share it with multiple requests, or [Queues](/queues/) to handle your jobs asynchronous.

For the purpose of this guide, you are going to use a [KV store](/kv/concepts/kv-namespaces/) to cache your screenshots.

Create two namespaces, one for production, and one for development.

```sh
npx wrangler kv namespace create BROWSER_KV_DEMO
npx wrangler kv namespace create BROWSER_KV_DEMO --preview
```

Take note of the IDs for the next step.

## 4. Configure the Wrangler configuration file

Configure your `browser-worker` project's [Wrangler configuration file](/workers/wrangler/configuration/) by adding a browser [binding](/workers/runtime-apis/bindings/) and a [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). Bindings allow your Workers to interact with resources on the Cloudflare developer platform. Your browser `binding` name is set by you, this guide uses the name `MYBROWSER`. Browser bindings allow for communication between a Worker and a headless browser which allows you to do actions such as taking a screenshot, generating a PDF and more.

Update your [Wrangler configuration file](/workers/wrangler/configuration/) with the Browser Rendering API binding and the KV namespaces you created:

<WranglerConfig>

```toml title="wrangler.toml"
name = "browser-worker"
main = "src/index.js"
compatibility_date = "2023-03-14"
compatibility_flags = [ "nodejs_compat" ]

browser = { binding = "MYBROWSER" }
kv_namespaces = [
  { binding = "BROWSER_KV_DEMO", id = "22cf855786094a88a6906f8edac425cd", preview_id = "e1f8b68b68d24381b57071445f96e623" }
]
```

</WranglerConfig>

## 5. Code

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">
Update `src/index.js` with your Worker code:

```js
import puppeteer from "@cloudflare/puppeteer";

export default {
	async fetch(request, env) {
		const { searchParams } = new URL(request.url);
		let url = searchParams.get("url");
		let img;
		if (url) {
			url = new URL(url).toString(); // normalize
			img = await env.BROWSER_KV_DEMO.get(url, { type: "arrayBuffer" });
			if (img === null) {
				const browser = await puppeteer.launch(env.MYBROWSER);
				const page = await browser.newPage();
				await page.goto(url);
				img = await page.screenshot();
				await env.BROWSER_KV_DEMO.put(url, img, {
					expirationTtl: 60 * 60 * 24,
				});
				await browser.close();
			}
			return new Response(img, {
				headers: {
					"content-type": "image/jpeg",
				},
			});
		} else {
			return new Response("Please add an ?url=https://example.com/ parameter");
		}
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">
Update `src/index.ts` with your Worker code:

```ts
import puppeteer from "@cloudflare/puppeteer";

interface Env {
	MYBROWSER: Fetcher;
	BROWSER_KV_DEMO: KVNamespace;
}

export default {
	async fetch(request, env): Promise<Response> {
		const { searchParams } = new URL(request.url);
		let url = searchParams.get("url");
		let img: Buffer;
		if (url) {
			url = new URL(url).toString(); // normalize
			img = await env.BROWSER_KV_DEMO.get(url, { type: "arrayBuffer" });
			if (img === null) {
				const browser = await puppeteer.launch(env.MYBROWSER);
				const page = await browser.newPage();
				await page.goto(url);
				img = (await page.screenshot()) as Buffer;
				await env.BROWSER_KV_DEMO.put(url, img, {
					expirationTtl: 60 * 60 * 24,
				});
				await browser.close();
			}
			return new Response(img, {
				headers: {
					"content-type": "image/jpeg",
				},
			});
		} else {
			return new Response("Please add an ?url=https://example.com/ parameter");
		}
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

This Worker instantiates a browser using Puppeteer, opens a new page, navigates to what you put in the `"url"` parameter, takes a screenshot of the page, stores the screenshot in KV, closes the browser, and responds with the JPEG image of the screenshot.

If your Worker is running in production, it will store the screenshot to the production KV namespace. If you are running `wrangler dev`, it will store the screenshot to the dev KV namespace.

If the same `"url"` is requested again, it will use the cached version in KV instead, unless it expired.

## 6. Test

Run [`npx wrangler dev --remote`](/workers/wrangler/commands/#dev) to test your Worker remotely before deploying to Cloudflare's global network. Local mode support does not exist for Browser Rendering so `--remote` is required.

To test taking your first screenshot, go to the following URL:

`<LOCAL_HOST_URL>/?url=https://example.com`

## 7. Deploy

Run `npx wrangler deploy` to deploy your Worker to the Cloudflare global network.

To take your first screenshot, go to the following URL:

`<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/?url=https://example.com`

## Related resources

- Other [Puppeteer examples](https://github.com/cloudflare/puppeteer/tree/main/examples)

---

# /content - Fetch HTML

URL: https://developers.cloudflare.com/browser-rendering/rest-api/content-endpoint/

import { Tabs, TabItem } from "~/components";

The `/content` endpoint instructs the browser to navigate to a website and capture the fully rendered HTML of a page, including the `head` section, after JavaScript execution. This is ideal for capturing content from JavaScript-heavy or interactive websites.

## Basic usage

<Tabs syncKey="workersExamples"> <TabItem label="curl">

Go to `https://example.com` and return the rendered HTML.

```bash
curl -X 'POST' 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/content' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <apiToken>' \
  -d '{"url": "https://example.com"}'
```

</TabItem> <TabItem label="TypeScript SDK">

```typescript
import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiEmail: process.env["CLOUDFLARE_EMAIL"], // This is the default and can be omitted
	apiKey: process.env["CLOUDFLARE_API_KEY"], // This is the default and can be omitted
});

const content = await client.browserRendering.content.create({
	account_id: "account_id",
});

console.log(content);
```

</TabItem> </Tabs>

## Advanced usage

Navigate to `https://cloudflare.com/` but block images and stylesheets from loading. Undesired requests can be blocked by resource type (`rejectResourceTypes`) or by using a regex pattern (`rejectRequestPattern`). The opposite can also be done, only allow requests that match `allowRequestPattern` or `allowResourceTypes`.

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/content' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
      "url": "https://cloudflare.com/",
      "rejectResourceTypes": ["image"],
      "rejectRequestPattern": ["/^.*\\.(css)"]
		}'

```

Many more options exist, like setting HTTP headers using `setExtraHTTPHeaders`, setting `cookies`, and using `gotoOptions` to control page load behaviour - check the endpoint [reference](/api/resources/browser_rendering/subresources/content/methods/create/) for all available parameters.

---

# REST API

URL: https://developers.cloudflare.com/browser-rendering/rest-api/

The REST API is a RESTful interface that provides endpoints for common browser actions such as capturing screenshots, extracting HTML content, generating PDFs, and more.
The following are the available options:

import { DirectoryListing } from "~/components";

<DirectoryListing />

Use the REST API when you need a fast, simple way to perform common browser tasks such as capturing screenshots, extracting HTML, or generating PDFs without writing complex scripts. If you require more advanced automation, custom workflows, or persistent browser sessions, [Workers Bindings](/browser-rendering/workers-bindings/) are the better choice.

## Before you begin

Before you begin, make sure you [create a custom API Token](/fundamentals/api/get-started/create-token/) with the following permissions:

- `Browser Rendering - Edit`

:::note[Note]

Currently, the Cloudflare dashboard displays usage metrics exclusively for the [Workers Bindings method](/browser-rendering/workers-bindings/). Usage data for the REST API is not yet available in the dashboard. We are actively working on adding REST API usage metrics to the dashboard.

:::

---

# /json - Capture structured data

URL: https://developers.cloudflare.com/browser-rendering/rest-api/json-endpoint/

import { Tabs, TabItem } from "~/components";

The `/json` endpoint extracts structured data from a webpage. You can specify the expected output using either a `prompt` or a `response_format` parameter which accepts a JSON schema. The endpoint returns the extracted data in JSON format.

:::note[Note]

The `/json` endpoint leverages [Workers AI](/workers-ai/) for data extraction. Using this endpoint incurs usage on Workers AI, which you can monitor usage through the Workers AI Dashboard.

:::

## Basic Usage

<Tabs syncKey="workersExamples"> <TabItem label="curl">

### With a Prompt and JSON schema

This example captures webpage data by providing both a prompt and a JSON schema. The prompt guides the extraction process, while the JSON schema defines the expected structure of the output.

```bash
curl --request POST 'https://api.cloudflare.com/client/v4/accounts/CF_ACCOUNT_ID/browser-rendering/json' \
  --header 'authorization: Bearer CF_API_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
  "url": "https://developers.cloudflare.com/",
  "prompt": "Get me the list of AI products",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
        "type": "object",
        "properties": {
          "products": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "link": {
                  "type": "string"
                }
              },
              "required": [
                "name"
              ]
            }
          }
        }
      }
  }
}'
```

```json output collapse={15-48}
{
	"success": true,
	"result": {
		"products": [
			{
				"name": "Build a RAG app",
				"link": "https://developers.cloudflare.com/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai/"
			},
			{
				"name": "Workers AI",
				"link": "https://developers.cloudflare.com/workers-ai/"
			},
			{
				"name": "Vectorize",
				"link": "https://developers.cloudflare.com/vectorize/"
			},
			{
				"name": "AI Gateway",
				"link": "https://developers.cloudflare.com/ai-gateway/"
			},
			{
				"name": "AI Playground",
				"link": "https://playground.ai.cloudflare.com/"
			}
		]
	}
}
```

### With only a prompt

In this example, only a prompt is provided. The endpoint will use the prompt to extract the data, but the response will not be structured according to a JSON schema.
This is useful for simple extractions where you do not need a specific format.

```bash
curl --request POST 'https://api.cloudflare.com/client/v4/accounts/CF_ACCOUNT_ID/browser-rendering/json' \
  --header 'authorization: Bearer CF_API_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "url": "https://developers.cloudflare.com/",
    "prompt": "get me the list of AI products"
  }'
```

```json output

	"success": true,
	"result": {
		"AI Products": [
			"Build a RAG app",
			"Workers AI",
			"Vectorize",
			"AI Gateway",
			"AI Playground"
		]
	}
}
```

### With only a JSON schema (no prompt)

In this case, you supply a JSON schema via the `response_format` parameter. The schema defines the structure of the extracted data.

```bash
curl --request POST 'https://api.cloudflare.com/client/v4/accounts/CF_ACCOUNT_ID/browser-rendering/json' \
  --header 'authorization: Bearer CF_API_TOKEN' \
  --header 'content-type: application/json' \
  --data '"response_format": {
    "type": "json_schema",
    "json_schema": {
        "type": "object",
        "properties": {
          "products": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "link": {
                  "type": "string"
                }
              },
              "required": [
                "name"
              ]
            }
          }
        }
      }
  }'
```

```json output collapse={13-68}
{
	"success": true,
	"result": {
		"products": [
			{
				"name": "Workers",
				"link": "https://developers.cloudflare.com/workers/"
			},
			{
				"name": "Pages",
				"link": "https://developers.cloudflare.com/pages/"
			},
			{
				"name": "R2",
				"link": "https://developers.cloudflare.com/r2/"
			},
			{
				"name": "Images",
				"link": "https://developers.cloudflare.com/images/"
			},
			{
				"name": "Stream",
				"link": "https://developers.cloudflare.com/stream/"
			},
			{
				"name": "Build a RAG app",
				"link": "https://developers.cloudflare.com/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai/"
			},
			{
				"name": "Workers AI",
				"link": "https://developers.cloudflare.com/workers-ai/"
			},
			{
				"name": "Vectorize",
				"link": "https://developers.cloudflare.com/vectorize/"
			},
			{
				"name": "AI Gateway",
				"link": "https://developers.cloudflare.com/ai-gateway/"
			},
			{
				"name": "AI Playground",
				"link": "https://playground.ai.cloudflare.com/"
			},
			{
				"name": "Access",
				"link": "https://developers.cloudflare.com/cloudflare-one/policies/access/"
			},
			{
				"name": "Tunnel",
				"link": "https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/"
			},
			{
				"name": "Gateway",
				"link": "https://developers.cloudflare.com/cloudflare-one/policies/gateway/"
			},
			{
				"name": "Browser Isolation",
				"link": "https://developers.cloudflare.com/cloudflare-one/policies/browser-isolation/"
			},
			{
				"name": "Replace your VPN",
				"link": "https://developers.cloudflare.com/learning-paths/replace-vpn/concepts/"
			}
		]
	}
}
```

</TabItem> <TabItem label="TypeScript SDK">

Below is an example using the TypeScript SDK:

```typescript
import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiEmail: process.env["CLOUDFLARE_EMAIL"], // This is the default and can be omitted
	apiKey: process.env["CLOUDFLARE_API_KEY"], // This is the default and can be omitted
});

const json = await client.browserRendering.json.create({
	account_id: "account_id",
});

console.log(json);
```

</TabItem> </Tabs>

---

# /links - Retrieve links from a webpage

URL: https://developers.cloudflare.com/browser-rendering/rest-api/links-endpoint/

import { Tabs, TabItem } from "~/components";

The `/links` endpoint retrieves all links from a webpage. It can be used to extract all links from a page, including those that are hidden.

## Basic usage

<Tabs syncKey="workersExamples"> <TabItem label="curl">

This example grabs all links from the Cloudflare Developers homepage.
The response will be a JSON array containing the links found on the page.

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/links' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://developers.cloudflare.com/"
  }'
```

```json output collapse={12-80}
{
	"success": true,
	"result": [
		"https://developers.cloudflare.com/",
		"https://developers.cloudflare.com/products/",
		"https://developers.cloudflare.com/api/",
		"https://developers.cloudflare.com/fundamentals/api/reference/sdks/",
		"https://dash.cloudflare.com/",
		"https://developers.cloudflare.com/fundamentals/subscriptions-and-billing/",
		"https://developers.cloudflare.com/api/",
		"https://developers.cloudflare.com/changelog/",
		"https://developers.cloudflare.com/glossary/",
		"https://developers.cloudflare.com/reference-architecture/",
		"https://developers.cloudflare.com/web-analytics/",
		"https://developers.cloudflare.com/support/troubleshooting/http-status-codes/",
		"https://developers.cloudflare.com/registrar/",
		"https://developers.cloudflare.com/1.1.1.1/setup/",
		"https://developers.cloudflare.com/workers/",
		"https://developers.cloudflare.com/pages/",
		"https://developers.cloudflare.com/r2/",
		"https://developers.cloudflare.com/images/",
		"https://developers.cloudflare.com/stream/",
		"https://developers.cloudflare.com/products/?product-group=Developer+platform",
		"https://developers.cloudflare.com/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai/",
		"https://developers.cloudflare.com/workers-ai/",
		"https://developers.cloudflare.com/vectorize/",
		"https://developers.cloudflare.com/ai-gateway/",
		"https://playground.ai.cloudflare.com/",
		"https://developers.cloudflare.com/products/?product-group=AI",
		"https://developers.cloudflare.com/cloudflare-one/policies/access/",
		"https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/",
		"https://developers.cloudflare.com/cloudflare-one/policies/gateway/",
		"https://developers.cloudflare.com/cloudflare-one/policies/browser-isolation/",
		"https://developers.cloudflare.com/learning-paths/replace-vpn/concepts/",
		"https://developers.cloudflare.com/products/?product-group=Cloudflare+One",
		"https://workers.cloudflare.com/playground#LYVwNgLglgDghgJwgegGYHsHALQBM4RwDcABAEbogB2+CAngLzbPYZb6HbW5QDGU2AAwAmAIyiAzMIAsATlmi5ALhYs2wDnC40+AkeKlyFcgLAAoAMLoqEAKY3sAESgBnGOhdRo1pSXV4CYhIqOGBbBgAiKBpbAA8AOgArFwjSVCgwe1DwqJiE5IjzKxt7CGwAFToYW184GBgwPgIoa2REuAA3OBdeBFgIAGpgdFxwW3NzOPckElxbVDhwCBIAbzMSEm66Kl4-WwheAAsACgRbAEcQWxcIAEpV9Y2SXmsbkkOIYDASBhIAAwAPABCRwAeQs5QAmgAFACi70+YAAfI8NgCKLg6Cink8AYdREiABK2MBgdAkADqmDAuAByHx2JxJABMCR5UOrhIwEQAGsQDASAB3bokADm9lsCAItlw5DomxIFjJIFwqDAiFslMwPMl8TprNRzOQGKxfyIZkNZwgIAQVGCtkFJAAStd3FQXLZjh8vgAaB5M962OBzBAuXxrAMbCIvEoOCBVWwRXwROyxFDesBEI6ID0QBgAVXKADFsAAOCI+w0bAC+lZx1du5prlerRHMqmY6k02h4-CEYkkMnkilkRWsdgczjcHi8LSovn8mlIITCkTChE0qT8GSyq4iZDJZEKlnHpQqCdq9UavGarWS1gmZhWEW50QA+sNRpkk7k5vkUtW7Ydl2gQ9ro-YGEOxiyMwQA",
		"https://workers.cloudflare.com/playground#LYVwNgLglgDghgJwgegGYHsHALQBM4RwDcABAEbogB2+CAngLzbPYZb6HbW5QDGU2AAwB2AMwAWAKyCAjMICc8meIBcLFm2Ac4XGnwEiJ0uYuUBYAFABhdFQgBTO9gAiUAM4x0bqNFsqSmngExCRUcMD2DABEUDT2AB4AdABWblGkqFBgjuGRMXFJqVGWNnaOENgAKnQw9v5wMDBgfARQtsjJcABucG68CLAQANTA6Ljg9paWCZ5IJLj2qHDgECQA3hYkJL10VLwB9hC8ABYAFAj2AI4g9m4QAJTrm1skvLZ388EkDE8vL8f2MBgdD+KIAd0wYFwUQANM8tgBfIgWeEkC4QEAIKgkABKt08VDc9hSblsp2092RiLhSMs6mYmm0uh4-CEYiksgUSnEJVsDicrg8Xh8bSo-kC2lIYQi0QihG06QCWRyMqiZGBZGK1j55SqNTq20azV4rXaqVsUwsayiwDgsQA+qNxtkoip8gtCmkEXT6Yzgsz9GyjJzTOJmEA",
		"https://workers.cloudflare.com/playground#LYVwNgLglgDghgJwgegGYHsHALQBM4RwDcABAEbogB2+CAngLzbPYZb6HbW5QDGU2AAwBWABwBGAOyjRANgDMAFgCcygFwsWbYBzhcafASInS5S1QFgAUAGF0VCAFMH2ACJQAzjHQeo0e2ok2ngExCRUcMCODABEUDSOAB4AdABWHjGkqFBgzpHRcQkp6THWdg7OENgAKnQwjoFwMDBgfARQ9sipcABucB68CLAQANTA6LjgjtbWSd5IJLiOqHDgECQA3lYkJP10VLxBjhC8ABYAFAiOAI4gjh4QAJSb2zskyABUH69vHyQASo4WnBeI4SAADK7jJzgkgAdz8pxIEFOYNOPnWdEo8M8SIg6BIHmcuBIV1u9wgHmR6B+Ow+yFpvHsD1JjmhYIYJBipwgEBgHjUyGQSUiLUcySZwEyVlpVwgIAQVF2cLgfiOJwuUPQTgANKzyQ9HkRXgBfHVWE1EayaZjaXT6Hj8IRiKQyBQqZRlexOFzuLw+PwdKiBYK6UgRKKxKKEXSZII5PKRmJkMDoMilWzeyo1OoNXbNVq8dqddL2GZWDYxYCqqgAfXGk1yMTUhSWxQyJutNrtoQdhmdJjd5mUzCAA",
		"https://workers.cloudflare.com/playground#LYVwNgLglgDghgJwgegGYHsHALQBM4RwDcABAEbogB2+CAngLzbPYZb6HbW5QDGU2AAwBmACyiAnBMFSAbIICMALhYs2wDnC40+AkeKkyJ8hQFgAUAGF0VCAFNb2ACJQAzjHSuo0G0pLq8AmISKjhgOwYAIigaOwAPADoAK1dI0lQoMAcwiOjYxJTIi2tbBwhsABU6GDs-OBgYMD4CKBtkJLgANzhXXgRYCABqYHRccDsLC3iPJBJcO1Q4cAgSAG9zEhIeuipefzsIXgALAAoEOwBHEDtXCABKNY3Nkl4bW7mb6FCfKgBVACUADIkBgkSJHCAQGCuJTIZDxMKNOwJV7ANJPTavKjvW4EECuazzEEkYSKIgYkjnCAgBBUEj-G4ebHI848c68CAnea3GItGwAwEAGhIuOpBNGdju5M2AF9BeYZUQLKpmOpNNoePwhGJJNI5IpijZ7I4XO5PN5WlQ-AFNKRQuEouFCJo0v5MtkHZEyGB0GQilYjWVKtValsGk1eHyqO1XDZJuZVpFgHAYgB9EZjLKRJR5eYFVIy5UqtVBDW6bUGPXGRTMIA",
		"https://workers.cloudflare.com/playground#LYVwNgLglgDghgJwgegGYHsHALQBM4RwDcABAEbogB2+CAngLzbPYZb6HbW5QDGU2AAwAOAJwBmAIyiATKMkB2AKwyAXCxZtgHOFxp8BIidLmKVAWABQAYXRUIAU3vYAIlADOMdO6jQ7qki08AmISKjhgBwYAIigaBwAPADoAK3do0lQoMCcIqNj45LToq1t7JwhsABU6GAcAuBgYMD4CKDtkFLgANzh3XgRYCABqYHRccAcrK0SvJBJcB1Q4cAgSAG9LEhI+uipeQIcIXgALAAoEBwBHEAd3CABKDa3tnfc9g9RqXj8qEgBZI4ncYAOXQEAAgmAwOgAO4OXAXa63e5PTavV6XCAgBB-KgOWEkABKdy8VHcDjOAANARBgbgSAASdaXG53CBJSJ08YAXzC4J20LhCKSVIANM8MRj7gQQO4AgAWQRKMUvKUkE4OOCLBDyyXq15QmGwgLRADiAFEqtFVQaSDzbVKeQ8iGr7W7kMgSAB5KhgOgkS1VEislEQdwkWGYADWkd8JxIdI8JBgCHQCToSTdUFQJCRbPunKB4xIAEIGAwSOardEnlicX9afSwZChfDEaH2S63fXcYdjucqScIBAYPLPYkIs0HEleOhgFTu9sHZYeUQrBpmFodHoePwhGIpLJ5MoZKU7I5nG5PN5fO0qAEgjpSOFIjEudqQhlAtlcm-omQMJkCUNgXhU1S1PUOxNC0vBtB0aR2NMljrNEwBwHEAD6YwTDk0SqAUixFOkPIbpu24hLuBgHsYx5mDIzBAA",
		"https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/",
		"https://developers.cloudflare.com/ssl/origin-configuration/origin-ca/",
		"https://developers.cloudflare.com/dns/zone-setups/full-setup/setup/",
		"https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/",
		"https://developers.cloudflare.com/waf/custom-rules/use-cases/allow-traffic-from-specific-countries/",
		"https://discord.cloudflare.com/",
		"https://x.com/CloudflareDev",
		"https://community.cloudflare.com/",
		"https://github.com/cloudflare",
		"https://developers.cloudflare.com/sponsorships/",
		"https://developers.cloudflare.com/style-guide/",
		"https://blog.cloudflare.com/",
		"https://developers.cloudflare.com/fundamentals/",
		"https://support.cloudflare.com/",
		"https://www.cloudflarestatus.com/",
		"https://www.cloudflare.com/trust-hub/compliance-resources/",
		"https://www.cloudflare.com/trust-hub/gdpr/",
		"https://www.cloudflare.com/",
		"https://www.cloudflare.com/people/",
		"https://www.cloudflare.com/careers/",
		"https://radar.cloudflare.com/",
		"https://speed.cloudflare.com/",
		"https://isbgpsafeyet.com/",
		"https://rpki.cloudflare.com/",
		"https://ct.cloudflare.com/",
		"https://x.com/cloudflare",
		"http://discord.cloudflare.com/",
		"https://www.youtube.com/cloudflare",
		"https://github.com/cloudflare/cloudflare-docs",
		"https://www.cloudflare.com/privacypolicy/",
		"https://www.cloudflare.com/website-terms/",
		"https://www.cloudflare.com/disclosure/",
		"https://www.cloudflare.com/trademark/"
	]
}
```

</TabItem> <TabItem label="TypeScript SDK">

```typescript
import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiEmail: process.env["CLOUDFLARE_EMAIL"], // This is the default and can be omitted
	apiKey: process.env["CLOUDFLARE_API_KEY"], // This is the default and can be omitted
});

const links = await client.browserRendering.links.create({
	account_id: "account_id",
});

console.log(links);
```

</TabItem> </Tabs>
## Advanced usage

In this example we can pass a `visibleLinksOnly` parameter to only return links that are visible on the page.

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/links' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://developers.cloudflare.com/",
    "visibleLinksOnly": true
  }'
```

```json output collapse={12-80}
{
	"success": true,
	"result": [
		"https://developers.cloudflare.com/",
		"https://developers.cloudflare.com/products/",
		"https://developers.cloudflare.com/api/",
		"https://developers.cloudflare.com/fundamentals/api/reference/sdks/",
		"https://dash.cloudflare.com/",
		"https://developers.cloudflare.com/fundamentals/subscriptions-and-billing/",
		"https://developers.cloudflare.com/api/",
		"https://developers.cloudflare.com/changelog/",
		"https://developers.cloudflare.com/glossary/",
		"https://developers.cloudflare.com/reference-architecture/",
		"https://developers.cloudflare.com/web-analytics/",
		"https://developers.cloudflare.com/support/troubleshooting/http-status-codes/",
		"https://developers.cloudflare.com/registrar/",
		"https://developers.cloudflare.com/1.1.1.1/setup/",
		"https://developers.cloudflare.com/workers/",
		"https://developers.cloudflare.com/pages/",
		"https://developers.cloudflare.com/r2/",
		"https://developers.cloudflare.com/images/",
		"https://developers.cloudflare.com/stream/",
		"https://developers.cloudflare.com/products/?product-group=Developer+platform",
		"https://developers.cloudflare.com/workers-ai/tutorials/build-a-retrieval-augmented-generation-ai/",
		"https://developers.cloudflare.com/workers-ai/",
		"https://developers.cloudflare.com/vectorize/",
		"https://developers.cloudflare.com/ai-gateway/",
		"https://playground.ai.cloudflare.com/",
		"https://developers.cloudflare.com/products/?product-group=AI",
		"https://developers.cloudflare.com/cloudflare-one/policies/access/",
		"https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/",
		"https://developers.cloudflare.com/cloudflare-one/policies/gateway/",
		"https://developers.cloudflare.com/cloudflare-one/policies/browser-isolation/",
		"https://developers.cloudflare.com/learning-paths/replace-vpn/concepts/",
		"https://developers.cloudflare.com/products/?product-group=Cloudflare+One",
		"https://workers.cloudflare.com/playground#LYVwNgLglgDghgJwgegGYHsHALQBM4RwDcABAEbogB2+CAngLzbPYZb6HbW5QDGU2AAwAmAIyiAzMIAsATlmi5ALhYs2wDnC40+AkeKlyFcgLAAoAMLoqEAKY3sAESgBnGOhdRo1pSXV4CYhIqOGBbBgAiKBpbAA8AOgArFwjSVCgwe1DwqJiE5IjzKxt7CGwAFToYW184GBgwPgIoa2REuAA3OBdeBFgIAGpgdFxwW3NzOPckElxbVDhwCBIAbzMSEm66Kl4-WwheAAsACgRbAEcQWxcIAEpV9Y2SXmsbkkOIYDASBhIAAwAPABCRwAeQs5QAmgAFACi70+YAAfI8NgCKLg6Cink8AYdREiABK2MBgdAkADqmDAuAByHx2JxJABMCR5UOrhIwEQAGsQDASAB3bokADm9lsCAItlw5DomxIFjJIFwqDAiFslMwPMl8TprNRzOQGKxfyIZkNZwgIAQVGCtkFJAAStd3FQXLZjh8vgAaB5M962OBzBAuXxrAMbCIvEoOCBVWwRXwROyxFDesBEI6ID0QBgAVXKADFsAAOCI+w0bAC+lZx1du5prlerRHMqmY6k02h4-CEYkkMnkilkRWsdgczjcHi8LSovn8mlIITCkTChE0qT8GSyq4iZDJZEKlnHpQqCdq9UavGarWS1gmZhWEW50QA+sNRpkk7k5vkUtW7Ydl2gQ9ro-YGEOxiyMwQA",
		"https://workers.cloudflare.com/playground#LYVwNgLglgDghgJwgegGYHsHALQBM4RwDcABAEbogB2+CAngLzbPYZb6HbW5QDGU2AAwB2AMwAWAKyCAjMICc8meIBcLFm2Ac4XGnwEiJ0uYuUBYAFABhdFQgBTO9gAiUAM4x0bqNFsqSmngExCRUcMD2DABEUDT2AB4AdABWblGkqFBgjuGRMXFJqVGWNnaOENgAKnQw9v5wMDBgfARQtsjJcABucG68CLAQANTA6Ljg9paWCZ5IJLj2qHDgECQA3hYkJL10VLwB9hC8ABYAFAj2AI4g9m4QAJTrm1skvLZ388EkDE8vL8f2MBgdD+KIAd0wYFwUQANM8tgBfIgWeEkC4QEAIKgkABKt08VDc9hSblsp2092RiLhSMs6mYmm0uh4-CEYiksgUSnEJVsDicrg8Xh8bSo-kC2lIYQi0QihG06QCWRyMqiZGBZGK1j55SqNTq20azV4rXaqVsUwsayiwDgsQA+qNxtkoip8gtCmkEXT6Yzgsz9GyjJzTOJmEA",
		"https://workers.cloudflare.com/playground#LYVwNgLglgDghgJwgegGYHsHALQBM4RwDcABAEbogB2+CAngLzbPYZb6HbW5QDGU2AAwBWABwBGAOyjRANgDMAFgCcygFwsWbYBzhcafASInS5S1QFgAUAGF0VCAFMH2ACJQAzjHQeo0e2ok2ngExCRUcMCODABEUDSOAB4AdABWHjGkqFBgzpHRcQkp6THWdg7OENgAKnQwjoFwMDBgfARQ9sipcABucB68CLAQANTA6LjgjtbWSd5IJLiOqHDgECQA3lYkJP10VLxBjhC8ABYAFAiOAI4gjh4QAJSb2zskyABUH69vHyQASo4WnBeI4SAADK7jJzgkgAdz8pxIEFOYNOPnWdEo8M8SIg6BIHmcuBIV1u9wgHmR6B+Ow+yFpvHsD1JjmhYIYJBipwgEBgHjUyGQSUiLUcySZwEyVlpVwgIAQVF2cLgfiOJwuUPQTgANKzyQ9HkRXgBfHVWE1EayaZjaXT6Hj8IRiKQyBQqZRlexOFzuLw+PwdKiBYK6UgRKKxKKEXSZII5PKRmJkMDoMilWzeyo1OoNXbNVq8dqddL2GZWDYxYCqqgAfXGk1yMTUhSWxQyJutNrtoQdhmdJjd5mUzCAA",
		"https://workers.cloudflare.com/playground#LYVwNgLglgDghgJwgegGYHsHALQBM4RwDcABAEbogB2+CAngLzbPYZb6HbW5QDGU2AAwBmACyiAnBMFSAbIICMALhYs2wDnC40+AkeKkyJ8hQFgAUAGF0VCAFNb2ACJQAzjHSuo0G0pLq8AmISKjhgOwYAIigaOwAPADoAK1dI0lQoMAcwiOjYxJTIi2tbBwhsABU6GDs-OBgYMD4CKBtkJLgANzhXXgRYCABqYHRccDsLC3iPJBJcO1Q4cAgSAG9zEhIeuipefzsIXgALAAoEOwBHEDtXCABKNY3Nkl4bW7mb6FCfKgBVACUADIkBgkSJHCAQGCuJTIZDxMKNOwJV7ANJPTavKjvW4EECuazzEEkYSKIgYkjnCAgBBUEj-G4ebHI848c68CAnea3GItGwAwEAGhIuOpBNGdju5M2AF9BeYZUQLKpmOpNNoePwhGJJNI5IpijZ7I4XO5PN5WlQ-AFNKRQuEouFCJo0v5MtkHZEyGB0GQilYjWVKtValsGk1eHyqO1XDZJuZVpFgHAYgB9EZjLKRJR5eYFVIy5UqtVBDW6bUGPXGRTMIA",
		"https://workers.cloudflare.com/playground#LYVwNgLglgDghgJwgegGYHsHALQBM4RwDcABAEbogB2+CAngLzbPYZb6HbW5QDGU2AAwAOAJwBmAIyiATKMkB2AKwyAXCxZtgHOFxp8BIidLmKVAWABQAYXRUIAU3vYAIlADOMdO6jQ7qki08AmISKjhgBwYAIigaBwAPADoAK3do0lQoMCcIqNj45LToq1t7JwhsABU6GAcAuBgYMD4CKDtkFLgANzh3XgRYCABqYHRccAcrK0SvJBJcB1Q4cAgSAG9LEhI+uipeQIcIXgALAAoEBwBHEAd3CABKDa3tnfc9g9RqXj8qEgBZI4ncYAOXQEAAgmAwOgAO4OXAXa63e5PTavV6XCAgBB-KgOWEkABKdy8VHcDjOAANARBgbgSAASdaXG53CBJSJ08YAXzC4J20LhCKSVIANM8MRj7gQQO4AgAWQRKMUvKUkE4OOCLBDyyXq15QmGwgLRADiAFEqtFVQaSDzbVKeQ8iGr7W7kMgSAB5KhgOgkS1VEislEQdwkWGYADWkd8JxIdI8JBgCHQCToSTdUFQJCRbPunKB4xIAEIGAwSOardEnlicX9afSwZChfDEaH2S63fXcYdjucqScIBAYPLPYkIs0HEleOhgFTu9sHZYeUQrBpmFodHoePwhGIpLJ5MoZKU7I5nG5PN5fO0qAEgjpSOFIjEudqQhlAtlcm-omQMJkCUNgXhU1S1PUOxNC0vBtB0aR2NMljrNEwBwHEAD6YwTDk0SqAUixFOkPIbpu24hLuBgHsYx5mDIzBAA",
		"https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/",
		"https://developers.cloudflare.com/ssl/origin-configuration/origin-ca/",
		"https://developers.cloudflare.com/dns/zone-setups/full-setup/setup/",
		"https://developers.cloudflare.com/ssl/origin-configuration/ssl-modes/",
		"https://developers.cloudflare.com/waf/custom-rules/use-cases/allow-traffic-from-specific-countries/",
		"https://discord.cloudflare.com/",
		"https://x.com/CloudflareDev",
		"https://community.cloudflare.com/",
		"https://github.com/cloudflare",
		"https://developers.cloudflare.com/sponsorships/",
		"https://developers.cloudflare.com/style-guide/",
		"https://blog.cloudflare.com/",
		"https://developers.cloudflare.com/fundamentals/",
		"https://support.cloudflare.com/",
		"https://www.cloudflarestatus.com/",
		"https://www.cloudflare.com/trust-hub/compliance-resources/",
		"https://www.cloudflare.com/trust-hub/gdpr/",
		"https://www.cloudflare.com/",
		"https://www.cloudflare.com/people/",
		"https://www.cloudflare.com/careers/",
		"https://radar.cloudflare.com/",
		"https://speed.cloudflare.com/",
		"https://isbgpsafeyet.com/",
		"https://rpki.cloudflare.com/",
		"https://ct.cloudflare.com/",
		"https://x.com/cloudflare",
		"http://discord.cloudflare.com/",
		"https://www.youtube.com/cloudflare",
		"https://github.com/cloudflare/cloudflare-docs",
		"https://www.cloudflare.com/privacypolicy/",
		"https://www.cloudflare.com/website-terms/",
		"https://www.cloudflare.com/disclosure/",
		"https://www.cloudflare.com/trademark/"
	]
}
```

---

# /markdown - Extract Markdown from a webpage

URL: https://developers.cloudflare.com/browser-rendering/rest-api/markdown-endpoint/

import { Tabs, TabItem } from "~/components";

The `/markdown` endpoint retrieves a webpage's content and converts it into Markdown format. You can specify a URL and optional parameters to refine the extraction process.

## Basic usage

### Using a URL

<Tabs syncKey="workersExamples"> <TabItem label="curl">

This example fetches the Markdown representation of a webpage.

```bash
curl -X 'POST' 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/markdown' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <apiToken>' \
  -d '{
    "url": "https://example.com"
  }'
```

```json output

	"success": true,
	"result": "# Example Domain\n\nThis domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission.\n\n[More information...](https://www.iana.org/domains/example)"
}
```

</TabItem> <TabItem label="TypeScript SDK">

```typescript
import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiEmail: process.env["CLOUDFLARE_EMAIL"], // This is the default and can be omitted
	apiKey: process.env["CLOUDFLARE_API_KEY"], // This is the default and can be omitted
});

const markdown = await client.browserRendering.markdown.create({
	account_id: "account_id",
});

console.log(markdown);
```

</TabItem> </Tabs>

### Use raw HTML

Instead of fetching the content by specifying the URL, you can provide raw HTML content directly.

```bash
curl -X 'POST' 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/markdown' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <apiToken>' \
  -d '{
    "html": "<div>Hello World</div>"
  }'
```

```json output
{
	"success": true,
	"result": "Hello World"
}
```

## Advanced usage

You can refine the Markdown extraction by using the `rejectRequestPattern` parameter. In this example, requests matching the given regex pattern (such as CSS files) are excluded.

```bash
curl -X 'POST' 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/markdown' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <apiToken>' \
  -d '{
    "url": "https://example.com",
    "rejectRequestPattern": ["/^.*\\.(css)/"]
  }'
```

```json output
{
	"success": true,
	"result": "# Example Domain\n\nThis domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission.\n\n[More information...](https://www.iana.org/domains/example)"
}
```

## Potential use-cases

1. **Content extraction:** Convert a blog post or article into Markdown format for storage or further processing.
2. **Static site generation:** Retrieve structured Markdown content for use in static site generators like Jekyll or Hugo.
3. **Automated summarization:** Extract key content from web pages while ignoring CSS, scripts, or unnecessary elements.

---

# /pdf - Render PDF

URL: https://developers.cloudflare.com/browser-rendering/rest-api/pdf-endpoint/

import { Tabs, TabItem } from "~/components";

The `/pdf` endpoint instructs the browser to generate a PDF of a webpage or custom HTML using Cloudflare's headless browser rendering service.

## Endpoint

```txt
https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf
```

## Required fields
You must provide either `url` or `html`:
-  `url` (string)
-  `html` (string)

## Common use cases

-  Capture a PDF of a webpage
-  Generate PDFs, such as invoices, licenses, reports, and certificates, directly from HTML

## Basic usage

### Convert a URL to PDF

<Tabs syncKey="workersExamples"> <TabItem label="curl">

Navigate to `https://example.com/` and inject custom CSS and an external stylesheet. Then return the rendered page as a PDF.

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "addStyleTag": [
      { "content": "body { font-family: Arial; }" },
      { "url": "https://cdn.jsdelivr.net/npm/bootstrap@3.3.7/dist/css/bootstrap.min.css" }
    ]
  }' \
  --output "output.pdf"
```

</TabItem> <TabItem label="TypeScript SDK">

```typescript
import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiEmail: process.env["CLOUDFLARE_EMAIL"], // This is the default and can be omitted
	apiKey: process.env["CLOUDFLARE_API_KEY"], // This is the default and can be omitted
});

const pdf = await client.browserRendering.pdf.create({
	account_id: "account_id",
});

console.log(pdf);

const content = await pdf.blob();
console.log(content);
```

</TabItem> </Tabs>

### Convert custom HTML to PDF

If you have raw HTML you want to generate a PDF from, use the `html` option. You can still apply custom styles using the `addStyleTag` parameter.

```bash
curl -X POST https://api.cloudflare.com/client/v4/accounts/<acccountID>/browser-rendering/pdf \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
  "html": "<html><body>Advanced Snapshot</body></html>",
	"addStyleTag": [
      { "content": "body { font-family: Arial; }" },
      { "url": "https://cdn.jsdelivr.net/npm/bootstrap@3.3.7/dist/css/bootstrap.min.css" }
    ]
}' \
  --output "invoice.pdf"
```

## Advanced usage

:::note[Looking for more parameters?]
Visit the [Browser Rendering PDF API reference](/api/resources/browser_rendering/subresources/pdf/methods/create/) for all available parameters, such as setting HTTP credentials using `authenticate`, setting `cookies`, and customizing load behavior using `gotoOptions`.
:::

### Advanced page load with custom headers and viewport

Navigate to `https://example.com`, setting additional HTTP headers and configuring the page size (viewport). The PDF generation will wait until there are no more than two network connections for at least 500 ms, or until the maximum timeout of 4500 ms is reached, before rendering.

The `goToOptions` parameter exposes most of [Puppeteer's API](https://pptr.dev/api/puppeteer.gotooptions).

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "setExtraHTTPHeaders": {
      "X-Custom-Header": "value"
    },
    "viewport": {
      "width": 1200,
      "height": 800
    },
    "gotoOptions": {
      "waitUntil": "networkidle2",
      "timeout": 45000
    }
  }' \
  --output "advanced-output.pdf"
```

### Blocking images and styles when generating a PDF

The options `rejectResourceTypes` and `rejectRequestPattern` can be used to block requests during rendering. The opposite can also be done, _only_ allow certain requests using `allowResourceTypes` and `allowRequestPattern`.

```bash
curl -X POST https://api.cloudflare.com/client/v4/accounts/<acccountID>/browser-rendering/pdf \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://cloudflare.com/",
  "rejectResourceTypes": ["image"],
  "rejectRequestPattern": ["/^.*\\.(css)"]
}' \
  --output "cloudflare.pdf"
```

---

# /scrape - Scrape HTML elements

URL: https://developers.cloudflare.com/browser-rendering/rest-api/scrape-endpoint/

import { Tabs, TabItem } from "~/components";

The `/scrape` endpoint extracts structured data from specific elements on a webpage, returning details such as element dimensions and inner HTML.

## Basic usage

<Tabs syncKey="workersExamples"> <TabItem label="curl">

Go to `https://example.com` and extract metadata from all `h1` and `a` elements in the DOM.

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/scrape' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "elements": [{
    "selector": "h1"
  },
  {
    "selector": "a"
  }]
}'
```

```json output
{
	"success": true,
	"result": [
		{
			"results": [
				{
					"attributes": [],
					"height": 39,
					"html": "Example Domain",
					"left": 100,
					"text": "Example Domain",
					"top": 133.4375,
					"width": 600
				}
			],
			"selector": "h1"
		},
		{
			"results": [
				{
					"attributes": [
						{ "name": "href", "value": "https://www.iana.org/domains/example" }
					],
					"height": 20,
					"html": "More information...",
					"left": 100,
					"text": "More information...",
					"top": 249.875,
					"width": 142
				}
			],
			"selector": "a"
		}
	]
}
```

</TabItem> <TabItem label="TypeScript SDK">

```typescript
import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiEmail: process.env["CLOUDFLARE_EMAIL"], // This is the default and can be omitted
	apiKey: process.env["CLOUDFLARE_API_KEY"], // This is the default and can be omitted
});

const scrapes = await client.browserRendering.scrape.create({
	account_id: "account_id",
	elements: [{ selector: "selector" }],
});

console.log(scrapes);
```

</TabItem> </Tabs>

Many more options exist, like setting HTTP credentials using `authenticate`, setting `cookies`, and using `gotoOptions` to control page load behaviour - check the endpoint [reference](/api/resources/browser_rendering/subresources/scrape/methods/create/) for all available parameters.

### Response fields

- `results` _(array of objects)_ - Contains extracted data for each selector.
  - `selector` _(string)_ - The CSS selector used.
  - `results` _(array of objects)_ - List of extracted elements matching the selector.
    - `text` _(string)_ - Inner text of the element.
    - `html` _(string)_ - Inner HTML of the element.
    - `attributes` _(array of objects)_ - List of extracted attributes such as `href` for links.
    - `height`, `width`, `top`, `left` _(number)_ - Position and dimensions of the element.

---

# /screenshot - Capture screenshot

URL: https://developers.cloudflare.com/browser-rendering/rest-api/screenshot-endpoint/

import { Tabs, TabItem } from "~/components";

The `/screenshot` endpoint renders the webpage by processing its HTML and JavaScript, then captures a screenshot of the fully rendered page.

## Basic usage

<Tabs syncKey="workersExamples"> <TabItem label="curl">

Sets the HTML content of the page to `Hello World!` and then takes a screenshot. The option `omitBackground` hides the default white background and allows capturing screenshots with transparency.

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "Hello World!",
    "screenshotOptions": {
      "omitBackground": true
    }
  }' \
  --output "screenshot.png"
```

</TabItem> <TabItem label="TypeScript SDK">

```typescript
import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiEmail: process.env["CLOUDFLARE_EMAIL"], // This is the default and can be omitted
	apiKey: process.env["CLOUDFLARE_API_KEY"], // This is the default and can be omitted
});

const screenshot = await client.browserRendering.screenshot.create({
	account_id: "account_id",
});

console.log(screenshot.status);
```

</TabItem> </Tabs>

For more options to control the final screenshot, like `clip`, `captureBeyondViewport`, `fullPage` and others, check the endpoint [reference](/api/resources/browser_rendering/subresources/screenshot/methods/create/).

## Advanced usage

Navigate to `https://cloudflare.com/`, changing the page size (`viewport`) and waiting until there are no active network connections (`waitUntil`) or up to a maximum of `4500ms` (`timeout`). Then take a `fullPage` screenshot.

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://cnn.com/",
    "screenshotOptions": {
       "fullPage": true
    },
    "viewport": {
      "width": 1280,
      "height": 720
    },
    "gotoOptions": {
      "waitUntil": "networkidle0",
      "timeout": 45000
    }
  }' \
  --output "advanced-screenshot.png"
```

## Customize CSS and embed custom JavaScript

Instruct the browser to go to `https://example.com`, embed custom JavaScript (`addScriptTag`) and add extra styles (`addStyleTag`), both inline (`addStyleTag.content`) and by loading an external stylesheet (`addStyleTag.url`).

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "addScriptTag": [
      { "content": "document.querySelector(`h1`).innerText = `Hello World!!!`" }
    ],
    "addStyleTag": [
      {
        "content": "div { background: linear-gradient(45deg, #2980b9  , #82e0aa  ); }"
      },
      {
        "url": "https://cdn.jsdelivr.net/npm/bootstrap@3.3.7/dist/css/bootstrap.min.css"
      }
    ]
  }' \
  --output "screenshot.png"
```

Many more options exist, like setting HTTP credentials using `authenticate`, setting `cookies`, and using `gotoOptions` to control page load behaviour - check the endpoint [reference](/api/resources/browser_rendering/subresources/screenshot/methods/create/) for all available parameters.

---

# /snapshot - Take a webpage snapshot

URL: https://developers.cloudflare.com/browser-rendering/rest-api/snapshot/

import { Tabs, TabItem } from "~/components";

The `/snapshot` endpoint captures both the HTML content and a screenshot of the webpage in one request. It returns the HTML as a text string and the screenshot as a Base64-encoded image.

## Basic usage

<Tabs syncKey="workersExamples"> <TabItem label="curl">

1. Go to `https://example.com/`.
2. Inject custom JavaScript.
3. Capture the rendered HTML.
4. Take a screenshot.

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/snapshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "addScriptTag": [
      { "content": "document.body.innerHTML = \"Snapshot Page\";" }
    ]
  }'
```

```json output
{
	"success": true,
	"result": {
		"screenshot": "Base64EncodedScreenshotString",
		"content": "<html>...</html>"
	}
}
```

</TabItem> <TabItem label="TypeScript SDK">

```typescript
import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiEmail: process.env["CLOUDFLARE_EMAIL"], // This is the default and can be omitted
	apiKey: process.env["CLOUDFLARE_API_KEY"], // This is the default and can be omitted
});

const snapshot = await client.browserRendering.snapshot.create({
	account_id: "account_id",
});

console.log(snapshot.content);
```

</TabItem> </Tabs>

## Advanced usage

The `html` property in the JSON payload, it sets the html to `<html><body>Advanced Snapshot</body></html>` then does the following steps:

1. Disable JavaScript.
2. Sets the screenshot to `fullPage`.
3. Changes the page size `(viewport)`.
4. Waits up to `30000ms` or until the `DOMContentLoaded` event fires.
5. Returns the rendered HTML content and a base-64 encoded screenshot of the page.

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/snapshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "<html><body>Advanced Snapshot</body></html>",
    "setJavaScriptEnabled": false,
    "screenshotOptions": {
       "fullPage": true
    },
    "viewport": {
      "width": 1200,
      "height": 800
    },
    "gotoOptions": {
      "waitUntil": "domcontentloaded",
      "timeout": 30000
    }
  }'
```

```json output
{
	"success": true,
	"result": {
		"screenshot": "AdvancedBase64Screenshot",
		"content": "<html><body>Advanced Snapshot</body></html>"
	}
}
```

Many more options exist, like setting HTTP credentials using `authenticate`, setting `cookies`, and using `gotoOptions` to control page load behaviour - check the endpoint [reference](/api/resources/browser_rendering/subresources/snapshot/) for all available parameters.

---

# Plans

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/plans/

import { FeatureTable, Render } from "~/components"

<FeatureTable id="ssl.z_custom_hostnames" />

## Enterprise plan benefits

The Enterprise plan offers features that give SaaS providers flexibility when it comes to meeting their end customer's requirements. In addition to that, Enterprise customers are able to extend all of the benefits of the Enterprise plan to their customer's custom hostnames. This includes advanced Bot Mitigation, WAF rules, analytics, DDoS mitigation, and more.

In addition, large SaaS providers rely on Enterprise level support, multi-user accounts, SSO, and other benefits that are not provided in non-Enterprise plans.

<Render file="non-contract-enablement" product="fundamentals" />

---

# Analytics

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/hostname-analytics/

import { Render } from "~/components"

You can use custom hostname analytics for two general purposes: exploring how your customers use your product and sharing the benefits provided by Cloudflare with your customers.

These analytics include **Site Analytics**, **Bot Analytics**, **Cache Analytics**, **Security Events**, and [any other datasets](/analytics/graphql-api/features/data-sets/) with the `clientRequestHTTPHost` field.

:::note


The plan of your Cloudflare for SaaS application determines the analytics available for your custom hostnames.


:::

## Explore customer usage

Use custom hostname analytics to help your organization with billing and infrastructure decisions, answering questions like:

* "How many total requests is your service getting?"
* "Is one customer transferring significantly more data than the others?"
* "How many global customers do you have and where are they distributed?"

If you see one customer is using more data than another, you might increase their bill. If requests are increasing in a certain geographic region, you might want to increase the origin servers in that region.

To access custom hostname analytics, either [use the dashboard](/analytics/faq/about-analytics/) and filter by the `Host` field or [use the GraphQL API](/analytics/graphql-api/) and filter by the `clientRequestHTTPHost` field. For more details, refer to our tutorial on [Querying HTTP events by hostname with GraphQL](/analytics/graphql-api/tutorials/end-customer-analytics/).

## Share Cloudflare data with your customers

With custom hostname analytics, you can also share site information with your customers, including data about:

* How many pageviews their site is receiving.
* Whether their site has a large percentage of bot traffic.
* How fast their site is.

Build custom dashboards to share this information by specifying an individual custom hostname in `clientRequestHTTPHost` field of [any dataset](/analytics/graphql-api/features/data-sets/) that includes this field.

## Logpush

[Logpush](/logs/about/) sends metadata from Cloudflare products to your cloud storage destination or SIEM.

Using [filters](/logs/reference/filters/), you can send set sample rates (or not include logs altogether) based on filter criteria. This flexibility allows you to maintain selective logs for custom hostnames without massively increasing your log volume.

Filtering is available for [all Cloudflare datasets](/logs/reference/log-fields/zone/).

<Render file="filtering-limitations" product="logs" />

---

# Cloudflare for SaaS

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/

import { LinkButton, Render } from "~/components";

<Render file="ssl-for-saas-definition" /> <br />

As a SaaS provider, you may want to support subdomains under your own zone in addition to letting your customers use their own domain names with your services. For example, a customer may want to use their vanity domain `app.customer.com` to point to an application hosted on your Cloudflare zone `service.saas.com`. Cloudflare for SaaS allows you to increase security, performance, and reliability of your customers' domains.

<Render file="non-contract-enablement" product="fundamentals" />

## Benefits

When you use Cloudflare for SaaS, it helps you to:

- Provide custom domain support.
- Keep your customers' traffic encrypted.
- Keep your customers online.
- Facilitate fast load times of your customers' domains.
- Gain insight through traffic analytics.

## Limitations

If your customers already have their applications on Cloudflare, they cannot control some Cloudflare features for hostnames managed by your Custom Hostnames configuration, including:

- Argo
- Early Hints
- Page Shield
- Spectrum
- Wildcard DNS

## How it works

As the SaaS provider, you can extend Cloudflare's products to customer-owned custom domains by adding them to your zone [as custom hostnames](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/). Through a suite of easy-to-use products, Cloudflare for SaaS routes traffic from custom hostnames to an origin, set up on your domain. Cloudflare for SaaS is highly customizable. Three possible configurations are shown below.

### Standard Cloudflare for SaaS configuration:

Custom hostnames are routed to a default origin server called fallback origin. This configuration is available on all plans.

![Standard case](~/assets/images/cloudflare-for-platforms/use-cases/Standard.png)

### Cloudflare for SaaS with Apex Proxying:

This allows you to support apex domains even if your customers are using a DNS provider that does not allow a CNAME at the apex. This is available as an add-on for Enterprise plans. For more details, refer to [Apex Proxying](/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/apex-proxying/).

![Advanced case](~/assets/images/cloudflare-for-platforms/use-cases/Advanced.png)

### Cloudflare for SaaS with BYOIP:

This allows you to support apex domains even if your customers are using a DNS provider that does not allow a CNAME at the apex. Also, you can point to your own IPs if you want to bring an IP range to Cloudflare (instead of Cloudflare provided IPs). This is available as an add-on for Enterprise plans.

![Pro Case](~/assets/images/cloudflare-for-platforms/use-cases/Pro.png)

## Availability

Cloudflare for SaaS is bundled with non-Enterprise plans and available as an add-on for Enterprise plans. For more details, refer to [Plans](/cloudflare-for-platforms/cloudflare-for-saas/plans/).

## Next steps

<LinkButton
	variant="primary"
	href="/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/"
>
	Get started
</LinkButton>
<LinkButton
	variant="secondary"
	href="https://blog.cloudflare.com/introducing-ssl-for-saas/"
>
	Learn more
</LinkButton>

---

# Workers for Platforms

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/

import { CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedProduct, Stream } from "~/components"

<Description>


Deploy custom code on behalf of your users or let your users directly deploy their own code to your platform, managing infrastructure.


</Description>

<Plan type="paid" />

Workers for Platforms allows you to run your own code as a wrapper around your user's code. With Workers for Platforms, you can logically group your code separately from your users' code, create custom logic, and use additional APIs such as [script tags](/cloudflare-for-platforms/workers-for-platforms/configuration/tags/) for bulk operations.

Workers for Platforms is built on top of [Cloudflare Workers](/workers/). Workers for Platforms lets you surpass Cloudflare Workers' 500 scripts per account [limit](/cloudflare-for-platforms/workers-for-platforms/platform/limits/).

<br></br>

<Stream id="c8afb7a0a811f07db4b4ffaf56c277bc" title="Workers for Platforms Overview" thumbnail="8.6s" />

***

## Features

<Feature header="Get started" href="/cloudflare-for-platforms/workers-for-platforms/get-started/configuration/" cta="Get started">
Learn how to set up Workers for Platforms.
</Feature>

<Feature header="Workers for Platforms architecture" href="/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/" cta="Learn more">
Learn about Workers for Platforms architecture.
</Feature>

***

## Related products

<RelatedProduct header="Workers" href="/workers/" product="workers">

Cloudflare Workers provides a serverless execution environment that allows you to create new applications or augment existing ones without configuring or maintaining infrastructure.


</RelatedProduct>

***

## More resources

<CardGrid>

<LinkTitleCard title="Limits" href="/cloudflare-for-platforms/workers-for-platforms/platform/limits/" icon="document">
Learn about limits that apply to your Workers for Platforms project.
</LinkTitleCard>

<LinkTitleCard title="Developer Discord" href="https://discord.cloudflare.com" icon="discord">
Connect with the Workers community on Discord to ask questions, show what you are building, and discuss the platform with other developers.
</LinkTitleCard>

<LinkTitleCard title="@CloudflareDev" href="https://x.com/cloudflaredev" icon="x.com">
Follow @CloudflareDev on Twitter to learn about product announcements, and what is new in Cloudflare Workers.
</LinkTitleCard>

</CardGrid>

---

# Demos and architectures

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/demos/

import { ExternalResources, GlossaryTooltip, ResourcesBySelector } from "~/components"

Learn how you can use Workers for Platforms within your existing architecture.

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Workers for Platforms.

<ExternalResources type="apps" products={["Workers for Platforms"]} />

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use Workers:

<ResourcesBySelector types={["reference-architecture","design-guide","reference-architecture-diagram"]} products={["WorkersForPlatforms"]} />

---

# Client API

URL: https://developers.cloudflare.com/constellation/platform/client-api/

The Constellation client API allows developers to interact with the inference engine using the models configured for each project. Inference is the process of running data inputs on a machine-learning model and generating an output, or otherwise known as a prediction.

Before you use the Constellation client API, you need to:

* Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up).
* Enable Constellation by logging into the Cloudflare dashboard > **Workers & Pages** > **Constellation**.
* Create a Constellation project and configure the binding.
* Import the `@cloudflare/constellation` library in your code:

```javascript
import { Tensor, run } from "@cloudflare/constellation";
```

## Tensor class

Tensors are essentially multidimensional numerical arrays used to represent any kind of data, like a piece of text, an image, or a time series. TensorFlow popularized the use of [Tensors](https://www.tensorflow.org/guide/tensor) in machine learning (hence the name). Other frameworks and runtimes have since followed the same concept.

Constellation also uses Tensors for model input.

Tensors have a data type, a shape, the data, and a name.

```typescript
enum TensorType {
    Bool = "bool",
    Float16 = "float16",
    Float32 = "float32",
    Int8 = "int8",
    Int16 = "int16",
    Int32 = "int32",
    Int64 = "int64",
}

type TensorOpts = {
  shape?: number[],
  name?: string
}

declare class Tensor<TensorType> {
  constructor(
    type: T,
    value: any | any[],
    opts: TensorOpts = {}
  )
}
```

### Create new Tensor

```typescript
new Tensor(
  type:TensorType,
  value:any | any[],
  options?:TensorOpts
  )
```

#### type

Defines the type of data represented in the Tensor. Options are:

* TensorType.Bool
* TensorType.Float16
* TensorType.Float32
* TensorType.Int8
* TensorType.Int16
* TensorType.Int32
* TensorType.Int64

#### value

This is the tensor's data. Example tensor values can include:

* scalar: 4
* vector: \[1, 2, 3]
* two-axes 3x2 matrix: \[\[1,2], \[2,4], \[5,6]]
* three-axes 3x2 matrix \[ \[\[1, 2], \[3, 4]], \[\[5, 6], \[7, 8]], \[\[9, 10], \[11, 12]] ]

#### options

You can pass options to your tensor:

##### shape

Tensors store multidimensional data. The shape of the data can be a scalar, a vector, a 2D matrix or multiple-axes matrixes. Some examples:

* \[] - scalar data
* \[3] - vector with 3 elements
* \[3, 2] - two-axes 3x2 matrix
* \[3, 2, 2] - three-axis 2x2 matrix

Refer to the [TensorFlow documentation](https://www.tensorflow.org/guide/tensor) for more information about shapes.

If you don't pass the shape, then we try to infer it from the value object. If we can't, we thrown an error.

##### name

Naming a tensor is optional, it can be a useful key for mapping operations when building the tensor inputs.

### Tensor examples

#### A scalar

```javascript
  new Tensor(TensorType.Int16, 123);
```

#### Arrays

```javascript
  new Tensor(TensorType.Int32, [1, 23]);
  new Tensor(TensorType.Int32, [ [1, 2], [3, 4], ], { shape: [2, 2] });
  new Tensor(TensorType.Int32, [1, 23], { shape: [1] });
```

#### Named

```javascript
  new Tensor(TensorType.Int32, 1, { name: "foo" });
```

### Tensor properties

You can read the tensor's properties after it has been created:

```javascript
const tensor = new Tensor(TensorType.Int32, [ [1, 2], [3, 4], ], { shape: [2, 2], name: "test" });

console.log ( tensor.type );
// TensorType.Int32

console.log ( tensor.shape );
// [2, 2]

console.log ( tensor.name );
// test

console.log ( tensor.value );
//  [ [1, 2], [3, 4], ]
```

### Tensor methods

#### async tensor.toJSON()

Serializes the tensor to a JSON object:

```javascript
const tensor = new Tensor(TensorType.Int32, [ [1, 2], [3, 4], ], { shape: [2, 2], name: "test" });

tensor.toJSON();

{
  type: TensorType.Int32,
  name: "test",
  shape:  [2, 2],
  value: [ [1, 2], [3, 4], ]
}
```

#### async tensor.fromJSON()

Serializes a JSON object to a tensor:

```javascript
const tensor = Tensor.fromJSON(
  {
    type: TensorType.Int32,
    name: "test",
    shape:  [2, 2],
    value: [ [1, 2], [3, 4], ]
  }
);
```

## InferenceSession class

Constellation requires an inference session before you can run a task. A session is locked to a specific project, defined in your binding, and the project model.

You can, and should, if possible, run multiple tasks under the same inference session. Reusing the same session, means that we instantiate the runtime and load the model to memory once.

```typescript
export class InferenceSession {
    constructor(binding: any, modelId: string, options: SessionOptions = {})
}

export type InferenceSession = {
  binding: any;
  model: string;
  options: SessionOptions;
};
```

### InferenceSession methods

#### new InferenceSession()

To create a new session:

```javascript
import { InferenceSession } from "@cloudflare/constellation";

const session = new InferenceSession(
  env.PROJECT,
  "0ae7bd14-a0df-4610-aa85-1928656d6e9e"
);
```

* **env.PROJECT** is the project binding defined in your Wrangler configuration.
* **0ae7bd14...** is the model ID inside the project. Use Wrangler to list the models and their IDs in a project.

#### async session.run()

Runs a task in the created inference session. Takes a list of tensors as the input.

```javascript
import { Tensor, InferenceSession, TensorType } from "@cloudflare/constellation";

const session = new InferenceSession(
  env.PROJECT,
  "0ae7bd14-a0df-4610-aa85-1998656d6e9e"
);

const tensorInputArray = [ new Tensor(TensorType.Int32, 1), new Tensor(TensorType.Int32, 2), new Tensor(TensorType.Int32, 3) ];

const out = await session.run(tensorInputArray);

```

You can also use an object and name your tensors.

```javascript
const tensorInputNamed = {
  "tensor1": new Tensor(TensorType.Int32, 1),
  "tensor2": new Tensor(TensorType.Int32, 2),
  "tensor3": new Tensor(TensorType.Int32, 3)
};

out = await session.run(tensorInputNamed);
```

This is the same as using the name option when you create a tensor.

```javascript
{ "tensor1": new Tensor(TensorType.Int32, 1) } == [ new Tensor(TensorType.Int32, 1, { name: "tensor1" } ];
```

---

# Platform

URL: https://developers.cloudflare.com/constellation/platform/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Static Frontend, Container Backend

URL: https://developers.cloudflare.com/containers/examples/container-backend/

import { WranglerConfig, Details } from "~/components";

A common pattern is to serve a static frontend application (e.g., React, Vue, Svelte) using Static Assets,
then pass backend requests to a containerized backend application.

In this example, we'll show an example using a simple `index.html` file served as a static asset,
but you can select from one of many frontend frameworks. See our [Workers framework examples](/workers/framework-guides/web-apps/) for more information.

For a full example, see the [Static Frontend + Container Backend Template](https://github.com/mikenomitch/static-frontend-container-backend).

## Configure Static Assets and a Container

<WranglerConfig>
```json
{
  "name": "cron-container",
  "main": "src/index.ts",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS"
  },
  "containers": [
    {
      "class_name": "Backend",
      "image": "./Dockerfile",
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "class_name": "Backend",
        "name": "BACKEND"
      }
    ]
  },
  "migrations": [
    {
      "new_sqlite_classes": [
        "Backend"
      ],
      "tag": "v1"
    }
  ]
}
```
</WranglerConfig>

## Add a simple index.html file to serve

Create a simple `index.html` file in the `./dist` directory.

<Details header="index.html">
```html
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Widgets</title>
  <script defer src="https://cdnjs.cloudflare.com/ajax/libs/alpinejs/3.13.3/cdn.min.js"></script>
</head>

<body>
  <div x-data="widgets()" x-init="fetchWidgets()">
    <h1>Widgets</h1>
    <div x-show="loading">Loading...</div>
    <div x-show="error" x-text="error" style="color: red;"></div>
    <ul x-show="!loading && !error">
      <template x-for="widget in widgets" :key="widget.id">
        <li>
          <span x-text="widget.name"></span> - (ID: <span x-text="widget.id"></span>)
        </li>
      </template>
    </ul>

    <div x-show="!loading && !error && widgets.length === 0">
      No widgets found.
    </div>

  </div>

  <script>
    function widgets() {
      return {
        widgets: [],
        loading: false,
        error: null,

        async fetchWidgets() {
          this.loading = true;
          this.error = null;

          try {
            const response = await fetch('/api/widgets');
            if (!response.ok) {
              throw new Error(`HTTP ${response.status}: ${response.statusText}`);
            }
            this.widgets = await response.json();
          } catch (err) {
            this.error = err.message;
          } finally {
            this.loading = false;
          }
        }
      }
    }
  </script>

</body>

</html>
```
</Details>

In this example, we are using [Alpine.js](https://alpinejs.dev/) to fetch a list of widgets from `/api/widgets`.

This is meant to be a very simple example, but you can get significantly more complex.
See [examples of Workers integrating with frontend frameworks](/workers/framework-guides/web-apps/) for more information.

## Define a Worker

Your Worker needs to be able to both serve static assets and route requests to the containerized backend.

In this case, we will pass requests to one of three container instances if the route starts with `/api`,
and all other requests will be served as static assets.

```javascript
import { Container, getRandom } from "@cloudflare/containers";

const INSTANCE_COUNT = 3;

class Backend extends Container {
	defaultPort = 8080; // pass requests to port 8080 in the container
	sleepAfter = "2h"; // only sleep a container if it hasn't gotten requests in 2 hours
}

export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		if (url.pathname.startsWith("/api")) {
			// note: "getRandom" to be replaced with latency-aware routing in the near future
			const containerInstance = getRandom(env.BACKEND, INSTANCE_COUNT);
			return containerInstance.fetch(request);
		}

		return env.ASSETS.fetch(request);
	},
};
```

:::note
This example uses the `getRandom` function, which is a temporary helper that will randomly
select of of N instances of a Container to route requests to.

In the future, we will provide improved latency-aware load balancing and autoscaling.

This will make scaling stateless instances simple and routing more efficient. See the
[autoscaling documentation](/containers/scaling-and-routing) for more details.
:::

## Define a backend container

Your container should be able to handle requests to `/api/widgets`.

In this case, we'll use a simple Golang backend that returns a hard-coded list of widgets.

<Details header="server.go">
```go
package main

import (
	"encoding/json"
	"log"
	"net/http"
)

func handler(w http.ResponseWriter, r \*http.Request) {
    widgets := []map[string]interface{}{
        {"id": 1, "name": "Widget A"},
        {"id": 2, "name": "Sprocket B"},
        {"id": 3, "name": "Gear C"},
    }

    w.Header().Set("Content-Type", "application/json")
    w.Header().Set("Access-Control-Allow-Origin", "*")
    json.NewEncoder(w).Encode(widgets)

}

func main() {
    http.HandleFunc("/api/widgets", handler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

```
</Details>

---

# Cron Container

URL: https://developers.cloudflare.com/containers/examples/cron/

import { WranglerConfig } from "~/components";

To launch a container on a schedule, you can use a Workers [Cron Trigger](/workers/configuration/cron-triggers/).

For a full example, see the [Cron Container Template](https://github.com/mikenomitch/cron-container/tree/main).

Use a cron expression in your Wrangler config to specify the schedule:

<WranglerConfig>

```json
{
	"name": "cron-container",
	"main": "src/index.ts",
	"triggers": {
		"crons": [
			"*/2 * * * *" // Run every 2 minutes
		]
	},
	"containers": [
		{
			"class_name": "CronContainer",
			"image": "./Dockerfile"
		}
	],
	"durable_objects": {
		"bindings": [
			{
				"class_name": "CronContainer",
				"name": "CRON_CONTAINER"
			}
		]
	},
	"migrations": [
		{
			"new_sqlite_classes": [
				"CronContainer"
			],
			"tag": "v1"
		}
	]
}
```

</WranglerConfig>

Then in your Worker, call your Container from the "scheduled" handler:

```ts
import { Container, getContainer } from "@cloudflare/containers";

export class CronContainer extends Container {
	sleepAfter = "5m";
	manualStart = true;
}

export default {
	async fetch(): Promise<Response> {
		return new Response(
			"This Worker runs a cron job to execute a container on a schedule.",
		);
	},

	async scheduled(
		_controller: any,
		env: { CRON_CONTAINER: DurableObjectNamespace<CronContainer> },
	) {
		await getContainer(env.CRON_CONTAINER).startContainer({
			envVars: {
				MESSAGE: "Start Time: " + new Date().toISOString(),
			},
		});
	},
};
```

---

# Env Vars and Secrets

URL: https://developers.cloudflare.com/containers/examples/env-vars-and-secrets/

import { WranglerConfig, PackageManagers } from "~/components";

Environment variables can be passed into a Container using the `envVars` field
in the `Container` class, or by setting manually when the Container starts.

Secrets can be passed into a Container by using [Worker Secrets](/workers/configuration/secrets/)
or the [Secret Store](/secrets-store/integrations/workers/), then passing them into the Container
as environment variables.

These examples show the various ways to pass in secrets and environment variables. In each, we will
be passing in:

- the variable `"ACCOUNT_NAME"` as a hard-coded environment variable
- the secret `"CONTAINER_SECRET_KEY"` as a secret from Worker Secrets
- the secret `"ACCOUNT_API_KEY"` as a secret from the Secret Store

In practice, you may just use one of the methods for storing secrets, but
we will show both for completeness.

## Creating secrets

First, let's create the `"CONTAINER_SECRET_KEY"` secret in Worker Secrets:

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="secret put CONTAINER_SECRET_KEY"
/>

Then, let's create a store called "demo" in the Secret Store, and add
the `"ACCOUNT_API_KEY"` secret to it:

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="secrets-store store create demo --remote"
/>

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="secrets-store secret create demo --name ACCOUNT_API_KEY --scopes workers --remote"
/>

For full details on how to create secrets, see the [Workers Secrets documentation](/workers/configuration/secrets/)
and the [Secret Store documentation](/secrets-store/integrations/workers/).

## Adding a secrets binding

Next, we need to add bindings to access our secrets and environment variables
in Wrangler configuration.

<WranglerConfig>

```json
{
	"name": "my-container-worker",
	"vars": {
		"ACCOUNT_NAME": "my-account"
	},
	"secrets_store_secrets": [
		{
			"binding": "SECRET_STORE",
			"store_id": "demo",
			"secret_name": "ACCOUNT_API_KEY"
		}
	]
	// rest of the configuration...
}
```

</WranglerConfig>

Note that `"CONTAINER_SECRET_KEY"` does not need to be set, at it is automatically
added to `env`.

Also note that we did not configure anything specific for environment variables
or secrets in the container-related portion of wrangler configuration.

## Using `envVars` on the Container class

Now, let's define a Container using the `envVars` field in the `Container` class:

```js
export class MyContainer extends Container {
  defaultPort = 8080;
  sleepAfter = '10s';
  envVars = {
    ACCOUNT_NAME: env.ACCOUNT_NAME,
		ACCOUNT_API_KEY: env.SECRET_STORE.ACCOUNT_API_KEY,
		CONTAINER_SECRET_KEY: env.CONTAINER_SECRET_KEY,
	};
}
```

Every instance of this `Container` will now have these variables and secrets
set as environment variables when it launches.

## Setting environment variables per-instance

But what if you want to set environment variables on a per-instance basis?

In this case, set `manualStart` then use the `start` method to pass in environment variables for each instance.
We'll assume that we've set additional secrets in the Secret Store.

```js
export class MyContainer extends Container {
	defaultPort = 8080;
	sleepAfter = '10s';
	manualStart = true;
}

export default {
	async fetch(request, env) {
		if (new URL(request.url).pathname === '/launch-instances') {
			let idOne = env.MY_CONTAINER.idFromName('foo');
			let instanceOne = env.MY_CONTAINER.get(idOne);

			let idTwo = env.MY_CONTAINER.idFromName('foo');
			let instanceTwo = env.MY_CONTAINER.get(idTwo);

			// Each instance gets a different set of environment variables

			await instanceOne.start({
				envVars: {
					ACCOUNT_NAME: env.ACCOUNT_NAME + "-1",
					ACCOUNT_API_KEY: env.SECRET_STORE.ACCOUNT_API_KEY_ONE,
					CONTAINER_SECRET_KEY: env.CONTAINER_SECRET_KEY_TWO,
				}
			)

			await instanceTwo.start({
				envVars: {
					ACCOUNT_NAME: env.ACCOUNT_NAME + "-2",
					ACCOUNT_API_KEY: env.SECRET_STORE.ACCOUNT_API_KEY_TWO,
					CONTAINER_SECRET_KEY: env.CONTAINER_SECRET_KEY_TWO,
				}
			)
			return new Response('Container instances launched');
		}

		// ... etc ...
	}
}
```

---

# Examples

URL: https://developers.cloudflare.com/containers/examples/

import { GlossaryTooltip, ListExamples } from "~/components";

Explore the following examples of Container functionality:

<ListExamples directory="containers/examples" />

---

# Stateless Instances

URL: https://developers.cloudflare.com/containers/examples/stateless/

To simply proxy requests to one of multiple instances of a container, you can use the `getRandom` function:

```ts
import { Container, getRandom } from "@cloudflare/containers";

const INSTANCE_COUNT = 3;

class Backend extends Container {
	defaultPort = 8080;
	sleepAfter = "2h";
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		// note: "getRandom" to be replaced with latency-aware routing in the near future
		const containerInstance = getRandom(env.BACKEND, INSTANCE_COUNT);
		return containerInstance.fetch(request);
	},
};
```

:::note
This example uses the `getRandom` function, which is a temporary helper that will randomly
select of of N instances of a Container to route requests to.

In the future, we will provide improved latency-aware load balancing and autoscaling.

This will make scaling stateless instances simple and routing more efficient. See the
[autoscaling documentation](/containers/scaling-and-routing) for more details.
:::

---

# Status Hooks

URL: https://developers.cloudflare.com/containers/examples/status-hooks/

When a Container starts, stops, and errors, it can trigger code execution in a Worker
that has defined status hooks on the `Container` class.

```js
import { Container } from '@cloudflare/containers';

export class MyContainer extends Container {
  defaultPort = 4000;
  sleepAfter = '5m';

  override onStart() {
    console.log('Container successfully started');
  }

  override onStop(stopParams) {
		if (stopParams.exitCode === 0) {
			console.log('Container stopped gracefully');
		} else {
			console.log('Container stopped with exit code:', stopParams.exitCode);
		}

		console.log('Container stop reason:', stopParams.reason);
  }

  override onError(error: string) {
    console.log('Container error:', error);
  }
}
```

---

# Websocket to Container

URL: https://developers.cloudflare.com/containers/examples/websocket/

WebSocket requests are automatically forwarded to a container using the default`fetch`
method on the `Container` class:

```js
import { Container, getContainer } from "@cloudflare/workers-types";

export class MyContainer extends Container {
	defaultPort = 8080;
	sleepAfter = "2m";
}

export default {
	async fetch(request, env) {
		// gets default instance and forwards websocket from outside Worker
		return getContainer(env.MY_CONTAINER).fetch(request);
	},
};
```

Additionally, the `containerFetch` method can be used to forward WebSocket requests as well.

{/* TODO: Add more advanced examples - like kicking off a WS request then passing messages to container from the WS */}

---

# Import and export data

URL: https://developers.cloudflare.com/d1/best-practices/import-export-data/

D1 allows you to import existing SQLite tables and their data directly, enabling you to migrate existing data into D1 quickly and easily. This can be useful when migrating applications to use Workers and D1, or when you want to prototype a schema locally before importing it to your D1 database(s).

D1 also allows you to export a database. This can be useful for [local development](/d1/best-practices/local-development/) or testing.

## Import an existing database

To import an existing SQLite database into D1, you must have:

1. The Cloudflare [Wrangler CLI installed](/workers/wrangler/install-and-update/).
2. A database to use as the target.
3. An existing SQLite (version 3.0+) database file to import.

:::note

You cannot import a raw SQLite database (`.sqlite3` files) directly. Refer to [how to convert an existing SQLite file](#convert-sqlite-database-files) first.

:::

For example, consider the following `users_export.sql` schema & values, which includes a `CREATE TABLE IF NOT EXISTS` statement:

```sql
CREATE TABLE IF NOT EXISTS users (
	id VARCHAR(50),
	full_name VARCHAR(50),
	created_on DATE
);
INSERT INTO users (id, full_name, created_on) VALUES ('01GREFXCN9519NRVXWTPG0V0BF', 'Catlaina Harbar', '2022-08-20 05:39:52');
INSERT INTO users (id, full_name, created_on) VALUES ('01GREFXCNBYBGX2GC6ZGY9FMP4', 'Hube Bilverstone', '2022-12-15 21:56:13');
INSERT INTO users (id, full_name, created_on) VALUES ('01GREFXCNCWAJWRQWC2863MYW4', 'Christin Moss', '2022-07-28 04:13:37');
INSERT INTO users (id, full_name, created_on) VALUES ('01GREFXCNDGQNBQAJG1AP0TYXZ', 'Vlad Koche', '2022-11-29 17:40:57');
INSERT INTO users (id, full_name, created_on) VALUES ('01GREFXCNF67KV7FPPSEJVJMEW', 'Riane Zamora', '2022-12-24 06:49:04');
```

With your `users_export.sql` file in the current working directory, you can pass the `--file=users_export.sql` flag to `d1 execute` to execute (import) our table schema and values:

```sh
npx wrangler d1 execute example-db --remote --file=users_export.sql
```

To confirm your table was imported correctly and is queryable, execute a `SELECT` statement to fetch all the tables from your D1 database:

```sh
npx wrangler d1 execute example-db --remote --command "SELECT name FROM sqlite_schema WHERE type='table' ORDER BY name;"
```

```sh output
...
🌀 To execute on your local development database, remove the --remote flag from your wrangler command.
🚣 Executed 1 commands in 0.3165ms
┌────────┐
│ name   │
├────────┤
│ _cf_KV │
├────────┤
│ users  │
└────────┘
```

:::note

The `_cf_KV` table is a reserved table used by D1's underlying storage system. It cannot be queried and does not incur read/write operations charges against your account.

:::

From here, you can now query our new table from our Worker [using the D1 Workers Binding API](/d1/worker-api/).

:::caution[Known limitations]

For imports, `wrangler d1 execute --file` is limited to 5GiB files, the same as the [R2 upload limit](/r2/platform/limits/). For imports larger than 5GiB, we recommend splitting the data into multiple files.
:::

### Convert SQLite database files

:::note

In order to convert a raw SQLite3 database dump (a `.sqlite3` file) you will need the [sqlite command-line tool](https://sqlite.org/cli.html) installed on your system.

:::

If you have an existing SQLite database from another system, you can import its tables into a D1 database. Using the `sqlite` command-line tool, you can convert an `.sqlite3` file into a series of SQL statements that can be imported (executed) against a D1 database.

For example, if you have a raw SQLite dump called `db_dump.sqlite3`, run the following `sqlite` command to convert it:

```sh
sqlite3 db_dump.sqlite3 .dump > db.sql
```

Once you have run the above command, you will need to edit the output SQL file to be compatible with D1:

1. Remove `BEGIN TRANSACTION` and `COMMIT;` from the file
2. Remove the following table creation statement (if present):
   ```sql
   CREATE TABLE _cf_KV (
    	key TEXT PRIMARY KEY,
    	value BLOB
   ) WITHOUT ROWID;
   ```

You can then follow the steps to [import an existing database](#import-an-existing-database) into D1 by using the `.sql` file you generated from the database dump as the input to `wrangler d1 execute`.

## Export an existing D1 database

In addition to importing existing SQLite databases, you might want to export a D1 database for local development or testing. You can export a D1 database to a `.sql` file using [wrangler d1 export](/workers/wrangler/commands/#d1-export) and then execute (import) with `d1 execute --file`.

To export full D1 database schema and data:

```sh
npx wrangler d1 export <database_name> --remote --output=./database.sql
```

To export single table schema and data:

```sh
npx wrangler d1 export <database_name> --remote --table=<table_name> --output=./table.sql
```

To export only D1 database schema:

```sh
npx wrangler d1 export <database_name> --remote --output=./schema.sql --no-data
```

To export only D1 table schema:

```sh
npx wrangler d1 export <database_name> --remote --table=<table_name> --output=./schema.sql --no-data
```

To export only D1 database data:

```sh
npx wrangler d1 export <database_name> --remote --output=./data.sql --no-schema
```

To export only D1 table data:

```sh
npx wrangler d1 export <database_name> --remote --table=<table_name> --output=./data.sql --no-schema
```

### Known limitations

- Export is not supported for virtual tables, including databases with virtual tables. D1 supports virtual tables for full-text search using SQLite's [FTS5 module](https://www.sqlite.org/fts5.html). As a workaround, delete any virtual tables, export, and then recreate virtual tables.
- A running export will block other database requests.
- Any numeric value in a column is affected by JavaScript's 52-bit precision for numbers. If you store a very large number (in `int64`), then retrieve the same value, the returned value may be less precise than your original number.

## Troubleshooting

If you receive an error when trying to import an existing schema and/or dataset into D1:

- Ensure you are importing data in SQL format (typically with a `.sql` file extension). Refer to [how to convert SQLite files](#convert-sqlite-database-files) if you have a `.sqlite3` database dump.
- Make sure the schema is [SQLite3](https://www.sqlite.org/docs.html) compatible. You cannot import data from a MySQL or PostgreSQL database into D1, as the types and SQL syntax are not directly compatible.
- If you have foreign key relationships between tables, ensure you are importing the tables in the right order. You cannot refer to a table that does not yet exist.
- If you receive a `"cannot start a transaction within a transaction"` error, make sure you have removed `BEGIN TRANSACTION` and `COMMIT` from your dumped SQL statements.

### Resolve `Statement too long` error

If you encounter a `Statement too long` error when trying to import a large SQL file into D1, it means that one of the SQL statements in your file exceeds the maximum allowed length.

To resolve this issue, convert the single large `INSERT` statement into multiple smaller `INSERT` statements. For example, instead of inserting 1,000 rows in one statement, split it into four groups of 250 rows, as illustrated in the code below.

Before:

```sql
INSERT INTO users (id, full_name, created_on)
VALUES
  ('1', 'Jacquelin Elara', '2022-08-20 05:39:52'),
  ('2', 'Hubert Simmons', '2022-12-15 21:56:13'),
  ...
  ('1000', 'Boris Pewter', '2022-12-24 07:59:54');
```

After:

```sql
INSERT INTO users (id, full_name, created_on)
VALUES
  ('1', 'Jacquelin Elara', '2022-08-20 05:39:52'),
  ...
  ('100', 'Eddy Orelo', '2022-12-15 22:16:15');
...
INSERT INTO users (id, full_name, created_on)
VALUES
  ('901', 'Roran Eroi', '2022-08-20 05:39:52'),
  ...
  ('1000', 'Boris Pewter', '2022-12-15 22:16:15');
```

## Foreign key constraints

When importing data, you may need to temporarily disable [foreign key constraints](/d1/sql-api/foreign-keys/). To do so, call `PRAGMA defer_foreign_keys = true` before making changes that would violate foreign keys.

Refer to the [foreign key documentation](/d1/sql-api/foreign-keys/) to learn more about how to work with foreign keys and D1.

## Next Steps

- Read the SQLite [`CREATE TABLE`](https://www.sqlite.org/lang_createtable.html) documentation.
- Learn how to [use the D1 Workers Binding API](/d1/worker-api/) from within a Worker.
- Understand how [database migrations work](/d1/reference/migrations/) with D1.

---

# Best practices

URL: https://developers.cloudflare.com/d1/best-practices/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Local development

URL: https://developers.cloudflare.com/d1/best-practices/local-development/

import { WranglerConfig } from "~/components";

D1 has fully-featured support for local development, running the same version of D1 as Cloudflare runs globally. Local development uses [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Workers, to manage local development sessions and state.

## Start a local development session

:::note

This guide assumes you are using [Wrangler v3.0](https://blog.cloudflare.com/wrangler3/) or later.

Users new to D1 and/or Cloudflare Workers should visit the [D1 tutorial](/d1/get-started/) to install `wrangler` and deploy their first database.

:::

Local development sessions create a standalone, local-only environment that mirrors the production environment D1 runs in so that you can test your Worker and D1 _before_ you deploy to production.

An existing [D1 binding](/workers/wrangler/configuration/#d1-databases) of `DB` would be available to your Worker when running locally.

To start a local development session:

1. Confirm you are using wrangler v3.0+.

   ```sh
   wrangler --version
   ```

   ```sh output
   ⛅️ wrangler 3.0.0
   ```

2. Start a local development session

   ```sh
   wrangler dev
   ```

   ```sh output
   ------------------
   wrangler dev now uses local mode by default, powered by 🔥 Miniflare and 👷 workerd.
   To run an edge preview session for your Worker, use wrangler dev --remote
   Your worker has access to the following bindings:
   - D1 Databases:
   	- DB: test-db (c020574a-5623-407b-be0c-cd192bab9545)
   ⎔ Starting local server...

   [mf:inf] Ready on http://127.0.0.1:8787/
   [b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit
   ```

In this example, the Worker has access to local-only D1 database. The corresponding D1 binding in your [Wrangler configuration file](/workers/wrangler/configuration/) would resemble the following:

<WranglerConfig>

```toml
[[d1_databases]]
binding = "DB"
database_name = "test-db"
database_id = "c020574a-5623-407b-be0c-cd192bab9545"
```

</WranglerConfig>

Note that `wrangler dev` separates local and production (remote) data. A local session does not have access to your production data by default. To access your production (remote) database, pass the `--remote` flag when calling `wrangler dev`. Any changes you make when running in `--remote` mode cannot be undone.

Refer to the [`wrangler dev` documentation](/workers/wrangler/commands/#dev) to learn more about how to configure a local development session.

## Develop locally with Pages

You can only develop against a _local_ D1 database when using [Cloudflare Pages](/pages/) by creating a minimal [Wrangler configuration file](/workers/wrangler/configuration/) in the root of your Pages project. This can be useful when creating schemas, seeding data or otherwise managing a D1 database directly, without adding to your application logic.

:::caution[Local development for remote databases]

It is currently not possible to develop against a _remote_ D1 database when using [Cloudflare Pages](/pages/).
:::

Your [Wrangler configuration file](/workers/wrangler/configuration/) should resemble the following:

<WranglerConfig>

```toml
# If you are only using Pages + D1, you only need the below in your Wrangler config file to interact with D1 locally.
[[d1_databases]]
binding = "DB" # Should match preview_database_id
database_name = "YOUR_DATABASE_NAME"
database_id = "the-id-of-your-D1-database-goes-here" # wrangler d1 info YOUR_DATABASE_NAME
preview_database_id = "DB" # Required for Pages local development
```

</WranglerConfig>

You can then execute queries and/or run migrations against a local database as part of your local development process by passing the `--local` flag to wrangler:

```bash
wrangler d1 execute YOUR_DATABASE_NAME \
  --local --command "CREATE TABLE IF NOT EXISTS users ( user_id INTEGER PRIMARY KEY, email_address TEXT, created_at INTEGER, deleted INTEGER, settings TEXT);"
```

The preceding command would execute queries the **local only** version of your D1 database. Without the `--local` flag, the commands are executed against the remote version of your D1 database running on Cloudflare's network.

## Persist data

:::note

By default, in Wrangler v3 and above, data is persisted across each run of `wrangler dev`. If your local development and testing requires or assumes an empty database, you should start with a `DROP TABLE <tablename>` statement to delete existing tables before using `CREATE TABLE` to re-create them.

:::

Use `wrangler dev --persist-to=/path/to/file` to persist data to a specific location. This can be useful when working in a team (allowing you to share) the same copy, when deploying via CI/CD (to ensure the same starting state), or as a way to keep data when migrating across machines.

Users of wrangler `2.x` must use the `--persist` flag: previous versions of wrangler did not persist data by default.

## Test programmatically

### Miniflare

[Miniflare](https://miniflare.dev/) allows you to simulate a Workers and resources like D1 using the same underlying runtime and code as used in production.

You can use Miniflare's [support for D1](https://miniflare.dev/storage/d1) to create D1 databases you can use for testing:



<WranglerConfig>

```toml
[[d1_databases]]
binding = "DB"
database_name = "test-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
```

</WranglerConfig>

```js
const mf = new Miniflare({
	d1Databases: {
		DB: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
	},
});
```

You can then use the `getD1Database()` method to retrieve the simulated database and run queries against it as if it were your real production D1 database:

```js
const db = await mf.getD1Database("DB");

const stmt = db.prepare("SELECT name, age FROM users LIMIT 3");
const { results } = await stmt.all();

console.log(results);
```

### `unstable_dev`

Wrangler exposes an [`unstable_dev()`](/workers/wrangler/api/) that allows you to run a local HTTP server for testing Workers and D1. Run [migrations](/d1/reference/migrations/) against a local database by setting a `preview_database_id` in your Wrangler configuration.

Given the below Wrangler configuration:

<WranglerConfig>

```toml
[[ d1_databases ]]
binding = "DB" # i.e. if you set this to "DB", it will be available in your Worker at `env.DB`
database_name = "your-database" # the name of your D1 database, set when created
database_id = "<UUID>" # The unique ID of your D1 database, returned when you create your database or run `
preview_database_id = "local-test-db" # A user-defined ID for your local test database.
```

</WranglerConfig>

Migrations can be run locally as part of your CI/CD setup by passing the `--local` flag to `wrangler`:

```sh
wrangler d1 migrations apply your-database --local
```

### Usage example

The following example shows how to use Wrangler's `unstable_dev()` API to:

- Run migrations against your local test database, as defined by `preview_database_id`.
- Make a request to an endpoint defined in your Worker. This example uses `/api/users/?limit=2`.
- Validate the returned results match, including the `Response.status` and the JSON our API returns.

```ts
import { unstable_dev } from "wrangler";
import type { UnstableDevWorker } from "wrangler";

describe("Test D1 Worker endpoint", () => {
	let worker: UnstableDevWorker;

	beforeAll(async () => {
		// Optional: Run any migrations to set up your `--local` database
		// By default, this will default to the preview_database_id
		execSync(`NO_D1_WARNING=true wrangler d1 migrations apply db --local`);

		worker = await unstable_dev("src/index.ts", {
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await worker.stop();
	});

	it("should return an array of users", async () => {
		// Our expected results
		const expectedResults = `{"results": [{"user_id": 1234, "email": "foo@example.com"},{"user_id": 6789, "email": "bar@example.com"}]}`;
		// Pass an optional URL to fetch to trigger any routing within your Worker
		const resp = await worker.fetch("/api/users/?limit=2");
		if (resp) {
			// https://jestjs.io/docs/expect#tobevalue
			expect(resp.status).toBe(200);
			const data = await resp.json();
			// https://jestjs.io/docs/expect#tomatchobjectobject
			expect(data).toMatchObject(expectedResults);
		}
	});
});
```

Review the [`unstable_dev()`](/workers/wrangler/api/#usage) documentation for more details on how to use the API within your tests.

## Related resources

- Use [`wrangler dev`](/workers/wrangler/commands/#dev) to run your Worker and D1 locally and debug issues before deploying.
- Learn [how to debug D1](/d1/observability/debug-d1/).
- Understand how to [access logs](/workers/observability/logs/) generated from your Worker and D1.

---

# Query a database

URL: https://developers.cloudflare.com/d1/best-practices/query-d1/

D1 is compatible with most SQLite's SQL convention since it leverages SQLite's query engine. You can use SQL commands to query D1.

There are a number of ways you can interact with a D1 database:

1. Using [D1 Workers Binding API](/d1/worker-api/) in your code.
2. Using [D1 REST API](/api/resources/d1/subresources/database/methods/create/).
3. Using [D1 Wrangler commands](/d1/wrangler-commands/).

## Use SQL to query D1

D1 understands SQLite semantics, which allows you to query a database using SQL statements via Workers BindingAPI or REST API (including Wrangler commands). Refer to [D1 SQL API](/d1/sql-api/sql-statements/) to learn more about supported SQL statements.

### Use foreign key relationships

When using SQL with D1, you may wish to define and enforce foreign key constraints across tables in a database. Foreign key constraints allow you to enforce relationships across tables, or prevent you from deleting rows that reference rows in other tables. An example of a foreign key relationship is shown below.

```sql
CREATE TABLE users (
    user_id INTEGER PRIMARY KEY,
    email_address TEXT,
    name TEXT,
    metadata TEXT
)

CREATE TABLE orders (
    order_id INTEGER PRIMARY KEY,
    status INTEGER,
    item_desc TEXT,
    shipped_date INTEGER,
    user_who_ordered INTEGER,
    FOREIGN KEY(user_who_ordered) REFERENCES users(user_id)
)
```

Refer to [Define foreign keys](/d1/sql-api/foreign-keys/) for more information.

### Query JSON

D1 allows you to query and parse JSON data stored within a database. For example, you can extract a value inside a JSON object.

Given the following JSON object (`type:blob`) in a column named `sensor_reading`, you can extract values from it directly.

```json
{
    "measurement": {
        "temp_f": "77.4",
        "aqi": [21, 42, 58],
        "o3": [18, 500],
        "wind_mph": "13",
        "location": "US-NY"
    }
}
```
```sql
-- Extract the temperature value
SELECT json_extract(sensor_reading, '$.measurement.temp_f')-- returns "77.4" as TEXT
```

Refer to [Query JSON](/d1/sql-api/query-json/) to learn more about querying JSON objects.

## Query D1 with Workers Binding API

Workers Binding API primarily interacts with the data plane, and allows you to query your D1 database from your Worker.

This requires you to:

1. Bind your D1 database to your Worker.
2. Prepare a statement.
3. Run the statement.

```js title="index.js"
export default {
    async fetch(request, env) {
        const {pathname} = new URL(request.url);
        const companyName1 = `Bs Beverages`;
        const companyName2 = `Around the Horn`;
        const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);

        if (pathname === `/RUN`) {
            const returnValue = await stmt.bind(companyName1).run();
            return Response.json(returnValue);
        }

        return new Response(
            `Welcome to the D1 API Playground!
						\nChange the URL to test the various methods inside your index.js file.`,
        );
    },
};
```

Refer to [Workers Binding API](/d1/worker-api/) for more information.

## Query D1 with REST API

REST API primarily interacts with the control plane, and allows you to create/manage your D1 database.

Refer to [D1 REST API](/api/resources/d1/subresources/database/methods/create/) for D1 REST API documentation.

## Query D1 with Wrangler commands

You can use Wrangler commands to query a D1 database. Note that Wrangler commands use REST APIs to perform its operations.

```sh
npx wrangler d1 execute prod-d1-tutorial --command="SELECT * FROM Customers"
```
```sh output
🌀 Mapping SQL input into an array of statements
🌀 Executing on local database production-db-backend (<DATABASE_ID>) from .wrangler/state/v3/d1:
┌────────────┬─────────────────────┬───────────────────┐
│ CustomerId │ CompanyName         │ ContactName       │
├────────────┼─────────────────────┼───────────────────┤
│ 1          │ Alfreds Futterkiste │ Maria Anders      │
├────────────┼─────────────────────┼───────────────────┤
│ 4          │ Around the Horn     │ Thomas Hardy      │
├────────────┼─────────────────────┼───────────────────┤
│ 11         │ Bs Beverages        │ Victoria Ashworth │
├────────────┼─────────────────────┼───────────────────┤
│ 13         │ Bs Beverages        │ Random Name       │
└────────────┴─────────────────────┴───────────────────┘
```

---

# Global read replication

URL: https://developers.cloudflare.com/d1/best-practices/read-replication/

import { GlossaryTooltip, Details, GitHubCode, APIRequest, Tabs, TabItem, TypeScriptExample } from "~/components"

D1 read replication can lower latency for read queries and scale read throughput by adding read-only database copies, called read replicas, across regions globally closer to clients.

Your application can use read replicas with D1 [Sessions API](/d1/worker-api/d1-database/#withsession). A session encapsulates all the queries from one logical session for your application. For example, a session may correspond to all queries coming from a particular web browser session. All queries within a session read from a database instance which is as up-to-date as your query needs it to be. Sessions API ensures [sequential consistency](/d1/best-practices/read-replication/#replica-lag-and-consistency-model) for all queries in a session.

To checkout D1 read replication, deploy the following Worker code using Sessions API, which will prompt you to create a D1 database and enable read replication on said database.

   [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/templates/tree/main/d1-starter-sessions-api-template)

:::note[Tip: Place your database further away for the read replication demo]
To simulate how read replication can improve a worst case latency scenario, set your D1 database location hint to be in a farther away region. For example, if you are in Europe create your database in Western North America (WNAM).
:::

<GitHubCode
repo="cloudflare/templates"
file="d1-starter-sessions-api/src/index.ts"
commit="3912e863acedd2be2438f8758f21374ed426fc54"
lang="ts"
useTypeScriptExample={true}
lines="7-44"
/>

## Primary database instance vs read replicas

![D1 read replication concept](/images/d1/d1-read-replication-concept.png)

When using D1 without read replication, D1 routes all queries (both read and write) to a specific database instance in [one location in the world](/d1/configuration/data-location/), known as the <GlossaryTooltip term="primary database instance"> primary database instance </GlossaryTooltip>. D1 request latency is dependent on the physical proximity of a user to the primary database instance. Users located further away from the primary database instance experience longer request latency due to [network round-trip time](https://www.cloudflare.com/learning/cdn/glossary/round-trip-time-rtt/).

When using read replication, D1 creates multiple asynchronously replicated copies of the primary database instance, which only serve read requests, called <GlossaryTooltip term="read replica"> read replicas </GlossaryTooltip>. D1 creates the read replicas in [multiple regions](/d1/best-practices/read-replication/#read-replica-locations) throughout the world across Cloudflare's network.

Even though a user may be located far away from the primary database instance, they could be close to a read replica. When D1 routes read requests to the read replica instead of the primary database instance, the user enjoys faster responses for their read queries.

D1 asynchronously replicates changes from the primary database instance to all read replicas. This means that at any given time, a read replica may be arbitrarily out of date. The time it takes for the latest committed data in the primary database instance to be replicated to the read replica is known as the <GlossaryTooltip term="replica lag"> replica lag </GlossaryTooltip>. Replica lag and non-deterministic routing to individual replicas can lead to application data consistency issues.
The D1 Sessions API solves this by ensuring sequential consistency.
For more information, refer to [replica lag and consistency model](/d1/best-practices/read-replication/#replica-lag-and-consistency-model).

:::note
All write queries are still forwarded to the primary database instance. Read replication only improves the response time for read query requests.
:::

| Type of database instance | Description                                                                                                                                       | How it handles write queries                                | How it handles read queries                               |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------- |
| Primary database instance | The database instance containing the “original” copy of the database                                                                              | Can serve write queries                                     | Can serve read queries                                    |
| Read replica database instance             | A database instance containing a copy of the original database which asynchronously receives updates from the primary database instance | Forwards any write queries to the primary database instance | Can serve read queries using its own copy of the database |

## Benefits of read replication

A system with multiple read replicas located around the world improves the performance of databases:

- The query latency decreases for users located close to the read replicas. By shortening the physical distance between a the database instance and the user, read query latency decreases, resulting in a faster application.
- The read throughput increases by distributing load across multiple replicas. Since multiple database instances are able to serve read-only requests, your application can serve a larger number of queries at any given time.

## Use Sessions API

By using [Sessions API](/d1/worker-api/d1-database/#withsession) for read replication, all of your queries from a single <GlossaryTooltip term="session">session</GlossaryTooltip> read from a version of the database which ensures sequential consistency. This ensures that the version of the database you are reading is logically consistent even if the queries are handled by different read replicas.

D1 read replication achieves this by attaching a <GlossaryTooltip term="bookmark">bookmark</GlossaryTooltip> to each query within a session. For more information, refer to [Bookmarks](/d1/reference/time-travel/#bookmarks).

### Enable read replication

Read replication can be enabled at the database level in the Cloudflare dashboard. Check **Settings** for your D1 database to view if read replication is enabled.

1. Go to [**Workers & Pages** > **D1**](https://dash.cloudflare.com/?to=/:account/workers/d1).
2. Select an existing database > **Settings** > **Enable Read Replication**.

### Start a session without constraints

To create a session from any available database version, use `withSession()` without any parameters, which will route the first query to any database instance, either the primary database instance or a read replica.

```ts
const session = env.DB.withSession() // synchronous
// query executes on either primary database or a read replica
const result = await session
	.prepare(`SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'`)
	.run()
```

- `withSession()` is the same as `withSession("first-unconstrained")`
- This approach is best when your application does not require the latest database version. All queries in a session ensure sequential consistency.
- Refer to the [D1 Workers Binding API documentation](/d1/worker-api/d1-database#withsession).

{/* #### Example of a D1 session without constraints

Suppose you want to develop a feature for displaying “likes” on a social network application.

The number of likes is a good example of a situation which does not require the latest information all the time. When displaying the number of likes of a post, the first request starts a new D1 session using the constraint `first-unconstrained`, which will be served by the nearest D1 read replica.

Subsequent interactions on the application should continue using the same session by passing the `bookmark` from the first query to subsequent requests. This guarantees that all interactions will observe information at least as up-to-date as the initial request, and therefore never show information older than what a user has already observed. The number of likes will be updated with newer counts over time with subsequent requests as D1 asynchronously updates the read replicas with the changes from the primary database.

```js
async function getLikes(postId: string, db: D1Database, bookmark: string | null): GetLikesResult {
  // NOTE: Achieve sequential consistency with given bookmark,
  //       or start a new session that can be served by any replica.
  const session = db.withSession(bookmark ?? "first-unconstrained");
  const { results } = session
	.prepare("SELECT * FROM likes WHERE postId = ?")
	.bind(postId)
	.run();
  return { bookmark: session.getBookmark(), likes: results };
}
``` */}

### Start a session with all latest data

To create a session from the latest database version, use `withSession("first-primary")`, which will route the first query to the primary database instance.

```ts
const session = env.DB.withSession(`first-primary`) // synchronous
// query executes on primary database
const result = await session
	.prepare(`SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'`)
	.run()
```

- This approach is best when your application requires the latest database version. All queries in a session ensure sequential consistency.
- Refer to the [D1 Workers Binding API documentation](/d1/worker-api/d1-database#withsession).

{/* #### Example of using `first-primary`

Suppose you want to develop a webpage for an electricity provider which lists the electricity bill statements. An assumption here is that each statement is immutable. Once issued, it never changes.

In this scenario, you want the first request of the page to show a list of all the statements and their issue dates. Therefore, the first request starts a new D1 session using the constraint `first-primary` to get the latest information (ensuring that the list includes all issued bill statements) from the primary database instance.

Then, when opening an individual electricity bill statement, we can continue using the same session by passing the `bookmark` from the first query to subsequent requests. Since each bill statement is immutable, any bill statement listed from the first query is guaranteed to be available in subsequent requests using the same session.

```ts
async function listBillStatements(accountId: string, db: D1Database): Promise<ListBillStatementsResult> {
	const session = db.withSession('first-primary');
	const { results } = (await session.prepare('SELECT * FROM bills WHERE accountId = ?').bind(accountId).run()) as unknown as {
		results: Bill[];
	};
	return { bookmark: session.getBookmark() ?? 'first-unconstrained', bills: results };
}

async function getBillStatement(accountId: string, billId: string, bookmark: string, db: D1Database): Promise<GetBillStatementResult> {
	// NOTE: We achieve sequential consistency with the given `bookmark`.
	const session = db.withSession(bookmark);
	const result = (await session
		.prepare('SELECT * FROM bills WHERE accountId = ? AND billId = ? LIMIT 1')
		.bind(accountId, billId)
		.first()) as unknown as Bill;

	return { bookmark: session.getBookmark() ?? 'first-unconstrained', bill: result };
}
``` */}

### Start a session from previous context (bookmark)

To create a new session from the context of a previous session, pass a `bookmark` parameter to guarantee that the session starts with a database version that is at least as up-to-date as the provided `bookmark`.

```ts
// retrieve bookmark from previous session stored in HTTP header
const bookmark = request.headers.get('x-d1-bookmark') ?? 'first-unconstrained';

const session = env.DB.withSession(bookmark)
const result = await session
	.prepare(`SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'`)
	.run()
// store bookmark for a future session
response.headers.set('x-d1-bookmark', session.getBookmark() ?? "")
```

- Starting a session with a `bookmark` ensures the new session will be at least as up-to-date as the previous session that generated the given `bookmark`.
- Refer to the [D1 Workers Binding API documentation](/d1/worker-api/d1-database#withsession).

{/* #### Example of using `bookmark`

This example follows from [Example of using `first-primary`](/d1/best-practices/read-replication/#example-of-using-first-primary), but retrieves the `bookmark` from HTTP cookie.

```ts collapse={1-10, 22-42, 61-86}
import { ListBillStatementsResult, GetBillStatementResult, Bill } from './types';

async function listBillStatements(accountId: string, db: D1Database): Promise<ListBillStatementsResult> {
	const session = db.withSession('first-primary');
	const { results } = (await session.prepare('SELECT * FROM bills WHERE accountId = ?').bind(accountId).run()) as unknown as {
		results: Bill[];
	};
	return { bookmark: session.getBookmark() ?? 'first-unconstrained', bills: results };
}

async function getBillStatement(accountId: string, billId: string, bookmark: string, db: D1Database): Promise<GetBillStatementResult> {
	// NOTE: We achieve sequential consistency with the given `bookmark`.
	const session = db.withSession(bookmark);
	const result = (await session
		.prepare('SELECT * FROM bills WHERE accountId = ? AND billId = ? LIMIT 1')
		.bind(accountId, billId)
		.first()) as unknown as Bill;

	return { bookmark: session.getBookmark() ?? 'first-unconstrained', bill: result };
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// URL path
		const url = new URL(request.url);
		const path = url.pathname;

		// Method
		const method = request.method;

		// Fetch using first-unconstrained
		if (path === '/bills' && method === 'GET') {
			// List bills
			const result = await listBillStatements('1', env.DB);
			return new Response(JSON.stringify(result), { status: 200 });
		}
		if (path === '/bill' && method === 'GET') {
			// Get bill
			const result = await getBillStatement('1', '1', 'first-unconstrained', env.DB);
			return new Response(JSON.stringify(result), { status: 200 });
		}

		// Fetch using bookmark from cookie
		if (path === '/bill/cookie' && method === 'GET') {
			// Get bill
			const cookie = request.headers.get('Cookie');
			const bookmark =
				cookie
					?.split(';')
					.find((c) => c.trim().startsWith('X-D1-Bookmark'))
					?.split('=')[1] ?? 'first-unconstrained';
			console.log('bookmark', bookmark);
			const result = await getBillStatement('1', '1', bookmark, env.DB);
			return new Response(JSON.stringify(result), {
				status: 200,
				headers: {
					'Set-Cookie': `X-D1-Bookmark=${result.bookmark}; Path=/; SameSite=Strict`,
				},
			});
		}

		// To ingest data
		if (path === '/bill' && method === 'POST') {
			// Create bill
			const { accountId, amount, description, due_date } = await request.json();
			const session = env.DB.withSession('first-primary');
			const { results } = await session
				.prepare('INSERT INTO bills (accountId, amount, description, due_date) VALUES (?, ?, ?, ?) RETURNING *')
				.bind(accountId, amount, description, due_date)
				.run();
			const bookmark = session.getBookmark() ?? 'first-unconstrained';

			return new Response(JSON.stringify(results), {
				status: 201,
				headers: {
					// Set bookmark cookie
					'Set-Cookie': `X-D1-Bookmark=${bookmark}; Path=/; SameSite=Strict`,
				},
			});
		}
		return new Response('Not Found', {
			status: 404,
			statusText: 'Not Found',
		});
	},
} satisfies ExportedHandler<Env>;
``` */}

### Check where D1 request was processed

To see how D1 requests are processed by the addition of read replicas, `served_by_region` and `served_by_primary` fields are returned in the `meta` object of [D1 Result](/d1/worker-api/return-object/#d1result).

```ts
const result = await env.DB.withSession()
	.prepare(`SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'`)
	.run();
console.log({
  servedByRegion: result.meta.served_by_region ?? "",
  servedByPrimary: result.meta.served_by_primary ?? "",
});
```

- `served_by_region` and `served_by_primary` fields are present for all D1 remote requests, regardless of whether read replication is enabled or if the Sessions API is used. On local development, `npx wrangler dev`, these fields are `undefined`.

### Enable read replication via REST API

With the REST API, set `read_replication.mode: auto` to enable read replication on a D1 database.

For this REST endpoint, you need to have an API token with `D1:Edit` permission. If you do not have an API token, follow the guide: [Create API token](/fundamentals/api/get-started/create-token/).

<Tabs>
<TabItem label="cURL">
```sh
curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/d1/database/{database_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read_replication": {"mode": "auto"}}'
```
</TabItem><TabItem label="TypeScript">

```ts
const headers = new Headers({
  "Authorization": `Bearer ${TOKEN}`
});

await fetch ("/v4/accounts/{account_id}/d1/database/{database_id}", {
	method: "PUT",
	headers: headers,
	body: JSON.stringify(
		{ "read_replication": { "mode": "auto" } }
	)
 }
)
```
</TabItem>
</Tabs>

### Disable read replication via REST API

With the REST API, set `read_replication.mode: disabled` to disable read replication on a D1 database.

For this REST endpoint, you need to have an API token with `D1:Edit` permission. If you do not have an API token, follow the guide: [Create API token](/fundamentals/api/get-started/create-token/).

:::note
Disabling read replication takes up to 24 hours for replicas to stop processing requests. Sessions API works with databases that do not have read replication enabled, so it is safe to run code with Sessions API even after disabling read replication.
:::

<Tabs>
<TabItem label="cURL">
```sh
curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/d1/database/{database_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read_replication": {"mode": "disabled"}}'
```
</TabItem><TabItem label="TypeScript">
```ts
const headers = new Headers({
  "Authorization": `Bearer ${TOKEN}`
});

await fetch ("/v4/accounts/{account_id}/d1/database/{database_id}", {
	method: "PUT",
	headers: headers,
	body: JSON.stringify(
		{ "read_replication": { "mode": "disabled" } }
	)
 }
)
```
</TabItem>
</Tabs>

### Check if read replication is enabled

On the Cloudflare dashboard, check **Settings** for your D1 database to view if read replication is enabled.

Alternatively, `GET` D1 database REST endpoint returns if read replication is enabled or disabled.

For this REST endpoint, you need to have an API token with `D1:Read` permission. If you do not have an API token, follow the guide: [Create API token](/fundamentals/api/get-started/create-token/).

<Tabs>
<TabItem label="cURL">
```sh
curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/d1/database/{database_id}" \
  -H "Authorization: Bearer $TOKEN"
```
</TabItem>
<TabItem label="TypeScript">
```ts
const headers = new Headers({
  "Authorization": `Bearer ${TOKEN}`
});

const response = await fetch("/v4/accounts/{account_id}/d1/database/{database_id}", {
  method: "GET",
  headers: headers
});

const data = await response.json();
console.log(data.read_replication.mode);
```
</TabItem>
</Tabs>

- Check the `read_replication` property of the `result` object
	- `"mode": "auto"` indicates read replication is enabled
	- `"mode": "disabled"` indicates read replication is disabled

## Read replica locations

Currently, D1 automatically creates a read replica in [every supported region](/d1/configuration/data-location/#available-location-hints), including the region where the primary database instance is located. These regions are:

- ENAM
- WNAM
- WEUR
- EEUR
- APAC
- OC

:::note
Read replica locations are subject to change at Cloudflare's discretion.
:::

## Observability

To see the impact of read replication and check the how D1 requests are processed by additional database instances, you can use:

- The `meta` object within the [`D1Result`](/d1/worker-api/return-object/#d1result) return object, which includes new fields:
  - `served_by_region`
  - `served_by_primary`
- The [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/d1), where you can view your database metrics breakdown by region that processed D1 requests.

## Known limitations

There are some known limitations for D1 read replication.

- Sessions API is only available via the [D1 Worker Binding](/d1/worker-api/d1-database/#withsession) and not yet available via the REST API.

## Background information

### Replica lag and consistency model

To account for <GlossaryTooltip term="replica lag">replica lag</GlossaryTooltip>, it is important to consider the consistency model for D1. A consistency model is a logical framework that governs how a database system serves user queries (how the data is updated and accessed) when there are multiple database instances. Different models can be useful in different use cases. Most database systems provide [read committed](https://jepsen.io/consistency/models/read-committed), [snapshot isolation](https://jepsen.io/consistency/models/snapshot-isolation), or [serializable](https://jepsen.io/consistency/models/serializable) consistency models, depending on their configuration.

#### Without Sessions API

Consider what could happen in a distributed database system.

![Distributed replicas could cause inconsistencies without Sessions API](/images/d1/consistency-without-sessions-api.png)

1. Your SQL write query is processed by the primary database instance.
2. You obtain a response acknowledging the write query.
3. Your subsequent SQL read query goes to a read replica.
4. The read replica has not yet been updated, so does not contain changes from your SQL write query. The returned results are inconsistent from your perspective.

#### With Sessions API

When using D1 Sessions API, your queries obtain bookmarks which allows the read replica to only serve sequentially consistent data.

![D1 offers sequential consistency when using Sessions API](/images/d1/consistency-with-sessions-api.png)

1. SQL write query is processed by the primary database instance.
2. You obtain a response acknowledging the write query. You also obtain a bookmark (100) which identifies the state of the database after the write query.
3. Your subsequent SQL read query goes to a read replica, and also provides the bookmark (100).
4. The read replica will wait until it has been updated to be at least as up-to-date as the provided bookmark (100).
5. Once the read replica has been updated (bookmark 104), it serves your read query, which is now sequentially consistent.

In the diagram, the returned bookmark is bookmark 104, which is different from the one provided in your read query (bookmark 100). This can happen if there were other writes from other client requests that also got replicated to the read replica in between the two write/read queries you executed.

#### Sessions API provides sequential consistency

D1 read replication offers [sequential consistency](https://jepsen.io/consistency/models/sequential). D1 creates a global order of all operations which have taken place on the database, and can identify the latest version of the database that a query has seen, using [bookmarks](/d1/reference/time-travel/#bookmarks). It then serves the query with a database instance that is at least as up-to-date as the bookmark passed along with the query to execute.

Sequential consistency has properties such as:

- **Monotonic reads**: If you perform two reads one after the other (read-1, then read-2), read-2 cannot read a version of the database prior to read-1.
- **Monotonic writes**: If you perform write-1 then write-2, all processes observe write-1 before write-2.
- **Writes follow reads**: If you read a value, then perform a write, the subsequent write must be based on the value that was just read.
- **Read my own writes**: If you write to the database, all subsequent reads will see the write.

## Supplementary information

You may wish to refer to the following resources:

- Blog: [Sequential consistency without borders: How D1 implements global read replication](https://blog.cloudflare.com/d1-read-replication-beta/)
- Blog: [Building D1: a Global Database](https://blog.cloudflare.com/building-d1-a-global-database/)
- [D1 Sessions API documentation](/d1/worker-api/d1-database#withsession)
- [Starter code for D1 Sessions API demo](https://github.com/cloudflare/templates/tree/main/d1-starter-sessions-api-template)
- [E-commerce store read replication tutorial](/d1/tutorials/using-read-replication-for-e-com)

---

# Remote development

URL: https://developers.cloudflare.com/d1/best-practices/remote-development/

D1 supports remote development using the [dashboard playground](/workers/playground/#use-the-playground). The dashboard playground uses a browser version of Visual Studio Code, allowing you to rapidly iterate on your Worker entirely in your browser.

## 1. Bind a D1 database to a Worker

:::note


This guide assumes you have previously created a Worker, and a D1 database.

Users new to D1 and/or Cloudflare Workers should read the [D1 tutorial](/d1/get-started/) to install `wrangler` and deploy their first database.


:::

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to [**Workers & Pages** > **Overview**](https://dash.cloudflare.com/?to=/:account/workers-and-pages).
3. Select an existing Worker.
4. Select the **Settings** tab.
5. Select the **Variables** sub-tab.
6. Scroll down to the **D1 Database Bindings** heading.
7. Enter a variable name, such as `DB`, and select the D1 database you wish to access from this Worker.
8. Select **Save and deploy**.

## 2. Start a remote development session

1. On the Worker's page on the Cloudflare dashboard, select **Edit Code** at the top of the page.
2. Your Worker now has access to D1.

Use the following Worker script to verify that the Worker has access to the bound D1 database:

```js
export default {
  async fetch(request, env, ctx) {
    const res = await env.DB.prepare("SELECT 1;").all();
    return new Response(JSON.stringify(res, null, 2));
  },
};
```

## Related resources

* Learn [how to debug D1](/d1/observability/debug-d1/).
* Understand how to [access logs](/workers/observability/logs/) generated from your Worker and D1.

---

# Use indexes

URL: https://developers.cloudflare.com/d1/best-practices/use-indexes/

import { GlossaryTooltip } from "~/components";

Indexes enable D1 to improve query performance over the indexed columns for common (popular) queries by reducing the amount of data (number of rows) the database has to scan when running a query.

## When is an index useful?

Indexes are useful:

* When you want to improve the read performance over columns that are regularly used in predicates - for example, a `WHERE email_address = ?` or `WHERE user_id = 'a793b483-df87-43a8-a057-e5286d3537c5'` - email addresses, usernames, user IDs and/or dates are good choices for columns to index in typical web applications or services.
* For enforcing uniqueness constraints on a column or columns - for example, an email address or user ID via the `CREATE UNIQUE INDEX`.
* In cases where you query over multiple columns together - `(customer_id, transaction_date)`.

Indexes are automatically updated when the table and column(s) they reference are inserted, updated or deleted. You do not need to manually update an index after you write to the table it references.

## Create an index

:::note

Tables that use the default primary key (an `INTEGER` based `ROWID`), or that define their own `INTEGER PRIMARY KEY`, do not need to create an index for that column.
:::

To create an index on a D1 table, use the `CREATE INDEX` SQL command and specify the table and column(s) to create the index over.

For example, given the following `orders` table, you may want to create an index on `customer_id`. Nearly all of your queries against that table filter on `customer_id`, and you would see a performance improvement by creating an index for it.

```sql
CREATE TABLE IF NOT EXISTS orders (
    order_id INTEGER PRIMARY KEY,
    customer_id STRING NOT NULL, -- for example, a unique ID aba0e360-1e04-41b3-91a0-1f2263e1e0fb
    order_date STRING NOT NULL,
    status INTEGER NOT NULL,
    last_updated_date STRING NOT NULL
)
```

To create the index on the `customer_id` column, execute the below statement against your database:

:::note

A common naming format for indexes is `idx_TABLE_NAME_COLUMN_NAMES`, so that you can identify the table and column(s) your indexes are for when managing your database.
:::

```sql
CREATE INDEX IF NOT EXISTS idx_orders_customer_id ON orders(customer_id)
```

Queries that reference the `customer_id` column will now benefit from the index:

```sql
-- Uses the index: the indexed column is referenced by the query.
SELECT * FROM orders WHERE customer_id = ?

-- Does not use the index: customer_id is not in the query.
SELECT * FROM orders WHERE order_date = '2023-05-01'
```

In more complex cases, you can confirm whether an index was used by D1 by [analyzing a query](#test-an-index) directly.

### Run `PRAGMA optimize`

After creating an index, run the `PRAGMA optimize` command to improve your database performance.

`PRAGMA optimize` runs `ANALYZE` command on each table in the database, which collects statistics on the tables and indices. These statistics allows the <GlossaryTooltip term="query planner">query planner</GlossaryTooltip> to generate the most efficient query plan when executing the user query.

For more information, refer to [`PRAGMA optimize`](/d1/sql-api/sql-statements/#pragma-optimize).

## List indexes

List the indexes on a database, as well as the SQL definition, by querying the `sqlite_schema` system table:

```sql
SELECT name, type, sql FROM sqlite_schema WHERE type IN ('index');
```

This will return output resembling the below:

```txt
┌──────────────────────────────────┬───────┬────────────────────────────────────────┐
│ name                             │ type  │ sql                                    │
├──────────────────────────────────┼───────┼────────────────────────────────────────┤
│ idx_users_id                     │ index │ CREATE INDEX idx_users_id ON users(id) │
└──────────────────────────────────┴───────┴────────────────────────────────────────┘
```

Note that you cannot modify this table, or an existing index. To modify an index, [delete it first](#remove-indexes) and [create a new index](#create-an-index) with the updated definition.

## Test an index

Validate that an index was used for a query by prepending a query with [`EXPLAIN QUERY PLAN`](https://www.sqlite.org/eqp.html). This will output a query plan for the succeeding statement, including which (if any) indexes were used.

For example, if you assume the `users` table has an `email_address TEXT` column and you created an index `CREATE UNIQUE INDEX idx_email_address ON users(email_address)`, any query with a predicate on `email_address` should use your index.

```sql
EXPLAIN QUERY PLAN SELECT * FROM users WHERE email_address = 'foo@example.com';
QUERY PLAN
`--SEARCH users USING INDEX idx_email_address (email_address=?)
```

Review the `USING INDEX <INDEX_NAME>` output from the query planner, confirming the index was used.

This is also a fairly common use-case for an index. Finding a user based on their email address is often a very common query type for login (authentication) systems.

Using an index can reduce the number of rows read by a query. Use the `meta` object to estimate your usage. Refer to ["Can I use an index to reduce the number of rows read by a query?"](/d1/platform/pricing/#can-i-use-an-index-to-reduce-the-number-of-rows-read-by-a-query) and ["How can I estimate my (eventual) bill?"](/d1/platform/pricing/#how-can-i-estimate-my-eventual-bill).

## Multi-column indexes

For a multi-column index (an index that specifies multiple columns), queries will only use the index if they specify either *all* of the columns, or a subset of the columns provided all columns to the "left" are also within the query.

Given an index of `CREATE INDEX idx_customer_id_transaction_date ON transactions(customer_id, transaction_date)`, the following table shows when the index is used (or not):

| Query                                                                                       | Index Used?                                                                                        |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SELECT * FROM transactions WHERE customer_id = '1234' AND transaction_date = '2023-03-25'` | Yes: specifies both columns in the index.                                                          |
| `SELECT * FROM transactions WHERE transaction_date = '2023-03-28'`                          | No: only specifies `transaction_date`, and does not include other leftmost columns from the index. |
| `SELECT * FROM transactions WHERE customer_id = '56789'`                                    | Yes: specifies `customer_id`, which is the leftmost column in the index.                           |

Notes:

* If you created an index over three columns instead — `customer_id`, `transaction_date` and `shipping_status` — a query that uses both `customer_id` and `transaction_date` would use the index, as you are including all columns "to the left".
* With the same index, a query that uses only `transaction_date` and `shipping_status` would *not* use the index, as you have not used `customer_id` (the leftmost column) in the query.

## Partial indexes

Partial indexes are indexes over a subset of rows in a table. Partial indexes are defined by the use of a `WHERE` clause when creating the index. A partial index can be useful to omit certain rows, such as those where values are `NULL` or where rows with a specific value are present across queries.

* A concrete example of a partial index would be on a table with a `order_status INTEGER` column, where `6` might represent `"order complete"` in your application code.
* This would allow queries against orders that are yet to be fulfilled, shipped or are in-progress, which are likely to be some of the most common users (users checking their order status).
* Partial indexes also keep the index from growing unbounded over time. The index does not need to keep a row for every completed order, and completed orders are likely to be queried far fewer times than in-progress orders.

A partial index that filters out completed orders from the index would resemble the following:

```sql
CREATE INDEX idx_order_status_not_complete ON orders(order_status) WHERE order_status != 6
```

Partial indexes can be faster at read time (less rows in the index) and at write time (fewer writes to the index) than full indexes. You can also combine a partial index with a [multi-column index](#multi-column-indexes).

## Remove indexes

Use `DROP INDEX` to remove an index. Dropped indexes cannot be restored.

## Considerations

Take note of the following considerations when creating indexes:

* Indexes are not always a free performance boost. You should create indexes only on columns that reflect your most-queried columns. Indexes themselves need to be maintained. When you write to an indexed column, the database needs to write to the table and the index. The performance benefit of an index and reduction in rows read will, in nearly all cases, offset this additional write.
* You cannot create indexes that reference other tables or use non-deterministic functions, since the index would not be stable.
* Indexes cannot be updated. To add or remove a column from an index, [remove](#remove-indexes) the index and then [create a new index](#create-an-index) with the new columns.
* Indexes contribute to the overall storage required by your database: an index is effectively a table itself.

---

# Data location

URL: https://developers.cloudflare.com/d1/configuration/data-location/

Learn how the location of data stored in D1 is determined, including where the leader is placed and how you optimize that location based on your needs.

## Automatic (recommended)

By default, D1 will automatically create your primary database instance in a location close to where you issued the request to create a database. In most cases this allows D1 to choose the optimal location for your database on your behalf.

## Provide a location hint

Location hint is an optional parameter you can provide to indicate your desired geographical location for your primary database instance.

You may want to explicitly provide a location hint in cases where the majority of your writes to a specific database come from a different location than where you are creating the database from. Location hints can be useful when:

- Working in a distributed team.
- Creating databases specific to users in specific locations.
- Using continuous deployment (CD) or Infrastructure as Code (IaC) systems to programmatically create your databases.

Provide a location hint when creating a D1 database when:

- Using [`wrangler d1`](/workers/wrangler/commands/#d1) to create a database.
- Creating a database [via the Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/d1).

:::caution
Providing a location hint does not guarantee that D1 runs in your preferred location. Instead, it will run in the nearest possible location (by latency) to your preference.
:::

### Use Wrangler

:::note
To install Wrangler, the command-line interface for D1 and Workers, refer to [Install and Update Wrangler](/workers/wrangler/install-and-update/).
:::

To provide a location hint when creating a new database, pass the `--location` flag with a valid location hint:

```sh
wrangler d1 create new-database --location=weur
```

### Use the dashboard

To provide a location hint when creating a database via the dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to [**Workers & Pages** > **D1**](https://dash.cloudflare.com/?to=/:account/workers/d1).
3. Select **Create database**.
4. Provide a database name and an optional **Location**.
5. Select **Create** to create your database.

## Available location hints

D1 supports the following location hints:

| Hint | Hint description      |
| ---- | --------------------- |
| wnam | Western North America |
| enam | Eastern North America |
| weur | Western Europe        |
| eeur | Eastern Europe        |
| apac | Asia-Pacific          |
| oc   | Oceania               |

:::caution
D1 location hints are not currently supported for South America (`sam`), Africa (`afr`), and the Middle East (`me`). D1 databases do not run in these locations.
:::

## Read replica locations

With read replication enabled, D1 creates and distributes read-only copies of the primary database instance around the world. This reduces the query latency for users located far away from the primary database instance.

When using D1 read replication, D1 automatically creates a read replica in [every available region](/d1/configuration/data-location#available-location-hints), including the region where the primary database instance is located.

Refer to [D1 read replication](/d1/best-practices/read-replication/) for more information.

---

# Environments

URL: https://developers.cloudflare.com/d1/configuration/environments/

import { WranglerConfig } from "~/components";

[Environments](/workers/wrangler/environments/) are different contexts that your code runs in. Cloudflare Developer Platform allows you to create and manage different environments. Through environments, you can deploy the same project to multiple places under multiple names.

To specify different D1 databases for different environments, use the following syntax in your Wrangler file:

<WranglerConfig>

```toml
# This is a staging environment
[env.staging]
d1_databases = [
    { binding = "<BINDING_NAME_1>", database_name = "<DATABASE_NAME_1>", database_id = "<UUID1>" },
]

# This is a production environment
[env.production]
d1_databases = [
    { binding = "<BINDING_NAME_2>", database_name = "<DATABASE_NAME_2>", database_id = "<UUID2>" },
]
```

</WranglerConfig>

In the code above, the `staging` environment is using a different database (`DATABASE_NAME_1`) than the `production` environment (`DATABASE_NAME_2`).

## Anatomy of Wrangler file

If you need to specify different D1 databases for different environments, your [Wrangler configuration file](/workers/wrangler/configuration/) may contain bindings that resemble the following:

<WranglerConfig>

```toml
[[production.d1_databases]]
binding = "DB"
database_name = "DATABASE_NAME"
database_id = "DATABASE_ID"
```

</WranglerConfig>

In the above configuration:

- `[[production.d1_databases]]` creates an object `production` with a property `d1_databases`, where `d1_databases` is an array of objects, since you can create multiple D1 bindings in case you have more than one database.
- Any property below the line in the form `<key> = <value>` is a property of an object within the `d1_databases` array.

Therefore, the above binding is equivalent to:

```json
{
  "production": {
    "d1_databases": [
      {
        "binding": "DB",
        "database_name": "DATABASE_NAME",
        "database_id": "DATABASE_ID"
      }
    ]
  }
}
```

### Example



<WranglerConfig>

```toml
[[env.staging.d1_databases]]
binding = "BINDING_NAME_1"
database_name = "DATABASE_NAME_1"
database_id = "UUID_1"

[[env.production.d1_databases]]
binding = "BINDING_NAME_2"
database_name = "DATABASE_NAME_2"
database_id = "UUID_2"

```

</WranglerConfig>

The above is equivalent to the following structure in JSON:

```json
{
  "env": {
    "production": {
      "d1_databases": [
        {
          "binding": "BINDING_NAME_2",
          "database_id": "UUID_2",
          "database_name": "DATABASE_NAME_2"
        }
      ]
    },
    "staging": {
      "d1_databases": [
        {
          "binding": "BINDING_NAME_1",
          "database_id": "UUID_1",
          "database_name": "DATABASE_NAME_1"
        }
      ]
    }
  }
}
```

---

# Query D1 from Hono

URL: https://developers.cloudflare.com/d1/examples/d1-and-hono/

import { TabItem, Tabs } from "~/components";

Hono is a fast web framework for building API-first applications, and it includes first-class support for both [Workers](/workers/) and [Pages](/pages/).

When using Workers:

- Ensure you have configured your [Wrangler configuration file](/d1/get-started/#3-bind-your-worker-to-your-d1-database) to bind your D1 database to your Worker.
- You can access your D1 databases via Hono's [`Context`](https://hono.dev/api/context) parameter: [bindings](https://hono.dev/getting-started/cloudflare-workers#bindings) are exposed on `context.env`. If you configured a [binding](/pages/functions/bindings/#d1-databases) named `DB`, then you would access [D1 Workers Binding API](/d1/worker-api/prepared-statements/) methods via `c.env.DB`.
- Refer to the Hono documentation for [Cloudflare Workers](https://hono.dev/getting-started/cloudflare-workers).

If you are using [Pages Functions](/pages/functions/):

1. Bind a D1 database to your [Pages Function](/pages/functions/bindings/#d1-databases).
2. Pass the `--d1 BINDING_NAME=DATABASE_ID` flag to `wrangler dev` when developing locally. `BINDING_NAME` should match what call in your code, and `DATABASE_ID` should match the `database_id` defined in your Wrangler configuration file: for example, `--d1 DB=xxxx-xxxx-xxxx-xxxx-xxxx`.
3. Refer to the Hono guide for [Cloudflare Pages](https://hono.dev/getting-started/cloudflare-pages).

The following examples show how to access a D1 database bound to `DB` from both a Workers script and a Pages Function:

<Tabs> <TabItem label="workers">

```ts
import { Hono } from "hono";

// This ensures c.env.DB is correctly typed
type Bindings = {
	DB: D1Database;
};

const app = new Hono<{ Bindings: Bindings }>();

// Accessing D1 is via the c.env.YOUR_BINDING property
app.get("/query/users/:id", async (c) => {
	const userId = c.req.param("id");
	try {
		let { results } = await c.env.DB.prepare(
			"SELECT * FROM users WHERE user_id = ?",
		)
			.bind(userId)
			.all();
		return c.json(results);
	} catch (e) {
		return c.json({ err: e.message }, 500);
	}
});

// Export our Hono app: Hono automatically exports a
// Workers 'fetch' handler for you
export default app;
```

</TabItem> <TabItem label="pages">

```ts
import { Hono } from "hono";
import { handle } from "hono/cloudflare-pages";

const app = new Hono().basePath("/api");

// Accessing D1 is via the c.env.YOUR_BINDING property
app.get("/query/users/:id", async (c) => {
	const userId = c.req.param("id");
	try {
		let { results } = await c.env.DB.prepare(
			"SELECT * FROM users WHERE user_id = ?",
		)
			.bind(userId)
			.all();
		return c.json(results);
	} catch (e) {
		return c.json({ err: e.message }, 500);
	}
});

// Export the Hono instance as a Pages onRequest function
export const onRequest = handle(app);
```

</TabItem> </Tabs>

---

# Configuration

URL: https://developers.cloudflare.com/d1/configuration/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Query D1 from Remix

URL: https://developers.cloudflare.com/d1/examples/d1-and-remix/

import { TabItem, Tabs } from "~/components";

Remix is a full-stack web framework that operates on both client and server. You can query your D1 database(s) from Remix using Remix's [data loading](https://remix.run/docs/en/main/guides/data-loading) API with the [`useLoaderData`](https://remix.run/docs/en/main/hooks/use-loader-data) hook.

To set up a new Remix site on Cloudflare Pages that can query D1:

1. **Refer to [the Remix guide](/pages/framework-guides/deploy-a-remix-site/)**.
2. Bind a D1 database to your [Pages Function](/pages/functions/bindings/#d1-databases).
3. Pass the `--d1 BINDING_NAME=DATABASE_ID` flag to `wrangler dev` when developing locally. `BINDING_NAME` should match what call in your code, and `DATABASE_ID` should match the `database_id` defined in your [Wrangler configuration file](/workers/wrangler/configuration/): for example, `--d1 DB=xxxx-xxxx-xxxx-xxxx-xxxx`.

The following example shows you how to define a Remix [`loader`](https://remix.run/docs/en/main/route/loader) that has a binding to a D1 database.

- Bindings are passed through on the `context.env` parameter passed to a `LoaderFunction`.
- If you configured a [binding](/pages/functions/bindings/#d1-databases) named `DB`, then you would access [D1 Workers Binding API](/d1/worker-api/prepared-statements/) methods via `context.env.DB`.

<Tabs> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import type { LoaderFunction } from "@remix-run/cloudflare";
import { json } from "@remix-run/cloudflare";
import { useLoaderData } from "@remix-run/react";

interface Env {
  DB: D1Database;
}

export const loader: LoaderFunction = async ({ context, params }) => {
  let env = context.cloudflare.env as Env;

  let { results } = await env.DB.prepare("SELECT * FROM users LIMIT 5").all();
  return json(results);
};

export default function Index() {
  const results = useLoaderData<typeof loader>();
  return (
    <div style={{ fontFamily: "system-ui, sans-serif", lineHeight: "1.8" }}>
      <h1>Welcome to Remix</h1>
      <div>
        A value from D1:
        <pre>{JSON.stringify(results)}</pre>
      </div>
    </div>
  );
}
```

</TabItem> </Tabs>

---

# Query D1 from SvelteKit

URL: https://developers.cloudflare.com/d1/examples/d1-and-sveltekit/

import { TabItem, Tabs } from "~/components";

[SvelteKit](https://kit.svelte.dev/) is a full-stack framework that combines the Svelte front-end framework with Vite for server-side capabilities and rendering. You can query D1 from SvelteKit by configuring a [server endpoint](https://kit.svelte.dev/docs/routing#server) with a binding to your D1 database(s).

To set up a new SvelteKit site on Cloudflare Pages that can query D1:

1. **Refer to [the SvelteKit guide](/pages/framework-guides/deploy-a-svelte-kit-site/) and Svelte's [Cloudflare adapter](https://kit.svelte.dev/docs/adapter-cloudflare)**.
2. Install the Cloudflare adapter within your SvelteKit project: `npm i -D @sveltejs/adapter-cloudflare`.
3. Bind a D1 database [to your Pages Function](/pages/functions/bindings/#d1-databases).
4. Pass the `--d1 BINDING_NAME=DATABASE_ID` flag to `wrangler dev` when developing locally. `BINDING_NAME` should match what call in your code, and `DATABASE_ID` should match the `database_id` defined in your [Wrangler configuration file](/workers/wrangler/configuration/): for example, `--d1 DB=xxxx-xxxx-xxxx-xxxx-xxxx`.

The following example shows you how to create a server endpoint configured to query D1.

- Bindings are available on the `platform` parameter passed to each endpoint, via `platform.env.BINDING_NAME`.
- With SvelteKit's [file-based routing](https://kit.svelte.dev/docs/routing), the server endpoint defined in `src/routes/api/users/+server.ts` is available at `/api/users` within your SvelteKit app.

The example also shows you how to configure both your app-wide types within `src/app.d.ts` to recognize your `D1Database` binding, import the `@sveltejs/adapter-cloudflare` adapter into `svelte.config.js`, and configure it to apply to all of your routes.

<Tabs> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import type { RequestHandler } from "@sveltejs/kit";

/** @type {import('@sveltejs/kit').RequestHandler} */
export async function GET({ request, platform }) {
	let result = await platform.env.DB.prepare(
		"SELECT * FROM users LIMIT 5",
	).run();
	return new Response(JSON.stringify(result));
}
```

```ts
// See https://kit.svelte.dev/docs/types#app
// for information about these interfaces
declare global {
	namespace App {
		// interface Error {}
		// interface Locals {}
		// interface PageData {}
		interface Platform {
			env: {
				DB: D1Database;
			};
			context: {
				waitUntil(promise: Promise<any>): void;
			};
			caches: CacheStorage & { default: Cache };
		}
	}
}

export {};
```

```js
import adapter from "@sveltejs/adapter-cloudflare";

export default {
	kit: {
		adapter: adapter({
			// See below for an explanation of these options
			routes: {
				include: ["/*"],
				exclude: ["<all>"],
			},
		}),
	},
};
```

</TabItem> </Tabs>

---

# Examples

URL: https://developers.cloudflare.com/d1/examples/

import { GlossaryTooltip, ListExamples } from "~/components";

Explore the following <GlossaryTooltip term="code example">examples</GlossaryTooltip> for D1.

<ListExamples directory="d1/examples/" />

---

# Query D1 from Python Workers

URL: https://developers.cloudflare.com/d1/examples/query-d1-from-python-workers/

import { WranglerConfig } from "~/components";

The Cloudflare Workers platform supports [multiple languages](/workers/languages/), including TypeScript, JavaScript, Rust and Python. This guide shows you how to query a D1 database from [Python](/workers/languages/python/) and deploy your application globally.

:::note

Support for Python in Cloudflare Workers is in beta. Review the [documentation on Python support](/workers/languages/python/) to understand how Python works within the Workers platform.

:::

## Prerequisites

Before getting started, you should:

1. Review the [D1 tutorial](/d1/get-started/) for TypeScript and JavaScript to learn how to **create a D1 database and configure a Workers project**.
2. Refer to the [Python language guide](/workers/languages/python/) to understand how Python support works on the Workers platform.
3. Have basic familiarity with the Python language.

If you are new to Cloudflare Workers, refer to the [Get started guide](/workers/get-started/guide/) first before continuing with this example.

## Query from Python

This example assumes you have an existing D1 database. To allow your Python Worker to query your database, you first need to create a [binding](/workers/runtime-apis/bindings/) between your Worker and your D1 database and define this in your [Wrangler configuration file](/workers/wrangler/configuration/).

You will need the `database_name` and `database_id` for a D1 database. You can use the `wrangler` CLI to create a new database or fetch the ID for an existing database as follows:

```sh title="Create a database"
npx wrangler d1 create my-first-db
```

```sh title="Retrieve a database ID"
npx wrangler d1 info some-existing-db
```

```sh output
# ┌───────────────────┬──────────────────────────────────────┐
# │                   │ c89db32e-83f4-4e62-8cd7-7c8f97659029 │
# ├───────────────────┼──────────────────────────────────────┤
# │ name              │ db-enam                              │
# ├───────────────────┼──────────────────────────────────────┤
# │ created_at        │ 2023-06-12T16:52:03.071Z             │
# └───────────────────┴──────────────────────────────────────┘
```

### 1. Configure bindings

In your Wrangler file, create a new `[[d1_databases]]` configuration block and set `database_name` and `database_id` to the name and id (respectively) of the D1 database you want to query:

<WranglerConfig>

```toml
name = "python-and-d1"
main = "src/entry.py"
compatibility_flags = ["python_workers"] # Required for Python Workers
compatibility_date = "2024-03-29"

[[d1_databases]]
binding = "DB" # This will be how you refer to your database in your Worker
database_name = "YOUR_DATABASE_NAME"
database_id = "YOUR_DATABASE_ID"
```

</WranglerConfig>

The value of `binding` is how you will refer to your database from within your Worker. If you change this, you must change this in your Worker script as well.

### 2. Create your Python Worker

To create a Python Worker, create an empty file at `src/entry.py`, matching the value of `main` in your Wrangler file with the contents below:

```python
from workers import Response

async def on_fetch(request, env):
    # Do anything else you'd like on request here!

    # Query D1 - we'll list all tables in our database in this example
    results = await env.DB.prepare("PRAGMA table_list").all()
    # Return a JSON response
    return Response.json(results)

```

The value of `binding` in your Wrangler file exactly must match the name of the variable in your Python code. This example refers to the database via a `DB` binding, and query this binding via `await env.DB.prepare(...)`.

You can then deploy your Python Worker directly:

```sh
npx wrangler deploy
```

```sh output
# Example output
#
# Your worker has access to the following bindings:
# - D1 Databases:
#   - DB: db-enam (c89db32e-83f4-4e62-8cd7-7c8f97659029)
# Total Upload: 0.18 KiB / gzip: 0.17 KiB
# Uploaded python-and-d1 (4.93 sec)
# Published python-and-d1 (0.51 sec)
#   https://python-and-d1.YOUR_SUBDOMAIN.workers.dev
# Current Deployment ID: 80b72e19-da82-4465-83a2-c12fb11ccc72
```

Your Worker will be available at `https://python-and-d1.YOUR_SUBDOMAIN.workers.dev`.

If you receive an error deploying:

- Make sure you have configured your [Wrangler configuration file](/workers/wrangler/configuration/) with the `database_id` and `database_name` of a valid D1 database.
- Ensure `compatibility_flags = ["python_workers"]` is set in your [Wrangler configuration file](/workers/wrangler/configuration/), which is required for Python.
- Review the [list of error codes](/workers/observability/errors/), and ensure your code does not throw an uncaught exception.

## Next steps

- Refer to [Workers Python documentation](/workers/languages/python/) to learn more about how to use Python in Workers.
- Review the [D1 Workers Binding API](/d1/worker-api/) and how to query D1 databases.
- Learn [how to import data](/d1/best-practices/import-export-data/) to your D1 database.

---

# Billing

URL: https://developers.cloudflare.com/d1/observability/billing/

D1 exposes analytics to track billing metrics (rows read, rows written, and total storage) across all databases in your account.

The metrics displayed in the [Cloudflare dashboard](https://dash.cloudflare.com/) are sourced from Cloudflare's [GraphQL Analytics API](/analytics/graphql-api/). You can access the metrics [programmatically](/d1/observability/metrics-analytics/#query-via-the-graphql-api) via GraphQL or HTTP client.

## View metrics in the dashboard

Total account billable usage analytics for D1 are available in the Cloudflare dashboard. To view current and past metrics for an account:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Manage Account** > **Billing**.
3. Select the **Billable Usage** tab.

From here you can view charts of your account's D1 usage on a daily or month-to-date timeframe.

Note that billable usage history is stored for a maximum of 30 days.

## Billing Notifications

Usage-based billing notifications are available within the [Cloudflare dashboard](https://dash.cloudflare.com) for users looking to monitor their total account usage.

Notifications on the following metrics are available:
- Rows Read
- Rows Written

---

# Audit Logs

URL: https://developers.cloudflare.com/d1/observability/audit-logs/

[Audit logs](/fundamentals/account/account-security/review-audit-logs/) provide a comprehensive summary of changes made within your Cloudflare account, including those made to D1 databases. This functionality is available on all plan types, free of charge, and is always enabled.

## Viewing audit logs

To view audit logs for your D1 databases:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?account=audit-log) and select your account.
2. Go to **Manage Account** > **Audit Log**.

For more information on how to access and use audit logs, refer to [Review audit logs](/fundamentals/account/account-security/review-audit-logs/).

## Logged operations

The following configuration actions are logged:

<table>
	<tbody>
		<th colspan="5" rowspan="1" style="width:220px">
			Operation
		</th>
		<th colspan="5" rowspan="1">
			Description
		</th>
		<tr>
			<td colspan="5" rowspan="1">
				CreateDatabase
			</td>
			<td colspan="5" rowspan="1">
				Creation of a new database.
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				DeleteDatabase
			</td>
			<td colspan="5" rowspan="1">
				Deletion of an existing database.
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				<a href="/d1/reference/time-travel">TimeTravel</a>
			</td>
			<td colspan="5" rowspan="1">
				Restoration of a past database version.
			</td>
		</tr>
	</tbody>
</table>

## Example log entry

Below is an example of an audit log entry showing the creation of a new database:

```json
{
	"action": { "info": "CreateDatabase", "result": true, "type": "create" },
	"actor": {
		"email": "<ACTOR_EMAIL>",
		"id": "b1ab1021a61b1b12612a51b128baa172",
		"ip": "1b11:a1b2:12b1:12a::11a:1b",
		"type": "user"
	},
	"id": "a123b12a-ab11-1212-ab1a-a1aa11a11abb",
	"interface": "API",
	"metadata": {},
	"newValue": "",
	"newValueJson": { "database_name": "my-db" },
	"oldValue": "",
	"oldValueJson": {},
	"owner": { "id": "211b1a74121aa32a19121a88a712aa12" },
	"resource": {
		"id": "11a21122-1a11-12bb-11ab-1aa2aa1ab12a",
		"type": "d1.database"
	},
	"when": "2024-08-09T04:53:55.752Z"
}
```

---

# Debug D1

URL: https://developers.cloudflare.com/d1/observability/debug-d1/

D1 allows you to capture exceptions and log errors returned when querying a database. To debug D1, you will use the same tools available when [debugging Workers](/workers/observability/).

## Handle errors

The D1 [Workers Binding API](/d1/worker-api/) returns detailed error messages within an `Error` object.

To ensure you are capturing the full error message, log or return `e.message` as follows:

```ts
try {
    await db.exec("INSERTZ INTO my_table (name, employees) VALUES ()");
} catch (e: any) {
    console.error({
        message: e.message
    });
}
/*
{
  "message": "D1_EXEC_ERROR: Error in line 1: INSERTZ INTO my_table (name, employees) VALUES (): sql error: near \"INSERTZ\": syntax error in INSERTZ INTO my_table (name, employees) VALUES () at offset 0"
}
*/
```

### Errors

The [`stmt.`](/d1/worker-api/prepared-statements/) and [`db.`](/d1/worker-api/d1-database/) methods throw an [Error object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) whenever an error occurs.

:::note
Prior to [`wrangler` 3.1.1](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%403.1.1), D1 JavaScript errors used the [cause property](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) for detailed error messages.

To inspect these errors when using older versions of `wrangler`, you should log `error?.cause?.message`.
:::

To capture exceptions, log the `Error.message` value. For example, the code below has a query with an invalid keyword - `INSERTZ` instead of `INSERT`:

```js
try {
    // This is an intentional misspelling
    await db.exec("INSERTZ INTO my_table (name, employees) VALUES ()");
} catch (e: any) {
    console.error({
        message: e.message
    });
}
```

The code above throws the following error message:

```json
{
	"message": "D1_EXEC_ERROR: Error in line 1: INSERTZ INTO my_table (name, employees) VALUES (): sql error: near \"INSERTZ\": syntax error in INSERTZ INTO my_table (name, employees) VALUES () at offset 0"
}
```

### Error list

D1 returns the following error constants, in addition to the extended (detailed) error message:

| Message              | Cause                                                                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `D1_ERROR`           | Generic error.                                                                                                                                                   |
| `D1_TYPE_ERROR`      | Returned when there is a mismatch in the type between a column and a value. A common cause is supplying an `undefined` variable (unsupported) instead of `null`. |
| `D1_COLUMN_NOTFOUND` | Column not found.                                                                                                                                                |
| `D1_DUMP_ERROR`      | Database dump error.                                                                                                                                             |
| `D1_EXEC_ERROR`      | Exec error in line x: y error.                                                                                                                                   |


## View logs

View a stream of live logs from your Worker by using [`wrangler tail`](/workers/observability/logs/real-time-logs#view-logs-using-wrangler-tail) or via the [Cloudflare dashboard](/workers/observability/logs/real-time-logs#view-logs-from-the-dashboard).

## Report issues

* To report bugs or request features, go to the [Cloudflare Community Forums](https://community.cloudflare.com/c/developers/d1/85).
* To give feedback, go to the [D1 Discord channel](https://discord.com/invite/cloudflaredev).
* If you are having issues with Wrangler, report issues in the [Wrangler GitHub repository](https://github.com/cloudflare/workers-sdk/issues/new/choose).

You should include as much of the following in any bug report:

* The ID of your database. Use `wrangler d1 list` to match a database name to its ID.
* The query (or queries) you ran when you encountered an issue. Ensure you redact any personally identifying information (PII).
* The Worker code that makes the query, including any calls to `bind()` using the [Workers Binding API](/d1/worker-api/).
* The full error text, including the content of [`error.cause.message`](#handle-errors).

## Related resources

* Learn [how to debug Workers](/workers/observability/).
* Understand how to [access logs](/workers/observability/logs/) generated from your Worker and D1.
* Use [`wrangler dev`](/workers/wrangler/commands/#dev) to run your Worker and D1 locally and [debug issues before deploying](/workers/development-testing/).

---

# Observability

URL: https://developers.cloudflare.com/d1/observability/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Metrics and analytics

URL: https://developers.cloudflare.com/d1/observability/metrics-analytics/

import { Details } from "~/components";

D1 exposes database analytics that allow you to inspect query volume, query latency, and storage size across all and/or each database in your account.

The metrics displayed in the [Cloudflare dashboard](https://dash.cloudflare.com/) charts are queried from Cloudflare’s [GraphQL Analytics API](/analytics/graphql-api/). You can access the metrics [programmatically](#query-via-the-graphql-api) via GraphQL or HTTP client.

## Metrics

D1 currently exports the below metrics:

| Metric                 | GraphQL Field Name        | Description                                                                                                                           |
| ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Read Queries (qps)     | `readQueries`             | The number of read queries issued against a database. This is the raw number of read queries, and is not used for billing.            |
| Write Queries (qps)    | `writeQueries`            | The number of write queries issued against a database. This is the raw number of write queries, and is not used for billing.          |
| Rows read (count)      | `rowsRead`                | The number of rows read (scanned) across your queries. See [Pricing](/d1/platform/pricing/) for more details on how rows are counted. |
| Rows written (count)   | `rowsWritten`             | The number of rows written across your queries.                                                                                       |
| Query Response (bytes) | `queryBatchResponseBytes` | The total response size of the serialized query response, including any/all column names, rows and metadata. Reported in bytes.       |
| Query Latency (ms)     | `queryBatchTimeMs`        | The total query response time, including response serialization, on the server-side. Reported in milliseconds.                        |
| Storage (Bytes)        | `databaseSizeBytes`       | Maximum size of a database. Reported in bytes.                                                                                        |

Metrics can be queried (and are retained) for the past 31 days.

### Row counts

D1 returns the number of rows read, rows written (or both) in response to each individual query via [the Workers Binding API](/d1/worker-api/return-object/).

Row counts are a precise count of how many rows were read (scanned) or written by that query.
Inspect row counts to understand the performance and cost of a given query, including whether you can reduce the rows read [using indexes](/d1/best-practices/use-indexes/). Use query counts to understand the total volume of traffic against your databases and to discern which databases are actively in-use.

Refer to the [Pricing documentation](/d1/platform/pricing/) for more details on how rows are counted.

## View metrics in the dashboard

Per-database analytics for D1 are available in the Cloudflare dashboard. To view current and historical metrics for a database:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to [**Workers & Pages** > **D1**](https://dash.cloudflare.com/?to=/:account/workers/d1).
3. Select an existing database.
4. Select the **Metrics** tab.

You can optionally select a time window to query. This defaults to the last 24 hours.

## Query via the GraphQL API

You can programmatically query analytics for your D1 databases via the [GraphQL Analytics API](/analytics/graphql-api/). This API queries the same datasets as the Cloudflare dashboard, and supports GraphQL [introspection](/analytics/graphql-api/features/discovery/introspection/).

D1's GraphQL datasets require an `accountTag` filter with your Cloudflare account ID and include:

- `d1AnalyticsAdaptiveGroups`
- `d1StorageAdaptiveGroups`
- `d1QueriesAdaptiveGroups`

### Examples

To query the sum of `readQueries`, `writeQueries` for a given `$databaseId`, grouping by `databaseId` and `date`:

```graphql graphql-api-explorer
query D1ObservabilitySampleQuery(
	$accountTag: string!
	$start: Date
	$end: Date
	$databaseId: string
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			d1AnalyticsAdaptiveGroups(
				limit: 10000
				filter: { date_geq: $start, date_leq: $end, databaseId: $databaseId }
				orderBy: [date_DESC]
			) {
				sum {
					readQueries
					writeQueries
				}
				dimensions {
					date
					databaseId
				}
			}
		}
	}
}
```

To query both the average `queryBatchTimeMs` and the 90th percentile `queryBatchTimeMs` per database:

```graphql graphql-api-explorer
query D1ObservabilitySampleQuery2(
	$accountTag: string!
	$start: Date
	$end: Date
	$databaseId: string
) {
	viewer {
		accounts(filter: { accountTag: $accountId }) {
			d1AnalyticsAdaptiveGroups(
				limit: 10000
				filter: { date_geq: $start, date_leq: $end, databaseId: $databaseId }
				orderBy: [date_DESC]
			) {
				quantiles {
					queryBatchTimeMsP90
				}
				dimensions {
					date
					databaseId
				}
			}
		}
	}
}
```

To query your account-wide `readQueries` and `writeQueries`:

```graphql graphql-api-explorer
query D1ObservabilitySampleQuery3(
	$accountTag: string!
	$start: Date
	$end: Date
	$databaseId: string
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			d1AnalyticsAdaptiveGroups(
				limit: 10000
				filter: { date_geq: $start, date_leq: $end, databaseId: $databaseId }
			) {
				sum {
					readQueries
					writeQueries
				}
			}
		}
	}
}
```

## Query `insights`

D1 provides metrics that let you understand and debug query performance. You can access these via GraphQL's `d1QueriesAdaptiveGroups` or `wrangler d1 insights` command.

D1 captures your query strings to make it easier to analyze metrics across query executions. [Bound parameters](/d1/worker-api/prepared-statements/#guidance) are not captured to remove any sensitive information.

:::note

`wrangler d1 insights` is an experimental Wrangler command. Its options and output may change.

Run `wrangler d1 insights --help` to view current options.

:::

| Option             | Description                                                                                                      |
| ------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `--timePeriod`     | Fetch data from now to the provided time period (default: `1d`).                                                 |
| `--sort-type`      | The operation you want to sort insights by. Select between `sum` and `avg` (default: `sum`).                     |
| `--sort-by`        | The field you want to sort insights by. Select between `time`, `reads`, `writes`, and `count` (default: `time`). |
| `--sort-direction` | The sort direction. Select between `ASC` and `DESC` (default: `DESC`).                                           |
| `--json`           | A boolean value to specify whether to return the result as clean JSON (default: `false`).                        |
| `--limit`          | The maximum number of queries to be fetched.                                                                     |

<Details header="To find top 3 queries by execution count:">

```sh
npx wrangler d1 insights <database_name> --sort-type=sum --sort-by=count --limit=3
```

```sh output
 ⛅️ wrangler 3.95.0
-------------------

-------------------
🚧 `wrangler d1 insights` is an experimental command.
🚧 Flags for this command, their descriptions, and output may change between wrangler versions.
-------------------

[
  {
    "query": "SELECT tbl_name as name,\n                   (SELECT ncol FROM pragma_table_list(tbl_name)) as num_columns\n            FROM sqlite_master\n            WHERE TYPE = \"table\"\n              AND tbl_name NOT LIKE \"sqlite_%\"\n              AND tbl_name NOT LIKE \"d1_%\"\n              AND tbl_name NOT LIKE \"_cf_%\"\n            ORDER BY tbl_name ASC;",
    "avgRowsRead": 2,
    "totalRowsRead": 4,
    "avgRowsWritten": 0,
    "totalRowsWritten": 0,
    "avgDurationMs": 0.49505,
    "totalDurationMs": 0.9901,
    "numberOfTimesRun": 2,
    "queryEfficiency": 0
  },
  {
    "query": "SELECT * FROM Customers",
    "avgRowsRead": 4,
    "totalRowsRead": 4,
    "avgRowsWritten": 0,
    "totalRowsWritten": 0,
    "avgDurationMs": 0.1873,
    "totalDurationMs": 0.1873,
    "numberOfTimesRun": 1,
    "queryEfficiency": 1
  },
  {
    "query": "SELECT * From Customers",
    "avgRowsRead": 0,
    "totalRowsRead": 0,
    "avgRowsWritten": 0,
    "totalRowsWritten": 0,
    "avgDurationMs": 1.0225,
    "totalDurationMs": 1.0225,
    "numberOfTimesRun": 1,
    "queryEfficiency": 0
  }
]
```

</Details>

<Details header="To find top 3 queries by average execution time:">

```sh
npx wrangler d1 insights <database_name> --sort-type=avg --sort-by=time --limit=3
```

```sh output
⛅️ wrangler 3.95.0
-------------------

-------------------
🚧 `wrangler d1 insights` is an experimental command.
🚧 Flags for this command, their descriptions, and output may change between wrangler versions.
-------------------

[
  {
    "query": "SELECT * From Customers",
    "avgRowsRead": 0,
    "totalRowsRead": 0,
    "avgRowsWritten": 0,
    "totalRowsWritten": 0,
    "avgDurationMs": 1.0225,
    "totalDurationMs": 1.0225,
    "numberOfTimesRun": 1,
    "queryEfficiency": 0
  },
  {
    "query": "SELECT tbl_name as name,\n                   (SELECT ncol FROM pragma_table_list(tbl_name)) as num_columns\n            FROM sqlite_master\n            WHERE TYPE = \"table\"\n              AND tbl_name NOT LIKE \"sqlite_%\"\n              AND tbl_name NOT LIKE \"d1_%\"\n              AND tbl_name NOT LIKE \"_cf_%\"\n            ORDER BY tbl_name ASC;",
    "avgRowsRead": 2,
    "totalRowsRead": 4,
    "avgRowsWritten": 0,
    "totalRowsWritten": 0,
    "avgDurationMs": 0.49505,
    "totalDurationMs": 0.9901,
    "numberOfTimesRun": 2,
    "queryEfficiency": 0
  },
  {
    "query": "SELECT * FROM Customers",
    "avgRowsRead": 4,
    "totalRowsRead": 4,
    "avgRowsWritten": 0,
    "totalRowsWritten": 0,
    "avgDurationMs": 0.1873,
    "totalDurationMs": 0.1873,
    "numberOfTimesRun": 1,
    "queryEfficiency": 1
  }
]
```

</Details>

<Details header="To find top 10 queries by rows written in last 7 days:">

```sh
npx wrangler d1 insights <database_name> --sort-type=sum --sort-by=writes --limit=10 --timePeriod=7d
```

```sh output
⛅️ wrangler 3.95.0
-------------------

-------------------
🚧 `wrangler d1 insights` is an experimental command.
🚧 Flags for this command, their descriptions, and output may change between wrangler versions.
-------------------

[
  {
    "query": "SELECT * FROM Customers",
    "avgRowsRead": 4,
    "totalRowsRead": 4,
    "avgRowsWritten": 0,
    "totalRowsWritten": 0,
    "avgDurationMs": 0.1873,
    "totalDurationMs": 0.1873,
    "numberOfTimesRun": 1,
    "queryEfficiency": 1
  },
  {
    "query": "SELECT * From Customers",
    "avgRowsRead": 0,
    "totalRowsRead": 0,
    "avgRowsWritten": 0,
    "totalRowsWritten": 0,
    "avgDurationMs": 1.0225,
    "totalDurationMs": 1.0225,
    "numberOfTimesRun": 1,
    "queryEfficiency": 0
  },
  {
    "query": "SELECT tbl_name as name,\n                   (SELECT ncol FROM pragma_table_list(tbl_name)) as num_columns\n            FROM sqlite_master\n            WHERE TYPE = \"table\"\n              AND tbl_name NOT LIKE \"sqlite_%\"\n              AND tbl_name NOT LIKE \"d1_%\"\n              AND tbl_name NOT LIKE \"_cf_%\"\n            ORDER BY tbl_name ASC;",
    "avgRowsRead": 2,
    "totalRowsRead": 4,
    "avgRowsWritten": 0,
    "totalRowsWritten": 0,
    "avgDurationMs": 0.49505,
    "totalDurationMs": 0.9901,
    "numberOfTimesRun": 2,
    "queryEfficiency": 0
  }
]
```

</Details>

:::note
The quantity `queryEfficiency` measures how efficient your query was. It is calculated as: the number of rows returned divided by the number of rows read.

Generally, you should try to get `queryEfficiency` as close to `1` as possible. Refer to [Use indexes](/d1/best-practices/use-indexes/) for more information on efficient querying.
:::

---

# Alpha database migration guide

URL: https://developers.cloudflare.com/d1/platform/alpha-migration/

:::caution

D1 alpha databases stopped accepting live SQL queries on August 22, 2024.

:::

D1's open beta launched in October 2023, and newly created databases use a different underlying architecture that is significantly more reliable and performant, with increased database sizes, improved query throughput, and reduced latency.

This guide will instruct you to recreate alpha D1 databases on our production-ready system.

## Prerequisites

1. You have the [`wrangler` command-line tool](/workers/wrangler/install-and-update/) installed
2. You are using `wrangler` version `3.33.0` or later (released March 2024) as earlier versions do not have the [`--remote` flag](/d1/platform/release-notes/#2024-03-12) required as part of this guide
3. An 'alpha' D1 database. All databases created before July 27th, 2023 ([release notes](/d1/platform/release-notes/#2024-03-12)) use the alpha storage backend, which is no longer supported and was not recommended for production.

## 1. Verify that a database is alpha

```sh
npx wrangler d1 info <database_name>
```

If the database is alpha, the output of the command will include `version` set to `alpha`:

```
...
│ version           │ alpha                                 │
...
```

## 2. Create a manual backup

```sh
npx wrangler d1 backup create <alpha_database_name>
```

## 3. Download the manual backup

The command below will download the manual backup of the alpha database as `.sqlite3` file:

```sh
npx wrangler d1 backup download <alpha_database_name> <backup_id> # See available backups with wrangler d1 backup list <database_name>
```

## 4. Convert the manual backup into SQL statements

The command below will convert the manual backup of the alpha database from the downloaded `.sqlite3` file into SQL statements which can then be imported into the new database:

```sh
sqlite3 db_dump.sqlite3 .dump > db.sql
```

Once you have run the above command, you will need to edit the output SQL file to be compatible with D1:

1. Remove `BEGIN TRANSACTION` and `COMMIT;` from the file.
2. Remove the following table creation statement:

   ```sql
   CREATE TABLE _cf_KV (
    	key TEXT PRIMARY KEY,
    	value BLOB
   ) WITHOUT ROWID;
   ```

## 5. Create a new D1 database

All new D1 databases use the updated architecture by default.

Run the following command to create a new database:

```sh
npx wrangler d1 create <new_database_name>
```

## 6. Run SQL statements against the new D1 database

```sh
npx wrangler d1 execute <new_database_name> --remote --file=./db.sql
```

## 7. Delete your alpha database

To delete your previous alpha database, run:

```sh
npx wrangler d1 delete <alpha_database_name>
```

---

# Platform

URL: https://developers.cloudflare.com/d1/platform/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Limits

URL: https://developers.cloudflare.com/d1/platform/limits/

import { Render, Details } from "~/components";

| Feature                                                                                                             | Limit                                             |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| Databases                                                                                                           | 50,000 (Workers Paid)[^1] / 10 (Free)             |
| Maximum database size                                                                                               | 10 GB (Workers Paid) / 500 MB (Free)              |
| Maximum storage per account                                                                                         | 250 GB (Workers Paid)[^1] / 5 GB (Free)           |
| [Time Travel](/d1/reference/time-travel/) duration (point-in-time recovery)                                         | 30 days (Workers Paid) / 7 days (Free)            |
| Maximum Time Travel restore operations                                                                              | 10 restores per 10 minute (per database)          |
| Queries per Worker invocation (read [subrequest limits](/workers/platform/limits/#how-many-subrequests-can-i-make)) | 1000 (Workers Paid) / 50 (Free)                           |
| Maximum number of columns per table                                                                                 | 100                                               |
| Maximum number of rows per table                                                                                    | Unlimited (excluding per-database storage limits) |
| Maximum string, `BLOB` or table row size                                                                            | 2,000,000 bytes (2 MB)                            |
| Maximum SQL statement length                                                                                        | 100,000 bytes (100 KB)                            |
| Maximum bound parameters per query                                                                                  | 100                                               |
| Maximum arguments per SQL function                                                                                  | 32                                                |
| Maximum characters (bytes) in a `LIKE` or `GLOB` pattern                                                            | 50 bytes                                          |
| Maximum bindings per Workers script                                                                                 | Approximately 5,000 [^2]                          |
| Maximum SQL query duration                                                                                          | 30 seconds [^3]                                   |
| Maximum file import (`d1 execute`) size                                                                             | 5 GB [^4]                                         |

:::note[Batch limits]
Limits for individual queries (listed above) apply to each individual statement contained within a batch statement. For example, the maximum SQL statement length of 100 KB applies to each statement inside a `db.batch()`.
:::

[^1]: The maximum storage per account can be increased by request on Workers Paid and Enterprise plans. See the guidance on limit increases on this page to request an increase.
[^2]: A single Worker script can have up to 1 MB of script metadata. A binding is defined as a binding to a resource, such as a D1 database, KV namespace, [environmental variable](/workers/configuration/environment-variables/), or secret. Each resource binding is approximately 150-bytes, however environmental variables and secrets are controlled by the size of the value you provide. Excluding environmental variables, you can bind up to \~5,000 D1 databases to a single Worker script.
[^3]: Requests to Cloudflare API must resolve in 30 seconds. Therefore, this duration limit also applies to the entire batch call.
[^4]: The imported file is uploaded to R2. See [R2 upload limit](/r2/platform/limits).

<Details header = "Footnotes" open={true}>
1: The maximum storage per account can be increased by request on Workers Paid and Enterprise plans. See the guidance on limit increases on this page to request an increase.

2: A single Worker script can have up to 1 MB of script metadata. A binding is defined as a binding to a resource, such as a D1 database, KV namespace, [environmental variable](/workers/configuration/environment-variables/), or secret. Each resource binding is approximately 150 bytes, however environmental variables and secrets are controlled by the size of the value you provide. Excluding environmental variables, you can bind up to \~5,000 D1 databases to a single Worker script.

3: Requests to Cloudflare API must resolve in 30 seconds. Therefore, this duration limit also applies to the entire batch call.

4: The imported file is uploaded to R2. See [R2 upload limit](/r2/platform/limits).
</Details>

Cloudflare also offers other storage solutions such as [Workers KV](/kv/api/), [Durable Objects](/durable-objects/), and [R2](/r2/get-started/). Each product has different advantages and limits. Refer to [Choose a data or storage product](/workers/platform/storage-options/) to review which storage option is right for your use case.

<Render file="limits_increase" product="workers" />

## Frequently Asked Questions

Frequently asked questions related to D1 limits:

### How much work can a D1 database do?

D1 is designed for horizontal scale out across multiple, smaller (10 GB) databases, such as per-user, per-tenant or per-entity databases. D1 allows you to build applications with thousands of databases at no extra cost for isolating with multiple databases, as the pricing is based only on query and storage costs.

- Each D1 database can store up to 10 GB of data, and you can create up to thousands of separate D1 databases. This allows you to split a single monolithic database into multiple, smaller databases, thereby isolating application data by user, customer, or tenant.
- SQL queries over a smaller working data set can be more efficient and performant while improving data isolation.

:::caution
Note that the 10 GB limit of a D1 database cannot be further increased.
:::

### How many simultaneous connections can a Worker open to D1?

You can open up to six connections (to D1) simultaneously for each invocation of your Worker.

For more information on a Worker's simultaneous connections, refer to [Simultaneous open connections](/workers/platform/limits/#simultaneous-open-connections).

---

# Pricing

URL: https://developers.cloudflare.com/d1/platform/pricing/

import { Render } from "~/components";

D1 bills based on:

- **Usage**: Queries you run against D1 will count as rows read, rows written, or both (for transactions or batches).
- **Scale-to-zero**: You are not billed for hours or capacity units. If you are not running queries against your database, you are not billed for compute.
- **Storage**: You are only billed for storage above the included [limits](/d1/platform/limits/) of your plan.

## Billing metrics

<Render file="d1-pricing" product="workers" />

## Frequently Asked Questions

Frequently asked questions related to D1 pricing:

### Will D1 always have a Free plan?

Yes, the [Workers Free plan](/workers/platform/pricing/#workers) will always include the ability to prototype and experiment with D1 for free.

### What happens if I exceed the daily limits on reads and writes, or the total storage limit, on the Free plan?

When your account hits the daily read and/or write limits, you will not be able to run queries against D1. D1 API will return errors to your client indicating that your daily limits have been exceeded. Once you have reached your included storage limit, you will need to delete unused databases or clean up stale data before you can insert new data, create or alter tables or create indexes and triggers.

Upgrading to the Workers Paid plan will remove these limits, typically within minutes.

### What happens if I exceed the monthly included reads, writes and/or storage on the paid tier?

You will be billed for the additional reads, writes and storage according to [D1's pricing metrics](#billing-metrics).

### How can I estimate my (eventual) bill?

Every query returns a `meta` object that contains a total count of the rows read (`rows_read`) and rows written (`rows_written`) by that query. For example, a query that performs a full table scan (for instance, `SELECT * FROM users`) from a table with 5000 rows would return a `rows_read` value of `5000`:

```json
"meta": {
  "duration": 0.20472300052642825,
  "size_after": 45137920,
  "rows_read": 5000,
  "rows_written": 0
}
```

These are also included in the D1 [Cloudflare dashboard](https://dash.cloudflare.com) and the [analytics API](/d1/observability/metrics-analytics/), allowing you to attribute read and write volumes to specific databases, time periods, or both.

### Does D1 charge for data transfer / egress?

No.

### Does D1 charge additional for additional compute?

D1 itself does not charge for additional compute. Workers querying D1 and computing results: for example, serializing results into JSON and/or running queries, are billed per [Workers pricing](/workers/platform/pricing/#workers), in addition to your D1 specific usage.

### Do queries I run from the dashboard or Wrangler (the CLI) count as billable usage?

Yes, any queries you run against your database, including inserting (`INSERT`) existing data into a new database, table scans (`SELECT * FROM table`), or creating indexes count as either reads or writes.

### Can I use an index to reduce the number of rows read by a query?

Yes, you can use an index to reduce the number of rows read by a query. [Creating indexes](/d1/best-practices/use-indexes/) for your most queried tables and filtered columns reduces how much data is scanned and improves query performance at the same time. If you have a read-heavy workload (most common), this can be particularly advantageous. Writing to columns referenced in an index will add at least one (1) additional row written to account for updating the index, but this is typically offset by the reduction in rows read due to the benefits of an index.

### Does a freshly created database, and/or an empty table with no rows, contribute to my storage?

Yes, although minimal. An empty table consumes at least a few kilobytes, based on the number of columns (table width) in the table. An empty database consumes approximately 12 KB of storage.

---

# Release notes

URL: https://developers.cloudflare.com/d1/platform/release-notes/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/d1.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Backups (Legacy)

URL: https://developers.cloudflare.com/d1/reference/backups/

D1 has built-in support for creating and restoring backups of your databases with wrangler v3, including support for scheduled automatic backups and manual backup management.

:::caution[Planned removal]

Access to snapshot based backups for D1 alpha databases described in this documentation will be removed on [2025-07-01](/d1/platform/release-notes/#2025-07-01).

:::

:::caution[Time Travel]

Databases using D1's [production storage subsystem](https://blog.cloudflare.com/d1-turning-it-up-to-11/) can use Time Travel point-in-time recovery. [Time Travel](/d1/reference/time-travel/) replaces the snapshot based backups used for legacy alpha databases.

To understand which storage subsystem your database uses, run `wrangler d1 info YOUR_DATABASE` and check for the `version` field in the output.Databases with `version: alpha` only support the older, snapshot based backup API.

:::

## Automatic backups

D1 automatically backs up your databases every hour on your behalf, and [retains backups for 24 hours](/d1/platform/limits/). Backups will block access to the DB while they are running. In most cases this should only be a second or two, and any requests that arrive during the backup will be queued.

To view and manage these backups, including any manual backups you have made, you can use the `d1 backup list <DATABASE_NAME>` command to list each backup.

For example, to list all of the backups of a D1 database named `existing-db`:

```sh
wrangler d1 backup list existing-db
```

```sh output

┌──────────────┬──────────────────────────────────────┬────────────┬─────────┐
│ created_at   │ id                                   │ num_tables │ size    │
├──────────────┼──────────────────────────────────────┼────────────┼─────────┤
│ 1 hour ago   │ 54a23309-db00-4c5c-92b1-c977633b937c │ 1          │ 95.3 kB │
├──────────────┼──────────────────────────────────────┼────────────┼─────────┤
│ <...>        │ <...>                                │ <...>      │ <...>   │
├──────────────┼──────────────────────────────────────┼────────────┼─────────┤
│ 2 months ago │ 8433a91e-86d0-41a3-b1a3-333b080bca16 │ 1          │ 65.5 kB │
└──────────────┴──────────────────────────────────────┴────────────┴─────────┘%
```

The `id` of each backup allows you to download or restore a specific backup.

## Manually back up a database

Creating a manual backup of your database before making large schema changes, manually inserting or deleting data, or otherwise modifying a database you are actively using is a good practice to get into. D1 allows you to make a backup of a database at any time, and stores the backup on your behalf. You should also consider [using migrations](/d1/reference/migrations/) to simplify changes to an existing database.

To back up a D1 database, you must have:

1. The Cloudflare [Wrangler CLI installed](/workers/wrangler/install-and-update/)
2. An existing D1 database you want to back up.

For example, to create a manual backup of a D1 database named `example-db`, call `d1 backup create`.

```sh
wrangler d1 backup create example-db
```

```sh output
┌─────────────────────────────┬──────────────────────────────────────┬────────────┬─────────┬───────┐
│ created_at                  │ id                                   │ num_tables │ size    │ state │
├─────────────────────────────┼──────────────────────────────────────┼────────────┼─────────┼───────┤
│ 2023-02-04T15:49:36.113753Z │ 123a81a2-ab91-4c2e-8ebc-64d69633faf1 │ 1          │ 65.5 kB │ done  │
└─────────────────────────────┴──────────────────────────────────────┴────────────┴─────────┴───────┘
```

Larger databases, especially those that are several megabytes (MB) in size with many tables, may take a few seconds to backup. The `state` column in the output will let you know when the backup is done.

## Downloading a backup locally

To download a backup locally, call `wrangler d1 backup download <DATABASE_NAME> <BACKUP_ID>`. Use `wrangler d1 backup list <DATABASE_NAME>` to list the available backups, including their IDs, for a given D1 database.

For example, to download a specific backup for a database named `example-db`:

```sh
wrangler d1 backup download example-db 123a81a2-ab91-4c2e-8ebc-64d69633faf1
```

```sh output

🌀 Downloading backup 123a81a2-ab91-4c2e-8ebc-64d69633faf1 from 'example-db'
🌀 Saving to /Users/you/projects/example-db.123a81a2.sqlite3
🌀 Done!
```

The database backup will be download to the current working directory in native SQLite3 format. To import a local database, read [the documentation on importing data](/d1/best-practices/import-export-data/) to D1.

## Restoring a backup

:::caution

Restoring a backup will overwrite the existing version of your D1 database in-place. We recommend you make a manual backup before you restore a database, so that you have a backup to revert to if you accidentally restore the wrong backup or break your application.

:::

Restoring a backup will overwrite the current running version of a database with the backup. Database tables (and their data) that do not exist in the backup will no longer exist in the current version of the database, and queries that rely on them will fail.

To restore a previous backup of a D1 database named `existing-db`, pass the ID of that backup to `d1 backup restore`:

```sh
wrangler d1 backup restore existing-db  6cceaf8c-ceab-4351-ac85-7f9e606973e3
```

```sh output
Restoring existing-db from backup 6cceaf8c-ceab-4351-ac85-7f9e606973e3....
Done!
```

Any queries against the database will immediately query the current (restored) version once the restore has completed.

---

# Community projects

URL: https://developers.cloudflare.com/d1/reference/community-projects/

Members of the Cloudflare developer community and broader developer ecosystem have built and/or contributed tooling — including ORMs (Object Relational Mapper) libraries, query builders, and CLI tools — that build on top of D1.

:::note


Community projects are not maintained by the Cloudflare D1 team. They are managed and updated by the project authors.


:::

## Projects

### Sutando ORM

Sutando is an ORM designed for Node.js. With Sutando, each table in a database has a corresponding model that handles CRUD (Create, Read, Update, Delete) operations.

- [GitHub](https://github.com/sutandojs/sutando)
- [D1 with Sutando ORM Example](https://github.com/sutandojs/sutando-examples/tree/main/typescript/rest-hono-cf-d1)

### knex-cloudflare-d1

knex-cloudflare-d1 is the Cloudflare D1 dialect for Knex.js. Note that this is not an official dialect provided by Knex.js.

- [GitHub](https://github.com/kiddyuchina/knex-cloudflare-d1)

### Prisma ORM

[Prisma ORM](https://www.prisma.io/orm) is a next-generation JavaScript and TypeScript ORM that unlocks a new level of developer experience when working with databases thanks to its intuitive data model, automated migrations, type-safety and auto-completion.

* [Tutorial](/d1/tutorials/d1-and-prisma-orm/)
* [Docs](https://www.prisma.io/docs/orm/prisma-client/deployment/edge/deploy-to-cloudflare#d1)

### D1 adapter for Kysely ORM

Kysely is a type-safe and autocompletion-friendly typescript SQL query builder. With this adapter you can interact with D1 with the familiar Kysely interface.

* [Kysely GitHub](https://github.com/koskimas/kysely)
* [D1 adapter](https://github.com/aidenwallis/kysely-d1)

### feathers-kysely

The `feathers-kysely` database adapter follows the FeathersJS Query Syntax standard and works with any framework. It is built on the D1 adapter for Kysely and supports passing queries directly from client applications. Since the FeathersJS query syntax is a subset of MongoDB's syntax, this is a great tool for MongoDB users to use Cloudflare D1 without previous SQL experience.

* [feathers-kysely on npm](https://www.npmjs.com/package/feathers-kysely)
* [feathers-kysely on GitHub](https://github.com/marshallswain/feathers-kysely)

### Drizzle ORM

Drizzle is a headless TypeScript ORM with a head which runs on Node, Bun and Deno. Drizzle ORM lives on the Edge and it is a JavaScript ORM too. It comes with a drizzle-kit CLI companion for automatic SQL migrations generation. Drizzle automatically generates your D1 schema based on types you define in TypeScript, and exposes an API that allows you to query your database directly.

* [Docs](https://orm.drizzle.team/docs)
* [GitHub](https://github.com/drizzle-team/drizzle-orm)
* [D1 example](https://orm.drizzle.team/docs/connect-cloudflare-d1)

### Flyweight

Flyweight is an ORM designed specifically for databases related to SQLite. It has first-class D1 support that includes the ability to batch queries and integrate with the wrangler migration system.

* [GitHub](https://github.com/thebinarysearchtree/flyweight)

### d1-orm

Object Relational Mapping (ORM) is a technique to query and manipulate data by using JavaScript. Created by a Cloudflare Discord Community Champion, the `d1-orm` seeks to provide a strictly typed experience while using D1.

* [GitHub](https://github.com/Interactions-as-a-Service/d1-orm/issues)
* [Documentation](https://docs.interactions.rest/d1-orm/)

### workers-qb

`workers-qb` is a zero-dependency query builder that provides a simple standardized interface while keeping the benefits and speed of using raw queries over a traditional ORM. While not intended to provide ORM-like functionality, `workers-qb` makes it easier to interact with your database from code for direct SQL access.

* [GitHub](https://github.com/G4brym/workers-qb)
* [Documentation](https://workers-qb.massadas.com/)

### d1-console

Instead of running the `wrangler d1 execute` command in your terminal every time you want to interact with your database, you can interact with D1 from within the `d1-console`. Created by a Discord Community Champion, this gives the benefit of executing multi-line queries, obtaining command history, and viewing a cleanly formatted table output.

* [GitHub](https://github.com/isaac-mcfadyen/d1-console)

### L1

`L1` is a package that brings some Cloudflare Worker ecosystem bindings into PHP and Laravel via the Cloudflare API. It provides interaction with D1 via PDO, KV and Queues, with more services to add in the future, making PHP integration with Cloudflare a real breeze.

* [GitHub](https://github.com/renoki-co/l1)
* [Packagist](https://packagist.org/packages/renoki-co/l1)

### Staff Directory - a D1-based demo

Staff Directory is a demo project using D1, [HonoX](https://github.com/honojs/honox), and [Cloudflare Pages](/pages/). It uses D1 to store employee data, and is an example of a full-stack application built on top of D1.

* [GitHub](https://github.com/lauragift21/staff-directory)
* [D1 functionality](https://github.com/lauragift21/staff-directory/blob/main/app/db.ts)

### NuxtHub

`NuxtHub` is a Nuxt module that brings Cloudflare Worker bindings into your Nuxt application with no configuration. It leverages the [Wrangler Platform Proxy](/workers/wrangler/api/#getplatformproxy) in development and direct binding in production to interact with [D1](/d1/), [KV](/kv/) and [R2](/r2/) with server composables (`hubDatabase()`, `hubKV()` and `hubBlob()`).

`NuxtHub` also provides a way to use your remote D1 database in development using the `npx nuxt dev --remote` command.

* [GitHub](https://github.com/nuxt-hub/core)
* [Documentation](https://hub.nuxt.com)
* [Example](https://github.com/Atinux/nuxt-todos-edge)

## Feedback

To report a bug or file feature requests for these community projects, create an issue directly on the project's repository.

---

# Data security

URL: https://developers.cloudflare.com/d1/reference/data-security/

This page details the data security properties of D1, including:

* Encryption-at-rest (EAR).
* Encryption-in-transit (EIT).
* Cloudflare's compliance certifications.

## Encryption at Rest

All objects stored in D1, including metadata, live databases, and inactive databases are encrypted at rest. Encryption and decryption are automatic, do not require user configuration to enable, and do not impact the effective performance of D1.

Encryption keys are managed by Cloudflare and securely stored in the same key management systems we use for managing encrypted data across Cloudflare internally.

Objects are encrypted using [AES-256](https://www.cloudflare.com/learning/ssl/what-is-encryption/), a widely tested, highly performant and industry-standard encryption algorithm. D1 uses GCM (Galois/Counter Mode) as its preferred mode.

## Encryption in Transit

Data transfer between a Cloudflare Worker, and/or between nodes within the Cloudflare network and D1 is secured using the same [Transport Layer Security](https://www.cloudflare.com/learning/ssl/transport-layer-security-tls/) (TLS/SSL).

API access via the HTTP API or using the [wrangler](/workers/wrangler/install-and-update/) command-line interface is also over TLS/SSL (HTTPS).

## Compliance

To learn more about Cloudflare's adherence to industry-standard security compliance certifications, visit the Cloudflare [Trust Hub](https://www.cloudflare.com/trust-hub/compliance-resources/).

---

# Generated columns

URL: https://developers.cloudflare.com/d1/reference/generated-columns/

D1 allows you to define generated columns based on the values of one or more other columns, SQL functions, or even [extracted JSON values](/d1/sql-api/query-json/).

This allows you to normalize your data as you write to it or read it from a table, making it easier to query and reducing the need for complex application logic.

Generated columns can also have [indexes defined](/d1/best-practices/use-indexes/) against them, which can dramatically increase query performance over frequently queried fields.

## Types of generated columns

There are two types of generated columns:

* `VIRTUAL` (default): the column is generated when read. This has the benefit of not consuming storage, but can increase compute time (and thus reduce query performance), especially for larger queries.
* `STORED`: the column is generated when the row is written. The column takes up storage space just as a regular column would, but the column does not need to be generated on every read, which can improve read query performance.

When omitted from a generated column expression, generated columns default to the `VIRTUAL` type. The `STORED` type is recommended when the generated column is compute intensive. For example, when parsing large JSON structures.

## Define a generated column

Generated columns can be defined during table creation in a `CREATE TABLE` statement or afterwards via the `ALTER TABLE` statement.

To create a table that defines a generated column, you use the `AS` keyword:

```sql
CREATE TABLE some_table (
    -- other columns omitted
    some_generated_column AS <function_that_generates_the_column_data>
)
```

As a concrete example, to automatically extract the `location` value from the following JSON sensor data, you can define a generated column called `location` (of type `TEXT`), based on a `raw_data` column that stores the raw representation of our JSON data.

```json
{
    "measurement": {
        "temp_f": "77.4",
        "aqi": [21, 42, 58],
        "o3": [18, 500],
        "wind_mph": "13",
        "location": "US-NY"
    }
}
```

To define a generated column with the value of `$.measurement.location`, you can use the [`json_extract`](/d1/sql-api/query-json/#extract-values) function to extract the value from the `raw_data` column each time you write to that row:

```sql
CREATE TABLE sensor_readings (
    event_id INTEGER PRIMARY KEY,
    timestamp INTEGER NOT NULL,
    raw_data TEXT,
    location as (json_extract(raw_data, '$.measurement.location')) STORED
);
```

Generated columns can optionally be specified with the `column_name GENERATED ALWAYS AS <function> [STORED|VIRTUAL]` syntax. The `GENERATED ALWAYS` syntax is optional and does not change the behavior of the generated column when omitted.

## Add a generated column to an existing table

A generated column can also be added to an existing table. If the `sensor_readings` table did not have the generated `location` column, you could add it by running an `ALTER TABLE` statement:

```sql
ALTER TABLE sensor_readings
ADD COLUMN location as (json_extract(raw_data, '$.measurement.location'));
```

This defines a `VIRTUAL` generated column that runs `json_extract` on each read query.

Generated column definitions cannot be directly modified. To change how a generated column generates its data, you can use `ALTER TABLE table_name REMOVE COLUMN` and then `ADD COLUMN` to re-define the generated column, or `ALTER TABLE table_name RENAME COLUMN current_name TO new_name` to rename the existing column before calling `ADD COLUMN` with a new definition.

## Examples

Generated columns are not just limited to JSON functions like `json_extract`: you can use almost any available function to define how a generated column is generated.

For example, you could generate a `date` column based on the `timestamp` column from the previous `sensor_reading` table, automatically converting a Unix timestamp into a `YYYY-MM-dd` format within your database:

```sql
ALTER TABLE your_table
-- date(timestamp, 'unixepoch') converts a Unix timestamp to a YYYY-MM-dd formatted date
ADD COLUMN formatted_date AS (date(timestamp, 'unixepoch'))
```

Alternatively, you could define an `expires_at` column that calculates a future date, and filter on that date in your queries:

```sql
-- Filter out "expired" results based on your generated column:
-- SELECT * FROM your_table WHERE current_date() > expires_at
ALTER TABLE your_table
-- calculates a date (YYYY-MM-dd) 30 days from the timestamp.
ADD COLUMN expires_at AS (date(timestamp, '+30 days'));
```

## Additional considerations

* Tables must have at least one non-generated column. You cannot define a table with only generated column(s).
* Expressions can only reference other columns in the same table and row, and must only use [deterministic functions](https://www.sqlite.org/deterministic.html). Functions like `random()`, sub-queries or aggregation functions cannot be used to define a generated column.
* Columns added to an existing table via `ALTER TABLE ... ADD COLUMN` must be `VIRTUAL`. You cannot add a `STORED` column to an existing table.

---

# Glossary

URL: https://developers.cloudflare.com/d1/reference/glossary/

import { Glossary } from "~/components"

Review the definitions for terms used across Cloudflare's D1 documentation.

<Glossary product="d1" />

---

# Migrations

URL: https://developers.cloudflare.com/d1/reference/migrations/

import { WranglerConfig } from "~/components";

Database migrations are a way of versioning your database. Each migration is stored as an `.sql` file in your `migrations` folder. The `migrations` folder is created in your project directory when you create your first migration. This enables you to store and track changes throughout database development.

## Features

Currently, the migrations system aims to be simple yet effective. With the current implementation, you can:

* [Create](/workers/wrangler/commands/#d1-migrations-create) an empty migration file.
* [List](/workers/wrangler/commands/#d1-migrations-list) unapplied migrations.
* [Apply](/workers/wrangler/commands/#d1-migrations-apply) remaining migrations.

Every migration file in the `migrations` folder has a specified version number in the filename. Files are listed in sequential order. Every migration file is an SQL file where you can specify queries to be run.

:::note[Binding name vs Database name]
When running a migration script, you can use either the binding name or the database name.

However, the binding name can change, whereas the database name cannot. Therefore, to avoid accidentally running migrations on the wrong binding, you may wish to use the database name for D1 migrations.
:::

## Wrangler customizations

By default, migrations are created in the `migrations/` folder in your Worker project directory. Creating migrations will keep a record of applied migrations in the `d1_migrations` table found in your database.

This location and table name can be customized in your Wrangler file, inside the D1 binding.

<WranglerConfig>

```toml
[[ d1_databases ]]
binding = "<BINDING_NAME>" # i.e. if you set this to "DB", it will be available in your Worker at `env.DB`
database_name = "<DATABASE_NAME>"
database_id = "<UUID>"
preview_database_id = "<UUID>"
migrations_table = "<d1_migrations>" # Customize this value to change your applied migrations table name
migrations_dir = "<FOLDER_NAME>" # Specify your custom migration directory
```

</WranglerConfig>

## Foreign key constraints

When applying a migration, you may need to temporarily disable [foreign key constraints](/d1/sql-api/foreign-keys/). To do so, call `PRAGMA defer_foreign_keys = true` before making changes that would violate foreign keys.

Refer to the [foreign key documentation](/d1/sql-api/foreign-keys/) to learn more about how to work with foreign keys and D1.

---

# Reference

URL: https://developers.cloudflare.com/d1/reference/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Time Travel and backups

URL: https://developers.cloudflare.com/d1/reference/time-travel/

import { GlossaryTooltip} from "~/components"

Time Travel is D1's approach to backups and point-in-time-recovery, and allows you to restore a database to any minute within the last 30 days.

- You do not need to enable Time Travel. It is always on.
- Database history and restoring a database incur no additional costs.
- Time Travel automatically creates [bookmarks](#bookmarks) on your behalf. You do not need to manually trigger or remember to initiate a backup.

By not having to rely on scheduled backups and/or manually initiated backups, you can go back in time and restore a database prior to a failed migration or schema change, a `DELETE` or `UPDATE` statement without a specific `WHERE` clause, and in the future, fork/copy a production database directly.

:::note[Support for Time Travel]

Databases using D1's [new storage subsystem](https://blog.cloudflare.com/d1-turning-it-up-to-11/) can use Time Travel. Time Travel replaces the [snapshot-based backups](/d1/reference/backups/) used for legacy alpha databases.

To understand which storage subsystem your database uses, run `wrangler d1 info YOUR_DATABASE` and inspect the `version` field in the output. Databases with `version: production` support the new Time Travel API. Databases with `version: alpha` only support the older, snapshot-based backup API.

:::

## Bookmarks

Time Travel leverages D1's concept of a <GlossaryTooltip term="bookmark"> bookmark </GlossaryTooltip> to restore to a point in time. 

- Bookmarks older than 30 days are invalid and cannot be used as a restore point.
- Restoring a database to a specific bookmark does not remove or delete older bookmarks. For example, if you restore to a bookmark representing the state of your database 10 minutes ago, and determine that you needed to restore to an earlier point in time, you can still do so.
- Bookmarks are lexicographically sortable. Sorting orders a list of bookmarks from oldest-to-newest.
- Bookmarks can be derived from a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) (seconds since Jan 1st, 1970), and conversion between a specific timestamp and a bookmark is deterministic (stable).

Bookmarks are also leveraged by [Sessions API](/d1/best-practices/read-replication/#sessions-api-examples) to ensure sequential consistency within a Session.

## Timestamps

Time Travel supports two timestamp formats:

- [Unix timestamps](https://developer.mozilla.org/en-US/docs/Glossary/Unix_time), which correspond to seconds since January 1st, 1970 at midnight. This is always in UTC.
- The [JavaScript date-time string format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format), which is a simplified version of the ISO-8601 timestamp format. An valid date-time string for the July 27, 2023 at 11:18AM in Americas/New_York (EST) would look like `2023-07-27T11:18:53.000-04:00`.

## Requirements

- [`Wrangler`](/workers/wrangler/install-and-update/) `v3.4.0` or later installed to use Time Travel commands.
- A database on D1's production backend. You can check whether a database is using this backend via `wrangler d1 info DB_NAME` - the output show `version: production`.

## Retrieve a bookmark

You can retrieve a bookmark for the current timestamp by calling the `d1 info` command, which defaults to returning the current bookmark:

```sh
wrangler d1 time-travel info YOUR_DATABASE
```

```sh output
🚧 Time Traveling...
⚠️ The current bookmark is '00000085-0000024c-00004c6d-8e61117bf38d7adb71b934ebbf891683'
⚡️ To restore to this specific bookmark, run:
 `wrangler d1 time-travel restore YOUR_DATABASE --bookmark=00000085-0000024c-00004c6d-8e61117bf38d7adb71b934ebbf891683`
```

To retrieve the bookmark for a timestamp in the past, pass the `--timestamp` flag with a valid Unix or RFC3339 timestamp:

```sh title="Using an RFC3339 timestamp, including the timezone"
wrangler d1 time-travel info YOUR_DATABASE --timestamp="2023-07-09T17:31:11+00:00"
```

## Restore a database

To restore a database to a specific point-in-time:

:::caution

Restoring a database to a specific point-in-time is a _destructive_ operation, and overwrites the database in place. In the future, D1 will support branching & cloning databases using Time Travel.

:::

```sh
wrangler d1 time-travel restore YOUR_DATABASE --timestamp=UNIX_TIMESTAMP
```

```sh output
🚧 Restoring database YOUR_DATABASE from bookmark 00000080-ffffffff-00004c60-390376cb1c4dd679b74a19d19f5ca5be

⚠️ This will overwrite all data in database YOUR_DATABASE.
In-flight queries and transactions will be cancelled.

✔ OK to proceed (y/N) … yes
⚡️ Time travel in progress...
✅ Database YOUR_DATABASE restored back to bookmark 00000080-ffffffff-00004c60-390376cb1c4dd679b74a19d19f5ca5be

↩️ To undo this operation, you can restore to the previous bookmark: 00000085-ffffffff-00004c6d-2510c8b03a2eb2c48b2422bb3b33fad5
```

Note that:

- Timestamps are converted to a deterministic, stable bookmark. The same timestamp will always represent the same bookmark.
- Queries in flight will be cancelled, and an error returned to the client.
- The restore operation will return a [bookmark](#bookmarks) that allows you to [undo](#undo-a-restore) and revert the database.

## Undo a restore

You can undo a restore by:

- Taking note of the previous bookmark returned as part of a `wrangler d1 time-travel restore` operation
- Restoring directly to a bookmark in the past, prior to your last restore.

To fetch a bookmark from an earlier state:

```sh title: "Get a historical bookmark"
wrangler d1 time-travel info YOUR_DATABASE
```

```sh output
🚧 Time Traveling...
⚠️ The current bookmark is '00000085-0000024c-00004c6d-8e61117bf38d7adb71b934ebbf891683'
⚡️ To restore to this specific bookmark, run:
 `wrangler d1 time-travel restore YOUR_DATABASE --bookmark=00000085-0000024c-00004c6d-8e61117bf38d7adb71b934ebbf891683`
```

## Export D1 into R2 using Workflows

You can automatically export your D1 database into R2 storage via REST API and Cloudflare Workflows. This may be useful if you wish to store a state of your D1 database for longer than 30 days.

Refer to the guide [Export and save D1 database](/workflows/examples/backup-d1/).

## Notes

- You can quickly get the Unix timestamp from the command-line in macOS and Windows via `date %+s`.
- Time Travel does not yet allow you to clone or fork an existing database to a new copy. In the future, Time Travel will allow you to fork (clone) an existing database into a new database, or overwrite an existing database.
- You can restore a database back to a point in time up to 30 days in the past (Workers Paid plan) or 7 days (Workers Free plan). Refer to [Limits](/d1/platform/limits/) for details on Time Travel's limits.

---

# SQL API

URL: https://developers.cloudflare.com/d1/sql-api/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Define foreign keys

URL: https://developers.cloudflare.com/d1/sql-api/foreign-keys/

D1 supports defining and enforcing foreign key constraints across tables in a database.

Foreign key constraints allow you to enforce relationships across tables. For example, you can use foreign keys to create a strict binding between a `user_id` in a `users` table and the `user_id` in an `orders` table, so that no order can be created against a user that does not exist.

Foreign key constraints can also prevent you from deleting rows that reference rows in other tables. For example, deleting rows from the `users` table when rows in the `orders` table refer to them.

By default, D1 enforces that foreign key constraints are valid within all queries and migrations. This is identical to the behaviour you would observe when setting `PRAGMA foreign_keys = on` in SQLite for every transaction.

## Defer foreign key constraints

When running a [query](/d1/worker-api/), [migration](/d1/reference/migrations/) or [importing data](/d1/best-practices/import-export-data/) against a D1 database, there may be situations in which you need to disable foreign key validation during table creation or changes to your schema.

D1's foreign key enforcement is equivalent to SQLite's `PRAGMA foreign_keys = on` directive. Because D1 runs every query inside an implicit transaction, user queries cannot change this during a query or migration.

Instead, D1 allows you to call `PRAGMA defer_foreign_keys = on` or `off`, which allows you to violate foreign key constraints temporarily (until the end of the current transaction).

Calling `PRAGMA defer_foreign_keys = off` does not disable foreign key enforcement outside of the current transaction. If you have not resolved outstanding foreign key violations at the end of your transaction, it will fail with a `FOREIGN KEY constraint failed` error.

To defer foreign key enforcement, set `PRAGMA defer_foreign_keys = on` at the start of your transaction, or ahead of changes that would violate constraints:

```sql
-- Defer foreign key enforcement in this transaction.
PRAGMA defer_foreign_keys = on

-- Run your CREATE TABLE or ALTER TABLE / COLUMN statements
ALTER TABLE users ...

-- This is implicit if not set by the end of the transaction.
PRAGMA defer_foreign_keys = off
```

You can also explicitly set `PRAGMA defer_foreign_keys = off` immediately after you have resolved outstanding foreign key constraints. If there are still outstanding foreign key constraints, you will receive a `FOREIGN KEY constraint failed` error and will need to resolve the violation.

## Define a foreign key relationship

A foreign key relationship can be defined when creating a table via `CREATE TABLE` or when adding a column to an existing table via an `ALTER TABLE` statement.

To illustrate this with an example based on an e-commerce website with two tables:

* A `users` table that defines common properties about a user account, including a unique `user_id` identifier.
* An `orders` table that maps an order back to a `user_id` in the user table.

This mapping is defined as `FOREIGN KEY`, which ensures that:

* You cannot delete a row from the `users` table that would violate the foreign key constraint. This means that you cannot end up with orders that do not have a valid user to map back to.
* `orders` are always defined against a valid `user_id`, mitigating the risk of creating orders that refer to invalid (or non-existent) users.

```sql
CREATE TABLE users (
    user_id INTEGER PRIMARY KEY,
    email_address TEXT,
    name TEXT,
    metadata TEXT
)

CREATE TABLE orders (
    order_id INTEGER PRIMARY KEY,
    status INTEGER,
    item_desc TEXT,
    shipped_date INTEGER,
    user_who_ordered INTEGER,
    FOREIGN KEY(user_who_ordered) REFERENCES users(user_id)
)
```

You can define multiple foreign key relationships per-table, and foreign key definitions can reference multiple tables within your overall database schema.

## Foreign key actions

You can define *actions* as part of your foreign key definitions to either limit or propagate changes to a parent row (`REFERENCES table(column)`). Defining *actions* makes using foreign key constraints in your application easier to reason about, and help either clean up related data or prevent data from being islanded.

There are five actions you can set when defining the `ON UPDATE` and/or `ON DELETE` clauses as part of a foreign key relationship. You can also define different actions for `ON UPDATE` and `ON DELETE` depending on your requirements.

* `CASCADE` - Updating or deleting a parent key deletes all child keys (rows) associated to it.
* `RESTRICT` - A parent key cannot be updated or deleted when *any* child key refers to it. Unlike the default foreign key enforcement, relationships with `RESTRICT` applied return errors immediately, and not at the end of the transaction.
* `SET DEFAULT` - Set the child column(s) referred to by the foreign key definition to the `DEFAULT` value defined in the schema. If no `DEFAULT` is set on the child columns, you cannot use this action.
* `SET NULL` - Set the child column(s) referred to by the foreign key definition to SQL `NULL`.
* `NO ACTION` - Take no action.

:::caution[CASCADE usage]

Although `CASCADE` can be the desired behavior in some cases, deleting child rows across tables can have undesirable effects and/or result in unintended side effects for your users.
:::

In the following example, deleting a user from the `users` table will delete all related rows in the `scores` table as you have defined `ON DELETE CASCADE`. Delete all related rows in the `scores` table if you do not want to retain the scores for any users you have deleted entirely. This might mean that *other* users can no longer look up or refer to scores that were still valid.

```sql
CREATE TABLE users (
    user_id INTEGER PRIMARY KEY,
    email_address TEXT,
)

CREATE TABLE scores (
    score_id INTEGER PRIMARY KEY,
    game TEXT,
    score INTEGER,
    player_id INTEGER,
    FOREIGN KEY(player_id) REFERENCES users(user_id) ON DELETE CASCADE
)
```

## Next Steps

* Read the SQLite [`FOREIGN KEY`](https://www.sqlite.org/foreignkeys.html) documentation.
* Learn how to [use the D1 Workers Binding API](/d1/worker-api/) from within a Worker.
* Understand how [database migrations work](/d1/reference/migrations/) with D1.

---

# Query JSON

URL: https://developers.cloudflare.com/d1/sql-api/query-json/

D1 has built-in support for querying and parsing JSON data stored within a database. This enables you to:

* [Query paths](#extract-values) within a stored JSON object - for example, extracting the value of named key or array index directly, which is especially useful with larger JSON objects.
* Insert and/or replace values within an object or array.
* [Expand the contents of a JSON object](#expand-arrays-for-in-queries) or array into multiple rows - for example, for use as part of a `WHERE ... IN` predicate.
* Create [generated columns](/d1/reference/generated-columns/) that are automatically populated with values from JSON objects you insert.

One of the biggest benefits to parsing JSON within D1 directly is that it can directly reduce the number of round-trips (queries) to your database. It reduces the cases where you have to read a JSON object into your application (1), parse it, and then write it back (2).

This allows you to more precisely query over data and reduce the result set your application needs to additionally parse and filter on.

## Types

JSON data is stored as a `TEXT` column in D1. JSON types follow the same [type conversion rules](/d1/worker-api/#type-conversion) as D1 in general, including:

* A JSON null is treated as a D1 `NULL`.
* A JSON number is treated as an `INTEGER` or `REAL`.
* Booleans are treated as `INTEGER` values: `true` as `1` and `false` as `0`.
* Object and array values as `TEXT`.

## Supported functions

The following table outlines the JSON functions built into D1 and example usage.

* The `json` argument placeholder can be a JSON object, array, string, number or a null value.
* The `value` argument accepts string literals (only) and treats input as a string, even if it is well-formed JSON. The exception to this rule is when nesting `json_*` functions: the outer (wrapping) function will interpret the inner (wrapped) functions return value as JSON.
* The `path` argument accepts path-style traversal syntax - for example, `$` to refer to the top-level object/array, `$.key1.key2` to refer to a nested object, and `$.key[2]` to index into an array.

| Function                                                    | Description                                                                                                                                                    | Example                                                                                   |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `json(json)`                                                | Validates the provided string is JSON and returns a minified version of that JSON object.                                                                      | `json('{"hello":["world" ,"there"] }')` returns `{"hello":["world","there"]}`             |
| `json_array(value1, value2, value3, ...)`                   | Return a JSON array from the values.                                                                                                                           | `json_array(1, 2, 3)` returns `[1, 2, 3]`                                                 |
| `json_array_length(json)` - `json_array_length(json, path)` | Return the length of the JSON array                                                                                                                            | `json_array_length('{"data":["x", "y", "z"]}', '$.data')` returns `3`                     |
| `json_extract(json, path)`                                  | Extract the value(s) at the given path using `$.path.to.value` syntax.                                                                                         | `json_extract('{"temp":"78.3", "sunset":"20:44"}', '$.temp')` returns `"78.3"`            |
| `json -> path`                                              | Extract the value(s) at the given path using path syntax and return it as JSON.                                                                                |                                                                                           |
| `json ->> path`                                             | Extract the value(s) at the given path using path syntax and return it as a SQL type.                                                                          |                                                                                           |
| `json_insert(json, path, value)`                            | Insert a value at the given path. Does not overwrite an existing value.                                                                                        |                                                                                           |
| `json_object(label1, value1, ...)`                          | Accepts pairs of (keys, values) and returns a JSON object.                                                                                                     | `json_object('temp', 45, 'wind_speed_mph', 13)` returns `{"temp":45,"wind_speed_mph":13}` |
| `json_patch(target, patch)`                                 | Uses a JSON [MergePatch](https://tools.ietf.org/html/rfc7396) approach to merge the provided patch into the target JSON object.                                |                                                                                           |
| `json_remove(json, path, ...)`                              | Remove the key and value at the specified path.                                                                                                                | `json_remove('[60,70,80,90]', '$[0]')` returns `70,80,90]`                                |
| `json_replace(json, path, value)`                           | Insert a value at the given path. Overwrites an existing value, but does not create a new key if it doesn't exist.                                             |                                                                                           |
| `json_set(json, path, value)`                               | Insert a value at the given path. Overwrites an existing value.                                                                                                |                                                                                           |
| `json_type(json)` - `json_type(json, path)`                 | Return the type of the provided value or value at the specified path. Returns one of `null`, `true`, `false`, `integer`, `real`, `text`, `array`, or `object`. | `json_type('{"temperatures":[73.6, 77.8, 80.2]}', '$.temperatures')` returns `array`      |
| `json_valid(json)`                                          | Returns 0 (false) for invalid JSON, and 1 (true) for valid JSON.                                                                                               | `json_valid({invalid:json})`returns`0\`                                                  |
| `json_quote(value)`                                         | Converts the provided SQL value into its JSON representation.                                                                                                  | `json_quote('[1, 2, 3]')` returns `[1,2,3]`                                               |
| `json_group_array(value)`                                   | Returns the provided value(s) as a JSON array.                                                                                                                 |                                                                                           |
| `json_each(value)` - `json_each(value, path)`               | Returns each element within the object as an individual row. It will only traverse the top-level object.                                                       |                                                                                           |
| `json_tree(value)` - `json_tree(value, path)`               | Returns each element within the object as an individual row. It traverses the full object.                                                                     |                                                                                           |

The SQLite [JSON extension](https://www.sqlite.org/json1.html), on which D1 builds on, has additional usage examples.

## Error Handling

JSON functions will return a `malformed JSON` error when operating over data that isn't JSON and/or is not valid JSON. D1 considers valid JSON to be [RFC 7159](https://www.rfc-editor.org/rfc/rfc7159.txt) conformant.

In the following example, calling `json_extract` over a string (not valid JSON) will cause the query to return a `malformed JSON` error:

```sql
SELECT json_extract('not valid JSON: just a string', '$')
```

This will return an error:

```txt
ERROR 9015: SQL engine error: query error: Error code 1: SQL error or missing database (malformed
  JSON)`
```

## Generated columns

D1's support for [generated columns](/d1/reference/generated-columns/) allows you to create dynamic columns that are generated based on the values of other columns, including extracted or calculated values of JSON data.

These columns can be queried like any other column, and can have [indexes](/d1/best-practices/use-indexes/) defined on them. If you have JSON data that you frequently query and filter over, creating a generated column and an index can dramatically improve query performance.

For example, to define a column based on a value within a larger JSON object, use the `AS` keyword combined with a [JSON function](#supported-functions) to generate a typed column:

```sql
CREATE TABLE some_table (
    -- other columns omitted
    raw_data TEXT -- JSON: {"measurement":{"aqi":[21,42,58],"wind_mph":"13","location":"US-NY"}}
    location AS (json_extract(raw_data, '$.measurement.location')) STORED
)
```

Refer to [Generated columns](/d1/reference/generated-columns/) to learn more about how to generate columns.

## Example usage

### Extract values

There are three ways to extract a value from a JSON object in D1:

* The `json_extract()` function - for example, `json_extract(text_column_containing_json, '$.path.to.value)`.
* The `->` operator, which returns a JSON representation of the value.
* The `->>` operator, which returns an SQL representation of the value.

The `->` and `->>` operators functions both operate similarly to the same operators in PostgreSQL and MySQL/MariaDB.

Given the following JSON object in a column named `sensor_reading`, you can extract values from it directly.

```json
{
    "measurement": {
        "temp_f": "77.4",
        "aqi": [21, 42, 58],
        "o3": [18, 500],
        "wind_mph": "13",
        "location": "US-NY"
    }
}
```

```sql
-- Extract the temperature value
json_extract(sensor_reading, '$.measurement.temp_f')-- returns "77.4" as TEXT
```

```sql
-- Extract the maximum PM2.5 air quality reading
sensor_reading -> '$.measurement.aqi[3]' -- returns 58 as a JSON number
```

```sql
-- Extract the o3 (ozone) array in full
sensor_reading -\-> '$.measurement.o3' -- returns '[18, 500]' as TEXT
```

### Get the length of an array

You can get the length of a JSON array in two ways:

1. By calling `json_array_length(value)` directly
2. By calling `json_array_length(value, path)` to specify the path to an array within an object or outer array.

For example, given the following JSON object stored in a column called `login_history`, you could get a count of the last logins directly:

```json
{
    "user_id": "abc12345",
    "previous_logins": ["2023-03-31T21:07:14-05:00", "2023-03-28T08:21:02-05:00", "2023-03-28T05:52:11-05:00"]
}
```

```sql
json_array_length(login_history, '$.previous_logins') --> returns 3 as an INTEGER
```

You can also use `json_array_length` as a predicate in a more complex query - for example, `WHERE json_array_length(some_column, '$.path.to.value') >= 5`.

### Insert a value into an existing object

You can insert a value into an existing JSON object or array using `json_insert()`. For example, if you have a `TEXT` column called `login_history` in a `users` table containing the following object:

```json
{"history": ["2023-05-13T15:13:02+00:00", "2023-05-14T07:11:22+00:00", "2023-05-15T15:03:51+00:00"]}
```

To add a new timestamp to the `history` array within our `login_history` column, write a query resembling the following:

```sql
UPDATE users
SET login_history = json_insert(login_history, '$.history[#]', '2023-05-15T20:33:06+00:00')
WHERE user_id = 'aba0e360-1e04-41b3-91a0-1f2263e1e0fb'
```

Provide three arguments to `json_insert`:

1. The name of our column containing the JSON you want to modify.
2. The path to the key within the object to modify.
3. The JSON value to insert. Using `[#]` tells `json_insert` to append to the end of your array.

To replace an existing value, use `json_replace()`, which will overwrite an existing key-value pair if one already exists. To set a value regardless of whether it already exists, use `json_set()`.

### Expand arrays for IN queries

Use `json_each` to expand an array into multiple rows. This can be useful when composing a `WHERE column IN (?)` query over several values. For example, if you wanted to update a list of users by their integer `id`, use `json_each` to return a table with each value as a column called `value`:

```sql
UPDATE users
SET last_audited = '2023-05-16T11:24:08+00:00'
WHERE id IN (SELECT value FROM json_each('[183183, 13913, 94944]'))
```

This would extract only the `value` column from the table returned by `json_each`, with each row representing the user IDs you passed in as an array.

`json_each` effectively returns a table with multiple columns, with the most relevant being:

* `key` - the key (or index).
* `value` - the literal value of each element parsed by `json_each`.
* `type` - the type of the value: one of `null`, `true`, `false`, `integer`, `real`, `text`, `array`, or `object`.
* `fullkey` - the full path to the element: e.g. `$[1]` for the second element in an array, or `$.path.to.key` for a nested object.
* `path` - the top-level path - `$` as the path for an element with a `fullkey` of `$[0]`.

In this example, `SELECT * FROM json_each('[183183, 13913, 94944]')` would return a table resembling the below:

```sql
key|value|type|id|fullkey|path
0|183183|integer|1|$[0]|$
1|13913|integer|2|$[1]|$
2|94944|integer|3|$[2]|$
```

You can use `json_each` with [D1 Workers Binding API](/d1/worker-api/) in a Worker by creating a statement and using `JSON.stringify` to pass an array as a [bound parameter](/d1/worker-api/d1-database/#guidance):

```ts
const stmt = context.env.DB
    .prepare("UPDATE users SET last_audited = ? WHERE id IN (SELECT value FROM json_each(?1))")
const resp = await stmt.bind(
    "2023-05-16T11:24:08+00:00",
    JSON.stringify([183183, 13913, 94944])
    ).run()
```

This would only update rows in your `users` table where the `id` matches one of the three provided.

---

# SQL statements

URL: https://developers.cloudflare.com/d1/sql-api/sql-statements/

import { Details, Render } from "~/components";

D1 is compatible with most SQLite's SQL convention since it leverages SQLite's query engine. D1 supports a number of database-level statements that allow you to list tables, indexes, and inspect the schema for a given table or index.

You can execute any of these statements via the D1 console in the Cloudflare dashboard, [`wrangler d1 execute`](/workers/wrangler/commands/#d1), or with the [D1 Worker Bindings API](/d1/worker-api/d1-database).

## Supported SQLite extensions

D1 supports a subset of SQLite extensions for added functionality, including:

- Default SQLite extensions.
- [FTS5 module](https://www.sqlite.org/fts5.html) for full-text search.

## Compatible PRAGMA statements

D1 supports some [SQLite PRAGMA](https://www.sqlite.org/pragma.html) statements. The PRAGMA statement is an SQL extension for SQLite. PRAGMA commands can be used to:

- Modify the behavior of certain SQLite operations.
- Query the SQLite library for internal data about schemas or tables (but note that PRAGMA statements cannot query the contents of a table).
- Control [environmental variables](/workers/configuration/environment-variables/).

<Render file="use-pragma-statements" />

## Query `sqlite_master`

You can also query the `sqlite_master` table to show all tables, indexes, and the original SQL used to generate them:

```sql
SELECT name, sql FROM sqlite_master
```

```json
      {
        "name": "users",
        "sql": "CREATE TABLE users ( user_id INTEGER PRIMARY KEY, email_address TEXT, created_at INTEGER, deleted INTEGER, settings TEXT)"
      },
      {
        "name": "idx_ordered_users",
        "sql": "CREATE INDEX idx_ordered_users ON users(created_at DESC)"
      },
      {
        "name": "Order",
        "sql": "CREATE TABLE \"Order\" ( \"Id\" INTEGER PRIMARY KEY, \"CustomerId\" VARCHAR(8000) NULL, \"EmployeeId\" INTEGER NOT NULL, \"OrderDate\" VARCHAR(8000) NULL, \"RequiredDate\" VARCHAR(8000) NULL, \"ShippedDate\" VARCHAR(8000) NULL, \"ShipVia\" INTEGER NULL, \"Freight\" DECIMAL NOT NULL, \"ShipName\" VARCHAR(8000) NULL, \"ShipAddress\" VARCHAR(8000) NULL, \"ShipCity\" VARCHAR(8000) NULL, \"ShipRegion\" VARCHAR(8000) NULL, \"ShipPostalCode\" VARCHAR(8000) NULL, \"ShipCountry\" VARCHAR(8000) NULL)"
      },
      {
        "name": "Product",
        "sql": "CREATE TABLE \"Product\" ( \"Id\" INTEGER PRIMARY KEY, \"ProductName\" VARCHAR(8000) NULL, \"SupplierId\" INTEGER NOT NULL, \"CategoryId\" INTEGER NOT NULL, \"QuantityPerUnit\" VARCHAR(8000) NULL, \"UnitPrice\" DECIMAL NOT NULL, \"UnitsInStock\" INTEGER NOT NULL, \"UnitsOnOrder\" INTEGER NOT NULL, \"ReorderLevel\" INTEGER NOT NULL, \"Discontinued\" INTEGER NOT NULL)"
      }
```

## Search with LIKE

You can perform a search using SQL's `LIKE` operator:

```js
const { results } = await env.DB.prepare(
	"SELECT * FROM Customers WHERE CompanyName LIKE ?",
)
	.bind("%eve%")
	.all();
console.log("results: ", results);
```
```js output
results:  [...]
```

## Related resources

- Learn [how to create indexes](/d1/best-practices/use-indexes/#list-indexes) in D1.
- Use D1's [JSON functions](/d1/sql-api/query-json/) to query JSON data.
- Use [`wrangler dev`](/workers/wrangler/commands/#dev) to run your Worker and D1 locally and debug issues before deploying.

---

# Tutorials

URL: https://developers.cloudflare.com/d1/tutorials/

import { GlossaryTooltip, ListTutorials, YouTubeVideos } from "~/components";

View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with D1.

## Docs

<ListTutorials />

## Videos

<YouTubeVideos products={["D1"]} />

---

# D1 Database

URL: https://developers.cloudflare.com/d1/worker-api/d1-database/

import { Type, MetaInfo, Details } from "~/components";

To interact with your D1 database from your Worker, you need to access it through the environment bindings provided to the Worker (`env`).

```js
async fetch(request, env) {
	// D1 database is 'env.DB', where "DB" is the binding name from the Wrangler configuration file.
}
```

A D1 binding has the type `D1Database`, and supports a number of methods, as listed below.

## Methods

### `prepare()`

Prepares a query statement to be later executed.

```js
const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
```

#### Parameters

- <code>query</code>: <Type text="String"/> <MetaInfo text="Required"/>
  - The SQL query you wish to execute on the database.

#### Return values

- <code>D1PreparedStatement</code>: <Type text="Object"/>
  - An object which only contains methods. Refer to [Prepared statement methods](/d1/worker-api/prepared-statements/).

#### Guidance

You  can use the `bind` method to dynamically bind a value into the query statement, as shown below.

- Example of a static statement without using `bind`:

	```js
	const stmt = db
		.prepare("SELECT * FROM Customers WHERE CompanyName = Alfreds Futterkiste AND CustomerId = 1")
	```

- Example of an ordered statement using `bind`:

	```js
	const stmt = db
		.prepare("SELECT * FROM Customers WHERE CompanyName = ? AND CustomerId = ?")
		.bind("Alfreds Futterkiste", 1);
	```

Refer to the [`bind` method documentation](/d1/worker-api/prepared-statements/#bind) for more information.

### `batch()`

Sends multiple SQL statements inside a single call to the database. This can have a huge performance impact as it reduces latency from network round trips to D1. D1 operates in auto-commit. Our implementation guarantees that each statement in the list will execute and commit, sequentially, non-concurrently.

Batched statements are [SQL transactions](https://www.sqlite.org/lang_transaction.html). If a statement in the sequence fails, then an error is returned for that specific statement, and it aborts or rolls back the entire sequence.

To send batch statements, provide `D1Database::batch` a list of prepared statements and get the results in the same order.

```js
const companyName1 = `Bs Beverages`;
const companyName2 = `Around the Horn`;
const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);
const batchResult = await env.DB.batch([
	stmt.bind(companyName1),
	stmt.bind(companyName2)
]);
```

#### Parameters

- <code>statements</code>: <Type text="Array"/>
  - An array of [`D1PreparedStatement`](#prepare)s.

#### Return values

- <code>results</code>: <Type text="Array"/>
  - An array of `D1Result` objects containing the results of the [`D1Database::prepare`](#prepare) statements. Each object is in the array position corresponding to the array position of the initial [`D1Database::prepare`](#prepare) statement within the `statements`.
  - Refer to [`D1Result`](/d1/worker-api/return-object/#d1result) for more information about this object.

<Details header="Example of return values" open={false}>

```js
const companyName1 = `Bs Beverages`;
const companyName2 = `Around the Horn`;
const stmt = await env.DB.batch([
	env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`).bind(companyName1),
	env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`).bind(companyName2)
]);
return Response.json(stmt)
```
```js output
[
  {
    "success": true,
    "meta": {
      "served_by": "miniflare.db",
      "duration": 0,
      "changes": 0,
      "last_row_id": 0,
      "changed_db": false,
      "size_after": 8192,
      "rows_read": 4,
      "rows_written": 0
    },
    "results": [
      {
        "CustomerId": 11,
        "CompanyName": "Bs Beverages",
        "ContactName": "Victoria Ashworth"
      },
      {
        "CustomerId": 13,
        "CompanyName": "Bs Beverages",
        "ContactName": "Random Name"
      }
    ]
  },
  {
    "success": true,
    "meta": {
      "served_by": "miniflare.db",
      "duration": 0,
      "changes": 0,
      "last_row_id": 0,
      "changed_db": false,
      "size_after": 8192,
      "rows_read": 4,
      "rows_written": 0
    },
    "results": [
      {
        "CustomerId": 4,
        "CompanyName": "Around the Horn",
        "ContactName": "Thomas Hardy"
      }
    ]
  }
]
```
```js
console.log(stmt[1].results);
```
```js output
[
  {
    "CustomerId": 4,
    "CompanyName": "Around the Horn",
    "ContactName": "Thomas Hardy"
  }
]
```
</Details>

#### Guidance

- You can construct batches reusing the same prepared statement:

	```js
		const companyName1 = `Bs Beverages`;
		const companyName2 = `Around the Horn`;
		const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);
		const batchResult = await env.DB.batch([
			stmt.bind(companyName1),
			stmt.bind(companyName2)
		]);
		return Response.json(batchResult);
	```

### `exec()`

Executes one or more queries directly without prepared statements or parameter bindings.

```js
const returnValue = await env.DB.exec(`SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"`);
```

#### Parameters

- <code>query</code>: <Type text="String"/> <MetaInfo text="Required"/>
  - The SQL query statement without parameter binding.

#### Return values

- <code>D1ExecResult</code>: <Type text="Object"/>
  - The `count` property contains the number of executed queries.
  - The `duration` property contains the duration of operation in milliseconds.
	- Refer to [`D1ExecResult`](/d1/worker-api/return-object/#d1execresult) for more information.

<Details header="Example of return values" open={false}>
```js
const returnValue = await env.DB.exec(`SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"`);
return Response.json(returnValue);
```
```js output
{
  "count": 1,
  "duration": 1
}
```
</Details>

#### Guidance

- If an error occurs, an exception is thrown with the query and error messages, execution stops and further statements are not executed. Refer to [Errors](/d1/observability/debug-d1/#errors) to learn more.
- This method can have poorer performance (prepared statements can be reused in some cases) and, more importantly, is less safe.
- Only use this method for maintenance and one-shot tasks (for example, migration jobs).
- The input can be one or multiple queries separated by `\n`.

### `dump`

:::caution
This API only works on databases created during D1's alpha period. Check which version your database uses with `wrangler d1 info <DATABASE_NAME>`.
:::

Dumps the entire D1 database to an SQLite compatible file inside an ArrayBuffer.

```js
const dump = await db.dump();
return new Response(dump, {
	status: 200,
	headers: {
		"Content-Type": "application/octet-stream",
	},
});
```

#### Parameters

- None.

#### Return values

- None.

### `withSession()`

Starts a D1 session which maintains sequential consistency among queries executed on the returned `D1DatabaseSession` object.

```ts
const session = env.DB.withSession("<parameter>");
```

#### Parameters

- <code>first-primary</code>: <Type text="String"/><MetaInfo text="Optional"/>
  - Directs the first query in the Session (whether read or write) to the primary database instance. Use this option if you need to start the Session with the most up-to-date data from the primary database instance.
  - Subsequent queries in the Session may use read replicas.
  - Subsequent queries in the Session have sequential consistency.

- <code>first-unconstrained</code>: <Type text="String"/><MetaInfo text="Optional"/>
  - Directs the first query in the Session (whether read or write) to any database instance. Use this option if you do not need to start the Session with the most up-to-date data, and wish to prioritize minimizing query latency from the very start of the Session.
  - Subsequent queries in the Session have sequential consistency.
  - This is the default behavior when no parameter is provided.

- <code>bookmark</code>: <Type text="String"/><MetaInfo text="Optional"/>
  - A [`bookmark`](/d1/reference/time-travel/#bookmarks) from a previous D1 Session. This allows you to start a new Session from at least the provided `bookmark`.
  - Subsequent queries in the Session have sequential consistency.

#### Return values

- <code>D1DatabaseSession</code>: <Type text="Object"/>
  - An object which contains the methods [`prepare()`](/d1/worker-api/d1-database#prepare) and [`batch()`](/d1/worker-api/d1-database#batch) similar to `D1Database`, along with the additional [`getBookmark`](/d1/worker-api/d1-database#getbookmark) method.

#### Guidance

You can return the last encountered `bookmark` for a given Session using [`session.getBookmark()`](/d1/worker-api/d1-database/#getbookmark).

## `D1DatabaseSession` methods

### `getBookmark`

Retrieves the latest `bookmark` from the D1 Session.

```ts
const session = env.DB.withSession("first-primary");
const result = await session
	.prepare(`SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'`)
	.run()
return { bookmark } = session.getBookmark();
```

#### Parameters

- None

#### Return values

- <code>bookmark</code>: <Type text="String | null"/>
  - A [`bookmark`](/d1/reference/time-travel/#bookmarks) which identifies the latest version of the database seen by the last query executed within the Session.
  - Returns `null` if no query is executed within a Session.

### `prepare()`

This method is equivalent to [`D1Database::prepare`](/d1/worker-api/d1-database/#prepare).

### `batch()`

This method is equivalent to [`D1Database::batch`](/d1/worker-api/d1-database/#batch).

---

# Workers Binding API

URL: https://developers.cloudflare.com/d1/worker-api/

import { DirectoryListing, Details, Steps } from "~/components";

You can execute SQL queries on your D1 database from a Worker using the Worker Binding API. To do this, you can perform the following steps:

1. [Bind the D1 Database](/d1/get-started/#3-bind-your-worker-to-your-d1-database).
2. [Prepare a statement](/d1/worker-api/d1-database/#prepare).
3. [Run the prepared statement](/d1/worker-api/prepared-statements).
4. Analyze the [return object](/d1/worker-api/return-object) (if necessary).

Refer to the relevant sections for the API documentation.

## TypeScript support

D1 Worker Bindings API is fully-typed via the runtime types generated by running [`wrangler types`](/workers/languages/typescript/#typescript) package, and also supports [generic types](https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-types) as part of its TypeScript API. A generic type allows you to provide an optional `type parameter` so that a function understands the type of the data it is handling.

When using the query statement methods [`D1PreparedStatement::run`](/d1/worker-api/prepared-statements/#run), [`D1PreparedStatement::raw`](/d1/worker-api/prepared-statements/#raw) and [`D1PreparedStatement::first`](/d1/worker-api/prepared-statements/#first), you can provide a type representing each database row. D1's API will [return the result object](/d1/worker-api/return-object/#d1result) with the correct type.

For example, providing an `OrderRow` type as a type parameter to [`D1PreparedStatement::run`](/d1/worker-api/prepared-statements/#run) will return a typed `Array<OrderRow>` object instead of the default `Record<string, unknown>` type:

```ts
// Row definition
type OrderRow = {
Id: string;
CustomerName: string;
OrderDate: number;
};

// Elsewhere in your application
const result = await env.MY_DB.prepare(
"SELECT Id, CustomerName, OrderDate FROM [Order] ORDER BY ShippedDate DESC LIMIT 100",
).run<OrderRow>();
```

## Type conversion

D1 automatically converts supported JavaScript (including TypeScript) types passed as parameters via the Workers Binding API to their associated D1 types <sup>1</sup>.
This conversion is permanent and one-way only. This means that when reading the written values back in your code, you will get the converted values rather than the originally inserted values.

:::note
We recommend using [STRICT tables](https://www.sqlite.org/stricttables.html) in your SQL schema to avoid issues with mismatched types between values that are actually stored in your database compared to values defined by your schema.
:::

The type conversion during writes is as follows:

| JavaScript (write)   | D1                          | JavaScript (read)  |
| -------------------- | --------------------------- | ------------------ |
| null                 | `NULL`                      | null               |
| Number               | `REAL`                      | Number             |
| Number <sup>2</sup>  | `INTEGER`                   | Number             |
| String               | `TEXT`                      | String             |
| Boolean <sup>3</sup> | `INTEGER`                   | Number (`0`,`1`)   |
| ArrayBuffer          | `BLOB`                      | Array <sup>4</sup> |
| ArrayBuffer View     | `BLOB`                      | Array <sup>4</sup> |
| undefined            | Not supported. <sup>5</sup> | -                  |

<sup>1</sup> D1 types correspond to the underlying [SQLite
types](https://www.sqlite.org/datatype3.html).

<sup>2</sup> D1 supports 64-bit signed `INTEGER` values internally, however
[BigInts](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt)
are not currently supported in the API yet. JavaScript integers are safe up to
[`Number.MAX_SAFE_INTEGER`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER).

<sup>3</sup> Booleans will be cast to an `INTEGER` type where `1` is `TRUE` and
`0` is `FALSE`.

<sup>4</sup> `ArrayBuffer` and [`ArrayBuffer`
views](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/isView)
are converted using
[`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from).

<sup>5</sup> Queries with `undefined` values will return a `D1_TYPE_ERROR`.

## API playground

The D1 Worker Binding API playground is an `index.js` file where you can test each of the documented Worker Binding APIs for D1. The file builds from the end-state of the [Get started](/d1/get-started/#write-queries-within-your-worker) code.

You can use this alongside the API documentation to better understand how each API works.

Follow the steps to setup your API playground.

### 1. Complete the Get started tutorial

Complete the [Get started](/d1/get-started/#write-queries-within-your-worker) tutorial. Ensure you use JavaScript instead of TypeScript.

### 2. Modify the content of `index.js`

Replace the contents of your `index.js` file with the code below to view the effect of each API.

<Details header="index.js" open={false}>
```js
export default {
	async fetch(request, env) {
	  const { pathname } = new URL(request.url);
	//   if (pathname === "/api/beverages") {
	// 	// If you did not use `DB` as your binding name, change it here
	// 	const { results } = await env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?",).bind("Bs Beverages").all();
	// 	return Response.json(results);
	//   }
		const companyName1 = `Bs Beverages`;
		const companyName2 = `Around the Horn`;
		const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);
		const stmtMulti = env.DB.prepare(`SELECT * FROM Customers; SELECT * FROM Customers WHERE CompanyName = ?`);
		const session = env.DB.withSession("first-primary")
		const sessionStmt = session.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);

	  if (pathname === `/RUN`){
		const returnValue = await stmt.bind(companyName1).run();
		return Response.json(returnValue);

	} else if (pathname === `/RAW`){
		const returnValue = await stmt.bind(companyName1).raw();
		return Response.json(returnValue);

	} else if (pathname === `/FIRST`){
		const returnValue = await stmt.bind(companyName1).first();
		return Response.json(returnValue);

	} else if (pathname === `/BATCH`) {
		const batchResult = await env.DB.batch([
			stmt.bind(companyName1),
			stmt.bind(companyName2)
		]);
		return Response.json(batchResult);

	} else if (pathname === `/EXEC`){
		const returnValue = await env.DB.exec(`SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"`);
		return Response.json(returnValue);

	} else if (pathname === `/WITHSESSION`){
		const returnValue = await sessionStmt.bind(companyName1).run();
		console.log("You're now using D1 Sessions!")
		return Response.json(returnValue);
	}

	  return new Response(
		`Welcome to the D1 API Playground!
		\nChange the URL to test the various methods inside your index.js file.`,
	  );
	},
  };
```
</Details>

### 3. Deploy the Worker

<Steps>
1. Navigate to your tutorial directory you created by following step 1.
2. Run `npx wrangler deploy`.
	```sh
	npx wrangler deploy
	```
	```sh output
	⛅️ wrangler 3.112.0
	--------------------

	Total Upload: 1.90 KiB / gzip: 0.59 KiB
	Your worker has access to the following bindings:
	- D1 Databases:
		- DB: DATABASE_NAME (<DATABASE_ID>)
	Uploaded WORKER_NAME (7.01 sec)
	Deployed WORKER_NAME triggers (1.25 sec)
		https://jun-d1-rr.d1-sandbox.workers.dev
	Current Version ID: VERSION_ID
	```
3. Open a browser at the specified address.
</Steps>

### 4. Test the APIs

Change the URL to test the various D1 Worker Binding APIs.

---

# Return objects

URL: https://developers.cloudflare.com/d1/worker-api/return-object/

Some D1 Worker Binding APIs return a typed object.

| D1 Worker Binding API                                                                                                          | Return object |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| [`D1PreparedStatement::run`](/d1/worker-api/prepared-statements/#run), [`D1Database::batch`](/d1/worker-api/d1-database/#batch)| `D1Result`    |
| [`D1Database::exec`](/d1/worker-api/d1-database/#exec)                                                                         | `D1ExecResult`|

## `D1Result`

The methods [`D1PreparedStatement::run`](/d1/worker-api/prepared-statements/#run) and [`D1Database::batch`](/d1/worker-api/d1-database/#batch) return a typed [`D1Result`](#d1result) object for each query statement. This object contains:

- The success status
- A meta object with the internal duration of the operation in milliseconds
- The results (if applicable) as an array

```js
{
  success: boolean, // true if the operation was successful, false otherwise
  meta: {
    served_by: string // the version of Cloudflare's backend Worker that returned the result
    served_by_region: string // the region of the database instance that executed the query
    served_by_primary: boolean // true if (and only if) the database instance that executed the query was the primary
    timings: {
      sql_duration_ms: number // the duration of the SQL query execution by the database instance (not including any network time)
    }
    duration: number, // the duration of the SQL query execution only, in milliseconds
		changes: number, // the number of changes made to the database
		last_row_id: number, // the last inserted row ID, only applies when the table is defined without the `WITHOUT ROWID` option
		changed_db: boolean, // true if something on the database was changed
    size_after: number, // the size of the database after the query is successfully applied
    rows_read: number, // the number of rows read (scanned) by this query
    rows_written: number // the number of rows written by this query
  }
  results: array | null, // [] if empty, or null if it does not apply
}
```

### Example

```js
const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
const returnValue = await stmt.run();
return Response.json(returnValue)
```
```json
{
  "success": true,
  "meta": {
    "served_by": "miniflare.db",
    "served_by_region": "WEUR",
    "served_by_primary": true,
    "timings": {
      "sql_duration_ms": 0.2552
    },
    "duration": 0.2552,
    "changes": 0,
    "last_row_id": 0,
    "changed_db": false,
    "size_after": 16384,
    "rows_read": 4,
    "rows_written": 0
  },
  "results": [
    {
      "CustomerId": 11,
      "CompanyName": "Bs Beverages",
      "ContactName": "Victoria Ashworth"
    },
    {
      "CustomerId": 13,
      "CompanyName": "Bs Beverages",
      "ContactName": "Random Name"
    }
  ]
}
```

## `D1ExecResult`

The method [`D1Database::exec`](/d1/worker-api/d1-database/#exec) returns a typed [`D1ExecResult`](#d1execresult) object for each query statement. This object contains:

- The number of executed queries
- The duration of the operation in milliseconds

```js
{
	"count": number, // the number of executed queries
	"duration": number // the duration of the operation, in milliseconds
}
```

### Example

```js
const returnValue = await env.DB.exec(`SELECT * FROM Customers WHERE CompanyName = "Bs Beverages"`);
return Response.json(returnValue);
```
```js output
{
  "count": 1,
  "duration": 1
}
```

:::note[Storing large numbers]
Any numeric value in a column is affected by JavaScript's 52-bit precision for numbers. If you store a very large number (in `int64`), then retrieve the same value, the returned value may be less precise than your original number.
:::

---

# Prepared statement methods

URL: https://developers.cloudflare.com/d1/worker-api/prepared-statements/

import { Type, MetaInfo, Details } from "~/components";

This chapter documents the various ways you can run and retrieve the results of a query after you have [prepared your statement](/d1/worker-api/d1-database/#prepare).

## Methods

### `bind()`

Binds a parameter to the prepared statement.

```js
const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
```

#### Parameter

- <code>Variable</code>: <Type text="string"/>
  - The variable to be appended into the prepared statement. See [guidance](#guidance) below.

#### Return values

- <code>D1PreparedStatement</code>: <Type text="Object"/>
  - A `D1PreparedStatement` where the input parameter has been included in the statement.

#### Guidance

- D1 follows the [SQLite convention](https://www.sqlite.org/lang_expr.html#varparam) for prepared statements parameter binding. Currently, D1 only supports Ordered (`?NNNN`) and Anonymous (`?`) parameters. In the future, D1 will support named parameters as well.

	| Syntax | Type      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
	| ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
	| `?NNN` | Ordered   | A question mark followed by a number `NNN` holds a spot for the `NNN`-th parameter. `NNN` must be between `1` and `SQLITE_MAX_VARIABLE_NUMBER`                                                                                                                                                                                                                                                                                                                                                                                                    |
	| `?`    | Anonymous | A question mark that is not followed by a number creates a parameter with a number one greater than the largest parameter number already assigned. If this means the parameter number is greater than `SQLITE_MAX_VARIABLE_NUMBER`, it is an error. This parameter format is provided for compatibility with other database engines. But because it is easy to miscount the question marks, the use of this parameter format is discouraged. Programmers are encouraged to use one of the symbolic formats below or the `?NNN` format above instead. |

	To bind a parameter, use the `.bind` method.

	Order and anonymous examples:

	```js
	const stmt = db.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind("");
	```

	```js
	const stmt = db
		.prepare("SELECT * FROM Customers WHERE CompanyName = ? AND CustomerId = ?")
		.bind("Alfreds Futterkiste", 1);
	```

	```js
	const stmt = db
		.prepare("SELECT * FROM Customers WHERE CompanyName = ?2 AND CustomerId = ?1")
		.bind(1, "Alfreds Futterkiste");
	```

#### Static statements

D1 API supports static statements. Static statements are SQL statements where the variables have been hard coded. When writing a static statement, you manually type the variable within the statement string.

:::note
The recommended approach is to bind parameters to create a prepared statement (which are precompiled objects used by the database) to run the SQL. Prepared statements lead to faster overall execution and prevent SQL injection attacks.
:::

Example of a prepared statement with dynamically bound value:

```js
const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
// A variable (someVariable) will replace the placeholder '?' in the query.
// `stmt` is a prepared statement.
```

Example of a static statement:

```js
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = Bs Beverages");
// "Bs Beverages" is hard-coded into the query.
// `stmt` is a static statement.
```

### `run()`

Runs the prepared query (or queries) and returns results. The returned results includes metadata.

```js
const returnValue = await stmt.run();
```

#### Parameter

- None.

#### Return values

- <code>D1Result</code>: <Type text="Object"/>
  - An object containing the success status, a meta object, and an array of objects containing the query results.
  - For more information on the object, refer to [`D1Result`](/d1/worker-api/return-object/#d1result).

<Details header="Example of return values" open = {false}>
```js
const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
const returnValue = await stmt.run();
```
```js
return Response.json(returnValue);
```
```js output
{
  "success": true,
  "meta": {
    "served_by": "miniflare.db",
    "duration": 1,
    "changes": 0,
    "last_row_id": 0,
    "changed_db": false,
    "size_after": 8192,
    "rows_read": 4,
    "rows_written": 0
  },
  "results": [
    {
      "CustomerId": 11,
      "CompanyName": "Bs Beverages",
      "ContactName": "Victoria Ashworth"
    },
    {
      "CustomerId": 13,
      "CompanyName": "Bs Beverages",
      "ContactName": "Random Name"
    }
  ]
}
```
</Details>

#### Guidance

- `results` is empty for write operations such as `UPDATE`, `DELETE`, or `INSERT`.
- When using TypeScript, you can pass a [type parameter](/d1/worker-api/#typescript-support) to [`D1PreparedStatement::run`](#run) to return a typed result object.
- [`D1PreparedStatement::run`](#run) is functionally equivalent to `D1PreparedStatement::all`, and can be treated as an alias.
- You can choose to extract only the results you expect from the statement by simply returning the `results` property of the return object.

<Details header="Example of returning only the `results`" open={false}>
```js
return Response.json(returnValue.results);
```
```js output
[
  {
    "CustomerId": 11,
    "CompanyName": "Bs Beverages",
    "ContactName": "Victoria Ashworth"
  },
  {
    "CustomerId": 13,
    "CompanyName": "Bs Beverages",
    "ContactName": "Random Name"
  }
]
```
</Details>

### `raw()`

Runs the prepared query (or queries), and returns the results as an array of arrays. The returned results do not include metadata.

Column names are not included in the result set by default. To include column names as the first row of the result array, set `.raw({columnNames: true})`.

```js
const returnValue = await stmt.raw();
```

#### Parameters

- <code>columnNames</code>: <Type text="Object"/> <MetaInfo text="Optional"/>
  - A boolean object which includes column names as the first row of the result array.

#### Return values

- <code>Array</code>: <Type text="Array"/>
  - An array of arrays. Each sub-array represents a row.

<Details header="Example of return values" open = {false}>
```js
const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
const returnValue = await stmt.raw();
return Response.json(returnValue);
```
```js output
[
  [11, "Bs Beverages",
    "Victoria Ashworth"
  ],
  [13, "Bs Beverages",
    "Random Name"
  ]
]
```

With parameter `columnNames: true`:
```js
const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
const returnValue = await stmt.raw({columnNames:true});
return Response.json(returnValue)
```
```js output
[
  [
    "CustomerId",
    "CompanyName",
    "ContactName"
  ],
  [11, "Bs Beverages",
    "Victoria Ashworth"
  ],
  [13, "Bs Beverages",
    "Random Name"
  ]
]
```
</Details>

#### Guidance

- When using TypeScript, you can pass a [type parameter](/d1/worker-api/#typescript-support) to [`D1PreparedStatement::raw`](#raw) to return a typed result array.

### `first()`

Runs the prepared query (or queries), and returns the first row of the query result as an object. This does not return any metadata. Instead, it directly returns the object.

```js
const values = await stmt.first();
```

#### Parameters

- <code>columnName</code>: <Type text="String"/> <MetaInfo text="Optional"/>
  - Specify a `columnName` to return a value from a specific column in the first row of the query result.
- None.
  - Do not pass a parameter to obtain all columns from the first row.

#### Return values

- <code>firstRow</code>: <Type text="Object"/> <MetaInfo text="Optional"/>
  - An object containing the first row of the query result.
  - The return value will be further filtered to a specific attribute if `columnName` was specified.

- `null`: <Type text="null"/>
  - If the query returns no rows.

<Details header ="Example of return values" open = {false}>

Get all the columns from the first row:

```js
const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
const returnValue = await stmt.first();
return Response.json(returnValue)
```
```js output
{
  "CustomerId": 11,
  "CompanyName": "Bs Beverages",
  "ContactName": "Victoria Ashworth"
}
```

Get a specific column from the first row:

```js
const someVariable = `Bs Beverages`;
const stmt = env.DB.prepare("SELECT * FROM Customers WHERE CompanyName = ?").bind(someVariable);
const returnValue = await stmt.first(CustomerId);
return Response.json(returnValue)
```
```js output
11
```
</Details>

#### Guidance

- If the query returns rows but `column` does not exist, then [`D1PreparedStatement::first`](#first) throws the `D1_ERROR` exception.
- [`D1PreparedStatement::first`](#first) does not alter the SQL query. To improve performance, consider appending `LIMIT 1` to your statement.
- When using TypeScript, you can pass a [type parameter](/d1/worker-api/#typescript-support) to [`D1PreparedStatement::first`](#first) to return a typed result object.

---

# Create a sitemap from Sanity CMS with Workers

URL: https://developers.cloudflare.com/developer-spotlight/tutorials/create-sitemap-from-sanity-cms/

import { TabItem, Tabs, WranglerConfig, PackageManagers } from "~/components";

In this tutorial, you will put together a Cloudflare Worker that creates and serves a sitemap using data from [Sanity.io](https://www.sanity.io), a headless CMS.

The high-level workflow of the solution you are going to build in this tutorial is the following:

1. A URL on your domain (for example, `cms.example.com/sitemap.xml`) will be routed to a Cloudflare Worker.
2. The Worker will fetch your CMS data such as slugs and last modified dates.
3. The Worker will use that data to assemble a sitemap.
4. Finally, The Worker will return the XML sitemap ready for search engines.

## Before you begin

Before you start, make sure you have:

- A Cloudflare account. If you do not have one, [sign up](https://dash.cloudflare.com/sign-up/workers-and-pages) before continuing.
- A domain added to your Cloudflare account using a [full setup](/dns/zone-setups/full-setup/setup/), that is, using Cloudflare for your authoritative DNS nameservers.
- [npm](https://docs.npmjs.com/getting-started) and [Node.js](https://nodejs.org/en/) installed on your machine.

## Create a new Worker

Cloudflare Workers provides a serverless execution environment that allows you to create new applications or augment existing ones without configuring or maintaining infrastructure.

While you can create Workers in the Cloudflare dashboard, it is a best practice to create them locally, where you can use version control and [Wrangler](/workers/wrangler/install-and-update/), the Workers command-line interface, to deploy them.

Create a new Worker project using [C3](/pages/get-started/c3/) (`create-cloudflare` CLI):

<PackageManagers type="create" pkg="cloudflare@latest" />

In this tutorial, the Worker will be named `cms-sitemap`.

Select the options in the command-line interface (CLI) that work best for you, such as using JavaScript or TypeScript. The starter template you choose does not matter as this tutorial provides all the required code for you to paste in your project.

Next, require the `@sanity/client` package.

<PackageManagers pkg="@sanity/client@latest" />

## Configure Wrangler

A default `wrangler.jsonc` was generated in the previous step.

The Wrangler file is a configuration file used to specify project settings and deployment configurations in a structured format.

For this tutorial your [Wrangler configuration file](/workers/wrangler/configuration/) should be similar to the following:

<WranglerConfig>

```toml
name = "cms-sitemap"
main = "src/index.ts"
compatibility_date = "2024-04-19"
minify = true

[vars]
# The CMS will return relative URLs, so we need to know the base URL of the site.
SITEMAP_BASE = "https://example.com"
# Modify to match your project ID.
SANITY_PROJECT_ID = "5z5j5z5j"
SANITY_DATASET = "production"
```

</WranglerConfig>

You must update the `[vars]` section to match your needs. See the inline comments to understand the purpose of each entry.

:::caution

Secrets do not belong in [Wrangler configuration file](/workers/wrangler/configuration/)s. If you need to add secrets, use `.dev.vars` for local secrets and the `wranger secret put` command for deploying secrets. For more information, refer to [Secrets](/workers/configuration/secrets/).

:::

## Add code

In this step you will add the boilerplate code that will get you close to the complete solution.

For the purpose of this tutorial, the code has been condensed into two files:

- `index.ts|js`: Serves as the entry point for requests to the Worker and routes them to the proper place.
- `Sitemap.ts|js`: Retrieves the CMS data that will be turned into a sitemap. For a better separation of concerns and organization, the CMS logic should be in a separate file.

Paste the following code into the existing `index.ts|js` file:

```ts
/**
 * Welcome to Cloudflare Workers!
 *
 * - Run `npm run dev` in your terminal to start a development server
 * - Open a browser tab at http://localhost:8787/ to see your worker in action
 * - Run `npm run deploy` to publish your worker
 *
 * Bind resources to your worker in Wrangler config file. After adding bindings, a type definition for the
 * `Env` object can be regenerated with `npm run cf-typegen`.
 *
 * Learn more at https://developers.cloudflare.com/workers/
 */

import { Sitemap } from "./Sitemap";

// Export a default object containing event handlers.
export default {
	// The fetch handler is invoked when this worker receives an HTTPS request
	// and should return a Response (optionally wrapped in a Promise).
	async fetch(request, env, ctx): Promise<Response> {
		const url = new URL(request.url);

		// You can get pretty far with simple logic like if/switch-statements.
		// If you need more complex routing, consider Hono https://hono.dev/.
		if (url.pathname === "/sitemap.xml") {
			const handleSitemap = new Sitemap(request, env, ctx);
			return handleSitemap.fetch();
		}

		return new Response(`Try requesting /sitemap.xml`, {
			headers: { "Content-Type": "text/html" },
		});
	},
} satisfies ExportedHandler<Env>;
```

You do not need to modify anything in this file after pasting the above code.

Next, create a new file named `Sitemap.ts|js` and paste the following code:

```ts
import { createClient, SanityClient } from "@sanity/client";

export class Sitemap {
	private env: Env;
	private ctx: ExecutionContext;

	constructor(request: Request, env: Env, ctx: ExecutionContext) {
		this.env = env;
		this.ctx = ctx;
	}

	async fetch(): Promise<Response> {
		// Modify the query to use your CMS's schema.
		//
		// Request these:
		// - "slug": The slug of the post.
		// - "lastmod": When the post was updated.
		//
		// Notes:
		// - The slugs are prefixed to help form the full relative URL in the sitemap.
		// - Order the slugs to ensure the sitemap is in a consistent order.
		const query = `*[defined(postFields.slug.current)] {
			_type == 'articlePost' => {
				'slug': '/posts/' + postFields.slug.current,
				'lastmod': _updatedAt,
			},
			_type == 'examplesPost' => {
				'slug': '/examples/' + postFields.slug.current,
				'lastmod': _updatedAt,
			},
			_type == 'templatesPost' => {
				'slug': '/templates/' + postFields.slug.current,
				'lastmod': _updatedAt,
			}
		} | order(slug asc)`;

		const dataForSitemap = await this.fetchCmsData(query);

		if (!dataForSitemap) {
			console.error(
				"Error fetching data for sitemap",
				JSON.stringify(dataForSitemap),
			);
			return new Response("Error fetching data for sitemap", { status: 500 });
		}

		const sitemapXml = `<?xml version="1.0" encoding="UTF-8"?>
		<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
		  ${dataForSitemap
				.filter(Boolean)
				.map(
					(item: any) => `
			<url>
			  <loc>${this.env.SITEMAP_BASE}${item.slug}</loc>
			  <lastmod>${item.lastmod}</lastmod>
			</url>
		  `,
				)
				.join("")}
		</urlset>`;

		return new Response(sitemapXml, {
			headers: {
				"content-type": "application/xml",
			},
		});
	}

	private async fetchCmsData(query: string) {
		const client: SanityClient = createClient({
			projectId: this.env.SANITY_PROJECT_ID,
			dataset: this.env.SANITY_DATASET,
			useCdn: true,
			apiVersion: "2024-01-01",
		});

		try {
			const data = await client.fetch(query);
			return data;
		} catch (error) {
			console.error(error);
		}
	}
}
```

In steps 4 and 5 you will modify the code you pasted into `src/Sitemap.ts` according to your needs.

## Query CMS data

The following query in `src/Sitemap.ts` defines which data will be retrieved from the CMS. The exact query depends on your schema:

```ts
const query = `*[defined(postFields.slug.current)] {
  _type == 'articlePost' => {
    'slug': '/posts/' + postFields.slug.current,
    'lastmod': _updatedAt,
  },
  _type == 'examplesPost' => {
    'slug': '/examples/' + postFields.slug.current,
    'lastmod': _updatedAt,
  },
  _type == 'templatesPost' => {
    'slug': '/templates/' + postFields.slug.current,
    'lastmod': _updatedAt,
  }
} | order(slug asc)`;
```

If necessary, adapt the provided query to your specific schema, taking the following into account:

- The query must return two properties: `slug` and `lastmod`, as these properties are referenced when creating the sitemap. [GROQ](https://www.sanity.io/docs/how-queries-work) (Graph-Relational Object Queries) and [GraphQL](https://www.sanity.io/docs/graphql) enable naming properties — for example, `"lastmod": _updatedAt` — allowing you to map custom field names to the required properties.
- You will likely need to prefix each slug with the base path. For `www.example.com/posts/my-post`, the slug returned is `my-post`, but the base path (`/posts/`) is what needs to be prefixed (the domain is automatically added).
- Add a sort to the query to provide a consistent order (`order(slug asc)` in the provided tutorial code).

The data returned by the query will be used to generate an XML sitemap.

## Create the sitemap from the CMS data

The relevant code from `src/Sitemap.ts` generating the sitemap and returning it with the correct content type is the following:

```ts
const sitemapXml = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  ${dataForSitemap
		.filter(Boolean)
		.map(
			(item: any) => `
  <url>
    <loc>${this.env.SITEMAP_BASE}${item.slug}</loc>
    <lastmod>${item.lastmod}</lastmod>
  </url>
  `,
		)
		.join("")}
</urlset>`;

return new Response(sitemapXml, {
	headers: {
		"content-type": "application/xml",
	},
});
```

The URL (`loc`) and last modification date (`lastmod`) are the only two properties added to the sitemap because, [according to Google](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap#additional-notes-about-xml-sitemaps), other properties such as `priority` and `changefreq` will be ignored.

Finally, the sitemap is returned with the content type of `application/xml`.

At this point, you can test the Worker locally by running the following command:

```sh
wrangler dev
```

This command will output a localhost URL in the terminal. Open this URL with `/sitemap.xml` appended to view the sitemap in your browser. If there are any errors, they will be shown in the terminal output.

Once you have confirmed the sitemap is working, move on to the next step.

## Deploy the Worker

Now that your project is working locally, there are two steps left:

1. Deploy the Worker.
2. Bind it to a domain.

To deploy the Worker, run the following command in your terminal:

```sh
wrangler deploy
```

The terminal will log information about the deployment, including a new custom URL in the format `{worker-name}.{account-subdomain}.workers.dev`. While you could use this hostname to obtain your sitemap, it is a best practice to host the sitemap on the same domain your content is on.

## Route a URL to the Worker

In this step, you will make the Worker available on a new subdomain using a built-in Cloudflare feature.

One of the benefits of using a subdomain is that you do not have to worry about this sitemap conflicting with your root domain's sitemap, since both are probably using the `/sitemap.xml` path.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.

2. In Account Home, select **Workers & Pages**, and then select your Worker.

3. Go to **Settings** > **Triggers** > **Custom Domains** > **Add Custom Domain**.

4. Enter the domain or subdomain you want to configure for your Worker.

   For this tutorial, use a subdomain on the domain that is in your sitemap. For example, if your sitemap outputs URLs like `www.example.com` then a suitable subdomain is `cms.example.com`.

5. Select **Add Custom Domain**.

   After adding the subdomain, Cloudflare automatically adds the proper DNS record binding the Worker to the subdomain.

6. To verify your configuration, go to your new subdomain and append `/sitemap.xml`. For example:

   ```txt
   cms.example.com/sitemap.xml
   ```

The browser should show the sitemap as when you tested locally.

You now have a sitemap for your headless CMS using a highly maintainable and serverless setup.

---

# Custom access control for files in R2 using D1 and Workers

URL: https://developers.cloudflare.com/developer-spotlight/tutorials/custom-access-control-for-files/

import { Render, PackageManagers, WranglerConfig } from "~/components";

This tutorial gives you an overview on how to create a TypeScript-based Cloudflare Worker which allows you to control file access based on a simple username and password authentication. To achieve this, we will use a [D1 database](/d1/) for user management and an [R2 bucket](/r2/) for file storage.

The following sections will guide you through the process of creating a Worker using the Cloudflare CLI, creating and setting up a D1 database and R2 bucket, and then implementing the functionality to securely upload and fetch files from the created R2 bucket.

## Prerequisites

<Render file="prereqs" product="workers" />

## 1. Create a new Worker application

To get started developing your Worker you will use the [`create-cloudflare` CLI](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare). To do this, open a terminal window and run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"custom-access-control"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

Then, move into your newly created Worker:

```sh
cd custom-access-control
```

## 2. Create a new D1 database and binding

Now that you have created your Worker, next you will need to create a D1 database.
This can be done through the Cloudflare Portal or the Wrangler CLI.
For this tutorial, we will use the Wrangler CLI for simplicity.

To create a D1 database, just run the following command.
If you get asked to install wrangler, just confirm by pressing `y` and then press `Enter`.

```sh
npx wrangler d1 create <YOUR_DATABASE_NAME>
```

Replace `<YOUR_DATABASE_NAME>` with the name you want to use for your database. Keep in mind that this name can't be changed later on.

After the database is successfully created, you will see the data for the binding displayed as an output.
The binding declaration will start with `[[d1_databases]]` and contain the binding name, database name and ID.
To use the database in your worker, you will need to add the binding to your Wrangler file, by copying the declaration and pasting it into the wrangler file, as shown in the example below.

<WranglerConfig>

```toml
[[d1_databases]]
binding = "DB"
database_name = "<YOUR_DATABASE_NAME>"
database_id = "<YOUR_DATABASE_ID>"
```

</WranglerConfig>

## 3. Create R2 bucket and binding

Now that the D1 database is created, you also need to create an R2 bucket which will be used to store the uploaded files.
This step can also be done through the Cloudflare Portal, but as before, we will use the Wrangler CLI for this tutorial.
To create an R2 bucket, run the following command:

```sh
npx wrangler r2 bucket create <YOUR_BUCKET_NAME>
```

This works similar to the D1 database creation, where you will need to replace `<YOUR_BUCKET_NAME>` with the name you want to use for your bucket.
To do this, go to the Wrangler file again and then add the following lines:

<WranglerConfig>

```toml
[[r2_buckets]]
binding = "BUCKET"
bucket_name = "<YOUR_BUCKET_NAME>"
```

</WranglerConfig>

Now that you have prepared the Wrangler configuration, you should update the `worker-configuration.d.ts` file to include the new bindings.
This file will then provide TypeScript with the correct type definitions for the bindings, which allows for type checking and code completion in your editor.
You could either update it manually or run the following command in the directory of your project to update it automatically based on the [Wrangler configuration file](/workers/wrangler/configuration/) (recommended).

```sh
npm run cf-typegen
```

## 4. Database preparation

Before you can start developing the Worker, you need to prepare the D1 database.

For this you need to

1. Create a table in the database which will then be used to store the user data
2. Create a unique index on the username column, which will speed up database queries and ensure that the username is unique
3. Insert a test user into the table, so you can test your code later on

As this operation only needs to be done once, this will be done through the Wrangler CLI and not in the Worker's code.
Copy the commands listed below, replace the placeholders and then run them in order to prepare the database.
For this tutorial you can replace the `<YOUR_USERNAME>` and `<YOUR_HASHED_PASSWORD>` placeholders with `admin` and `5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8` respecively.
And `<YOUR_DATABASE_NAME>` should be replaced with the name you used to create the database.

```sh
npx wrangler d1 execute <YOUR_DATABASE_NAME> --command "CREATE TABLE user (id INTEGER PRIMARY KEY NOT NULL, username STRING NOT NULL, password STRING NOT NULL)" --remote
npx wrangler d1 execute <YOUR_DATABASE_NAME> --command "CREATE UNIQUE INDEX user_username ON user (username)"  --remote
npx wrangler d1 execute <YOUR_DATABASE_NAME> --command "INSERT INTO user (username, password) VALUES ('<YOUR_USERNAME>', '<YOUR_HASHED_PASSWORD>')"  --remote
```

## 5. Implement authentication in the Worker

Now that the database and bucket are all set up, you can start to develop the Worker application.
The first thing you will need to do is to implement the authentication for the requests.

This tutorial will use a simple username and password authentication, where the username and password (hashed) are stored in the D1 database.
The requests will contain the username and password as a base64 encoded string, which is also called Basic Authentication.
Depending on the request method, this string will be retrieved from the `Authorization` header for POST requests or the `Authorization` search parameter for GET requests.

To handle the authentication, you will need to replace the current code within `index.ts` file with the following code:

```ts
export default {
	async fetch(
		request: Request,
		env: Env,
		ctx: ExecutionContext,
	): Promise<Response> {
		try {
			const url = new URL(request.url);
			let authBase64;
			if (request.method === "POST") {
				authBase64 = request.headers.get("Authorization");
			} else if (request.method === "GET") {
				authBase64 = url.searchParams.get("Authorization");
			} else {
				return new Response("Method Not Allowed!", { status: 405 });
			}
			if (!authBase64 || authBase64.substring(0, 6) !== "Basic ") {
				return new Response("Unauthorized!", { status: 401 });
			}

			const authString = atob(authBase64.substring(6));
			const [username, password] = authString.split(":");
			if (!username || !password) {
				return new Response("Unauthorized!", { status: 401 });
			}

			// TODO: Check if the username and password are correct
		} catch (error) {
			console.error("An error occurred!", error);
			return new Response("Internal Server Error!", { status: 500 });
		}
	},
};
```

The code above currently extracts the username and password from the request, but does not yet check if the username and password are correct.

To check the username and password, you will need to hash the password and then query the D1 database table `user` with the given username and hashed password.
If the username and password are correct, you will retrieve a record from D1. If the username or password is incorrect, undefined will be returned and a `401 Unauthorized` response will be sent.
To add this functionality, you will need to add the following code to the `fetch` function by replacing the TODO comment from the last code snippet:

```ts
const passwordHashBuffer = await crypto.subtle.digest(
	{ name: "SHA-256" },
	new TextEncoder().encode(password),
);
const passwordHashArray = Array.from(new Uint8Array(passwordHashBuffer));
const passwordHashString = passwordHashArray
	.map((b) => b.toString(16).padStart(2, "0"))
	.join("");

const user = await env.DB.prepare(
	"SELECT id FROM user WHERE username = ? AND password = ? LIMIT 1",
)
	.bind(username, passwordHashString)
	.first<{ id: number }>();
if (!user) {
	return new Response("Unauthorized!", { status: 401 });
}

// TODO: Implement upload functionality
```

This code will now ensure that every request is authenticated before it can be processed further.

## 6. Upload a file through the Worker

Now that the authentication is set up, you can start to implement the functionality for uploading a file through the Worker.
To do this, you will need to add a new code path that handles HTTP `POST` requests.
Then within it, you will need to get the data from the request, which is sent within the body of the request, by using the `request.blob()` function.
After that, you can upload the data to the R2 bucket by using the `env.BUCKET.put` function.
And finally, you will return a `200 OK` response to the client.

To implement this functionality, you will need to replace the TODO comment from the last code snippet with the following code:

```ts
if (request.method === "POST") {
	// Upload the file to the R2 bucket with the user id followed by a slash as the prefix and then the path of the URL
	await env.BUCKET.put(`${user.id}/${url.pathname}`, request.body);
	return new Response("OK", { status: 200 });
}
// TODO: Implement GET request handling
```

This code will now allow you to upload a file through the Worker, which will be stored in your R2 bucket.

## 7. Fetch from the R2 bucket

To round up the Worker application, you will need to implement the functionality to fetch files from the R2 bucket.
This can be done by adding a new code path that handles `GET` requests.
Within this code path, you will need to extract the URL pathname and then retrieve the asset from the R2 bucket by using the `env.BUCKET.get` function.

To finalize the code, just replace the TODO comment for handling GET requests from the last code snippet with the following code:

```ts
if (request.method === "GET") {
	const file = await env.BUCKET.get(`${user.id}/${url.pathname.slice(1)}`);
	if (!file) {
		return new Response("Not Found!", { status: 404 });
	}
	const headers = new Headers();
	file.writeHttpMetadata(headers);
	return new Response(file.body, { headers });
}
return new Response("Method Not Allowed!", { status: 405 });
```

This code now allows you to fetch and return data from the R2 bucket when a `GET` request is made to the Worker application.

## 8. Deploy your Worker

After completing the code for this Cloudflare Worker tutorial, you will need to deploy it to Cloudflare.
To do this open the terminal in the directory created for your application, and then run:

```sh
npx wrangler deploy
```

You might get asked to authenticate (if not logged in already) and select an account. After that, the Worker will be deployed to Cloudflare.
When the deployment finished successfully, you will see a success message with the URL where your Worker is now accessible.

## 9. Test your Worker (optional)

To finish this tutorial, you should test your Worker application by sending a `POST` request to upload a file and after that a `GET` request to fetch the file.
This can be done by using a tool like `curl` or `Postman`, but for simplicity, this will describe the usage of `curl`.

Copy the following command which can be used to upload a simple JSON file with the content `{"Hello": "Worker!"}`.
Replace `<YOUR_API_SECRET>` with the base64 encoded username and password combination and then run the command. For this example you can use `YWRtaW46cGFzc3dvcmQ=`, which can be decoded to `admin` and `test`, for the api secret placeholder.

```sh
curl --location '<YOUR_WORKER_URL>/myFile.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <YOUR_API_SECRET>' \
--data '{
    "Hello": "Worker!"
}'
```

Then run the next command, or simply open the URL in your browser, to fetch the file you just uploaded:

```sh
curl --location '<YOUR_WORKER_URL>/myFile.json?Authorization=Basic%20YWRtaW46cGFzc3dvcmQ%3D'
```

## Next steps

If you want to learn more about Cloudflare Workers, R2, or D1 you can check out the following documentation:

- [Cloudflare Workers](/workers/)
- [Cloudflare R2](/r2/)
- [Cloudflare D1](/d1/)

---

# Recommend products on e-commerce sites using Workers AI and Stripe

URL: https://developers.cloudflare.com/developer-spotlight/tutorials/creating-a-recommendation-api/

import {
	Render,
	TabItem,
	Tabs,
	PackageManagers,
	WranglerConfig,
} from "~/components";

E-commerce and media sites often work on increasing the average transaction value to boost profitability. One of the strategies to increase the average transaction value is "cross-selling," which involves recommending related products. Cloudflare offers a range of products designed to build mechanisms for retrieving data related to the products users are viewing or requesting. In this tutorial, you will experience developing functionalities necessary for cross-selling by creating APIs for related product searches and product recommendations.

## Goals

In this workshop, you will develop three REST APIs.

1. An API to search for information highly related to a specific product.
2. An API to suggest products in response to user inquiries.
3. A Webhook API to synchronize product information with external e-commerce applications.

By developing these APIs, you will learn about the resources needed to build cross-selling and recommendation features for e-commerce sites.

You will also learn how to use the following Cloudflare products:

- [**Cloudflare Workers**](/workers/): Execution environment for API applications
- [**Cloudflare Vectorize**](/vectorize/): Vector DB used for related product searches
- [**Cloudflare Workers AI**](/workers-ai/): Used for vectorizing data and generating recommendation texts

<Render file="tutorials-before-you-start" product="workers" />

<Render file="prereqs" product="workers" />

### Prerequisites

This tutorial involves the use of several Cloudflare products. Some of these products have free tiers, while others may incur minimal charges. Please review the following billing information carefully.

<Render file="ai-local-usage-charges" product="workers" />

## 1. Create a new Worker project

First, let's create a Cloudflare Workers project.

<Render file="c3-definition" product="workers" />

To efficiently create and manage multiple APIs, let's use [`Hono`](https://hono.dev). Hono is an open-source application framework released by a Cloudflare Developer Advocate. It is lightweight and allows for the creation of multiple API paths, as well as efficient request and response handling.
Open your command line interface (CLI) and run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"cross-sell-api --framework=hono"}
/>

If this is your first time running the `C3` command, you will be asked whether you want to install it. Confirm that the package name for installation is `create-cloudflare` and answer `y`.

```sh
Need to install the following packages:
create-cloudflare@latest
Ok to proceed? (y)
```

During the setup, you will be asked if you want to manage your project source code with `Git`. It is recommended to answer `Yes` as it helps in recording your work and rolling back changes. You can also choose `No`, which will not affect the tutorial progress.

```sh
╰ Do you want to use git for version control?
  Yes / No
```

Finally, you will be asked if you want to deploy the application to your Cloudflare account. For now, select `No` and start development locally.

```sh
╭ Deploy with Cloudflare Step 3 of 3
│
╰ Do you want to deploy your application?
  Yes / No
```

If you see a message like the one below, the project setup is complete. You can open the `cross-sell-api` directory in your preferred IDE to start development.

```sh
├  APPLICATION CREATED  Deploy your application with npm run deploy
│
│ Navigate to the new directory cd cross-sell-api
│ Run the development server npm run dev
│ Deploy your application npm run deploy
│ Read the documentation https://developers.cloudflare.com/workers
│ Stuck? Join us at https://discord.cloudflare.com
│
╰ See you again soon!
```

Cloudflare Workers applications can be developed and tested in a local environment. On your CLI, change directory into your newly created Workers and run `npx wrangler dev` to start the application. Using `Wrangler`, the application will start, and you'll see a URL beginning with `localhost`.

```sh
 ⛅️ wrangler 3.60.1
-------------------

⎔ Starting local server...
[wrangler:inf] Ready on http://localhost:8787
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ [b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit            │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────╯

```

You can send a request to the API using the `curl` command. If you see the text `Hello Hono!`, the API is running correctly.

```sh
curl http://localhost:8787
```

```sh output
Hello Hono!
```

So far, we've covered how to create a Cloudflare Worker project and introduced tools and open-source projects like the `C3` command and the `Hono` framework that streamline development with Cloudflare. Leveraging these features will help you develop applications on Cloudflare Workers more smoothly.

## 2. Create an API to import product information

Now, we will start developing the three APIs that will be used in our cross-sell system. First, let's create an API to synchronize product information with an existing e-commerce application. In this example, we will set up a system where product registrations in [Stripe](https://stripe.com) are synchronized with the cross-sell system.

This API will receive product information sent from an external service like Stripe as a Webhook event. It will then extract the necessary information for search purposes and store it in a database for related product searches. Since vector search will be used, we also need to implement a process that converts strings to vector data using an Embedding model provided by Cloudflare Workers AI.

The process flow is illustrated as follows:

```mermaid
sequenceDiagram
    participant Stripe

    box Cloudflare
        participant CF_Workers
        participant CF_Workers_AI
        participant CF_Vectorize
    end

    Stripe->>CF_Workers: Send product registration event
    CF_Workers->>CF_Workers_AI: Request product information vectorization
    CF_Workers_AI->>CF_Workers: Send back vector data result
    CF_Workers->>CF_Vectorize: Save vector data
```

Let's start implementing step-by-step.

### Bind Workers AI and Vectorize to your Worker

This API requires the use of Workers AI and Vectorize. To use these resources from a Worker, you will need to first create the resources then [bind](/workers/runtime-apis/bindings/#what-is-a-binding) them to a Worker. First, let's create a Vectorize index with Wrangler using the command `wrangler vectorize create {index_name} --dimensions={number_of_dimensions} --metric={similarity_metric}`. The values for `dimensions` and `metric` depend on the type of [Text Embedding Model](/workers-ai/models/) you are using for data vectorization (Embedding). For example, if you are using the `bge-large-en-v1.5` model, the command is:

```sh
npx wrangler vectorize create stripe-products --dimensions=1024 --metric=cosine
```

When this command executes successfully, you will see a message like the following. It provides the items you need to add to the [Wrangler configuration file](/workers/wrangler/configuration/) to bind the Vectorize index with your Worker application.

```sh
✅ Successfully created a new Vectorize index: 'stripe-products'
📋 To start querying from a Worker, add the following binding configuration into your Wrangler configuration file:

[[vectorize]]
binding = "VECTORIZE_INDEX"
index_name = "stripe-products"
```

To use the created Vectorize index from your Worker, let's add the binding. Open the [Wrangler configuration file](/workers/wrangler/configuration/) and add the copied lines.

<WranglerConfig>

```toml null {5,6,7}
name = "cross-sell-api"
main = "src/index.ts"
compatibility_date = "2024-06-05"

[[vectorize]]
binding = "VECTORIZE_INDEX"
index_name = "stripe-products"
```

</WranglerConfig>

Additionally, let's add the configuration to use Workers AI in the [Wrangler configuration file](/workers/wrangler/configuration/).

<WranglerConfig>

```toml null {9,10}
name = "cross-sell-api"
main = "src/index.ts"
compatibility_date = "2024-06-05"

[[vectorize]]
binding = "VECTORIZE_INDEX"
index_name = "stripe-products"

[ai]
binding = "AI" # available in your Worker on env.AI
```

</WranglerConfig>

When handling bound resources from your application, you can generate TypeScript type definitions to develop more safely. Run the `npm run cf-typegen` command. This command updates the `worker-configuration.d.ts` file, allowing you to use both Vectorize and Workers AI in a type-safe manner.

```sh
npm run cf-typegen
```

```sh output

> cf-typegen
> wrangler types --env-interface CloudflareBindings

 ⛅️ wrangler 3.60.1
-------------------

interface CloudflareBindings {
        VECTORIZE_INDEX: VectorizeIndex;
        AI: Ai;
}
```

Once you save these changes, the respective resources and APIs will be available for use in the Workers application. You can access these properties from `env`. In this example, you can use them as follows:

```ts
app.get("/", (c) => {
	c.env.AI; // Workers AI SDK
	c.env.VECTORIZE_INDEX; // Vectorize SDK
	return c.text("Hello Hono!");
});
```

Finally, rerun the `npx wrangler dev` command with the `--remote` option. This is necessary because Vectorize indexes are not supported in local mode. If you see the message, `Vectorize bindings are not currently supported in local mode. Please use --remote if you are working with them.`, rerun the command with the `--remote` option added.

```sh
npx wrangler dev --remote
```

### Create a webhook API to handle product registration events

You can receive notifications about product registration and information via POST requests using webhooks. Let's create an API that accepts POST requests. Open your `src/index.ts` file and add the following code:

```ts
app.post("/webhook", async (c) => {
	const body = await c.req.json();
	if (body.type === "product.created") {
		const product = body.data.object;
		console.log(JSON.stringify(product, null, 2));
	}
	return c.text("ok", 200);
});
```

This code implements an API that processes POST requests to the `/webhook` endpoint. The data sent by Stripe's Webhook events is included in the request body in JSON format. Therefore, we use `c.req.json()` to extract the data. There are multiple types of Webhook events that Stripe can send, so we added a conditional to only process events when a product is newly added, as indicated by the `type`.

### Add Stripe's API Key to the project

When developing a webhook API, you need to ensure that requests from unauthorized sources are rejected. To prevent unauthorized API requests from causing unintended behavior or operational confusion, you need a mechanism to verify the source of API requests. When integrating with Stripe, you can protect the API by generating a signing secret used for webhook verification.

1. Refer to the [Stripe documentation](https://docs.stripe.com/keys) to get a [secret API key for the test environment](https://docs.stripe.com/keys#reveal-an-api-secret-key-for-test-mode).
2. Save the obtained API key in a `.dev.vars` file.

```
STRIPE_SECRET_API_KEY=sk_test_XXXX
```

3. Follow the [guide](https://docs.stripe.com/stripe-cli) to install Stripe CLI.
4. Use the following Stripe CLI command to forward Webhook events from Stripe to your local application.

```sh
stripe listen --forward-to http://localhost:8787/webhook --events product.created
```

5. Copy the signing secret that starts with `whsec_` from the Stripe CLI command output.

```
> Ready! You are using Stripe API Version [2024-06-10]. Your webhook signing secret is
whsec_xxxxxx (^C to quit)
```

6. Save the obtained signing secret in the `.dev.vars` file.

```
STRIPE_WEBHOOK_SECRET=whsec_xxxxxx
```

7. Run `npm run cf-typegen` to update the type definitions in `worker-configuration.d.ts`.
8. Run `npm install stripe` to add the Stripe SDK to your application.
9. Restart the `npm run dev -- --remote` command to import the API key into your application.

Finally, modify the source code of `src/index.ts` as follows to ensure that the webhook API cannot be used from sources other than your Stripe account.

````ts
import { Hono } from "hono";
import { env } from "hono/adapter";
import Stripe from "stripe";

type Bindings = {
	[key in keyof CloudflareBindings]: CloudflareBindings[key];
};

const app = new Hono<{
	Bindings: Bindings;
	Variables: {
		stripe: Stripe;
	};
}>();

/**
 * Initialize Stripe SDK client
 * We can use this SDK without initializing on each API route,
 * just get it by the following example:
 * ```
 * const stripe = c.get('stripe')
 * ```
 */
app.use("*", async (c, next) => {
	const { STRIPE_SECRET_API_KEY } = env(c);
	const stripe = new Stripe(STRIPE_SECRET_API_KEY);
	c.set("stripe", stripe);
	await next();
});

app.post("/webhook", async (c) => {
	const { STRIPE_WEBHOOK_SECRET } = env(c);
	const stripe = c.get("stripe");
	const signature = c.req.header("stripe-signature");
	if (!signature || !STRIPE_WEBHOOK_SECRET || !stripe) {
		return c.text("", 400);
	}
	try {
		const body = await c.req.text();
		const event = await stripe.webhooks.constructEventAsync(
			body,
			signature,
			STRIPE_WEBHOOK_SECRET,
		);
		if (event.type === "product.created") {
			const product = event.data.object;
			console.log(JSON.stringify(product, null, 2));
		}
		return c.text("", 200);
	} catch (err) {
		const errorMessage = `⚠️  Webhook signature verification failed. ${err instanceof Error ? err.message : "Internal server error"}`;
		console.log(errorMessage);
		return c.text(errorMessage, 400);
	}
});

export default app;
````

This ensures that an HTTP 400 error is returned if the Webhook API is called directly by unauthorized sources.

```sh
curl -XPOST http://localhost:8787/webhook -I
```

```sh output
HTTP/1.1 400 Bad Request
Content-Length: 0
Content-Type: text/plain; charset=UTF-8
```

Use the Stripe CLI command to test sending events from Stripe.

```sh
stripe trigger product.created
```

```sh output
Setting up fixture for: product
Running fixture for: product
Trigger succeeded! Check dashboard for event details.
```

The product information added on the Stripe side is recorded as a log on the terminal screen where `npm run dev` is executed.

```
{
  id: 'prod_QGw9VdIqVCNABH',
  object: 'product',
  active: true,
  attributes: [],
  created: 1718087602,
  default_price: null,
  description: '(created by Stripe CLI)',
  features: [],
  images: [],
  livemode: false,
  marketing_features: [],
  metadata: {},
  name: 'myproduct',
  package_dimensions: null,
  shippable: null,
  statement_descriptor: null,
  tax_code: null,
  type: 'service',
  unit_label: null,
  updated: 1718087603,
  url: null
}
[wrangler:inf] POST /webhook 201 Created (14ms)
```

## 3. Convert text into vector data using Workers AI

We've prepared to ingest product information, so let's start implementing the preprocessing needed to create an index for search. In vector search using Cloudflare Vectorize, text data must be converted to numerical data before indexing. By storing data as numerical sequences, we can search based on the similarity of these vectors, allowing us to retrieve highly similar data.

In this step, we'll first implement the process of converting externally sent data into text data. This is necessary because the information to be converted into vector data is in text form. If you want to include product names, descriptions, and metadata as search targets, add the following processing.

```ts null {3,4,5,6,7,8,9}
if (event.type === "product.created") {
	const product = event.data.object;
	const productData = [
		`## ${product.name}`,
		product.description,
		"### metadata",
		Object.entries(product.metadata)
			.map(([key, value]) => `- ${key}: ${value}`)
			.join("\n"),
	].join("\n");
	console.log(JSON.stringify(productData, null, 2));
}
```

By adding this processing, you convert product information in JSON format into a simple Markdown format product introduction text.

```sh
## product name
product description.
### metadata
- key: value
```

Now that we've converted the data to text, let's convert it to vector data. By using the Text Embedding model of Workers AI, we can convert text into vector data of any desired dimension.

```ts null {7,8,9,10,11,12,13}
const productData = [
	`## ${product.name}`,
	product.description,
	"### metadata",
	Object.entries(product.metadata)
		.map(([key, value]) => `- ${key}: ${value}`)
		.join("\n"),
].join("\n");
const embeddings = await c.env.AI.run("@cf/baai/bge-large-en-v1.5", {
	text: productData,
});
console.log(JSON.stringify(embeddings, null, 2));
```

When using Workers AI, execute the `c.env.AI.run()` function. Specify the model you want to use as the first argument. In the second argument, input text data about the text you want to convert using the Text Embedding model or the instructions for the generated images or text. If you want to save the converted vector data using Vectorize, make sure to select a model that matches the number of `dimensions` specified in the `npx wrangler vectorize create` command. If the numbers do not match, there is a possibility that the converted vector data cannot be saved.

### Save vector data to Vectorize

Finally, let's save the created data to Vectorize. Edit `src/index.ts` to implement the indexing process using the `VECTORIZE_INDEX` binding. Since the data to be saved will be vector data, save the pre-conversion text data as metadata.

```ts null {16,17,18,19,20,21,22,23,24}
if (event.type === "product.created") {
	const product = event.data.object;
	const productData = [
		`## ${product.name}`,
		product.description,
		"### metadata",
		Object.entries(product.metadata)
			.map(([key, value]) => `- ${key}: ${value}`)
			.join("\n"),
	].join("\n");
	console.log(JSON.stringify(productData, null, 2));
	const embeddings = await c.env.AI.run("@cf/baai/bge-large-en-v1.5", {
		text: productData,
	});
	await c.env.VECTORIZE_INDEX.insert([
		{
			id: product.id,
			values: embeddings.data[0],
			metadata: {
				name: product.name,
				description: product.description || "",
				product_metadata: product.metadata,
			},
		},
	]);
}
```

With this, we have established a mechanism to synchronize the product data with the database for recommendations. Use Stripe CLI commands to save some product data.

```bash
stripe products create --name="Smartphone X" \
  --description="Latest model with cutting-edge features" \
  -d "default_price_data[currency]=usd" \
  -d "default_price_data[unit_amount]=79900" \
  -d "metadata[category]=electronics"
```

```bash
stripe products create --name="Ultra Notebook" \
  --description="Lightweight and powerful notebook computer" \
  -d "default_price_data[currency]=usd" \
  -d "default_price_data[unit_amount]=129900" \
  -d "metadata[category]=computers"
```

```bash
stripe products create --name="Wireless Earbuds Pro" \
  --description="High quality sound with noise cancellation" \
  -d "default_price_data[currency]=usd" \
  -d "default_price_data[unit_amount]=19900" \
  -d "metadata[category]=audio"
```

```bash
stripe products create --name="Smartwatch 2" \
  --description="Stay connected with the latest smartwatch" \
  -d "default_price_data[currency]=usd" \
  -d "default_price_data[unit_amount]=29900" \
  -d "metadata[category]=wearables"
```

```bash
stripe products create --name="Tablet Pro" \
  --description="Versatile tablet for work and play" \
  -d "default_price_data[currency]=usd" \
  -d "default_price_data[unit_amount]=49900" \
  -d "metadata[category]=computers"
```

If the save is successful, you will see logs like `[200] POST` in the screen where you are running the `stripe listen` command.

```sh
2024-06-11 16:41:42   --> product.created [evt_1PQPKsL8xlxrZ26gst0o1DK3]
2024-06-11 16:41:45  <--  [200] POST http://localhost:8787/webhook [evt_1PQPKsL8xlxrZ26gst0o1DK3]
2024-06-11 16:41:47   --> product.created [evt_1PQPKxL8xlxrZ26gGk90TkcK]
2024-06-11 16:41:49  <--  [200] POST http://localhost:8787/webhook [evt_1PQPKxL8xlxrZ26gGk90TkcK]
```

If you confirm one log entry for each piece of registered data, the save process is complete. Next, we will implement the API for related product searches.

## 4. Create a related products search API using Vectorize

Now that we have prepared the index for searching, the next step is to implement an API to search for related products. By utilizing a vector index, we can perform searches based on how similar the data is. Let's implement an API that searches for product data similar to the specified product ID using this method.

In this API, the product ID is received as a part of the API path. Using the received ID, vector data is retrieved from Vectorize using `c.env.VECTORIZE_INDEX.getByIds()`. The return value of this process includes vector data, which is then passed to `c.env.VECTORIZE_INDEX.query()` to conduct a similarity search. To quickly check which products are recommended, we set `returnMetadata` to `true` to obtain the stored metadata information as well. The `topK` parameter specifies the number of data items to retrieve. Change this value if you want to obtain less than 2 or more than 4 data items.

```ts
app.get("/products/:product_id", async (c) => {
	// Get the product ID from API path parameters
	const productId = c.req.param("product_id");

	// Retrieve the indexed data by the product ID
	const [product] = await c.env.VECTORIZE_INDEX.getByIds([productId]);

	// Search similar products by using the embedding data
	const similarProducts = await c.env.VECTORIZE_INDEX.query(product.values, {
		topK: 3,
		returnMetadata: true,
	});

	return c.json({
		product: {
			...product.metadata,
		},
		similarProducts,
	});
});
```

Let's run this API. Use a product ID that starts with `prod_`, which can be obtained from the result of running the `stripe products crate` command or the `stripe products list` command.

```sh
curl http://localhost:8787/products/prod_xxxx
```

If you send a request using a product ID that exists in the Vectorize index, the data for that product and two related products will be returned as follows.

```json
{
	"product": {
		"name": "Tablet Pro",
		"description": "Versatile tablet for work and play",
		"product_metadata": {
			"category": "computers"
		}
	},
	"similarProducts": {
		"count": 3,
		"matches": [
			{
				"id": "prod_QGxFoHEpIyxHHF",
				"metadata": {
					"name": "Tablet Pro",
					"description": "Versatile tablet for work and play",
					"product_metadata": {
						"category": "computers"
					}
				},
				"score": 1
			},
			{
				"id": "prod_QGxFEgfmOmy5Ve",
				"metadata": {
					"name": "Ultra Notebook",
					"description": "Lightweight and powerful notebook computer",
					"product_metadata": {
						"category": "computers"
					}
				},
				"score": 0.724717327
			},
			{
				"id": "prod_QGwkGYUcKU2UwH",
				"metadata": {
					"name": "demo product",
					"description": "aaaa",
					"product_metadata": {
						"test": "hello"
					}
				},
				"score": 0.635707003
			}
		]
	}
}
```

Looking at the `score` in `similarProducts`, you can see that there is data with a `score` of `1`. This means it is exactly the same as the query used to search. By looking at the metadata, it is evident that the data is the same as the product ID sent in the request. Since we want to search for related products, let's add a `filter` to prevent the same product from being included in the search results. Here, a filter is added to exclude data with the same product name using the `metadata` name.

```ts null {7,8,9,10,11}
app.get("/products/:product_id", async (c) => {
	const productId = c.req.param("product_id");
	const [product] = await c.env.VECTORIZE_INDEX.getByIds([productId]);
	const similarProducts = await c.env.VECTORIZE_INDEX.query(product.values, {
		topK: 3,
		returnMetadata: true,
		filter: {
			name: {
				$ne: product.metadata?.name.toString(),
			},
		},
	});

	return c.json({
		product: {
			...product.metadata,
		},
		similarProducts,
	});
});
```

After adding this process, if you run the API, you will see that there is no data with a `score` of `1`.

```json
{
	"product": {
		"name": "Tablet Pro",
		"description": "Versatile tablet for work and play",
		"product_metadata": {
			"category": "computers"
		}
	},
	"similarProducts": {
		"count": 3,
		"matches": [
			{
				"id": "prod_QGxFEgfmOmy5Ve",
				"metadata": {
					"name": "Ultra Notebook",
					"description": "Lightweight and powerful notebook computer",
					"product_metadata": {
						"category": "computers"
					}
				},
				"score": 0.724717327
			},
			{
				"id": "prod_QGwkGYUcKU2UwH",
				"metadata": {
					"name": "demo product",
					"description": "aaaa",
					"product_metadata": {
						"test": "hello"
					}
				},
				"score": 0.635707003
			},
			{
				"id": "prod_QGxFEafrNDG88p",
				"metadata": {
					"name": "Smartphone X",
					"description": "Latest model with cutting-edge features",
					"product_metadata": {
						"category": "electronics"
					}
				},
				"score": 0.632409942
			}
		]
	}
}
```

In this way, you can implement a system to search for related product information using Vectorize.

## 5. Create a recommendation API that answers user questions.

Recommendations can be more than just displaying related products; they can also address user questions and concerns. The final API will implement a process to answer user questions using Vectorize and Workers AI.

This API will implement the following processes:

1. Vectorize the user's question using the Text Embedding Model from Workers AI.
2. Use Vectorize to search and retrieve highly relevant products.
3. Convert the search results into a string in Markdown format.
4. Utilize the Text Generation Model from Workers AI to generate a response based on the search results.

This method realizes a text generation mechanism called Retrieval Augmented Generation (RAG) using Cloudflare. The bindings and other preparations are already completed, so let's add the API.

```ts
app.post("/ask", async (c) => {
	const { question } = await c.req.json();
	if (!question) {
		return c.json({
			message: "Please tell me your question.",
		});
	}
	/**
	 * Convert the question to the vector data
	 */
	const embeddedQuestion = await c.env.AI.run("@cf/baai/bge-large-en-v1.5", {
		text: question,
	});

	/**
	 * Query similarity data from Vectorize index
	 */
	const similarProducts = await c.env.VECTORIZE_INDEX.query(
		embeddedQuestion.data[0],
		{
			topK: 3,
			returnMetadata: true,
		},
	);

	/**
	 * Convert the JSON data to the Markdown text
	 **/
	const contextData = similarProducts.matches.reduce((prev, current) => {
		if (!current.metadata) return prev;
		const productTexts = Object.entries(current.metadata).map(
			([key, value]) => {
				switch (key) {
					case "name":
						return `## ${value}`;
					case "product_metadata":
						return `- ${key}: ${JSON.stringify(value)}`;
					default:
						return `- ${key}: ${value}`;
				}
			},
		);
		const productTextData = productTexts.join("\n");
		return `${prev}\n${productTextData}`;
	}, "");

	/**
	 * Generate the answer
	 */
	const response = await c.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
		messages: [
			{
				role: "system",
				content: `You are an assistant for question-answering tasks. Use the following pieces of retrieved context to answer the question. If you don't know the answer, just say that you don't know.\n#Context: \n${contextData} `,
			},
			{
				role: "user",
				content: question,
			},
		],
	});

	return c.json(response);
});
```

Let's use the created API to consult on a product. You can send your question in the body of a POST request. For example, if you want to ask about getting a new PC, you can execute the following command:

```sh
curl -X POST "http://localhost:8787/ask" -H "Content-Type: application/json" -d '{"question": "I want to get a new PC"}'
```

When the question is sent, a recommendation text will be generated as introduced earlier. In this example, the `Ultra Notebook` product was recommended. This is because it has a `notebook compucoter` description, which means it received a relatively high score in the Vectorize search.

```json
{
	"response": "Exciting! You're looking to get a new PC! Based on the context I retrieved, I'd recommend considering the \"Ultra Notebook\" since it's described as a lightweight and powerful notebook computer, which fits the category of \"computers\". Would you like to know more about its specifications or features?"
}
```

The text generation model generates new text each time based on the input prompt (questions or product search results). Therefore, even if you send the same request to this API, the response text may differ slightly. When developing for production, use features like logging or caching in the [AI Gateway](/ai-gateway/) to set up proper control and debugging.

## 6. Deploy the application

Before deploying the application, we need to make sure your Worker project has access to the Stripe API keys we created earlier. Since the API keys of external services are defined in `.dev.vars`, this information also needs to be set in your Worker project. To save API keys and secrets, run the `npx wrangler secret put <KEY>` command. In this tutorial, you'll execute the command twice, referring to the values set in `.dev.vars`.

```sh
npx wrangler secret put STRIPE_SECRET_API_KEY
npx wrangler secret put STRIPE_WEBHOOK_SECRET
```

Then, run `npx wrangler deploy`. This will deploy the application on Cloudflare, making it publicly accessible.

## Conclusion

As you can see, using Cloudflare Workers, Workers AI, and Vectorize allows you to easily implement related product or product recommendation APIs. Even if product data is managed on external services like Stripe, you can incorporate them by adding a webhook API. Additionally, though not introduced in this tutorial, you can save information such as user preferences and interested categories in Workers KV or D1. By using this stored information as text generation prompts, you can provide more accurate recommendation functions.

Use the experience from this tutorial to enhance your e-commerce site with new ideas.

---

# Setup Fullstack Authentication with Next.js, Auth.js, and Cloudflare D1

URL: https://developers.cloudflare.com/developer-spotlight/tutorials/fullstack-authentication-with-next-js-and-cloudflare-d1/

import {
	Render,
	PackageManagers,
	Type,
	TypeScriptExample,
	FileTree,
} from "~/components";

In this tutorial, you will build a [Next.js app](/workers/framework-guides/web-apps/nextjs/) with authentication powered by Auth.js, Resend, and [Cloudflare D1](/d1/).

Before continuing, make sure you have a Cloudflare account and have installed and [authenticated Wrangler](https://developers.cloudflare.com/workers/wrangler/commands/#login). Some experience with HTML, CSS, and JavaScript/TypeScript is helpful but not required. In this tutorial, you will learn:

- How to create a Next.js application and run it on Cloudflare Workers
- How to bind a Cloudflare D1 database to your Next.js app and use it to store authentication data
- How to use Auth.js to add serverless fullstack authentication to your Next.js app

You can find the finished code for this project on [GitHub](https://github.com/mackenly/auth-js-d1-example).

## Prerequisites

<Render file="prereqs" product="workers" />

3. Create or login to a [Resend account](https://resend.com/signup) and get an [API key](https://resend.com/docs/dashboard/api-keys/introduction#add-api-key).
4. [Install and authenticate Wrangler](/workers/wrangler/install-and-update/).

## 1. Create a Next.js app using Workers

From within the repository or directory where you want to create your project run:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"auth-js-d1-example --framework=next"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "web-framework",
		framework: "Next.js",
	}}
/>

This will create a new Next.js project using [OpenNext](https://opennext.js.org/) that will run in a Worker using [Workers Static Assets](#static-assets).

Before we get started, open your project's `tsconfig.json` file and modify the following to the `compilerOptions` object to allow for top level await needed to let our application get the Cloudflare context:

```json title="tsconfig.json"
{
	"compilerOptions": {
		"target": "ES2022",
	}
}
```

Throughout this tutorial, we'll add several values to Cloudflare Secrets. For [local development](/workers/configuration/secrets/#local-development-with-secrets), add those same values to a file in the top level of your project called `.dev.vars` and make sure it is not committed into version control. This will let you work with Secret values locally. Go ahead and copy and paste the following into `.dev.vars` for now and replace the values as we go.

```sh title=".dev.vars"
AUTH_SECRET = "<replace-me>"
AUTH_RESEND_KEY = "<replace-me>"
AUTH_EMAIL_FROM = "onboarding@resend.dev"
AUTH_URL = "http://localhost:8787/"
```

:::note[Manually set URL]
Within the Workers environment, the `AUTH_URL` doesn't always get picked up automatically by Auth.js, hence why we're specifying it manually here (we'll need to do the same for prod later).
:::

## 2. Install Auth.js

Following the [installation instructions](https://authjs.dev/getting-started/installation?framework=Next.js) from Auth.js, begin by installing Auth.js:

<PackageManagers pkg="next-auth@beta" />

Now run the following to generate an `AUTH_SECRET`:

```sh
npx auth secret
```

Now, deviating from the standard Auth.js setup, locate your generated secret (likely in a file named `.env.local`) and [add the secret to your Workers application](/workers/configuration/secrets/#adding-secrets-to-your-project) by running the following and completing the steps to add a secret's value that we just generated:

```sh
npx wrangler secret put AUTH_SECRET
```

If you have not deployed yet that's fine. Allow wrangler to create the worker for you.

After adding the secret, update your `.dev.vars` file to include an `AUTH_SECRET` value (this secret should be different from the one you generated earlier for security purposes):

```sh title=".dev.vars"
# ...
AUTH_SECRET = "<replace-me>"
# ...
```

Next, go into `cloudflare-env.d.ts` file and add the following to the <Type text="CloudflareEnv" /> interface:

```ts title="cloudflare-env.d.ts"
interface CloudflareEnv {
	AUTH_SECRET: string;
}
```

## 3. Install Cloudflare D1 Adapter

Now, install the Auth.js D1 adapter by running:

<PackageManagers pkg="@auth/d1-adapter" />

Create a D1 database using the following command:

```sh title="Create D1 database"
npx wrangler d1 create auth-js-d1-example-db
```

When finished you should see instructions to add the database binding to your [Wrangler configuration file](/workers/wrangler/configuration/). Example binding:

import { WranglerConfig} from "~/components";

<WranglerConfig>

```toml title="wrangler.toml"
[[d1_databases]]
binding = "DB"
database_name = "auth-js-d1-example-db"
database_id = "<unique-ID-for-your-database>"
```

</WranglerConfig>

Now, within your `cloudflare-env.d.ts`, add your D1 binding, like:

```ts title="cloudflare-env.d.ts"
interface CloudflareEnv {
	DB: D1Database;
	AUTH_SECRET: string;
}
```

## 4. Configure Credentials Provider

Auth.js provides integrations for many different [credential providers](https://authjs.dev/getting-started/authentication) such as Google, GitHub, etc. For this tutorial we're going to use [Resend for magic links](https://authjs.dev/getting-started/authentication/email). You should have already created a Resend account and have an [API key](https://resend.com/docs/dashboard/api-keys/introduction#add-api-key).

Using either a [Resend verified domain email address](https://resend.com/docs/dashboard/domains/introduction) or `onboarding@resend.dev`, add a new Secret to your Worker containing the email your magic links will come from:

```sh title="Add Resend email to secrets"
npx wrangler secret put AUTH_EMAIL_FROM
```

Next, ensure the `AUTH_EMAIL_FROM` environment variable is updated in your `.dev.vars` file with the email you just added as a secret:

```sh title=".dev.vars"
# ...
AUTH_EMAIL_FROM = "onboarding@resend.dev"
# ...
```

Now [create a Resend API key](https://resend.com/docs/dashboard/api-keys/introduction) with `Sending access` and add it to your Worker's Secrets:

```sh title="Add Resend API key to secrets"
npx wrangler secret put AUTH_RESEND_KEY
```

As with previous secrets, update your `.dev.vars` file with the new secret value for `AUTH_RESEND_KEY` to use in local development:

```sh title=".dev.vars"
# ...
AUTH_RESEND_KEY = "<replace-me>"
# ...
```

After adding both of those Secrets, your `cloudflare-env.d.ts` should now include the following:

```ts title="cloudflare-env.d.ts"
interface CloudflareEnv {
	DB: D1Database;
	AUTH_SECRET: string;
	AUTH_RESEND_KEY: string;
	AUTH_EMAIL_FROM: string;
}
```

Credential providers and database adapters are provided to Auth.js through a configuration file called `auth.ts`. Create a file within your `src/app/` directory called `auth.ts` with the following contents:

<TypeScriptExample filename="src/app/auth.ts">
```ts
import NextAuth from "next-auth";
import { NextAuthResult } from "next-auth";
import { D1Adapter } from "@auth/d1-adapter";
import Resend from "next-auth/providers/resend";
import { getCloudflareContext } from "@opennextjs/cloudflare";

const authResult = async (): Promise<NextAuthResult> => {
	return NextAuth({
		providers: [
			Resend({
				apiKey: (await getCloudflareContext({async: true})).env.AUTH_RESEND_KEY,
				from: (await getCloudflareContext({async: true})).env.AUTH_EMAIL_FROM,
			}),
		],
		adapter: D1Adapter((await getCloudflareContext({async: true})).env.DB),
	});
};

export const { handlers, signIn, signOut, auth } = await authResult();
```
</TypeScriptExample>

Now, lets add the route handler and middleware used to authenticate and persist sessions.

Create a new directory structure and route handler within `src/app/api/auth/[...nextauth]` called `route.ts`. The file should contain:

<TypeScriptExample filename="src/app/api/auth/[...nextauth]/route.ts">
```ts
import { handlers } from "../../../auth";

export const { GET, POST } = handlers;
```
</TypeScriptExample>

Now, within the `src/` directory, create a `middleware.ts` file. If you do not have a `src/` directory, create a `middleware.ts` file in the root of your project. This will persist session data.

<TypeScriptExample filename="src/middleware.ts">
```ts
export { auth as middleware } from "./app/auth";
```
</TypeScriptExample>

## 5. Create Database Tables

The D1 adapter requires that tables be created within your database. It [recommends](https://authjs.dev/getting-started/adapters/d1#migrations) using the exported `up()` method to complete this. Within `src/app/api/` create a directory called `setup` containing a file called `route.ts`. Within this route handler, add the following code:

<TypeScriptExample filename="src/app/api/setup/route.ts">
```ts
import { up } from "@auth/d1-adapter";
import { getCloudflareContext } from "@opennextjs/cloudflare";

export async function GET() {
    try {
        await up((await getCloudflareContext({async: true})).env.DB)
    } catch (e: unknown) {
        if (e instanceof Error) {
            const causeMessage = e.cause instanceof Error ? e.cause.message : String(e.cause);
            console.log(causeMessage, e.message)
        }
    }
    return new Response('Migration completed');
}

```
</TypeScriptExample>

You'll need to run this once on your production database to create the necessary tables. If you're following along with this tutorial, we'll run it together in a few steps.

:::note[Clean up]
Running this multiple times won't hurt anything since the tables are only created if they do not already exist, but it's a good idea to remove this route from your production code once you've run it since you won't need it anymore.
:::

Before we go further, make sure you've created all of the necessary files:
<FileTree>
- src/
  - app/
    - api/
      - auth/
        - [...nextauth]/
          - route.ts
      - setup/
        - route.ts
    - auth.ts
    - page.ts
  - middleware.ts
- cloudflare-env.d.ts
- wrangler.toml
</FileTree>

## 6. Build Sign-in Interface
We've completed the backend steps for our application. Now, we need a way to sign in. First, let's install [shadcn](https://ui.shadcn.com/):
```sh title="Install shadcn"
npx shadcn@latest init -d
```

Next, run the following to add a few components:
```sh title="Add components"
npx shadcn@latest add button input card avatar label
```

To make it easy, we've provided a basic sign-in interface for you below that you can copy into your app. You will likely want to customize this to fit your needs, but for now, this will let you sign in, see your account details, and update your user's name.

Replace the contents of `page.ts` from within the `app/` directory with the following:

```ts title="src/app/page.ts"
import { redirect } from 'next/navigation';
import { signIn, signOut, auth } from './auth';
import { updateRecord } from '@auth/d1-adapter';
import { getCloudflareContext } from '@opennextjs/cloudflare';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Card, CardContent, CardDescription, CardHeader, CardTitle, CardFooter } from '@/components/ui/card';
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
import { Label } from '@/components/ui/label';

async function updateName(formData: FormData): Promise<void> {
	'use server';
	const session = await auth();
	if (!session?.user?.id) {
		return;
	}
	const name = formData.get('name') as string;
	if (!name) {
		return;
	}
	const query = `UPDATE users SET name = $1 WHERE id = $2`;
	await updateRecord((await getCloudflareContext({async: true})).env.DB, query, [name, session.user.id]);
	redirect('/');
}

export default async function Home() {
	const session = await auth();
	return (
		<main className="flex items-center justify-center min-h-screen bg-background">
			<Card className="w-full max-w-md">
				<CardHeader className="space-y-1">
					<CardTitle className="text-2xl font-bold text-center">{session ? 'User Profile' : 'Login'}</CardTitle>
					<CardDescription className="text-center">
						{session ? 'Manage your account' : 'Welcome to the auth-js-d1-example demo'}
					</CardDescription>
				</CardHeader>
				<CardContent>
					{session ? (
						<div className="space-y-4">
							<div className="flex items-center space-x-4">
								<Avatar>
									<AvatarImage src={session.user?.image || ''} alt={session.user?.name || ''} />
									<AvatarFallback>{session.user?.name?.[0] || 'U'}</AvatarFallback>
								</Avatar>
								<div>
									<p className="font-medium">{session.user?.name || 'No name set'}</p>
									<p className="text-sm text-muted-foreground">{session.user?.email}</p>
								</div>
							</div>
							<div>
								<p className="text-sm font-medium">User ID: {session.user?.id}</p>
							</div>
							<form action={updateName} className="space-y-2">
								<Label htmlFor="name">Update Name</Label>
								<Input id="name" name="name" placeholder="Enter new name" />
								<Button type="submit" className="w-full">
									Update Name
								</Button>
							</form>
						</div>
					) : (
						<form
							action={async (formData) => {
								'use server';
								await signIn('resend', { email: formData.get('email') as string });
							}}
							className="space-y-4"
						>
							<div className="space-y-2">
								<Input
									type="email"
									name="email"
									placeholder="Email"
									autoCapitalize="none"
									autoComplete="email"
									autoCorrect="off"
									required
								/>
							</div>
							<Button className="w-full" type="submit">
								Sign in with Resend
							</Button>
						</form>
					)}
				</CardContent>
				{session && (
					<CardFooter>
						<form
							action={async () => {
								'use server';
								await signOut();
								Response.redirect('/');
							}}
						>
							<Button type="submit" variant="outline" className="w-full">
								Sign out
							</Button>
						</form>
					</CardFooter>
				)}
			</Card>
		</main>
	);
}
```

## 7. Preview and Deploy

Now, it's time to preview our app. Run the following to preview your application:

<PackageManagers
	type="run"
	args={"preview"}
/>

:::caution[Windows support]
OpenNext has [limited Windows support](https://opennext.js.org/cloudflare#windows-support) and recommends using WSL2 if developing on Windows.

Also, you may need to comment out the `@import "tw-animate-css"` line in the `globals.css` file.
:::

You should see our login form. But wait, we're not done yet. Remember to create your database tables by visiting `/api/setup`. You should see `Migration completed`. This means your database is ready to go.

Navigate back to your application's homepage. Enter your email and sign in (use the same email as your Resend account if you used the `onboarding@resend.dev` address). You should receive an email in your inbox (check spam). Follow the link to sign in. If everything is configured correctly, you should now see a basic user profile letting your update your name and sign out.

Now let's deploy our application to production. From within the project's directory run:

<PackageManagers
	type="run"
	args={"deploy"}
/>

This will build and deploy your application as a Worker. Note that you may need to select which account you want to deploy your Worker to. After your app is deployed, Wrangler should give you the URL on which it was deployed. It might look something like this: `https://auth-js-d1-example.example.workers.dev`. Add your URL to your Worker using:

```sh title="Add URL to secrets"
npx wrangler secret put AUTH_URL
```

After the changes are deployed, you should now be able to access and try out your new application.

:::note[D1 Database Creation]
You will need to hit the `/api/setup` on your deployed URL to create the necessary tables in your D1 database. It will create 4 tables if they don’t already exist: `accounts`, `sessions`, `users`, and `verification_tokens`. If the `api/setup` route is not working, you can also initialize your tables manually. Look in [migrations.ts](https://github.com/nextauthjs/next-auth/blob/main/packages/adapter-d1/src/migrations.ts) of the Auth.js D1 adapter for the relevant SQL.
:::

You have successfully created, configured, and deployed a fullstack Next.js application with authentication powered by Auth.js, Resend, and Cloudflare D1.

## Related resources

To build more with Workers, refer to [Tutorials](/workers/tutorials/).

Find more information about the tools and services used in this tutorial at:

- [Auth.js](https://authjs.dev/getting-started)
- [Resend](https://resend.com/)
- [Cloudflare D1](/d1/)

If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on [Discord](https://discord.cloudflare.com) to connect with other developers and the Cloudflare team.

---

# Send form submissions using Astro and Resend

URL: https://developers.cloudflare.com/developer-spotlight/tutorials/handle-form-submission-with-astro-resend/

This tutorial will instruct you on how to send emails from [Astro](https://astro.build/) and Cloudflare Workers (via Cloudflare SSR Adapter) using [Resend](https://resend.com/).

## Prerequisites

Make sure you have the following set up before proceeding with this tutorial:

- A [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages)
- Installed [npm](https://docs.npmjs.com/getting-started).
- A [Resend account](https://resend.com/signup).

## 1. Create a new Astro project and install Cloudflare Adapter:

Open your terminal and run the below command:

```bash title="Create Astro project"
npm create cloudflare@latest my-astro-app -- --framework=astro
```

Follow the prompts to configure your project, selecting your preferred options for TypeScript usage, TypeScript strictness, version control, and deployment.

After the initial installation change into the newly created project directory `my-astro-app` and run the following to add the Cloudflare adapter:

```bash title="Install Cloudflare Adapter"
npm run astro add cloudflare
```

The [`@astrojs/cloudflare` adapter](https://github.com/withastro/adapters/tree/main/packages/cloudflare#readme) allows Astro's Server-Side Rendered (SSR) sites and components to work on Cloudflare Pages and converts Astro's endpoints into Cloudflare Workers endpoints.

## 2. Add your domain to Resend

:::note

If you do not have a domain and just want to test you can skip to step 4 of this section.

:::

1. **Add Your Domain from Cloudflare to Resend:**
   - After signing up for Resend, navigate to the side menu and click `Domains`.
   - Look for the button to add a new domain and click it.
   - A pop-up will appear where you can type in your domain. Do so, then choose a region and click the `add` button.
   - After clicking the add button Resend will provide you with a list of DNS records (DKIM, SPF, and DMARC).
2. **Copy DNS Records from Resend to Cloudflare:**
   - Go back to your Cloudflare dashboard.
   - Select the domain you want to use and find the "DNS" section.
   - Copy and paste the DNS records from Resend to Cloudflare.
3. **Verify Your Domain:**
   - Return to Resend and click on the "Verify DNS Records" button.
   - If everything is set up correctly, your domain status will change to "Verified."
4. **Create an API Key:**
   - In Resend, find the "API Keys" option in the side menu and click it.
   - Create a new API key with a descriptive name and give Full Access permission.
5. **Save the API key for Local Development and Deployed Worker**
   - For local development, create an .env in the root folder of your Astro project and save the API key as RESEND_API_KEY='Api key here' (no quotes).
   - For a deployed Worker, run the following in your CLI and follow the instructions.

```bash
npx wrangler secret put RESEND_API_KEY
```

## 3. Create an Astro endpoint

In the `src/pages` directory, create a new folder called `api`. Inside the `api` folder, create a new file called `sendEmail.json.ts`. This will create an endpoint at `/api/sendEmail.json`.

Copy the following code into the `sendEmail.json.ts` file. This code sets up a POST route that handles form submissions, and validates the form data.

```ts
export const prerender = false; //This will not work without this line

import type { APIRoute } from "astro";

export const POST: APIRoute = async ({ request }) => {
	const data = await request.formData();
	const name = data.get("name");
	const email = data.get("email");
	const message = data.get("message"); // Validate the data - making sure values are not empty

	if (!name || !email || !message) {
		return new Response(null, {
			status: 404,
			statusText: "Did not provide the right data",
		});
	}
};
```

## 4. Send emails using Resend

Next you will need to install the Resend SDK.

```bash title="Install Resend's SDK"
npm i resend
```

Once the SDK is installed you can add in the rest of the code that sends an email using the Resend's API, and conditionally checks if the Resend response was successful or not.

```ts
export const prerender = false; //This will not work without this line

import type { APIRoute } from "astro";
import { Resend } from "resend";

const resend = new Resend(import.meta.env.RESEND_API_KEY);

export const POST: APIRoute = async ({ request }) => {
	const data = await request.formData();
	const name = data.get("name");
	const email = data.get("email");
	const message = data.get("message"); // Validate the data - making sure values are not empty

	if (!name || !email || !message) {
		return new Response(
			JSON.stringify({
				message: `Fill out all fields.`,
			}),
			{
				status: 404,
				statusText: "Did not provide the right data",
			},
		);
	} // Sending information to Resend

	const sendResend = await resend.emails.send({
		from: "support@resend.dev",
		to: "delivered@resend.dev",
		subject: `Sumbission from ${name}`,
		html: `<p>Hi ${name},</p><p>Your message was received.</p>`,
	}); // If the message was sent successfully, return a 200 response

	if (sendResend.data) {
		return new Response(
			JSON.stringify({
				message: `Message successfully sent!`,
			}),
			{
				status: 200,
				statusText: "OK",
			},
		); // If there was an error sending the message, return a 500 response
	} else {
		return new Response(
			JSON.stringify({
				message: `Message failed to send: ${sendResend.error}`,
			}),
			{
				status: 500,
				statusText: `Internal Server Error: ${sendResend.error}`,
			},
		);
	}
};
```

:::note

Make sure to change the 'to' property in 'resend.emails.send' function, if you set up your own domain in step 2. If you skipped that step, keep the value '[delivered@resend.dev](mailto:delivered@resend.dev)'; otherwise, Resend will throw an error.

:::

## 5. Create an Astro Form Component

In the `src` directory, create a new folder called `components`. Inside the `components` folder, create a new file `AstroForm.astro` and copy the provided code into it.

```typescript
---
export const prerender = false;

type formData = {
  name: string;
  email: string;
  message: string;
};

if (Astro.request.method === "POST") {
  try {
    const formData = await Astro.request.formData();
    const response = await fetch(Astro.url + "/api/sendEmail.json", {
      method: "POST",
      body: formData,
    });

    const data: formData = await response.json();

    if (response.status === 200) {
      console.log(data.message);
    }
  } catch (error) {
    if (error instanceof Error) {
      console.error(`Error: ${error.message}`);
    }
  }
}
---

<form method="POST">
    <label>
        Name
        <input type="text" id="name" name="name" required />
    </label>
    <label>
        Email
        <input type="email" id="email" name="email" required />
    </label>
    <label>
        Message
        <textarea id="message" name="message" required />
    </label>
    <button>Send</button>
</form>

```

This code creates an Astro component that renders a form and handles the form submission. When the form is submitted, the component will send a POST request to the `/api/sendEmail.json` endpoint created in the previous step with the form data.

:::caution[File Extension]

Astro requires an absolute URL, which is why you should use `Astro.url + "/api/sendEmail.json`. If you use a relative path the post request will fail.

:::

Additionally, adding the `export const prerender = false;` will enable SSR; otherwise, the component will be static and unable to send a post request. If you don't enable it inside the component then you will need to enable SSR via the [template directive](https://docs.astro.build/en/reference/directives-reference/).

After creating the `AstroForm` component, add the component to your main index file located in the `src/pages` directory. Below is an example of how the main index file should look with the `AstroForm` component added.

```typescript
---
import AstroForm from '../components/AstroForm.astro'
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width" />
    <meta name="generator" content={Astro.generator} />
    <title>Astro</title>
  </head>
  <body>
    <AstroForm />
  </body>
</html>

```

## 6. Conclusion

You now have an Astro form component that sends emails via Resend and Cloudflare Workers. You can view your project locally via `npm run preview`, or you can deploy it live via `npm run deploy`.

---

# Tutorials

URL: https://developers.cloudflare.com/developer-spotlight/tutorials/

import { ListTutorials } from "~/components";

<ListTutorials />

---

# Alarms

URL: https://developers.cloudflare.com/durable-objects/api/alarms/

import { Type, GlossaryTooltip } from "~/components";

## Background

Durable Objects alarms allow you to schedule the Durable Object to be woken up at a time in the future. When the alarm's scheduled time comes, the `alarm()` handler method will be called. Alarms are modified using the <GlossaryTooltip term="Storage API">Storage API</GlossaryTooltip>, and alarm operations follow the same rules as other storage operations.

Notably:

- Each Durable Object is able to schedule a single alarm at a time by calling `setAlarm()`.
- Alarms have guaranteed at-least-once execution and are retried automatically when the `alarm()` handler throws.
- Retries are performed using exponential backoff starting at a 2 second delay from the first failure with up to 6 retries allowed.

:::note[How are alarms different from Cron Triggers?]

Alarms are more fine grained than [Cron Triggers](/workers/configuration/cron-triggers/). A Worker can have up to three Cron Triggers configured at once, but it can have an unlimited amount of Durable Objects, each of which can have an alarm set.

Alarms are directly scheduled from within your Durable Object. Cron Triggers, on the other hand, are not programmatic. [Cron Triggers](/workers/configuration/cron-triggers/) execute based on their schedules, which have to be configured through the Cloudflare dashboard or API.

:::

Alarms can be used to build distributed primitives, like queues or batching of work atop Durable Objects. Alarms also provide a mechanism to guarantee that operations within a Durable Object will complete without relying on incoming requests to keep the Durable Object alive. For a complete example, refer to [Use the Alarms API](/durable-objects/examples/alarms-api/).

## Storage methods

### `getAlarm`

- <code>getAlarm()</code>: <Type text="number | null" />

  - If there is an alarm set, then return the currently set alarm time as the number of milliseconds elapsed since the UNIX epoch. Otherwise, return `null`.

  - If `getAlarm` is called while an [`alarm`](/durable-objects/api/alarms/#alarm) is already running, it returns `null` unless `setAlarm` has also been called since the alarm handler started running.

### `setAlarm`

- <code>{" "}setAlarm(scheduledTimeMs <Type text="number" />)</code>
  : <Type text="void" />

  - Set the time for the alarm to run. Specify the time as the number of milliseconds elapsed since the UNIX epoch.
  - If you call `setAlarm` when there is already one scheduled, it will override the existing alarm.

:::caution[Calling `setAlarm` inside the constructor]
If you wish to call `setAlarm` inside the constructor of a Durable Object, ensure that you are first checking whether an alarm has already been set.

This is due to the fact that, if the Durable Object wakes up after being inactive, the constructor is invoked before the [`alarm` handler](/durable-objects/api/alarms/#alarm). Therefore, if the constructor calls `setAlarm`, it could interfere with the next alarm which has already been set.
:::

### `deleteAlarm`

- `deleteAlarm()`: <Type text='void' />

  - Unset the alarm if there is a currently set alarm.

  - Calling `deleteAlarm()` inside the `alarm()` handler may prevent retries on a best-effort basis, but is not guaranteed.

## Handler methods

### `alarm`

- <code>alarm(`alarmInfo`<Type text="Object"/>)</code>: <Type text='void' />

  - Called by the system when a scheduled alarm time is reached.

  - The optional parameter `alarmInfo` object has two properties:
    - `retryCount` <Type text="number"/>: The number of times this alarm event has been retried.
    - `isRetry` <Type text="boolean"/>: A boolean value to indicate if the alarm has been retried. This value is `true` if this alarm event is a retry.

  - Only one instance of `alarm()` will ever run at a given time per Durable Object instance.
  - The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at 2 second delays for up to 6 retries. This only applies to the most recent `setAlarm()` call. Retries will be performed if the method fails with an uncaught exception.

  - This method can be `async`.

## Example

This example shows how to both set alarms with the `setAlarm(timestamp)` method and handle alarms with the `alarm()` handler within your Durable Object.

- The `alarm()` handler will be called once every time an alarm fires.
- If an unexpected error terminates the Durable Object, the `alarm()` handler may be re-instantiated on another machine.
- Following a short delay, the `alarm()` handler will run from the beginning on the other machine.

```js
import { DurableObject } from "cloudflare:workers";

export default {
	async fetch(request, env) {
		let id = env.ALARM_EXAMPLE.idFromName("foo");
		return await env.ALARM_EXAMPLE.get(id).fetch(request);
	},
};

const SECONDS = 1000;

export class AlarmExample extends DurableObject {
	constructor(ctx, env) {
		this.ctx = ctx;
		this.storage = ctx.storage;
	}
	async fetch(request) {
		// If there is no alarm currently set, set one for 10 seconds from now
		let currentAlarm = await this.storage.getAlarm();
		if (currentAlarm == null) {
			this.storage.setAlarm(Date.now() + 10 * SECONDS);
		}
	}
	async alarm() {
		// The alarm handler will be invoked whenever an alarm fires.
		// You can use this to do work, read from the Storage API, make HTTP calls
		// and set future alarms to run using this.storage.setAlarm() from within this handler.
	}
}
```

The following example shows how to use the `alarmInfo` property to identify if the alarm event has been attempted before.

```js
class MyDurableObject extends DurableObject {
  async alarm(alarmInfo) {
    if (alarmInfo?.retryCount != 0) {
      console.log("This alarm event has been attempted ${alarmInfo?.retryCount} times before.");
    }
  }
}
```

## Related resources

- Understand how to [use the Alarms API](/durable-objects/examples/alarms-api/) in an end-to-end example.
- Read the [Durable Objects alarms announcement blog post](https://blog.cloudflare.com/durable-objects-alarms/).
- Review the [Storage API](/durable-objects/api/storage-api/) documentation for Durable Objects.

---

# Durable Object Base Class

URL: https://developers.cloudflare.com/durable-objects/api/base/

import { Render, Tabs, TabItem, GlossaryTooltip, Type, MetaInfo, TypeScriptExample } from "~/components";

The `DurableObject` base class is an abstract class which all Durable Objects inherit from. This base class provides a set of optional methods, frequently referred to as handler methods, which can respond to events, for example a webSocketMessage when using the [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api). To provide a concrete example, here is a Durable Object `MyDurableObject` which extends `DurableObject` and implements the fetch handler to return "Hello, World!" to the calling Worker.

<TypeScriptExample>
```ts
export class MyDurableObject extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}

	async fetch(request: Request) {
		return new Response("Hello, World!");
	}
}
```
</TypeScriptExample>

## Methods

### `fetch`

- <code>fetch(<Type text="Request"/>)</code>: <Type text="Response"/> | <Type text="Promise <Response>"/>

  - Takes an HTTP request object and returns an HTTP response object. This method allows the Durable Object to emulate an HTTP server where a Worker with a binding to that object is the client.

  - This method can be `async`.

### `alarm`

- <code>alarm(`alarmInfo`<Type text="Object"/>)</code>: <Type text="Promise <void>"/>

  - Called by the system when a scheduled alarm time is reached.

  - The optional parameter `alarmInfo` object has two properties:
    - `retryCount` <Type text="number"/>: The number of times this alarm event has been retried.
    - `isRetry` <Type text="boolean"/>: A boolean value to indicate if the alarm has been retried. This value is `true` if this alarm event is a retry.

  - The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at two second delays for up to six retries. Retries will be performed if the method fails with an uncaught exception.

  - This method can be `async`.

  - Refer to [`alarm`](/durable-objects/api/alarms/#alarm) for more information.

### `webSocketMessage`

- <code> webSocketMessage(ws <Type text="WebSocket" />, message{" "} <Type text="string | ArrayBuffer" />)</code>: <Type text="void" />

  - Called by the system when an accepted WebSocket receives a message.

  - This method can be `async`.

  - This method is not called for WebSocket control frames. The system will respond to an incoming [WebSocket protocol ping](https://www.rfc-editor.org/rfc/rfc6455#section-5.5.2) automatically without interrupting hibernation.

### `webSocketClose`

- <code> webSocketClose(ws <Type text="WebSocket" />, code <Type text="number" />, reason <Type text="string" />, wasClean <Type text="boolean" />)</code>: <Type text="void" />

  - Called by the system when a WebSocket is closed. `wasClean()` is true if the connection closed cleanly, false otherwise.

  - This method can be `async`.

### `webSocketError`

- <code> webSocketError(ws <Type text="WebSocket" />, error <Type text="any" />)</code> : <Type text="void" />

  - Called by the system when any non-disconnection related errors occur.

  - This method can be `async`.

## Properties

### `DurableObjectState`

See [`DurableObjectState` documentation](/durable-objects/api/state/).

### `Env`

A list of bindings which are available to the Durable Object.

## Related resources

- Refer to [Use WebSockets](/durable-objects/best-practices/websockets/) for more information on examples of WebSocket methods and best practices.

---

# Durable Object Container

URL: https://developers.cloudflare.com/durable-objects/api/container/

import {
	Render,
	Tabs,
	TabItem,
	GlossaryTooltip,
	Type,
	MetaInfo,
	TypeScriptExample,
} from "~/components";

## Description

When using a [Container-enabled Durable Object](/containers), you can access the Durable Object's associated container via
the `container` object which is on the `ctx` property. This allows you to start, stop, and interact with the container.

:::note
It is likely preferable to use the official `Container` class, which provides helper methods and
a more idiomatic API for working with containers on top of Durable Objects.
:::

<TypeScriptExample filename="index.ts">
```ts
export class MyDurableObject extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);

    	// boot the container when starting the DO
    	this.ctx.blockConcurrencyWhile(async () => {
    		this.ctx.container.start();
    });
    }

}

````
</TypeScriptExample>


## Attributes

### `running`

`running` returns `true` if the container is currently running. It does not ensure that the container has fully started and ready to accept requests.

```js
	this.ctx.container.running;
````

## Methods

### `start`

`start` boots a container. This method does not block until the container is fully started.
You may want to confirm the container is ready to accept requests before using it.

```js
this.ctx.container.start({
	env: {
		FOO: "bar",
	},
	enableInternet: false,
	entrypoint: ["node", "server.js"],
});
```

#### Parameters

- `options` (optional): An object with the following properties:
  - `env`: An object containing environment variables to pass to the container. This is useful for passing configuration values or secrets to the container.
  - `entrypoint`: An array of strings representing the command to run in the container.
  - `enableInternet`: A boolean indicating whether to enable internet access for the container.

#### Return values

- None.

### `destroy`

`destroy` stops the container and optionally returns a custom error message to the `monitor()` error callback.

```js
this.ctx.container.destroy("Manually Destroyed");
```

#### Parameters

- `error` (optional): A string that will be sent to the error handler of the `monitor` method. This is useful for logging or debugging purposes.

#### Return values

- A promise that returns once the container is destroyed.

### `signal`

`signal` sends an IPC signal to the container, such as SIGKILL or SIGTERM. This is useful for stopping the container gracefully or forcefully.

```js
const SIGTERM = 15;
this.ctx.container.signal(SIGTERM);
```

#### Parameters

- `signal`: a number representing the signal to send to the container. This is typically a POSIX signal number, such as SIGTERM (15) or SIGKILL (9).

#### Return values

- None.

### `getTcpPort`

`getTcpPort` returns a TCP port from the container. This can be used to communicate with the container over TCP and HTTP.

```js
const port = this.ctx.container.getTcpPort(8080);
const res = await port.fetch("http://container/set-state", {
	body: initialState,
	method: "POST",
});
```

#### Parameters

- `port` (number): a TCP port number to use for communication with the container.

#### Return values

- `TcpPort`: a `TcpPort` object representing the TCP port. This object can be used to send requests to the container over TCP and HTTP.

### `monitor`

`monitor` returns a promise that resolves when a container exits and errors if a container errors. This is useful for setting up
callbacks to handle container status changes in your Workers code.

```js
class MyContainer extends DurableObject {
	constructor(ctx, env) {
		super(ctx, env);
		function onContainerExit() {
			console.log("Container exited");
		}

		// the "err" value can be customized by the destroy() method
		async function onContainerError(err) {
			console.log("Container errored", err);
		}

		this.ctx.container.start();
		this.ctx.container.monitor().then(onContainerExit).catch(onContainerError);
	}
}
```

#### Parameters

- None

#### Return values

- A promise that resolves when the container exits.

## Related resources

- [Containers](/containers)
- [Get Started With Containers](/containers/get-started)

---

# Durable Object ID

URL: https://developers.cloudflare.com/durable-objects/api/id/

import { Render, Tabs, TabItem, GlossaryTooltip } from "~/components";

## Description

A Durable Object ID is a 64-digit hexadecimal number used to identify a <GlossaryTooltip term="Durable Object">Durable Object</GlossaryTooltip>. Not all 64-digit hex numbers are valid IDs. Durable Object IDs are constructed indirectly via the [`DurableObjectNamespace`](/durable-objects/api/namespace) interface.

The `DurableObjectId` interface refers to a new or existing Durable Object. This interface is most frequently used by [`DurableObjectNamespace::get`](/durable-objects/api/namespace/#get) to obtain a [`DurableObjectStub`](/durable-objects/api/stub) for submitting requests to a Durable Object. Note that creating an ID for a Durable Object does not create the Durable Object. The Durable Object is created lazily after creating a stub from a `DurableObjectId`. This ensures that objects are not constructed until they are actually accessed.

:::note[Logging]

If you are experiencing an issue with a particular Durable Object, you may wish to log the `DurableObjectId` from your Worker and include it in your Cloudflare support request.

:::

## Methods

### `toString`

`toString` converts a `DurableObjectId` to a 64 digit hex string. This string is useful for logging purposes or storing the `DurableObjectId` elsewhere, for example, in a session cookie. This string can be used to reconstruct a `DurableObjectId` via `DurableObjectNamespace::idFromString`.

<Render file="example-id-from-string" />

#### Parameters

- None.

#### Return values

- A 64 digit hex string.

### `equals`

`equals` is used to compare equality between two instances of `DurableObjectId`.

```js
const id1 = env.MY_DURABLE_OBJECT.newUniqueId();
const id2 = env.MY_DURABLE_OBJECT.newUniqueId();
console.assert(!id1.equals(id2), "Different unique ids should never be equal.");
```

#### Parameters

- A required `DurableObjectId` to compare against.

#### Return values

- A boolean. True if equal and false otherwise.

## Properties

### `name`

`name` is an optional property of a `DurableObjectId`, which returns the name that was used to create the `DurableObjectId` via [`DurableObjectNamespace::idFromName`](/durable-objects/api/namespace/#idfromname). This value is undefined if the `DurableObjectId` was constructed using [`DurableObjectNamespace::newUniqueId`](/durable-objects/api/namespace/#newuniqueid).

```js
const uniqueId = env.MY_DURABLE_OBJECT.newUniqueId();
const fromNameId = env.MY_DURABLE_OBJECT.idFromName("foo");
console.assert(uniqueId.name === undefined, "unique ids have no name");
console.assert(
	fromNameId.name === "foo",
	"name matches parameter to idFromName",
);
```

## Related resources

- [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/).

---

# Workers Binding API

URL: https://developers.cloudflare.com/durable-objects/api/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Durable Object Namespace

URL: https://developers.cloudflare.com/durable-objects/api/namespace/

import { Render, Tabs, TabItem, GlossaryTooltip } from "~/components";

## Description

A Durable Object namespace is a set of Durable Objects that are backed by the same <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>. There is only one Durable Object namespace per class. A Durable Object namespace can contain any number of Durable Objects.

The `DurableObjectNamespace` interface is used to obtain a reference to new or existing Durable Objects. The interface is accessible from the fetch handler on a Cloudflare Worker via the `env` parameter, which is the standard interface when referencing bindings declared in the [Wrangler configuration file](/workers/wrangler/configuration/).

This interface defines several [methods](/durable-objects/api/namespace/#methods) that can be used to create an ID for a Durable Object. Note that creating an ID for a Durable Object does not create the Durable Object. The Durable Object is created lazily after calling [`DurableObjectNamespace::get`](/durable-objects/api/namespace/#get) to create a [`DurableObjectStub`](/durable-objects/api/stub) from a `DurableObjectId`. This ensures that objects are not constructed until they are actually accessed.

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Durable Object
export class MyDurableObject extends DurableObject {
  ...
}

// Worker
export default {
  async fetch(request, env) {
    // Every unique ID refers to an individual instance of the Durable Object class
    const id = env.MY_DURABLE_OBJECT.idFromName("foo");

    // A stub is a client Object used to invoke methods defined by the Durable Object
    const stub = env.MY_DURABLE_OBJECT.get(id);
    ...
  }
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
  MY_DURABLE_OBJECT: DurableObjectNamespace<MyDurableObject>;
}

// Durable Object
export class MyDurableObject extends DurableObject {
  ...
}

// Worker
export default {
  async fetch(request, env) {
    // Every unique ID refers to an individual instance of the Durable Object class
    const id = env.MY_DURABLE_OBJECT.idFromName("foo");

    // A stub is a client Object used to invoke methods defined by the Durable Object
    const stub = env.MY_DURABLE_OBJECT.get(id);
    ...
  }
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

## Methods

### `idFromName`

`idFromName` creates a unique [`DurableObjectId`](/durable-objects/api/id) which refers to an individual instance of the Durable Object class. Named Durable Objects are the most common method of referring to Durable Objects.

```js
const fooId = env.MY_DURABLE_OBJECT.idFromName("foo");
const barId = env.MY_DURABLE_OBJECT.idFromName("bar");
```

#### Parameters

- A required string to be used to generate a [`DurableObjectId`](/durable-objects/api/id) corresponding to the name of a Durable Object.

#### Return values

- A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of a Durable Object class.

### `newUniqueId`

`newUniqueId` creates a randomly generated and unique [`DurableObjectId`](/durable-objects/api/id) which refers to an individual instance of the Durable Object class. IDs created using `newUniqueId`, will need to be stored as a string in order to refer to the same Durable Object again in the future. For example, the ID can be stored in Workers KV, another Durable Object, or in a cookie in the user's browser.

```js
const id = env.MY_DURABLE_OBJECT.newUniqueId();
const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" });
```

:::note[`newUniqueId` results in lower request latency at first use]

The first time you get a Durable Object stub based on an ID derived from a name, the system has to take into account the possibility that a Worker on the opposite side of the world could have coincidentally accessed the same named Durable Object at the same time. To guarantee that only one instance of the Durable Object is created, the system must check that the Durable Object has not been created anywhere else. Due to the inherent limit of the speed of light, this round-the-world check can take up to a few hundred milliseconds. `newUniqueId` can skip this check.

After this first use, the location of the Durable Object will be cached around the world so that subsequent lookups are faster.

:::

#### Parameters

- An optional object with the key `jurisdiction` and value of a [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string.

#### Return values

- A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of the Durable Object class.

### `idFromString`

`idFromString` creates a [`DurableObjectId`](/durable-objects/api/id) from a previously generated ID that has been converted to a string. This method throws an exception if the ID is invalid, for example, if the ID was not created from the same `DurableObjectNamespace`.

<Render file="example-id-from-string" />

#### Parameters

- A required string corresponding to a [`DurableObjectId`](/durable-objects/api/id) previously generated either by `newUniqueId` or `idFromName`.

#### Return values

- A [`DurableObjectId`](/durable-objects/api/id) referring to an instance of a Durable Object class.

### `get`

`get` obtains a [`DurableObjectStub`](/durable-objects/api/stub) from a [`DurableObjectId`](/durable-objects/api/id) which can be used to invoke methods on a Durable Object.

This method returns the <GlossaryTooltip term="stub">stub</GlossaryTooltip> immediately, often before a connection has been established to the Durable Object. This allows requests to be sent to the instance right away, without waiting for a network round trip.

```js
const id = env.MY_DURABLE_OBJECT.newUniqueId();
const stub = env.MY_DURABLE_OBJECT.get(id);
```

#### Parameters

- A required [`DurableObjectId`](/durable-objects/api/id)
- An optional object with the key `locationHint` and value of a [locationHint](/durable-objects/reference/data-location/#provide-a-location-hint) string.

#### Return values

- A [`DurableObjectStub`](/durable-objects/api/stub) referring to an instance of a Durable Object class.

### `jurisdiction`

`jurisdiction` creates a subnamespace from a namespace where all Durable Object IDs and references created from that subnamespace will be restricted to the specified [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction).

```js
const subnamespace = env.MY_DURABLE_OBJECT.jurisdiction("foo");
const euId = subnamespace.idFromName("foo");
```

#### Parameters

- A required [jurisdiction](/durable-objects/reference/data-location/#restrict-durable-objects-to-a-jurisdiction) string.

#### Return values

- A `DurableObjectNamespace` scoped to a particular geographic jurisdiction.

## Related resources

- [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/).

---

# Durable Object State

URL: https://developers.cloudflare.com/durable-objects/api/state/

import { Tabs, TabItem, GlossaryTooltip, Type, MetaInfo } from "~/components";

## Description

The `DurableObjectState` interface is accessible as an instance property on the <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>. This interface encapsulates methods that modify the state of a Durable Object, for example which WebSockets are attached to a Durable Object or how the runtime should handle concurrent Durable Object requests.

The `DurableObjectState` interface is different from the <GlossaryTooltip term="Storage API">Storage API</GlossaryTooltip> in that it does not have top-level methods which manipulate persistent application data. These methods are instead encapsulated in the [`DurableObjectStorage`](/durable-objects/api/storage-api) interface and accessed by [`DurableObjectState::storage`](/durable-objects/api/state/#storage).

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Durable Object
export class MyDurableObject extends DurableObject {
  // DurableObjectState is accessible via the ctx instance property
	constructor(ctx, env) {
		super(ctx, env);
	}
  ...
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
  MY_DURABLE_OBJECT: DurableObjectNamespace<MyDurableObject>;
}

// Durable Object
export class MyDurableObject extends DurableObject {
  // DurableObjectState is accessible via the ctx instance property
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}
  ...
}
```

</TabItem> </Tabs>

## Methods

### `waitUntil`

`waitUntil` waits until the promise which is passed as a parameter resolves and can extend a <GlossaryTooltip term= "request context">request context</GlossaryTooltip> up to 30 seconds after the last client disconnects.

:::note[`waitUntil` is not necessary]

The request context for a Durable Objects extends at least 60 seconds after the last client disconnects. So `waitUntil` is not necessary. It remains part of the `DurableObjectState` interface to remain compatible with [Workers Runtime APIs](/workers/runtime-apis/context/#waituntil).

:::

#### Parameters

- A required promise of any type.

#### Return values

- None.

### `blockConcurrencyWhile`

`blockConcurrencyWhile` executes an async callback while blocking any other events from being delivered to the Durable Object until the callback completes. This method guarantees ordering and prevents concurrent requests. All events that were not explicitly initiated as part of the callback itself will be blocked. Once the callback completes, all other events will be delivered.

* `blockConcurrencyWhile` is commonly used within the constructor of the Durable Object class to enforce initialization to occur before any requests are delivered.
* Another use case is executing `async` operations based on the current state of the Durable Object and using `blockConcurrencyWhile` to prevent that state from changing while yielding the event loop.
* If the callback throws an exception, the object will be terminated and reset. This ensures that the object cannot be left stuck in an uninitialized state if something fails unexpectedly.
* To avoid this behavior, enclose the body of your callback in a `try...catch` block to ensure it cannot throw an exception.

To help mitigate deadlocks there is a 30 second timeout applied when executing the callback. If this timeout is exceeded, the Durable Object will be reset. It is best practice to have the callback do as little work as possible to improve overall request throughput to the Durable Object.

:::note

You should only need `blockConcurrencyWhile` if you are making additional, asynchronous calls (such as to another API or service), and cannot tolerate other requests processed by the Durable Object changing its internal while the event loop is yielded from the original request.

In practice, this is quite rare, and most use cases do not need `blockConcurrencyWhile`.

:::

```js
// Durable Object
export class MyDurableObject extends DurableObject {
	initialized = false;

	constructor(ctx, env) {
		super(ctx, env);

		// blockConcurrencyWhile will ensure that initialized will always be true
		this.ctx.blockConcurrencyWhile(async () => {
			this.initialized = true;
		});
	}
  ...
}
```

#### Parameters

- A required callback which returns a `Promise<T>`.

#### Return values

- A `Promise<T>` returned by the callback.

### `acceptWebSocket`

`acceptWebSocket` is part of the [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api), which allows a Durable Object to be removed from memory to save costs while keeping its WebSockets connected.

`acceptWebSocket` adds a WebSocket to the set of WebSockets attached to the Durable Object. Once called, any incoming messages will be delivered by calling the Durable Object's `webSocketMessage` handler, and `webSocketClose` will be invoked upon disconnect. After calling `acceptWebSocket`, the WebSocket is accepted and its `send` and `close` methods can be used.

The [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api) takes the place of the standard [WebSockets API](/workers/runtime-apis/websockets/). Therefore, `ws.accept` must not have been called separately and `ws.addEventListener` method will not receive events as they will instead be delivered to the Durable Object.

The WebSocket Hibernation API permits a maximum of 32,768 WebSocket connections per Durable Object, but the CPU and memory usage of a given workload may further limit the practical number of simultaneous connections.

#### Parameters

- A required `WebSocket` with name `ws`.
- An optional `Array<string>` of associated tags. Tags can be used to retrieve WebSockets via [`DurableObjectState::getWebSockets`](/durable-objects/api/state/#getwebsockets). Each tag is a maximum of 256 characters and there can be at most 10 tags associated with a WebSocket.

#### Return values

- None.

### `getWebSockets`

`getWebSockets` is part of the [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api), which allows a Durable Object to be removed from memory to save costs while keeping its WebSockets connected.

`getWebSockets` returns an `Array<WebSocket>` which is the set of WebSockets attached to the Durable Object. An optional tag argument can be used to filter the list according to tags supplied when calling [`DurableObjectState::acceptWebSocket`](/durable-objects/api/state/#acceptwebsocket).

:::note[`waitUntil` is not necessary]

Disconnected WebSockets are not returned by this method, but `getWebSockets` may still return WebSockets even after `ws.close` has been called. For example, if the server-side WebSocket sends a close, but does not receive one back (and has not detected a disconnect from the client), then the connection is in the CLOSING 'readyState'. The client might send more messages, so the WebSocket is technically not disconnected.

:::

#### Parameters

- An optional tag of type `string`.

#### Return values

- An `Array<WebSocket>`.

### `setWebSocketAutoResponse`

`setWebSocketAutoResponse` is part of the [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api), which allows a Durable Object to be removed from memory to save costs while keeping its WebSockets connected.

`setWebSocketAutoResponse` sets an automatic response, auto-response, for the request provided for all WebSockets attached to the Durable Object. If a request is received matching the provided request then the auto-response will be returned without waking WebSockets in hibernation and incurring billable duration charges.

`setWebSocketAutoResponse` is a common alternative to setting up a server for static ping/pong messages because this can be handled without waking hibernating WebSockets.

#### Parameters

- An optional `WebSocketRequestResponsePair(request string, response string)` enabling any WebSocket accepted via [`DurableObjectState::acceptWebSocket`](/durable-objects/api/state/#acceptwebsocket) to automatically reply to the provided response when it receives the provided request. Both request and response are limited to 2,048 characters each. If the parameter is omitted, any previously set auto-response configuration will be removed. [`DurableObjectState::getWebSocketAutoResponseTimestamp`](/durable-objects/api/state/#getwebsocketautoresponsetimestamp) will still reflect the last timestamp that an auto-response was sent.

#### Return values

- None.

### `getWebSocketAutoResponse`

`getWebSocketAutoResponse` returns the `WebSocketRequestResponsePair` object last set by [`DurableObjectState::setWebSocketAutoResponse`](/durable-objects/api/state/#setwebsocketautoresponse), or null if not auto-response has been set.

:::note[inspect `WebSocketRequestResponsePair`]

`WebSocketRequestResponsePair` can be inspected further by calling `getRequest` and `getResponse` methods.

:::

#### Parameters

- None.

#### Return values

- A `WebSocketRequestResponsePair` or null.

### `getWebSocketAutoResponseTimestamp`

`getWebSocketAutoResponseTimestamp` is part of the [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api), which allows a Durable Object to be removed from memory to save costs while keeping its WebSockets connected.

`getWebSocketAutoResponseTimestamp` gets the most recent `Date` on which the given WebSocket sent an auto-response, or null if the given WebSocket never sent an auto-response.

#### Parameters

- A required `WebSocket`.

#### Return values

- A `Date` or null.

### `setHibernatableWebSocketEventTimeout`

`setHibernatableWebSocketEventTimeout` is part of the [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api), which allows a Durable Object to be removed from memory to save costs while keeping its WebSockets connected.

`setHibernatableWebSocketEventTimeout` sets the maximum amount of time in milliseconds that a WebSocket event can run for.

If no parameter or a parameter of `0` is provided and a timeout has been previously set, then the timeout will be unset. The maximum value of timeout is 604,800,000 ms (7 days).

#### Parameters

- An optional `number`.

#### Return values

- None.

### `getHibernatableWebSocketEventTimeout`

`getHibernatableWebSocketEventTimeout` is part of the [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api), which allows a Durable Object to be removed from memory to save costs while keeping its WebSockets connected.

`getHibernatableWebSocketEventTimeout` gets the currently set hibernatable WebSocket event timeout if one has been set via [`DurableObjectState::setHibernatableWebSocketEventTimeout`](/durable-objects/api/state/#sethibernatablewebsocketeventtimeout).

#### Parameters

- None.

#### Return values

- A number, or null if the timeout has not been set.

### `getTags`

`getTags` is part of the [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api), which allows a Durable Object to be removed from memory to save costs while keeping its WebSockets connected.

`getTags` returns tags associated with a given WebSocket. This method throws an exception if the WebSocket has not been associated with the Durable Object via [`DurableObjectState::acceptWebSocket`](/durable-objects/api/state/#acceptwebsocket).

#### Parameters

- A required `WebSocket`.

#### Return values

- An `Array<string>` of tags.

### `abort`

`abort` is used to forcibly reset a Durable Object. A JavaScript `Error` with the message passed as a parameter will be logged. This error is not able to be caught within the application code.

```js
// Durable Object
export class MyDurableObject extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}

  async sayHello() {
    // Error: Hello, World! will be logged
    this.ctx.abort("Hello, World!");
  }
}
```

:::caution[Not available in local development]

`abort` is not available in local development with the `wrangler dev` CLI command.

:::

#### Parameters

- An optional `string` .

#### Return values

- None.

## Properties

### `id`

`id` is a readonly property of type `DurableObjectId` corresponding to the [`DurableObjectId`](/durable-objects/api/id) of the Durable Object.

### `storage`

`storage` is a readonly property of type `DurableObjectStorage` encapsulating the [Storage API](/durable-objects/api/storage-api).

## Related resources

- [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/).

---

# Durable Object Storage

URL: https://developers.cloudflare.com/durable-objects/api/storage-api/

import {
	Render,
	Type,
	MetaInfo,
	GlossaryTooltip,
	TypeScriptExample,
  Details,
} from "~/components";

The Durable Object Storage API allows <GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> to access transactional and strongly consistent storage. A Durable Object's attached storage is private to its unique instance and cannot be accessed by other objects.

The Durable Object Storage API comes with several methods, including SQL, point-in-time recovery (PITR), key-value (KV), and alarm APIs. Available API methods depend on the storage backend for a Durable Objects class, either [SQLite](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class) or [KV](/durable-objects/reference/durable-objects-migrations/#create-durable-object-class-with-key-value-storage).

| Methods <sup>1</sup> | SQLite-backed Durable Object class | KV-backed Durable Object class |
| ----------------------- | ---------------------------- | ------------------------ |
| SQL API                 | ✅                           | ❌                       |
| PITR API                | ✅                           | ❌                       |
| KV API                  | ✅ <sup>2, 3</sup>           | ✅                       |
| Alarms API              | ✅                           | ✅                       |

<Details header="Footnotes" open={true}>

<sup>1</sup> Each method is implicitly wrapped inside a transaction, such that its results are atomic and isolated from all other storage operations, even when accessing multiple key-value pairs.

<sup>2</sup> KV API methods like `get()`, `put()`, `delete()`, or `list()` store data in a hidden SQLite table.

<sup>3</sup> KV methods which were previously asynchronous with KV storage (for example, [`get`](/durable-objects/api/storage-api/#get), [`put`](/durable-objects/api/storage-api/#put), [`delete`](/durable-objects/api/storage-api/#delete), [`deleteAll`](/durable-objects/api/storage-api/#deleteall), [`list`](/durable-objects/api/storage-api/#list)) are synchronous, even though they return promises. These methods will have completed their operations before they return the promise.

</Details>

<Render file="recommend-sqlite-do" product="durable-objects"/>

<Render file="do-sqlite-storage-no-bill-note"/>

## Access storage

Durable Objects gain access to Storage API via the `DurableObjectStorage` interface and accessed by the `DurableObjectState::storage` property. This is frequently accessed via `this.ctx.storage` with the `ctx` parameter passed to the Durable Object constructor.

The following code snippet shows you how to store and retrieve data using the Durable Object Storage API.

<TypeScriptExample>
```ts
export class Counter extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}

    async increment(): Promise<number> {
    	let value: number = (await this.ctx.storage.get('value')) || 0;
    	value += 1;
    	await this.ctx.storage.put('value', value);
    	return value;
    }

}
```
</TypeScriptExample>

JavaScript is a single-threaded and event-driven programming language. This means that JavaScript runtimes, by default, allow requests to interleave with each other which can lead to concurrency bugs. The Durable Objects runtime uses a combination of <GlossaryTooltip term="input gate">input gates</GlossaryTooltip> and <GlossaryTooltip term="output gate">output gates</GlossaryTooltip> to avoid this type of concurrency bug when performing storage operations. Learn more in our [blog post](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/).

## SQL API

The `SqlStorage` interface encapsulates methods that modify the SQLite database embedded within a Durable Object. The `SqlStorage` interface is accessible via the [`sql` property](/durable-objects/api/storage-api/#sql) of `DurableObjectStorage` class.

For example, using `sql.exec()`, a user can create a table, then insert rows into the table.

```ts
import { DurableObject } from "cloudflare:workers";

export class MyDurableObject extends DurableObject {
  sql: SqlStorage;
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.sql = ctx.storage.sql;

    this.sql.exec(`CREATE TABLE IF NOT EXISTS artist(
      artistid    INTEGER PRIMARY KEY,
      artistname  TEXT
    );INSERT INTO artist (artistid, artistname) VALUES
      (123, 'Alice'),
      (456, 'Bob'),
      (789, 'Charlie');`
    );
  }
}
```

* SQL API methods accessed with `ctx.storage.sql` are only allowed on [Durable Object classes with SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class) and will return an error if called on Durable Object classes with a key-value storage backend.
* When writing data, every index counts as an additional row. However, indexes may be beneficial for read-heavy use cases. Refer to [Index for SQLite Durable Objects](/durable-objects/best-practices/access-durable-objects-storage/#index-for-sqlite-durable-objects).
* Writing data to [SQLite virtual tables](https://www.sqlite.org/vtab.html) also counts towards rows written.

### `exec`

<code>exec(query: <Type text='string'/>, ...bindings: <Type text='any[]'/>)</code>: <Type text='SqlStorageCursor' />

#### Parameters

* `query`: <Type text ='string' />
  * The SQL query string to be executed. `query` can contain `?` placeholders for parameter bindings. Multiple SQL statements, separated with a semicolon, can be executed in the `query`. With multiple SQL statements, any parameter bindings are applied to the last SQL statement in the `query`, and the returned cursor is only for the last SQL statement.
* `...bindings`: <Type text='any[]' /> <MetaInfo text='Optional' />
  * Optional variable number of arguments that correspond to the `?` placeholders in `query`.

#### Returns

A cursor (`SqlStorageCursor`) to iterate over query row results as objects. `SqlStorageCursor` is a JavaScript [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), which supports iteration using `for (let row of cursor)`. `SqlStorageCursor` is also a JavaScript [Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol), which supports iteration using `cursor.next()`.

`SqlStorageCursor` supports the following methods:

* `next()`
  * Returns an object representing the next value of the cursor. The returned object has `done` and `value` properties adhering to the JavaScript [Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol). `done` is set to `false` when a next value is present, and `value` is set to the next row object in the query result. `done` is set to `true` when the entire cursor is consumed, and no `value` is set.
* `toArray()`
  * Iterates through remaining cursor value(s) and returns an array of returned row objects.
* `one()`
  * Returns a row object if query result has exactly one row. If query result has zero rows or more than one row, `one()` throws an exception.
* `raw()`: <Type text='Iterator' />
  * Returns an Iterator over the same query results, with each row as an array of column values (with no column names) rather than an object.
  * Returned Iterator supports `next()` and `toArray()` methods above.
  * Returned cursor and `raw()` iterator iterate over the same query results and can be combined. For example:

```ts
let cursor = this.sql.exec("SELECT * FROM artist ORDER BY artistname ASC;");
let rawResult = cursor.raw().next();

if (!rawResult.done) {
  console.log(rawResult.value); // prints [ 123, 'Alice' ]
} else {
  // query returned zero results
}

console.log(cursor.toArray()); // prints [{ artistid: 456, artistname: 'Bob' },{ artistid: 789, artistname: 'Charlie' }]
```

`SqlStorageCursor` has the following properties:

- `columnNames`: <Type text='string[]' />
  - The column names of the query in the order they appear in each row array returned by the `raw` iterator.
- `rowsRead`: <Type text='number' />
  - The number of rows read so far as part of this SQL `query`. This may increase as you iterate the cursor. The final value is used for [SQL billing](/durable-objects/platform/pricing/#sqlite-storage-backend).
- `rowsWritten`: <Type text='number' />
  - The number of rows written so far as part of this SQL `query`. This may increase as you iterate the cursor. The final value is used for [SQL billing](/durable-objects/platform/pricing/#sqlite-storage-backend).
- Any numeric value in a column is affected by JavaScript's 52-bit precision for numbers. If you store a very large number (in `int64`), then retrieve the same value, the returned value may be less precise than your original number.

:::note[SQL transactions]
Note that `sql.exec()` cannot execute transaction-related statements like `BEGIN TRANSACTION` or `SAVEPOINT`. Instead, use the [`ctx.storage.transaction()`](/durable-objects/api/storage-api/#transaction) or [`ctx.storage.transactionSync()`](/durable-objects/api/storage-api/#transactionsync) APIs to start a transaction, and then execute SQL queries in your callback.
:::

#### Examples

<Render file="durable-objects-sql" />

### `databaseSize`

`databaseSize`: <Type text ='number' />

#### Returns

The current SQLite database size in bytes.

```ts
let size = ctx.storage.sql.databaseSize;
```

## PITR (Point In Time Recovery) API

For [SQLite-backed Durable Objects](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class), the following point-in-time-recovery (PITR) API methods are available to restore a Durable Object's embedded SQLite database to any point in time in the past 30 days. These methods apply to the entire SQLite database contents, including both the object's stored SQL data and stored key-value data using the key-value `put()` API. The PITR API is not supported in local development because a durable log of data changes is not stored locally.

The PITR API represents points in time using 'bookmarks'. A bookmark is a mostly alphanumeric string like `0000007b-0000b26e-00001538-0c3e87bb37b3db5cc52eedb93cd3b96b`. Bookmarks are designed to be lexically comparable: a bookmark representing an earlier point in time compares less than one representing a later point, using regular string comparison.

### `getCurrentBookmark`

<code>ctx.storage.getCurrentBookmark()</code>: <Type text='Promise<string>' />

* Returns a bookmark representing the current point in time in the object's history.

### `getBookmarkForTime`

<code>ctx.storage.getBookmarkForTime(timestamp: <Type text='number | Date'/>)</code>: <Type text='Promise<string>' />

* Returns a bookmark representing approximately the given point in time, which must be within the last 30 days. If the timestamp is represented as a number, it is converted to a date as if using `new Date(timestamp)`.

### `onNextSessionRestoreBookmark`

<code>ctx.storage.onNextSessionRestoreBookmark(bookmark: <Type text='string'/>)</code>: <Type text='Promise<string>' />

  * Configures the Durable Object so that the next time it restarts, it should restore its storage to exactly match what the storage contained at the given bookmark. After calling this, the application should typically invoke `ctx.abort()` to restart the Durable Object, thus completing the point-in-time recovery.

This method returns a special bookmark representing the point in time immediately before the recovery takes place (even though that point in time is still technically in the future). Thus, after the recovery completes, it can be undone by performing a second recovery to this bookmark.


```ts
let now = new Date();
// restore to 2 days ago
let bookmark = ctx.storage.getBookmarkForTime(now - 2);
ctx.storage.onNextSessionRestoreBookmark(bookmark);
```

## KV API

### `get`

- <code>get(key <Type text="string" />, options <Type text="Object" />{" "}<MetaInfo text="optional" />)</code>: <Type text="Promise<any>" />

  - Retrieves the value associated with the given key. The type of the returned value will be whatever was previously written for the key, or undefined if the key does not exist.

- <code>get(keys <Type text="Array<string>" />, options <Type text="Object" />{" "}<MetaInfo text="optional" />)</code>: <Type text="Promise<Map<string, any>>" />

  - Retrieves the values associated with each of the provided keys. The type of each returned value in the [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) will be whatever was previously written for the corresponding key. Results in the `Map` will be sorted in increasing order of their UTF-8 encodings, with any requested keys that do not exist being omitted. Supports up to 128 keys at a time.

#### Supported options

- `allowConcurrency`: <Type text='boolean' />

  - By default, the system will pause delivery of I/O events to the Object while a storage operation is in progress, in order to avoid unexpected race conditions. Pass `allowConcurrency: true` to opt out of this behavior and allow concurrent events to be delivered.

- `noCache`: <Type text='boolean'/>

  - If true, then the key/value will not be inserted into the in-memory cache. If the key is already in the cache, the cached value will be returned, but its last-used time will not be updated. Use this when you expect this key will not be used again in the near future. This flag is only a hint. This flag will never change the semantics of your code, but it may affect performance.

### `put`

- <code>put(key <Type text="string" />, value <Type text="any" />, options{" "}<Type text="Object" /> <MetaInfo text="optional" />)</code>: <Type text="Promise" />

  - Stores the value and associates it with the given key. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types.

    The size of keys and values have different limits depending on the Durable Object storage backend you are using. Refer to either:
    - [SQLite-backed Durable Object limits](/durable-objects/platform/limits/#sqlite-backed-durable-objects-general-limits)
    - [KV-backed Durable Object limits](/durable-objects/platform/limits/#key-value-backed-durable-objects-general-limits).<br/><br/>

- <code>put(entries <Type text="Object" />, options <Type text="Object" />{" "}<MetaInfo text="optional" />)</code>: <Type text="Promise" />

  - Takes an Object and stores each of its keys and values to storage.
  - Each value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types.
  - Supports up to 128 key-value pairs at a time. The size of keys and values have different limits depending on the flavor of Durable Object you are using. Refer to either:
     - [SQLite-backed Durable Object limits](/durable-objects/platform/limits/#sqlite-backed-durable-objects-general-limits)
     - [KV-backed Durable Object limits](/durable-objects/platform/limits/#key-value-backed-durable-objects-general-limits)

### `delete`

- <code>delete(key <Type text="string" />, options <Type text="Object" />{" "}<MetaInfo text="optional" />)</code>: <Type text="Promise<boolean>" />

  - Deletes the key and associated value. Returns `true` if the key existed or `false` if it did not.

- <code>delete(keys <Type text="Array<string>" />, options <Type text="Object" />{" "}<MetaInfo text="optional" />)</code>: <Type text="Promise<number>" />

  - Deletes the provided keys and their associated values. Supports up to 128 keys at a time. Returns a count of the number of key-value pairs deleted.

#### Supported options

- `put()`, `delete()` and `deleteAll()` support the following options:

- `allowUnconfirmed` <Type text ='boolean' />

  - By default, the system will pause outgoing network messages from the Durable Object until all previous writes have been confirmed flushed to disk. If the write fails, the system will reset the Object, discard all outgoing messages, and respond to any clients with errors instead.

  - This way, Durable Objects can continue executing in parallel with a write operation, without having to worry about prematurely confirming writes, because it is impossible for any external party to observe the Object's actions unless the write actually succeeds.

  - After any write, subsequent network messages may be slightly delayed. Some applications may consider it acceptable to communicate on the basis of unconfirmed writes. Some programs may prefer to allow network traffic immediately. In this case, set `allowUnconfirmed` to `true` to opt out of the default behavior.

  - If you want to allow some outgoing network messages to proceed immediately but not others, you can use the allowUnconfirmed option to avoid blocking the messages that you want to proceed and then separately call the [`sync()`](/durable-objects/api/storage-api/#sync) method, which returns a promise that only resolves once all previous writes have successfully been persisted to disk.

- `noCache` <Type text ='boolean' />

  - If true, then the key/value will be discarded from memory as soon as it has completed writing to disk.

  - Use `noCache` if the key will not be used again in the near future. `noCache` will never change the semantics of your code, but it may affect performance.

  - If you use `get()` to retrieve the key before the write has completed, the copy from the write buffer will be returned, thus ensuring consistency with the latest call to `put()`.

:::note[Automatic write coalescing]

If you invoke `put()` (or `delete()`) multiple times without performing any `await` in the meantime, the operations will automatically be combined and submitted atomically. In case of a machine failure, either all of the writes will have been stored to disk or none of the writes will have been stored to disk.
:::

:::note[Write buffer behavior]

The `put()` method returns a `Promise`, but most applications can discard this promise without using `await`. The `Promise` usually completes immediately, because `put()` writes to an in-memory write buffer that is flushed to disk asynchronously. However, if an application performs a large number of `put()` without waiting for any I/O, the write buffer could theoretically grow large enough to cause the isolate to exceed its 128 MB memory limit. To avoid this scenario, such applications should use `await` on the `Promise` returned by `put()`. The system will then apply backpressure onto the application, slowing it down so that the write buffer has time to flush. Using `await` will disable automatic write coalescing.
:::

### `list`

- <code>list(options <Type text="Object" /> <MetaInfo text="optional" />)</code>: <Type text="Promise<Map<string, any>>" />

  - Returns all keys and values associated with the current Durable Object in ascending sorted order based on the keys' UTF-8 encodings.

  - The type of each returned value in the [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) will be whatever was previously written for the corresponding key.

  - Be aware of how much data may be stored in your Durable Object before calling this version of `list` without options because all the data will be loaded into the Durable Object's memory, potentially hitting its [limit](/durable-objects/platform/limits/). If that is a concern, pass options to `list` as documented below.

#### Supported options

- `start` <Type text ='string' />

  - Key at which the list results should start, inclusive.

- `startAfter` <Type text ='string' />

  - Key after which the list results should start, exclusive. Cannot be used simultaneously with `start`.

- `end` <Type text ='string' />

  - Key at which the list results should end, exclusive.

- `prefix` <Type text ='string' />

  - Restricts results to only include key-value pairs whose keys begin with the prefix.

- `reverse` <Type text='boolean' />

  - If true, return results in descending order instead of the default ascending order.
  - Enabling `reverse` does not change the meaning of `start`, `startKey`, or `endKey`. `start` still defines the smallest key in lexicographic order that can be returned (inclusive), effectively serving as the endpoint for a reverse-order list. `end` still defines the largest key in lexicographic order that the list should consider (exclusive), effectively serving as the starting point for a reverse-order list.

- `limit` <Type text ='number' />

  - Maximum number of key-value pairs to return.

- `allowConcurrency` <Type text ='boolean' />

  - Same as the option to `get()`, above.

- `noCache` <Type text ='boolean' />

  - Same as the option to `get()`, above.

## Alarms

### `getAlarm`

- <code>getAlarm(options <Type text="Object" /> <MetaInfo text="optional" />)</code>: <Type text="Promise<Number | null>" />

  - Retrieves the current alarm time (if set) as integer milliseconds since epoch. The alarm is considered to be set if it has not started, or if it has failed and any retry has not begun. If no alarm is set, `getAlarm()` returns `null`.

#### Supported options

- Same options as [`get()`](/durable-objects/api/storage-api/#get), but without `noCache`.

### `setAlarm`

- <code>setAlarm(scheduledTime <Type text="Date | number" />, options{" "}<Type text="Object" /> <MetaInfo text="optional" />)</code>: <Type text="Promise" />

  - Sets the current alarm time, accepting either a JavaScript `Date`, or integer milliseconds since epoch.

    If `setAlarm()` is called with a time equal to or before `Date.now()`, the alarm will be scheduled for asynchronous execution in the immediate future. If the alarm handler is currently executing in this case, it will not be canceled. Alarms can be set to millisecond granularity and will usually execute within a few milliseconds after the set time, but can be delayed by up to a minute due to maintenance or failures while failover takes place.

### `deleteAlarm`

- <code>deleteAlarm(options <Type text="Object" /> <MetaInfo text="optional" />)</code>: <Type text="Promise" />

  - Deletes the alarm if one exists. Does not cancel the alarm handler if it is currently executing.

#### Supported options

- `setAlarm()` and `deleteAlarm()` support the same options as [`put()`](/durable-objects/api/storage-api/#put), but without `noCache`.

## Other

### `deleteAll`

- <code>deleteAll(options <Type text="Object" /> <MetaInfo text="optional" />)</code>: <Type text="Promise" />

  - Deletes all stored data, effectively deallocating all storage used by the Durable Object. For Durable Objects with a key-value storage backend, `deleteAll()` removes all keys and associated values for an individual Durable Object. For Durable Objects with a [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class), `deleteAll()` removes the entire contents of a Durable Object's private SQLite database, including both SQL data and key-value data.
  - For Durable Objects with a key-value storage backend, an in-progress `deleteAll()` operation can fail, which may leave a subset of data undeleted. Durable Objects with a SQLite storage backend do not have a partial `deleteAll()` issue because `deleteAll()` operations are atomic (all or nothing).
  - `deleteAll()` does not proactively delete [alarms](/durable-objects/api/alarms/). Use [`deleteAlarm()`](/durable-objects/api/alarms/#deletealarm) to delete an alarm.

### `transactionSync`

- `transactionSync(callback)`: <Type text='any' />

  - Only available when using SQLite-backed Durable Objects.

  - Invokes `callback()` wrapped in a transaction, and returns its result.

  - If `callback()` throws an exception, the transaction will be rolled back.

  * The callback must complete synchronously, that is, it should not be declared `async` nor otherwise return a Promise. Only synchronous storage operations can be part of the transaction. This is intended for use with SQL queries using [`ctx.storage.sql.exec()`](/durable-objects/api/storage-api/#exec), which complete sychronously.

### `transaction`

- `transaction(closureFunction(txn))`: <Type text='Promise' />

  - Runs the sequence of storage operations called on `txn` in a single transaction that either commits successfully or aborts.

  - Explicit transactions are no longer necessary. Any series of write operations with no intervening `await` will automatically be submitted atomically, and the system will prevent concurrent events from executing while `await` a read operation (unless you use `allowConcurrency: true`). Therefore, a series of reads followed by a series of writes (with no other intervening I/O) are automatically atomic and behave like a transaction.

- `txn`

  - Provides access to the `put()`, `get()`, `delete()` and `list()` methods documented above to run in the current transaction context. In order to get transactional behavior within a transaction closure, you must call the methods on the `txn` Object instead of on the top-level `ctx.storage` Object.<br/><br/>Also supports a `rollback()` function that ensures any changes made during the transaction will be rolled back rather than committed. After `rollback()` is called, any subsequent operations on the `txn` Object will fail with an exception. `rollback()` takes no parameters and returns nothing to the caller.

  - When using [the SQLite-backed storage engine](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend), the `txn` object is obsolete. Any storage operations performed directly on the `ctx.storage` object, including SQL queries using [`ctx.storage.sql.exec()`](/durable-objects/api/storage-api/#exec), will be considered part of the transaction.

### `sync`

- `sync()`: <Type text='Promise' />

  - Synchronizes any pending writes to disk.

  - This is similar to normal behavior from automatic write coalescing. If there are any pending writes in the write buffer (including those submitted with [the `allowUnconfirmed` option](/durable-objects/api/storage-api/#supported-options-1)), the returned promise will resolve when they complete. If there are no pending writes, the returned promise will be already resolved.

## Storage properties

### `sql`

`sql` is a readonly property of type `DurableObjectStorage` encapsulating the [SQL API](/durable-objects/api/storage-api/#sql-api).

## Related resources

- [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/)
- [Zero-latency SQLite storage in every Durable Object blog](https://blog.cloudflare.com/sqlite-in-durable-objects/)
- [WebSockets API](/durable-objects/best-practices/websockets/)

---

# Durable Object Stub

URL: https://developers.cloudflare.com/durable-objects/api/stub/

import { Render, GlossaryTooltip } from "~/components";

## Description

The `DurableObjectStub` interface is a client used to invoke methods on a remote <GlossaryTooltip term="Durable Object">Durable Object</GlossaryTooltip>. The type of `DurableObjectStub` is generic to allow for RPC methods to be invoked on the stub.

Durable Objects implement E-order semantics, a concept deriving from the [E distributed programming language](<https://en.wikipedia.org/wiki/E_(programming_language)>). When you make multiple calls to the same Durable Object, it is guaranteed that the calls will be delivered to the remote Durable Object in the order in which you made them. E-order semantics makes many distributed programming problems easier. E-order is implemented by the [Cap'n Proto](https://capnproto.org) distributed object-capability RPC protocol, which Cloudflare Workers uses for internal communications.

If an exception is thrown by a Durable Object <GlossaryTooltip term="stub">stub</GlossaryTooltip> all in-flight calls and future calls will fail with [exceptions](/durable-objects/observability/troubleshooting/). To continue invoking methods on a remote Durable Object a Worker must recreate the stub. There are no ordering guarantees between different stubs.

<Render file="example-rpc" />

## Properties

### `id`

`id` is a property of the `DurableObjectStub` corresponding to the [`DurableObjectId`](/durable-objects/api/id) used to create the stub.

```js
const id = env.MY_DURABLE_OBJECT.newUniqueId();
const stub = env.MY_DURABLE_OBJECT.get(id);
console.assert(id.equals(stub.id), "This should always be true");
```

### `name`

`name` is an optional property of a `DurableObjectStub`, which returns the name that was used to create the [`DurableObjectId`](/durable-objects/api/id) via [`DurableObjectNamespace::idFromName`](/durable-objects/api/namespace/#idfromname) which was then used to create the `DurableObjectStub`. This value is undefined if the [`DurableObjectId`](/durable-objects/api/id) used to create the `DurableObjectStub` was constructed using [`DurableObjectNamespace::newUniqueId`](/durable-objects/api/namespace/#newuniqueid).

```js
const id = env.MY_DURABLE_OBJECT.idFromName("foo");
const stub = env.MY_DURABLE_OBJECT.get(id);
console.assert(stub.name === "foo", "This should always be true");
```

## Related resources

- [Durable Objects: Easy, Fast, Correct – Choose Three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/).

---

# WebGPU

URL: https://developers.cloudflare.com/durable-objects/api/webgpu/

:::caution

The WebGPU API is only available in local development. You cannot deploy Durable Objects to Cloudflare that rely on the WebGPU API. See [Workers AI](/workers-ai/) for information on running machine learning models on the GPUs in Cloudflare's global network.

:::

The [WebGPU API](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API) allows you to use the GPU directly from JavaScript.

The WebGPU API is only accessible from within [Durable Objects](/durable-objects/). You cannot use the WebGPU API from within Workers.

To use the WebGPU API in local development, enable the `experimental` and `webgpu` [compatibility flags](/workers/configuration/compatibility-flags/) in the [Wrangler configuration file](/workers/wrangler/configuration/) of your Durable Object.

```
compatibility_flags = ["experimental", "webgpu"]
```

The following subset of the WebGPU API is available from within Durable Objects:

| API                                                                                                                | Supported? | Notes |
| ------------------------------------------------------------------------------------------------------------------ | ---------- | ----- |
| [`navigator.gpu`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/gpu)                                  | ✅         |       |
| [`GPU.requestAdapter`](https://developer.mozilla.org/en-US/docs/Web/API/GPU/requestAdapter)                        | ✅         |       |
| [`GPUAdapterInfo`](https://developer.mozilla.org/en-US/docs/Web/API/GPUAdapterInfo)                                | ✅         |       |
| [`GPUAdapter`](https://developer.mozilla.org/en-US/docs/Web/API/GPUAdapter)                                        | ✅         |       |
| [`GPUBindGroupLayout`](https://developer.mozilla.org/en-US/docs/Web/API/GPUBindGroupLayout)                        | ✅         |       |
| [`GPUBindGroup`](https://developer.mozilla.org/en-US/docs/Web/API/GPUBindGroup)                                    | ✅         |       |
| [`GPUBuffer`](https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer)                                          | ✅         |       |
| [`GPUCommandBuffer`](https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandBuffer)                            | ✅         |       |
| [`GPUCommandEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder)                          | ✅         |       |
| [`GPUComputePassEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/GPUComputePassEncoder)                  | ✅         |       |
| [`GPUComputePipeline`](https://developer.mozilla.org/en-US/docs/Web/API/GPUComputePipeline)                        | ✅         |       |
| [`GPUComputePipelineError`](https://developer.mozilla.org/en-US/docs/Web/API/GPUPipelineError)                     | ✅         |       |
| [`GPUDevice`](https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice)                                          | ✅         |       |
| [`GPUOutOfMemoryError`](https://developer.mozilla.org/en-US/docs/Web/API/GPUOutOfMemoryError)                      | ✅         |       |
| [`GPUValidationError`](https://developer.mozilla.org/en-US/docs/Web/API/GPUValidationError)                        | ✅         |       |
| [`GPUInternalError`](https://developer.mozilla.org/en-US/docs/Web/API/GPUInternalError)                            | ✅         |       |
| [`GPUDeviceLostInfo`](https://developer.mozilla.org/en-US/docs/Web/API/GPUDeviceLostInfo)                          | ✅         |       |
| [`GPUPipelineLayout`](https://developer.mozilla.org/en-US/docs/Web/API/GPUPipelineLayout)                          | ✅         |       |
| [`GPUQuerySet`](https://developer.mozilla.org/en-US/docs/Web/API/GPUQuerySet)                                      | ✅         |       |
| [`GPUQueue`](https://developer.mozilla.org/en-US/docs/Web/API/GPUQueue)                                            | ✅         |       |
| [`GPUSampler`](https://developer.mozilla.org/en-US/docs/Web/API/GPUSampler)                                        | ✅         |       |
| [`GPUCompilationMessage`](https://developer.mozilla.org/en-US/docs/Web/API/GPUCompilationMessage)                  | ✅         |       |
| [`GPUShaderModule`](https://developer.mozilla.org/en-US/docs/Web/API/GPUShaderModule)                              | ✅         |       |
| [`GPUSupportedFeatures`](https://developer.mozilla.org/en-US/docs/Web/API/GPUSupportedFeatures)                    | ✅         |       |
| [`GPUSupportedLimits`](https://developer.mozilla.org/en-US/docs/Web/API/GPUSupportedLimits)                        | ✅         |       |
| [`GPUMapMode`](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API#reading_the_results_back_to_javascript) | ✅         |       |
| [`GPUShaderStage`](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API#create_a_bind_group_layout)         | ✅         |       |
| [`GPUUncapturedErrorEvent`](https://developer.mozilla.org/en-US/docs/Web/API/GPUUncapturedErrorEvent)              | ✅         |       |

The following subset of the WebGPU API is not yet supported:

| API                                                                                                             | Supported? | Notes |
| --------------------------------------------------------------------------------------------------------------- | ---------- | ----- |
| [`GPU.getPreferredCanvasFormat`](https://developer.mozilla.org/en-US/docs/Web/API/GPU/getPreferredCanvasFormat) |            |       |
| [`GPURenderBundle`](https://developer.mozilla.org/en-US/docs/Web/API/GPURenderBundle)                           |            |       |
| [`GPURenderBundleEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/GPURenderBundleEncoder)             |            |       |
| [`GPURenderPassEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/GPURenderPassEncoder)                 |            |       |
| [`GPURenderPipeline`](https://developer.mozilla.org/en-US/docs/Web/API/GPURenderPipeline)                       |            |       |
| [`GPUShaderModule`](https://developer.mozilla.org/en-US/docs/Web/API/GPUShaderModule)                           |            |       |
| [`GPUTexture`](https://developer.mozilla.org/en-US/docs/Web/API/GPUTexture)                                     |            |       |
| [`GPUTextureView`](https://developer.mozilla.org/en-US/docs/Web/API/GPUTextureView)                             |            |       |
| [`GPUExternalTexture`](https://developer.mozilla.org/en-US/docs/Web/API/GPUExternalTexture)                     |            |       |

## Examples

- [workers-wonnx](https://github.com/cloudflare/workers-wonnx/) — Image classification, running on a GPU via the WebGPU API, using the [wonnx](https://github.com/webonnx/wonnx) model inference runtime.

---

# Access Durable Objects Storage

URL: https://developers.cloudflare.com/durable-objects/best-practices/access-durable-objects-storage/

import { Render, GlossaryTooltip, WranglerConfig } from "~/components";

<GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> are a powerful compute API that provides a compute with storage building block. Each Durable Object has its own private, transactional, and strongly consistent storage. Durable Objects <GlossaryTooltip term="Storage API">Storage API</GlossaryTooltip> provides access to a Durable Object's attached storage.

A Durable Object's [in-memory state](/durable-objects/reference/in-memory-state/) is preserved as long as the Durable Object is not evicted from memory. Inactive Durable Objects with no incoming request traffic can be evicted. There are normal operations like [code deployments](/workers/configuration/versions-and-deployments/) that trigger Durable Objects to restart and lose their in-memory state. For these reasons, you should use Storage API to persist state durably on disk that needs to survive eviction or restart of Durable Objects.

## Access storage

<Render file="recommend-sqlite-do" product="durable-objects"/>

<Render file="do-sqlite-storage-no-bill-note"/>

[Storage API methods](/durable-objects/api/storage-api/#methods) are available on `ctx.storage` parameter passed to the Durable Object constructor. Storage API has several methods, including SQL, point-in-time recovery (PITR), key-value (KV), and alarm APIs.

Only Durable Object classes with a SQLite storage backend can access SQL API.

### Create SQLite-backed Durable Object class

Use `new_sqlite_classes` on the migration in your Worker's Wrangler file:

<WranglerConfig>

```toml
[[migrations]]
tag = "v1" # Should be unique for each entry
new_sqlite_classes = ["MyDurableObject"] # Array of new classes
```

</WranglerConfig>

[SQL API](/durable-objects/api/storage-api/#exec) is available on `ctx.storage.sql` parameter passed to the Durable Object constructor.

SQLite-backed Durable Objects also offer [point-in-time recovery API](/durable-objects/api/storage-api/#pitr-point-in-time-recovery-api), which uses <GlossaryTooltip term="bookmark">bookmarks</GlossaryTooltip> to allow you to restore a Durable Object's embedded SQLite database to any point in time in the past 30 days.

### Initialize instance variables from storage

A common pattern is to initialize a Durable Object from [persistent storage](/durable-objects/api/storage-api/) and set instance variables the first time it is accessed. Since future accesses are routed to the same Durable Object, it is then possible to return any initialized values without making further calls to persistent storage.

```ts
import { DurableObject } from "cloudflare:workers";

export class Counter extends DurableObject {
  value: number;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);

    // `blockConcurrencyWhile()` ensures no requests are delivered until
    // initialization completes.
    ctx.blockConcurrencyWhile(async () => {
      // After initialization, future reads do not need to access storage.
      this.value = (await ctx.storage.get("value")) || 0;
    });
  }

  async getCounterValue() {
    return this.value;
  }
}
```

### Remove a Durable Object's storage

A Durable Object fully ceases to exist if, when it shuts down, its storage is empty. If you never write to a Durable Object's storage at all (including setting <GlossaryTooltip term="alarm">alarms</GlossaryTooltip>), then storage remains empty, and so the Durable Object will no longer exist once it shuts down.

However if you ever write using [Storage API](/durable-objects/api/storage-api/), including setting alarms, then you must explicitly call [`storage.deleteAll()`](/durable-objects/api/storage-api/#deleteall) to empty storage and [`storage.deleteAlarm()`](/durable-objects/api/storage-api/#deletealarm) if you've configured an alarm. It is not sufficient to simply delete the specific data that you wrote, such as deleting a key or dropping a table, as some metadata may remain. The only way to remove all storage is to call `deleteAll()`. Calling `deleteAll()` ensures that a Durable Object will not be billed for storage.

```ts
export class MyDurableObject extends DurableObject<Env> {

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
  }

  // Clears Durable Object storage
  async clearDo():Promise<void> {
    // If you've configured a Durable Object alarm
    await this.ctx.storage.deleteAlarm();

    // This will delete all the storage associated with this Durable Object instance
    // This will also delete the Durable Object instance itself
    await this.ctx.storage.deleteAll();
  }
}
```

## SQL API Examples

<Render file="durable-objects-sql" />

## TypeScript and query results

You can use TypeScript [type parameters](https://www.typescriptlang.org/docs/handbook/2/generics.html#working-with-generic-type-variables) to provide a type for your results, allowing you to benefit from type hints and checks when iterating over the results of a query.

:::caution

Providing a type parameter does _not_ validate that the query result matches your type definition. In TypeScript, properties (fields) that do not exist in your result type will be silently dropped.

:::

Your type must conform to the shape of a TypeScript [Record](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type) type representing the name (`string`) of the column and the type of the column. The column type must be a valid `SqlStorageValue`: one of `ArrayBuffer | string | number | null`.

For example,

```ts
type User = {
	id: string;
	name: string;
	email_address: string;
	version: number;
}
```

This type can then be passed as the type parameter to a `sql.exec()` call:

```ts
// The type parameter is passed between angle brackets before the function argument:
const result = this.ctx.storage.sql.exec<User>("SELECT id, name, email_address, version FROM users WHERE id = ?", user_id).one()
// result will now have a type of "User"

// Alternatively, if you are iterating over results using a cursor
let cursor = this.sql.exec<User>("SELECT id, name, email_address, version FROM users WHERE id = ?", user_id)
for (let row of cursor) {
	// Each row object will be of type User
}

// Or, if you are using raw() to convert results into an array, define an array type:
type UserRow = [
  id: string,
  name: string,
  email_address: string,
  version: number,
];

// ... and then pass it as the type argument to the raw() method:
let cursor = sql.exec("SELECT id, name, email_address, version FROM users WHERE id = ?", user_id).raw<UserRow>();

for (let row of cursor) {
	// row is of type User
}
```

You can represent the shape of any result type you wish, including more complex types. If you are performing a
`JOIN` across multiple tables, you can compose a type that reflects the results of your queries.

## Indexes in SQLite

Creating indexes for your most queried tables and filtered columns reduces how much data is scanned and improves query performance at the same time. If you have a read-heavy workload (most common), this can be particularly advantageous. Writing to columns referenced in an index will add at least one (1) additional row written to account for updating the index, but this is typically offset by the reduction in rows read due to the benefits of an index.

<Render file="durable-objects-vs-d1" />

## Related resources

* [Zero-latency SQLite storage in every Durable Object blog post](https://blog.cloudflare.com/sqlite-in-durable-objects)

---

# Invoke methods

URL: https://developers.cloudflare.com/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/

import { Render, Tabs, TabItem, GlossaryTooltip } from "~/components";

## Invoking methods on a Durable Object

All new projects and existing projects with a compatibility date greater than or equal to [`2024-04-03`](/workers/configuration/compatibility-flags/#durable-object-stubs-and-service-bindings-support-rpc) should prefer to invoke [Remote Procedure Call (RPC)](/workers/runtime-apis/rpc/) methods defined on a <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>. Legacy projects can continue to invoke the `fetch` handler on the Durable Object class indefinitely.

### Invoke RPC methods

By writing a Durable Object class which inherits from the built-in type `DurableObject`, public methods on the Durable Objects class are exposed as [RPC methods](/workers/runtime-apis/rpc/), which you can call using a [DurableObjectStub](/durable-objects/api/stub) from a Worker.

All RPC calls are [asynchronous](/workers/runtime-apis/rpc/lifecycle/), accept and return [serializable types](/workers/runtime-apis/rpc/), and [propagate exceptions](/workers/runtime-apis/rpc/error-handling/) to the caller without a stack trace. Refer to [Workers RPC](/workers/runtime-apis/rpc/) for complete details.

<Render file="example-rpc" />

:::note

With RPC, the `DurableObject` superclass defines `ctx` and `env` as class properties. What was previously called `state` is now called `ctx` when you extend the `DurableObject` class. The name `ctx` is adopted rather than `state` for the `DurableObjectState` interface to be consistent between `DurableObject` and `WorkerEntrypoint` objects.

:::

Refer to [Build a Counter](/durable-objects/examples/build-a-counter/) for a complete example.

### Invoking the `fetch` handler

If your project is stuck on a compatibility date before [`2024-04-03`](/workers/configuration/compatibility-flags/#durable-object-stubs-and-service-bindings-support-rpc), or has the need to send a [`Request`](/workers/runtime-apis/request/) object and return a `Response` object, then you should send requests to a Durable Object via the fetch handler.

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Durable Object
export class MyDurableObject extends DurableObject {
	constructor(ctx, env) {
		super(ctx, env);
	}

	async fetch(request) {
		return new Response("Hello, World!");
	}
}

// Worker
export default {
	async fetch(request, env) {
		// Every unique ID refers to an individual instance of the Durable Object class
		const id = env.MY_DURABLE_OBJECT.idFromName("foo");

		// A stub is a client used to invoke methods on the Durable Object
		const stub = env.MY_DURABLE_OBJECT.get(id);

		// Methods on the Durable Object are invoked via the stub
		const response = await stub.fetch(request);

		return response;
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
	MY_DURABLE_OBJECT: DurableObjectNamespace<MyDurableObject>;
}

// Durable Object
export class MyDurableObject extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}

	async fetch(request: Request): Promise<Response> {
		return new Response("Hello, World!");
	}
}

// Worker
export default {
	async fetch(request, env) {
		// Every unique ID refers to an individual instance of the Durable Object class
		const id = env.MY_DURABLE_OBJECT.idFromName("foo");

		// A stub is a client used to invoke methods on the Durable Object
		const stub = env.MY_DURABLE_OBJECT.get(id);

		// Methods on the Durable Object are invoked via the stub
		const response = await stub.fetch(request);

		return response;
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

The `URL` associated with the [`Request`](/workers/runtime-apis/request/) object passed to the `fetch()` handler of your Durable Object must be a well-formed URL, but does not have to be a publicly-resolvable hostname.

Without RPC, customers frequently construct requests which corresponded to private methods on the Durable Object and dispatch requests from the `fetch` handler. RPC is obviously more ergonomic in this example.

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Durable Object
export class MyDurableObject extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}

	private hello(name) {
		return new Response(`Hello, ${name}!`);
	}

	private goodbye(name) {
		return new Response(`Goodbye, ${name}!`);
	}

	async fetch(request) {
		const url = new URL(request.url);
		let name = url.searchParams.get("name");
		if (!name) {
			name = "World";
		}

		switch (url.pathname) {
			case "/hello":
				return this.hello(name);
			case "/goodbye":
				return this.goodbye(name);
			default:
				return new Response("Bad Request", { status: 400 });
		}
	}
}

// Worker
export default {
	async fetch(_request, env, _ctx) {
		// Every unique ID refers to an individual instance of the Durable Object class
		const id = env.MY_DURABLE_OBJECT.idFromName("foo");

		// A stub is a client used to invoke methods on the Durable Object
		const stub = env.MY_DURABLE_OBJECT.get(id);

		// Invoke the fetch handler on the Durable Object stub
		let response = await stub.fetch("http://do/hello?name=World");

		return response;
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
	MY_DURABLE_OBJECT: DurableObjectNamespace<MyDurableObject>;
}

// Durable Object
export class MyDurableObject extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}

	private hello(name: string) {
		return new Response(`Hello, ${name}!`);
	}

	private goodbye(name: string) {
		return new Response(`Goodbye, ${name}!`);
	}

	async fetch(request: Request): Promise<Response> {
		const url = new URL(request.url);
		let name = url.searchParams.get("name");
		if (!name) {
			name = "World";
		}

		switch (url.pathname) {
			case "/hello":
				return this.hello(name);
			case "/goodbye":
				return this.goodbye(name);
			default:
				return new Response("Bad Request", { status: 400 });
		}
	}
}

// Worker
export default {
	async fetch(_request, env, _ctx) {
		// Every unique ID refers to an individual instance of the Durable Object class
		const id = env.MY_DURABLE_OBJECT.idFromName("foo");

		// A stub is a client used to invoke methods on the Durable Object
		const stub = env.MY_DURABLE_OBJECT.get(id);

		// Invoke the fetch handler on the Durable Object stub
		let response = await stub.fetch("http://do/hello?name=World");

		return response;
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

---

# Error handling

URL: https://developers.cloudflare.com/durable-objects/best-practices/error-handling/

import { GlossaryTooltip } from "~/components";


Any uncaught exceptions thrown by a <GlossaryTooltip term="Durable Object">Durable Object</GlossaryTooltip> or thrown by Durable Objects' infrastructure (such as overloads or network errors) will be propagated to the callsite of the client. Catching these exceptions allows you to retry creating the [`DurableObjectStub`](/durable-objects/api/stub) and sending requests.

JavaScript Errors with the property `.retryable` set to True are suggested to be retried if requests to the Durable Object are idempotent, or can be applied multiple times without changing the response. If requests are not idempotent, then you will need to decide what is best for your application.

JavaScript Errors with the property `.overloaded` set to True should not be retried. If a Durable Object is overloaded, then retrying will worsen the overload and increase the overall error rate.

It is strongly recommended to retry requests following the exponential backoff algorithm in production code when the error properties indicate that it is safe to do so.

## How exceptions are thrown

Durable Objects can throw exceptions in one of two ways:

- An exception can be thrown within the user code which implements a <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>. The resulting exception will have a `.remote` property set to `True` in this case.
- An exception can be generated by Durable Object's infrastructure. Some sources of infrastructure exceptions include: transient internal errors, sending too many requests to a single Durable Object, and too many requests being queued due to slow or excessive I/O (external API calls or storage operations) within an individual Durable Object. Some infrastructure exceptions may also have the `.remote` property set to `True` -- for example, when the Durable Object exceeds its memory or CPU limits.

Refer to [Troubleshooting](/durable-objects/observability/troubleshooting/) to review the types of errors returned by a Durable Object and/or Durable Objects infrastructure and how to prevent them.

## Example

This example demonstrates retrying requests using the recommended exponential backoff algorithm.

```ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
	ErrorThrowingObject: DurableObjectNamespace;
}

export default {
	async fetch(request, env, ctx) {
		let userId = new URL(request.url).searchParams.get("userId") || "";
		const id = env.ErrorThrowingObject.idFromName(userId);

		// Retry behavior can be adjusted to fit your application.
		let maxAttempts = 3;
		let baseBackoffMs = 100;
		let maxBackoffMs = 20000;

		let attempt = 0;
		while (true) {
			// Try sending the request
			try {
				// Create a Durable Object stub for each attempt, because certain types of
				// errors will break the Durable Object stub.
				const doStub = env.ErrorThrowingObject.get(id);
				const resp = await doStub.fetch("http://your-do/");

				return Response.json(resp);
			} catch (e: any) {
				if (!e.retryable) {
					// Failure was not a transient internal error, so don't retry.
					break;
				}
			}
			let backoffMs = Math.min(
				maxBackoffMs,
				baseBackoffMs * Math.random() * Math.pow(2, attempt),
			);
			attempt += 1;
			if (attempt >= maxAttempts) {
				// Reached max attempts, so don't retry.
				break;
			}
			await scheduler.wait(backoffMs);
		}
		return new Response("server error", { status: 500 });
	},
} satisfies ExportedHandler<Env>;

export class ErrorThrowingObject extends DurableObject {
	constructor(state: DurableObjectState, env: Env) {
		super(state, env);

		// Any exceptions that are raised in your constructor will also set the
		// .remote property to True
		throw new Error("no good");
	}

	async fetch(req: Request) {
		// Generate an uncaught exception
		// A .remote property will be added to the exception propagated to the caller
		// and will be set to True
		throw new Error("example error");

		// We never reach this
		return Response.json({});
	}
}
```

---

# Best practices

URL: https://developers.cloudflare.com/durable-objects/best-practices/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Use WebSockets

URL: https://developers.cloudflare.com/durable-objects/best-practices/websockets/

import { Tabs, TabItem, GlossaryTooltip, Type } from "~/components";

This guide covers how to use Durable Objects as WebSocket servers that can connect thousands of clients (per instance), as well as a WebSocket client to connect to other servers or even Durable Objects.

There are two sets of WebSockets API:

1. Native Durable Object WebSocket API, which allows your Durable Object to hibernate without disconnecting clients when not actively doing work **(recommended)**.
2. Web Standard WebSocket APIs, using the familiar `addEventListener` event pattern.

### What are WebSockets?

WebSockets are long-lived TCP connections that enable bi-directional, real-time communication between client and server. Both Cloudflare Durable Objects and Workers can act as WebSocket endpoints – either as a client or as a server. Because WebSocket sessions are long-lived, applications commonly use Durable Objects to accept either the client or server connection. While there are other use cases for using Workers exclusively with WebSockets, for example proxying WebSocket messages, WebSockets are most useful when combined with Durable Objects.

Because Durable Objects provide a single-point-of-coordination between [Cloudflare Workers](/workers/), a single Durable Object instance can be used in parallel with WebSockets to coordinate between multiple clients, such as participants in a chat room or a multiplayer game. Refer to [Cloudflare Edge Chat Demo](https://github.com/cloudflare/workers-chat-demo) for an example of using Durable Objects with WebSockets.

Both Cloudflare Durable Objects and Workers can use the [Web Standard WebSocket API](/workers/runtime-apis/websockets/) to build applications, but a major differentiator of Cloudflare Durable Objects relative to other platforms is the ability to Hibernate WebSocket connections to save costs. Clients can remain connected when the Durable Object is idle (and not sending messages or running compute tasks), which allows you to push events to clients and minimize the active duration (GB-seconds) associated with long-running Durable Object processes.

### WebSocket Hibernation API

In addition to [Workers WebSocket API](/workers/runtime-apis/websockets/), Cloudflare Durable Objects can use the WebSocket Hibernation API which extends the Web Standard WebSocket API to reduce costs. Specifically, [billable Duration (GB-s) charges](/durable-objects/platform/pricing/) are not incurred during periods of inactivity. Note that other events, for example [alarms](/durable-objects/api/alarms/), can prevent a Durable Object from being inactive and therefore prevent this cost saving.

The WebSocket consists of Cloudflare-specific extensions to the Web Standard WebSocket API. These extensions are either present on the [DurableObjectState](/durable-objects/api/state) interface, or as handler methods on the Durable Object class.

:::note

Hibernation is only supported when a Durable Object acts as a WebSocket server. Currently, outgoing WebSockets cannot hibernate.

:::

The Worker used in the WebSocket Standard API example does not require any code changes to make use of the WebSocket Hibernation API. The changes to the Durable Object are described in the code sample below. In summary, [`DurableObjectState::acceptWebSocket`](/durable-objects/api/state/#acceptwebsocket) is called to accept the server side of the WebSocket connection, and handler methods are defined on the Durable Object class for relevant event types rather than adding event listeners.

If an event occurs for a hibernated Durable Object's corresponding handler method, it will return to memory. This will call the Durable Object's constructor, so it is best to minimize work in the constructor when using WebSocket hibernation.

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Durable Object
export class WebSocketHibernationServer extends DurableObject {
	async fetch(request) {
		// Creates two ends of a WebSocket connection.
		const webSocketPair = new WebSocketPair();
		const [client, server] = Object.values(webSocketPair);

		// Calling `acceptWebSocket()` informs the runtime that this WebSocket is to begin terminating
		// request within the Durable Object. It has the effect of "accepting" the connection,
		// and allowing the WebSocket to send and receive messages.
		// Unlike `ws.accept()`, `state.acceptWebSocket(ws)` informs the Workers Runtime that the WebSocket
		// is "hibernatable", so the runtime does not need to pin this Durable Object to memory while
		// the connection is open. During periods of inactivity, the Durable Object can be evicted
		// from memory, but the WebSocket connection will remain open. If at some later point the
		// WebSocket receives a message, the runtime will recreate the Durable Object
		// (run the `constructor`) and deliver the message to the appropriate handler.
		this.ctx.acceptWebSocket(server);

		return new Response(null, {
			status: 101,
			webSocket: client,
		});
	}

	async webSocketMessage(ws, message) {
		// Upon receiving a message from the client, reply with the same message,
		// but will prefix the message with "[Durable Object]: " and return the
		// total number of connections.
		ws.send(
			`[Durable Object] message: ${message}, connections: ${this.ctx.getWebSockets().length}`,
		);
	}

	async webSocketClose(ws, code, reason, wasClean) {
		// If the client closes the connection, the runtime will invoke the webSocketClose() handler.
		ws.close(code, "Durable Object is closing WebSocket");
	}
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
	WEBSOCKET_HIBERNATION_SERVER: DurableObjectNamespace<WebSocketHibernationServer>;
}

// Durable Object
export class WebSocketHibernationServer extends DurableObject {
	async fetch(request: Request): Promise<Response> {
		// Creates two ends of a WebSocket connection.
		const webSocketPair = new WebSocketPair();
		const [client, server] = Object.values(webSocketPair);

		// Calling `acceptWebSocket()` informs the runtime that this WebSocket is to begin terminating
		// request within the Durable Object. It has the effect of "accepting" the connection,
		// and allowing the WebSocket to send and receive messages.
		// Unlike `ws.accept()`, `state.acceptWebSocket(ws)` informs the Workers Runtime that the WebSocket
		// is "hibernatable", so the runtime does not need to pin this Durable Object to memory while
		// the connection is open. During periods of inactivity, the Durable Object can be evicted
		// from memory, but the WebSocket connection will remain open. If at some later point the
		// WebSocket receives a message, the runtime will recreate the Durable Object
		// (run the `constructor`) and deliver the message to the appropriate handler.
		this.ctx.acceptWebSocket(server);

		return new Response(null, {
			status: 101,
			webSocket: client,
		});
	}

	async webSocketMessage(ws: WebSocket, message: ArrayBuffer | string) {
		// Upon receiving a message from the client, the server replies with the same message,
		// and the total number of connections with the "[Durable Object]: " prefix
		ws.send(
			`[Durable Object] message: ${message}, connections: ${this.ctx.getWebSockets().length}`,
		);
	}

	async webSocketClose(
		ws: WebSocket,
		code: number,
		reason: string,
		wasClean: boolean,
	) {
		// If the client closes the connection, the runtime will invoke the webSocketClose() handler.
		ws.close(code, "Durable Object is closing WebSocket");
	}
}
```

</TabItem> </Tabs>

Similar to the WebSocket Standard API example, to execute this code, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the <GlossaryTooltip term="namespace">namespace</GlossaryTooltip> and class name chosen previously.

```toml title="wrangler.toml"
name = "websocket-hibernation-server"

[[durable_objects.bindings]]
name = "WEBSOCKET_HIBERNATION_SERVER"
class_name = "WebSocketHibernationServer"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["WebSocketHibernationServer"]
```

A full example can be found in [Build a WebSocket server with WebSocket Hibernation](/durable-objects/examples/websocket-hibernation-server/).

:::caution[Support for local development]

Prior to `wrangler@3.13.2` and Miniflare `v3.20231016.0`, WebSockets did not hibernate when using local development environments such as `wrangler dev` or Miniflare.

If you are using older versions, note that while hibernatable WebSocket events such as [`webSocketMessage()`](/durable-objects/api/base/#websocketmessage) will still be delivered, the Durable Object will never be evicted from memory.

:::

## Extended methods

### `serializeAttachment`

- <code> serializeAttachment(value <Type text="any" />)</code>: <Type text="void" />

  - Keeps a copy of `value` associated with the WebSocket to survive hibernation. The value can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which is true of most types. If the value needs to be durable please use [Durable Object Storage](/durable-objects/api/storage-api/).

  - If you modify `value` after calling this method, those changes will not be retained unless you call this method again. The serialized size of `value` is limited to 2,048 bytes, otherwise this method will throw an error. If you need larger values to survive hibernation, use the [Storage API](/durable-objects/api/storage-api/) and pass the corresponding key to this method so it can be retrieved later.

### `deserializeAttachment`

- `deserializeAttachment()`: <Type text='any' />

  - Retrieves the most recent value passed to `serializeAttachment()`, or `null` if none exists.


### WebSocket Standard API

WebSocket connections are established by making an HTTP GET request with the `Upgrade: websocket` header. A Cloudflare Worker is commonly used to validate the request, proxy the request to the Durable Object to accept the server side connection, and return the client side connection in the response.

:::note[Validate requests in a Worker]

Both Workers and Durable Objects are billed, in part, based on the number of requests they receive. To avoid being billed for requests against a Durable Object for invalid requests, be sure to validate requests in your Worker.

:::

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
// Worker
export default {
	async fetch(request, env, ctx) {
		if (request.method === "GET" && request.url.endsWith("/websocket")) {
			// Expect to receive a WebSocket Upgrade request.
			// If there is one, accept the request and return a WebSocket Response.
			const upgradeHeader = request.headers.get("Upgrade");
			if (!upgradeHeader || upgradeHeader !== "websocket") {
				return new Response(null, {
					status: 426,
					statusText: "Durable Object expected Upgrade: websocket",
					headers: {
						"Content-Type": "text/plain",
					},
				});
			}

			// This example will refer to a single Durable Object instance, since the name "foo" is
			// hardcoded
			let id = env.WEBSOCKET_SERVER.idFromName("foo");
			let stub = env.WEBSOCKET_SERVER.get(id);

			// The Durable Object's fetch handler will accept the server side connection and return
			// the client
			return stub.fetch(request);
		}

		return new Response(null, {
			status: 400,
			statusText: "Bad Request",
			headers: {
				"Content-Type": "text/plain",
			},
		});
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
// Worker
export default {
	async fetch(request, env, ctx): Promise<Response> {
		if (request.method === "GET" && request.url.endsWith("/websocket")) {
			// Expect to receive a WebSocket Upgrade request.
			// If there is one, accept the request and return a WebSocket Response.
			const upgradeHeader = request.headers.get("Upgrade");
			if (!upgradeHeader || upgradeHeader !== "websocket") {
				return new Response(null, {
					status: 426,
					statusText: "Durable Object expected Upgrade: websocket",
					headers: {
						"Content-Type": "text/plain",
					},
				});
			}

			// This example will refer to a single Durable Object instance, since the name "foo" is
			// hardcoded
			let id = env.WEBSOCKET_SERVER.idFromName("foo");
			let stub = env.WEBSOCKET_SERVER.get(id);

			// The Durable Object's fetch handler will accept the server side connection and return
			// the client
			return stub.fetch(request);
		}

		return new Response(null, {
			status: 400,
			statusText: "Bad Request",
			headers: {
				"Content-Type": "text/plain",
			},
		});
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

Each WebSocket server in this example is represented by a Durable Object. This WebSocket server creates a single WebSocket connection and responds to all messages over that connection with the total number of accepted WebSocket connections. In the Durable Object's fetch handler we create client and server connections and add event listeners for relevant event types.

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Durable Object
export class WebSocketServer extends DurableObject {
	currentlyConnectedWebSockets;

	constructor(ctx, env) {
		// This is reset whenever the constructor runs because
		// regular WebSockets do not survive Durable Object resets.
		//
		// WebSockets accepted via the Hibernation API can survive
		// a certain type of eviction, but we will not cover that here.
		super(ctx, env);
		this.currentlyConnectedWebSockets = 0;
	}

	async fetch(request) {
		// Creates two ends of a WebSocket connection.
		const webSocketPair = new WebSocketPair();
		const [client, server] = Object.values(webSocketPair);

		// Calling `accept()` tells the runtime that this WebSocket is to begin terminating
		// request within the Durable Object. It has the effect of "accepting" the connection,
		// and allowing the WebSocket to send and receive messages.
		server.accept();
		this.currentlyConnectedWebSockets += 1;

		// Upon receiving a message from the client, the server replies with the same message,
		// and the total number of connections with the "[Durable Object]: " prefix
		server.addEventListener("message", (event) => {
			server.send(
				`[Durable Object] currentlyConnectedWebSockets: ${this.currentlyConnectedWebSockets}`,
			);
		});

		// If the client closes the connection, the runtime will close the connection too.
		server.addEventListener("close", (cls) => {
			this.currentlyConnectedWebSockets -= 1;
			server.close(cls.code, "Durable Object is closing WebSocket");
		});

		return new Response(null, {
			status: 101,
			webSocket: client,
		});
	}
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
// Durable Object
export class WebSocketServer extends DurableObject {
	currentlyConnectedWebSockets: number;

	constructor(ctx: DurableObjectState, env: Env) {
		// This is reset whenever the constructor runs because
		// regular WebSockets do not survive Durable Object resets.
		//
		// WebSockets accepted via the Hibernation API can survive
		// a certain type of eviction, but we will not cover that here.
		super(ctx, env);
		this.currentlyConnectedWebSockets = 0;
	}

	async fetch(request: Request): Promise<Response> {
		// Creates two ends of a WebSocket connection.
		const webSocketPair = new WebSocketPair();
		const [client, server] = Object.values(webSocketPair);

		// Calling `accept()` tells the runtime that this WebSocket is to begin terminating
		// request within the Durable Object. It has the effect of "accepting" the connection,
		// and allowing the WebSocket to send and receive messages.
		server.accept();
		this.currentlyConnectedWebSockets += 1;

		// Upon receiving a message from the client, the server replies with the same message,
		// and the total number of connections with the "[Durable Object]: " prefix
		server.addEventListener("message", (event: MessageEvent) => {
			server.send(
				`[Durable Object] currentlyConnectedWebSockets: ${this.currentlyConnectedWebSockets}`,
			);
		});

		// If the client closes the connection, the runtime will close the connection too.
		server.addEventListener("close", (cls: CloseEvent) => {
			this.currentlyConnectedWebSockets -= 1;
			server.close(cls.code, "Durable Object is closing WebSocket");
		});

		return new Response(null, {
			status: 101,
			webSocket: client,
		});
	}
}
```

</TabItem> </Tabs>

To execute this code, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the <GlossaryTooltip term="namespace">namespace</GlossaryTooltip> and class name chosen previously.

```toml title="wrangler.toml"
name = "websocket-server"

[[durable_objects.bindings]]
name = "WEBSOCKET_SERVER"
class_name = "WebSocketServer"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["WebSocketServer"]
```

A full example can be found in [Build a WebSocket server](/durable-objects/examples/websocket-server/).

:::caution[WebSockets disconnection]

Code updates will disconnect all WebSockets. If you deploy a new version of a Worker, every Durable Object is restarted. Any connections to old Durable Objects will be disconnected.

:::

## Related resources

- [Mozilla Developer Network's (MDN) documentation on the WebSocket class](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
- [Cloudflare's WebSocket template for building applications on Workers using WebSockets](https://github.com/cloudflare/websocket-template)
- [Durable Object base class](/durable-objects/api/base/)
- [Durable Object State interface](/durable-objects/api/state/)

---

# Use the Alarms API

URL: https://developers.cloudflare.com/durable-objects/examples/alarms-api/

import { GlossaryTooltip, WranglerConfig } from "~/components";

This example implements an <GlossaryTooltip term="alarm">`alarm()`</GlossaryTooltip> handler that allows batching of requests to a single Durable Object.

When a request is received and no alarm is set, it sets an alarm for 10 seconds in the future. The `alarm()` handler processes all requests received within that 10-second window.

If no new requests are received, no further alarms will be set until the next request arrives.

```js
import { DurableObject } from "cloudflare:workers";

// Worker
export default {
	async fetch(request, env) {
		let id = env.BATCHER.idFromName("foo");
		return await env.BATCHER.get(id).fetch(request);
	},
};

const SECONDS = 10;

// Durable Object
export class Batcher extends DurableObject {
	constructor(state, env) {
		this.state = state;
		this.storage = state.storage;
		this.state.blockConcurrencyWhile(async () => {
			let vals = await this.storage.list({ reverse: true, limit: 1 });
			this.count = vals.size == 0 ? 0 : parseInt(vals.keys().next().value);
		});
	}

	async fetch(request) {
		this.count++;

		// If there is no alarm currently set, set one for 10 seconds from now
		// Any further POSTs in the next 10 seconds will be part of this batch.
		let currentAlarm = await this.storage.getAlarm();
		if (currentAlarm == null) {
			this.storage.setAlarm(Date.now() + 1000 * SECONDS);
		}

		// Add the request to the batch.
		await this.storage.put(this.count, await request.text());
		return new Response(JSON.stringify({ queued: this.count }), {
			headers: {
				"content-type": "application/json;charset=UTF-8",
			},
		});
	}

	async alarm() {
		let vals = await this.storage.list();
		await fetch("http://example.com/some-upstream-service", {
			method: "POST",
			body: Array.from(vals.values()),
		});
		await this.storage.deleteAll();
		this.count = 0;
	}
}
```

The `alarm()` handler will be called once every 10 seconds. If an unexpected error terminates the Durable Object, the `alarm()` handler will be re-instantiated on another machine. Following a short delay, the `alarm()` handler will run from the beginning on the other machine.

Finally, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously.

<WranglerConfig>

```toml title="wrangler.toml"
name = "durable-object-alarm"
main = "src/index.ts"

[[durable_objects.bindings]]
name = "BATCHER"
class_name = "Batcher"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["Batcher"]
```

</WranglerConfig>

---

# Build a counter

URL: https://developers.cloudflare.com/durable-objects/examples/build-a-counter/

import { TabItem, Tabs, WranglerConfig } from "~/components";

This example shows how to build a counter using Durable Objects and Workers with [RPC methods](/workers/runtime-apis/rpc) that can print, increment, and decrement a `name` provided by the URL query string parameter, for example, `?name=A`.

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Worker
export default {
	async fetch(request, env) {
		let url = new URL(request.url);
		let name = url.searchParams.get("name");
		if (!name) {
			return new Response(
				"Select a Durable Object to contact by using" +
					" the `name` URL query string parameter, for example, ?name=A",
			);
		}

		// Every unique ID refers to an individual instance of the Counter class that
		// has its own state. `idFromName()` always returns the same ID when given the
		// same string as input (and called on the same class), but never the same
		// ID for two different strings (or for different classes).
		let id = env.COUNTERS.idFromName(name);

		// Construct the stub for the Durable Object using the ID.
		// A stub is a client Object used to send messages to the Durable Object.
		let stub = env.COUNTERS.get(id);

		// Send a request to the Durable Object using RPC methods, then await its response.
		let count = null;
		switch (url.pathname) {
			case "/increment":
				count = await stub.increment();
				break;
			case "/decrement":
				count = await stub.decrement();
				break;
			case "/":
				// Serves the current value.
				count = await stub.getCounterValue();
				break;
			default:
				return new Response("Not found", { status: 404 });
		}

		return new Response(`Durable Object '${name}' count: ${count}`);
	},
};

// Durable Object
export class Counter extends DurableObject {
	async getCounterValue() {
		let value = (await this.ctx.storage.get("value")) || 0;
		return value;
	}

	async increment(amount = 1) {
		let value = (await this.ctx.storage.get("value")) || 0;
		value += amount;
		// You do not have to worry about a concurrent request having modified the value in storage.
		// "input gates" will automatically protect against unwanted concurrency.
		// Read-modify-write is safe.
		await this.ctx.storage.put("value", value);
		return value;
	}

	async decrement(amount = 1) {
		let value = (await this.ctx.storage.get("value")) || 0;
		value -= amount;
		await this.ctx.storage.put("value", value);
		return value;
	}
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
	COUNTERS: DurableObjectNamespace<Counter>;
}

// Worker
export default {
	async fetch(request, env) {
		let url = new URL(request.url);
		let name = url.searchParams.get("name");
		if (!name) {
			return new Response(
				"Select a Durable Object to contact by using" +
					" the `name` URL query string parameter, for example, ?name=A",
			);
		}

		// Every unique ID refers to an individual instance of the Counter class that
		// has its own state. `idFromName()` always returns the same ID when given the
		// same string as input (and called on the same class), but never the same
		// ID for two different strings (or for different classes).
		let id = env.COUNTERS.idFromName(name);

		// Construct the stub for the Durable Object using the ID.
		// A stub is a client Object used to send messages to the Durable Object.
		let stub = env.COUNTERS.get(id);

		let count = null;
		switch (url.pathname) {
			case "/increment":
				count = await stub.increment();
				break;
			case "/decrement":
				count = await stub.decrement();
				break;
			case "/":
				// Serves the current value.
				count = await stub.getCounterValue();
				break;
			default:
				return new Response("Not found", { status: 404 });
		}

		return new Response(`Durable Object '${name}' count: ${count}`);
	},
} satisfies ExportedHandler<Env>;

// Durable Object
export class Counter extends DurableObject {
	async getCounterValue() {
		let value = (await this.ctx.storage.get("value")) || 0;
		return value;
	}

	async increment(amount = 1) {
		let value: number = (await this.ctx.storage.get("value")) || 0;
		value += amount;
		// You do not have to worry about a concurrent request having modified the value in storage.
		// "input gates" will automatically protect against unwanted concurrency.
		// Read-modify-write is safe.
		await this.ctx.storage.put("value", value);
		return value;
	}

	async decrement(amount = 1) {
		let value: number = (await this.ctx.storage.get("value")) || 0;
		value -= amount;
		await this.ctx.storage.put("value", value);
		return value;
	}
}
```

</TabItem> </Tabs>

Finally, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously.

<WranglerConfig>

```toml title="wrangler.toml"
name = "my-counter"
main = "src/index.ts"

[[durable_objects.bindings]]
name = "COUNTERS"
class_name = "Counter"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["Counter"]
```

</WranglerConfig>

### Related resources

- [Workers RPC](/workers/runtime-apis/rpc/)
- [Durable Objects: Easy, Fast, Correct — Choose three](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/).

---

# Build a rate limiter

URL: https://developers.cloudflare.com/durable-objects/examples/build-a-rate-limiter/

import { TabItem, Tabs, GlossaryTooltip, WranglerConfig } from "~/components";

This example shows how to build a rate limiter using <GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> and Workers that can be used to protect upstream resources, including third-party APIs that your application relies on and/or services that may be costly for you to invoke.

This example also discusses some decisions that need to be made when designing a system, such as a rate limiter, with Durable Objects.

The Worker creates a `RateLimiter` Durable Object on a per IP basis to protect upstream resources. IP based rate limiting can be effective without negatively impacting latency because any given IP will remain within a small geographic area colocated with the `RateLimiter` Durable Object. Furthermore, throughput is also improved because each IP gets its own Durable Object.

It might seem simpler to implement a global rate limiter, `const id = env.RATE_LIMITER.idFromName("global");`, which can provide better guarantees on the request rate to the upstream resource. However:

- This would require all requests globally to make a sub-request to a single Durable Object.
- Implementing a global rate limiter would add additional latency for requests not colocated with the Durable Object, and global throughput would be capped to the throughput of a single Durable Object.
- A single Durable Object that all requests rely on is typically considered an anti-pattern. Durable Objects work best when they are scoped to a user, room, service and/or the specific subset of your application that requires global co-ordination.

:::note

If you do not need unique or custom rate-limiting capabilities, refer to [Rate limiting rules](/waf/rate-limiting-rules/) that are part of Cloudflare's Web Application Firewall (WAF) product.

:::

The Durable Object uses a token bucket algorithm to implement rate limiting. The naive idea is that each request requires a token to complete, and the tokens are replenished according to the reciprocal of the desired number of requests per second. As an example, a 1000 requests per second rate limit will have a token replenished every millisecond (as specified by milliseconds_per_request) up to a given capacity limit.

This example uses Durable Object's [Alarms API](/durable-objects/api/alarms) to schedule the Durable Object to be woken up at a time in the future.

- When the alarm's scheduled time comes, the `alarm()` handler method is called, and in this case, the <GlossaryTooltip term="alarm">alarm</GlossaryTooltip> will add a token to the "Bucket".
- The implementation is made more efficient by adding tokens in bulk (as specified by milliseconds_for_updates) and preventing the alarm handler from being invoked every millisecond. More frequent invocations of Durable Objects will lead to higher invocation and duration charges.

The first implementation of a rate limiter is below:

<Tabs>
<TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Worker
export default {
	async fetch(request, env, _ctx) {
		// Determine the IP address of the client
		const ip = request.headers.get("CF-Connecting-IP");
		if (ip === null) {
			return new Response("Could not determine client IP", { status: 400 });
		}

		// Obtain an identifier for a Durable Object based on the client's IP address
		const id = env.RATE_LIMITER.idFromName(ip);

		try {
			const stub = env.RATE_LIMITER.get(id);
			const milliseconds_to_next_request =
				await stub.getMillisecondsToNextRequest();
			if (milliseconds_to_next_request > 0) {
				// Alternatively one could sleep for the necessary length of time
				return new Response("Rate limit exceeded", { status: 429 });
			}
		} catch (error) {
			return new Response("Could not connect to rate limiter", { status: 502 });
		}

		// TODO: Implement me
		return new Response("Call some upstream resource...");
	},
};

// Durable Object
export class RateLimiter extends DurableObject {
	static milliseconds_per_request = 1;
	static milliseconds_for_updates = 5000;
	static capacity = 10000;

	constructor(ctx, env) {
		super(ctx, env);
		this.tokens = RateLimiter.capacity;
	}

	async getMillisecondsToNextRequest() {
		this.checkAndSetAlarm();

		let milliseconds_to_next_request = RateLimiter.milliseconds_per_request;
		if (this.tokens > 0) {
			this.tokens -= 1;
			milliseconds_to_next_request = 0;
		}

		return milliseconds_to_next_request;
	}

	async checkAndSetAlarm() {
		let currentAlarm = await this.ctx.storage.getAlarm();
		if (currentAlarm == null) {
			this.ctx.storage.setAlarm(
				Date.now() +
					RateLimiter.milliseconds_for_updates *
						RateLimiter.milliseconds_per_request,
			);
		}
	}

	async alarm() {
		if (this.tokens < RateLimiter.capacity) {
			this.tokens = Math.min(
				RateLimiter.capacity,
				this.tokens + RateLimiter.milliseconds_for_updates,
			);
			this.checkAndSetAlarm();
		}
	}
}
```

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

```ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
	RATE_LIMITER: DurableObjectNamespace<RateLimiter>;
}

// Worker
export default {
	async fetch(request, env, _ctx): Promise<Response> {
		// Determine the IP address of the client
		const ip = request.headers.get("CF-Connecting-IP");
		if (ip === null) {
			return new Response("Could not determine client IP", { status: 400 });
		}

		// Obtain an identifier for a Durable Object based on the client's IP address
		const id = env.RATE_LIMITER.idFromName(ip);

		try {
			const stub = env.RATE_LIMITER.get(id);
			const milliseconds_to_next_request =
				await stub.getMillisecondsToNextRequest();
			if (milliseconds_to_next_request > 0) {
				// Alternatively one could sleep for the necessary length of time
				return new Response("Rate limit exceeded", { status: 429 });
			}
		} catch (error) {
			return new Response("Could not connect to rate limiter", { status: 502 });
		}

		// TODO: Implement me
		return new Response("Call some upstream resource...");
	},
} satisfies ExportedHandler<Env>;

// Durable Object
export class RateLimiter extends DurableObject {
	static readonly milliseconds_per_request = 1;
	static readonly milliseconds_for_updates = 5000;
	static readonly capacity = 10000;

	tokens: number;

	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		this.tokens = RateLimiter.capacity;
	}

	async getMillisecondsToNextRequest(): Promise<number> {
		this.checkAndSetAlarm();

		let milliseconds_to_next_request = RateLimiter.milliseconds_per_request;
		if (this.tokens > 0) {
			this.tokens -= 1;
			milliseconds_to_next_request = 0;
		}

		return milliseconds_to_next_request;
	}

	private async checkAndSetAlarm() {
		let currentAlarm = await this.ctx.storage.getAlarm();
		if (currentAlarm == null) {
			this.ctx.storage.setAlarm(
				Date.now() +
					RateLimiter.milliseconds_for_updates *
						RateLimiter.milliseconds_per_request,
			);
		}
	}

	async alarm() {
		if (this.tokens < RateLimiter.capacity) {
			this.tokens = Math.min(
				RateLimiter.capacity,
				this.tokens + RateLimiter.milliseconds_for_updates,
			);
			this.checkAndSetAlarm();
		}
	}
}
```

</TabItem>
</Tabs>

While the token bucket algorithm is popular for implementing rate limiting and uses Durable Object features, there is a simpler approach:

<Tabs>
<TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Durable Object
export class RateLimiter extends DurableObject {
	static milliseconds_per_request = 1;
	static milliseconds_for_grace_period = 5000;

	constructor(ctx, env) {
		super(ctx, env);
		this.nextAllowedTime = 0;
	}

	async getMillisecondsToNextRequest() {
		const now = Date.now();

		this.nextAllowedTime = Math.max(now, this.nextAllowedTime);
		this.nextAllowedTime += RateLimiter.milliseconds_per_request;

		const value = Math.max(
			0,
			this.nextAllowedTime - now - RateLimiter.milliseconds_for_grace_period,
		);
		return value;
	}
}
```

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

```ts title="index.ts"
import { DurableObject } from "cloudflare:workers";

// Durable Object
export class RateLimiter extends DurableObject {
	static milliseconds_per_request = 1;
	static milliseconds_for_grace_period = 5000;

	nextAllowedTime: number;

	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		this.nextAllowedTime = 0;
	}

	async getMillisecondsToNextRequest(): Promise<number> {
		const now = Date.now();

		this.nextAllowedTime = Math.max(now, this.nextAllowedTime);
		this.nextAllowedTime += RateLimiter.milliseconds_per_request;

		const value = Math.max(
			0,
			this.nextAllowedTime - now - RateLimiter.milliseconds_for_grace_period,
		);
		return value;
	}
}
```

</TabItem>
</Tabs>

Finally, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously.

<WranglerConfig>

```toml title="wrangler.toml"
name = "my-counter"
main = "src/index.ts"

[[durable_objects.bindings]]
name = "RATE_LIMITER"
class_name = "RateLimiter"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["RateLimiter"]
```

</WranglerConfig>

### Related resources

- Learn more about Durable Object's [Alarms API](/durable-objects/api/alarms) and how to configure alarms.
- [Understand how to troubleshoot](/durable-objects/observability/troubleshooting/) common errors related with Durable Objects.
- Review how [Durable Objects are priced](/durable-objects/platform/pricing/), including pricing examples.

---

# Durable Object in-memory state

URL: https://developers.cloudflare.com/durable-objects/examples/durable-object-in-memory-state/

import { WranglerConfig } from "~/components";

This example shows you how Durable Objects are stateful, meaning in-memory state can be retained between requests. After a brief period of inactivity, the Durable Object will be evicted, and all in-memory state will be lost. The next request will reconstruct the object, but instead of showing the city of the previous request, it will display a message indicating that the object has been reinitialized. If you need your applications state to survive eviction, write the state to storage by using the [Storage API](/durable-objects/api/storage-api/), or by storing your data elsewhere.

```js
import { DurableObject } from "cloudflare:workers";

// Worker
export default {
	async fetch(request, env) {
		return await handleRequest(request, env);
	},
};

async function handleRequest(request, env) {
	let id = env.LOCATION.idFromName("A");
	let obj = env.LOCATION.get(id);
	// Forward the request to the remote Durable Object.
	let resp = await obj.fetch(request);
	// Return the response to the client.
	return new Response(await resp.text());
}

// Durable Object
export class Location extends DurableObject {
	constructor(state, env) {
		this.state = state;
		// Upon construction, you do not have a location to provide.
		// This value will be updated as people access the Durable Object.
		// When the Durable Object is evicted from memory, this will be reset.
		this.location = null;
	}

	// Handle HTTP requests from clients.
	async fetch(request) {
		let response = null;

		if (this.location == null) {
			response = new String(`
This is the first request, you called the constructor, so this.location was null.
You will set this.location to be your city: (${request.cf.city}). Try reloading the page.`);
		} else {
			response = new String(`
The Durable Object was already loaded and running because it recently handled a request.

Previous Location: ${this.location}
New Location: ${request.cf.city}`);
		}

		// You set the new location to be the new city.
		this.location = request.cf.city;
		console.log(response);
		return new Response(response);
	}
}
```

Finally, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously.

<WranglerConfig>

```toml title="wrangler.toml"
name = "durable-object-in-memory-state"
main = "src/index.ts"

[[durable_objects.bindings]]
name = "LOCATION"
class_name = "Location"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["Location"]
```

</WranglerConfig>

---

# Durable Object Time To Live

URL: https://developers.cloudflare.com/durable-objects/examples/durable-object-ttl/

import { TabItem, Tabs, GlossaryTooltip, WranglerConfig } from "~/components";

A common feature request for Durable Objects is a Time To Live (TTL) for Durable Object instances. Durable Objects give developers the tools to implement a custom TTL in only a few lines of code. This example demonstrates how to implement a TTL making use of <GlossaryTooltip term="alarm">`alarms`</GlossaryTooltip>. While this TTL will be extended upon every new request to the Durable Object, this can be customized based on a particular use case.

:::caution[Be careful when calling `setAlarm` in the Durable Object class constructor]

In this example the TTL is extended upon every new fetch request to the Durable Object. It might be tempting to instead extend the TTL in the constructor of the Durable Object. This is not advised because the Durable Object's constructor will be called before invoking the alarm handler if the alarm wakes the Durable Object up from hibernation. This approach will naively result in the constructor continually extending the TTL without running the alarm handler. If you must call `setAlarm` in the Durable Object class constructor be sure to check that there is no alarm previously set.

:::

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Durable Object
export class MyDurableObject extends DurableObject {
  // Time To Live (TTL) in milliseconds
  timeToLiveMs = 1000;

  constructor(ctx, env) {
    super(ctx, env);
  }

  async fetch(_request) {
    // Extend the TTL immediately following every fetch request to a Durable Object.
    await this.ctx.storage.setAlarm(Date.now() + this.timeToLiveMs);
    ...
   }

  async alarm() {
    await this.ctx.storage.deleteAll();
  }
}

// Worker
export default {
  async fetch(request, env) {
    const id = env.MY_DURABLE_OBJECT.idFromName("foo");
        const stub = env.MY_DURABLE_OBJECT.get(id)
    return await stub.fetch(request);
  },
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
  MY_DURABLE_OBJECT: DurableObjectNamespace<MyDurableObject>;
}

// Durable Object
export class MyDurableObject extends DurableObject {
  // Time To Live (TTL) in milliseconds
  timeToLiveMs = 1000;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
  }

  async fetch(_request: Request) {
    // Extend the TTL immediately following every fetch request to a Durable Object.
    await this.ctx.storage.setAlarm(Date.now() + this.timeToLiveMs);
    ...
   }

  async alarm() {
    await this.ctx.storage.deleteAll();
  }
}

// Worker
export default {
  async fetch(request, env) {
    const id = env.MY_DURABLE_OBJECT.idFromName("foo");
        const stub = env.MY_DURABLE_OBJECT.get(id)
    return await stub.fetch(request);
  },
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

To test and deploy this example, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously.

<WranglerConfig>

```toml title="wrangler.toml"
name = "durable-object-ttl"
main = "src/index.ts"

[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "MyDurableObject"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["MyDurableObject"]
```

</WranglerConfig>

---

# Examples

URL: https://developers.cloudflare.com/durable-objects/examples/

import { ListExamples, GlossaryTooltip } from "~/components";

Explore the following <GlossaryTooltip term="code example">examples</GlossaryTooltip> for Durable Objects.

<ListExamples />

---

# Use RpcTarget class to handle Durable Object metadata

URL: https://developers.cloudflare.com/durable-objects/examples/reference-do-name-using-init/

import { TabItem, Tabs, GlossaryTooltip } from "~/components";

When working with Durable Objects, you will need to access the name that was used to create the Durable Object via `idFromName()`. This name is typically a meaningful identifier that represents what the Durable Object is responsible for (like a user ID, room name, or resource identifier).

However, there is a limitation in the current implementation: even though you can create a Durable Object with `.idFromName(name)`, you cannot directly access this name inside the Durable Object via `this.ctx.id.name`.

The `RpcTarget` pattern shown below offers a solution by creating a communication layer that automatically carries the name with each method call. This keeps your API clean while ensuring the Durable Object has access to its own name.

Based on your needs, you can either store the metadata temporarily in the `RpcTarget` class, or use Durable Object storage to persist the metadata for the lifetime of the object.

This example does not persist the Durable Object metadata. It demonstrates how to:

1. Create an `RpcTarget` class
2. Set the Durable Object metadata (identifier in this example) in the `RpcTarget` class
3. Pass the metadata to a Durable Object method
4. Clean up the `RpcTarget` class after use

```ts
import { DurableObject, RpcTarget } from "cloudflare:workers";

//  * Create an RpcDO class that extends RpcTarget
//  * Use this class to set the Durable Object metadata
//  * Pass the metadata in the Durable Object methods
//  * @param mainDo - The main Durable Object class
//  * @param doIdentifier - The identifier of the Durable Object

export class RpcDO extends RpcTarget {
	constructor(
		private mainDo: MyDurableObject,
		private doIdentifier: string,
	) {
		super();
	}

	//  * Pass the user's name to the Durable Object method
	//  * @param userName - The user's name to pass to the Durable Object method

	async computeMessage(userName: string): Promise<string> {
		// Call the Durable Object method and pass the user's name and the Durable Object identifier
		return this.mainDo.computeMessage(userName, this.doIdentifier);
	}

	//  * Call the Durable Object method without using the Durable Object identifier
	//  * @param userName - The user's name to pass to the Durable Object method

	async simpleGreeting(userName: string) {
		return this.mainDo.simpleGreeting(userName);
	}
}

//  * Create a Durable Object class
//  * You can use the RpcDO class to set the Durable Object metadata

export class MyDurableObject extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}

	//  * Initialize the RpcDO class
	//  * You can set the Durable Object metadata here
	//  * It returns an instance of the RpcDO class
	//  * @param doIdentifier - The identifier of the Durable Object

	async setMetaData(doIdentifier: string) {
		return new RpcDO(this, doIdentifier);
	}

	//  * Function that computes a greeting message using the user's name and DO identifier
	//  * @param userName - The user's name to include in the greeting
	//  * @param doIdentifier - The identifier of the Durable Object

	async computeMessage(
		userName: string,
		doIdentifier: string,
	): Promise<string> {
		console.log({
			userName: userName,
			durableObjectIdentifier: doIdentifier,
		});
		return `Hello, ${userName}! The identifier of this DO is ${doIdentifier}`;
	}

	//  * Function that is not in the RpcTarget
	//  * Not every function has to be in the RpcTarget

	private async notInRpcTarget() {
		return "This is not in the RpcTarget";
	}

	//  * Function that takes the user's name and does not use the Durable Object identifier
	//  * @param userName - The user's name to include in the greeting

	async simpleGreeting(userName: string) {
		// Call the private function that is not in the RpcTarget
		console.log(this.notInRpcTarget());

		return `Hello, ${userName}! This doesn't use the DO identifier.`;
	}
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		let id: DurableObjectId = env.MY_DURABLE_OBJECT.idFromName(
			new URL(request.url).pathname,
		);
		let stub = env.MY_DURABLE_OBJECT.get(id);

		//  * Set the Durable Object metadata using the RpcTarget
		//  * Notice that no await is needed here

		const rpcTarget = stub.setMetaData(id.name ?? "default");

		// Call the Durable Object method using the RpcTarget.
		// The DO identifier is passed in the RpcTarget
		const greeting = await rpcTarget.computeMessage("world");

		// Call the Durable Object method that does not use the Durable Object identifier
		const simpleGreeting = await rpcTarget.simpleGreeting("world");

		// Clean up the RpcTarget.
		try {
			(await rpcTarget)[Symbol.dispose]?.();
			console.log("RpcTarget cleaned up.");
		} catch (e) {
			console.error({
				message: "RpcTarget could not be cleaned up.",
				error: String(e),
				errorProperties: e,
			});
		}

		return new Response(greeting, { status: 200 });
	},
} satisfies ExportedHandler<Env>;
```

This example persists the Durable Object metadata. It demonstrates similar steps as the previous example, but uses Durable Object storage to store the identifier, eliminating the need to pass it through the RpcTarget.

```ts
import { DurableObject, RpcTarget } from "cloudflare:workers";

//  * Create an RpcDO class that extends RpcTarget
//  * Use this class to set the Durable Object metadata
//  * Pass the metadata in the Durable Object methods
//  * @param mainDo - The main Durable Object class
//  * @param doIdentifier - The identifier of the Durable Object

export class RpcDO extends RpcTarget {
	constructor(
		private mainDo: MyDurableObject,
		private doIdentifier: string,
	) {
		super();
	}

	//  * Pass the user's name to the Durable Object method
	//  * @param userName - The user's name to pass to the Durable Object method

	async computeMessage(userName: string): Promise<string> {
		// Call the Durable Object method and pass the user's name and the Durable Object identifier
		return this.mainDo.computeMessage(userName, this.doIdentifier);
	}

	//  * Call the Durable Object method without using the Durable Object identifier
	//  * @param userName - The user's name to pass to the Durable Object method

	async simpleGreeting(userName: string) {
		return this.mainDo.simpleGreeting(userName);
	}
}

//  * Create a Durable Object class
//  * You can use the RpcDO class to set the Durable Object metadata

export class MyDurableObject extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}

	//  * Initialize the RpcDO class
	//  * You can set the Durable Object metadata here
	//  * It returns an instance of the RpcDO class
	//  * @param doIdentifier - The identifier of the Durable Object

	async setMetaData(doIdentifier: string) {
		// Use DO storage to store the Durable Object identifier
		await this.ctx.storage.put("doIdentifier", doIdentifier);
		return new RpcDO(this, doIdentifier);
	}

	//  * Function that computes a greeting message using the user's name and DO identifier
	//  * @param userName - The user's name to include in the greeting

	async computeMessage(userName: string): Promise<string> {
		// Get the DO identifier from storage
		const doIdentifier = await this.ctx.storage.get("doIdentifier");
		console.log({
			userName: userName,
			durableObjectIdentifier: doIdentifier,
		});
		return `Hello, ${userName}! The identifier of this DO is ${doIdentifier}`;
	}

	//  * Function that is not in the RpcTarget
	//  * Not every function has to be in the RpcTarget

	private async notInRpcTarget() {
		return "This is not in the RpcTarget";
	}

	//  * Function that takes the user's name and does not use the Durable Object identifier
	//  * @param userName - The user's name to include in the greeting

	async simpleGreeting(userName: string) {
		// Call the private function that is not in the RpcTarget
		console.log(this.notInRpcTarget());

		return `Hello, ${userName}! This doesn't use the DO identifier.`;
	}
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		let id: DurableObjectId = env.MY_DURABLE_OBJECT.idFromName(
			new URL(request.url).pathname,
		);
		let stub = env.MY_DURABLE_OBJECT.get(id);

		//  * Set the Durable Object metadata using the RpcTarget
		//  * Notice that no await is needed here

		const rpcTarget = stub.setMetaData(id.name ?? "default");

		// Call the Durable Object method using the RpcTarget.
		// The DO identifier is stored in the Durable Object's storage
		const greeting = await rpcTarget.computeMessage("world");

		// Call the Durable Object method that does not use the Durable Object identifier
		const simpleGreeting = await rpcTarget.simpleGreeting("world");

		// Clean up the RpcTarget.
		try {
			(await rpcTarget)[Symbol.dispose]?.();
			console.log("RpcTarget cleaned up.");
		} catch (e) {
			console.error({
				message: "RpcTarget could not be cleaned up.",
				error: String(e),
				errorProperties: e,
			});
		}

		return new Response(greeting, { status: 200 });
	},
} satisfies ExportedHandler<Env>;
```

---

# Use Workers KV from Durable Objects

URL: https://developers.cloudflare.com/durable-objects/examples/use-kv-from-durable-objects/

import { GlossaryTooltip, WranglerConfig } from "~/components";

The following Worker script shows you how to configure a <GlossaryTooltip term="Durable Object">Durable Object</GlossaryTooltip> to read from and/or write to a [Workers KV namespace](/kv/concepts/how-kv-works/). This is useful when using a Durable Object to coordinate between multiple clients, and allows you to serialize writes to KV and/or broadcast a single read from KV to hundreds or thousands of clients connected to a single Durable Object [using WebSockets](/durable-objects/best-practices/websockets/).

Prerequisites:

* A [KV namespace](/kv/api/) created via the Cloudflare dashboard or the [wrangler CLI](/workers/wrangler/install-and-update/).
* A [configured binding](/kv/concepts/kv-bindings/) for the `kv_namespace` in the Cloudflare dashboard or Wrangler file.
* A [Durable Object namespace binding](/workers/wrangler/configuration/#durable-objects).

Configure your Wrangler file as follows:

<WranglerConfig>

```toml
name = "my-worker"
main = "src/index.ts"

kv_namespaces = [
  { binding = "YOUR_KV_NAMESPACE", id = "<id_of_your_namespace>" }
]

[durable_objects]
bindings = [
  { name = "YOUR_DO_CLASS", class_name = "YourDurableObject" }
]
```

</WranglerConfig>

```ts
import { DurableObject } from 'cloudflare:workers';

interface Env {
  YOUR_KV_NAMESPACE: KVNamespace;
  YOUR_DO_CLASS: DurableObjectNamespace;
}

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    // Assume each Durable Object is mapped to a roomId in a query parameter
    // In a production application, this will likely be a roomId defined by your application
    // that you validate (and/or authenticate) first.
    let url = new URL(req.url);
    let roomIdParam = url.searchParams.get("roomId");

    if (roomIdParam) {
      // Create (or get) a Durable Object based on that roomId.
      let durableObjectId = env.YOUR_DO_CLASS.idFromName(roomIdParam);
      // Get a "stub" that allows you to call that Durable Object
      let durableObjectStub = env.YOUR_DO_CLASS.get(durableObjectId);

      // Pass the request to that Durable Object and await the response
      // This invokes the constructor once on your Durable Object class (defined further down)
      // on the first initialization, and the fetch method on each request.
      //
      // You could pass the original Request to the Durable Object's fetch method
      // or a simpler URL with just the roomId.
      let response = await durableObjectStub.fetch(`http://do/${roomId}`);

      // This would return the value you read from KV *within* the Durable Object.
      return response;
    }
  }
}

export class YourDurableObject extends DurableObject {
  constructor(public state: DurableObjectState, env: Env) {
    this.state = state;
    // Ensure you pass your bindings and environmental variables into
    // each Durable Object when it is initialized
    this.env = env;
  }

  async fetch(request: Request) {
    // Error handling elided for brevity.
    // Write to KV
    await this.env.YOUR_KV_NAMESPACE.put("some-key");

    // Fetch from KV
    let val = await this.env.YOUR_KV_NAMESPACE.get("some-other-key");

    return Response.json(val);
  }
}
```

---

# Build a WebSocket server with WebSocket Hibernation

URL: https://developers.cloudflare.com/durable-objects/examples/websocket-hibernation-server/

import { TabItem, Tabs, WranglerConfig } from "~/components";

This example is similar to the [Build a WebSocket server](/durable-objects/examples/websocket-server/) example, but uses the WebSocket Hibernation API. The WebSocket Hibernation API should be preferred for WebSocket server applications built on Durable Objects, since it significantly decreases duration charge, and provides additional features that pair well with WebSocket applications. For more information, refer to [Use Durable Objects with WebSockets](/durable-objects/best-practices/websockets/).

:::note

WebSocket Hibernation is unavailable for outgoing WebSocket use cases. Hibernation is only supported when the Durable Object acts as a server. For use cases where outgoing WebSockets are required, refer to [Write a WebSocket client](/workers/examples/websockets/#write-a-websocket-client).

:::

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Worker
export default {
	async fetch(request, env, ctx) {
		if (request.url.endsWith("/websocket")) {
			// Expect to receive a WebSocket Upgrade request.
			// If there is one, accept the request and return a WebSocket Response.
			const upgradeHeader = request.headers.get("Upgrade");
			if (!upgradeHeader || upgradeHeader !== "websocket") {
				return new Response("Durable Object expected Upgrade: websocket", {
					status: 426,
				});
			}

			// This example will refer to the same Durable Object,
			// since the name "foo" is hardcoded.
			let id = env.WEBSOCKET_HIBERNATION_SERVER.idFromName("foo");
			let stub = env.WEBSOCKET_HIBERNATION_SERVER.get(id);

			return stub.fetch(request);
		}

		return new Response(null, {
			status: 400,
			statusText: "Bad Request",
			headers: {
				"Content-Type": "text/plain",
			},
		});
	},
};

// Durable Object
export class WebSocketHibernationServer extends DurableObject {
	async fetch(request) {
		// Creates two ends of a WebSocket connection.
		const webSocketPair = new WebSocketPair();
		const [client, server] = Object.values(webSocketPair);

		// Calling `acceptWebSocket()` informs the runtime that this WebSocket is to begin terminating
		// request within the Durable Object. It has the effect of "accepting" the connection,
		// and allowing the WebSocket to send and receive messages.
		// Unlike `ws.accept()`, `state.acceptWebSocket(ws)` informs the Workers Runtime that the WebSocket
		// is "hibernatable", so the runtime does not need to pin this Durable Object to memory while
		// the connection is open. During periods of inactivity, the Durable Object can be evicted
		// from memory, but the WebSocket connection will remain open. If at some later point the
		// WebSocket receives a message, the runtime will recreate the Durable Object
		// (run the `constructor`) and deliver the message to the appropriate handler.
		this.ctx.acceptWebSocket(server);

		return new Response(null, {
			status: 101,
			webSocket: client,
		});
	}

	async webSocketMessage(ws, message) {
		// Upon receiving a message from the client, reply with the same message,
		// but will prefix the message with "[Durable Object]: " and return the
		// total number of connections.
		ws.send(
			`[Durable Object] message: ${message}, connections: ${this.ctx.getWebSockets().length}`,
		);
	}

	async webSocketClose(ws, code, reason, wasClean) {
		// If the client closes the connection, the runtime will invoke the webSocketClose() handler.
		ws.close(code, "Durable Object is closing WebSocket");
	}
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
	WEBSOCKET_HIBERNATION_SERVER: DurableObjectNamespace<WebSocketHibernationServer>;
}

// Worker
export default {
	async fetch(
		request: Request,
		env: Env,
		ctx: ExecutionContext,
	): Promise<Response> {
		if (request.url.endsWith("/websocket")) {
			// Expect to receive a WebSocket Upgrade request.
			// If there is one, accept the request and return a WebSocket Response.
			const upgradeHeader = request.headers.get("Upgrade");
			if (!upgradeHeader || upgradeHeader !== "websocket") {
				return new Response("Durable Object expected Upgrade: websocket", {
					status: 426,
				});
			}

			// This example will refer to the same Durable Object,
			// since the name "foo" is hardcoded.
			let id = env.WEBSOCKET_HIBERNATION_SERVER.idFromName("foo");
			let stub = env.WEBSOCKET_HIBERNATION_SERVER.get(id);

			return stub.fetch(request);
		}

		return new Response(null, {
			status: 400,
			statusText: "Bad Request",
			headers: {
				"Content-Type": "text/plain",
			},
		});
	},
};

// Durable Object
export class WebSocketHibernationServer extends DurableObject {
	async fetch(request: Request): Promise<Response> {
		// Creates two ends of a WebSocket connection.
		const webSocketPair = new WebSocketPair();
		const [client, server] = Object.values(webSocketPair);

		// Calling `acceptWebSocket()` informs the runtime that this WebSocket is to begin terminating
		// request within the Durable Object. It has the effect of "accepting" the connection,
		// and allowing the WebSocket to send and receive messages.
		// Unlike `ws.accept()`, `state.acceptWebSocket(ws)` informs the Workers Runtime that the WebSocket
		// is "hibernatable", so the runtime does not need to pin this Durable Object to memory while
		// the connection is open. During periods of inactivity, the Durable Object can be evicted
		// from memory, but the WebSocket connection will remain open. If at some later point the
		// WebSocket receives a message, the runtime will recreate the Durable Object
		// (run the `constructor`) and deliver the message to the appropriate handler.
		this.ctx.acceptWebSocket(server);

		return new Response(null, {
			status: 101,
			webSocket: client,
		});
	}

	async webSocketMessage(ws: WebSocket, message: ArrayBuffer | string) {
		// Upon receiving a message from the client, the server replies with the same message,
		// and the total number of connections with the "[Durable Object]: " prefix
		ws.send(
			`[Durable Object] message: ${message}, connections: ${this.ctx.getWebSockets().length}`,
		);
	}

	async webSocketClose(
		ws: WebSocket,
		code: number,
		reason: string,
		wasClean: boolean,
	) {
		// If the client closes the connection, the runtime will invoke the webSocketClose() handler.
		ws.close(code, "Durable Object is closing WebSocket");
	}
}
```

</TabItem> </Tabs>

Finally, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously.

<WranglerConfig>

```toml title="wrangler.toml"
name = "websocket-hibernation-server"
main = "src/index.ts"

[[durable_objects.bindings]]
name = "WEBSOCKET_HIBERNATION_SERVER"
class_name = "WebSocketHibernationServer"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["WebSocketHibernationServer"]
```

</WranglerConfig>

### Related resources

- [Durable Objects: Edge Chat Demo with Hibernation](https://github.com/cloudflare/workers-chat-demo/).

---

# Testing with Durable Objects

URL: https://developers.cloudflare.com/durable-objects/examples/testing-with-durable-objects/

```ts
import { unstable_dev } from "wrangler";
import type { UnstableDevWorker } from "wrangler";
import { describe, expect, it, beforeAll, afterAll } from "vitest";

describe("Worker", () => {
	let worker: UnstableDevWorker;

	beforeAll(async () => {
		worker = await unstable_dev("src/index.ts", {
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await worker.stop();
	});

	it("should deny request for short paths", async () => {
		const cases = {
			failures: ["/", "/foo", "/foo/", "/%2F"],
		};
		for (const path of cases.failures) {
			const resp = await worker.fetch(`http://example.com${path}`);
			if (resp) {
				const text = await resp.text();
				expect(text).toMatchInlineSnapshot(
					'"path must be at least 5 characters"',
				);
			}
		}
	});

	describe("durable object", () => {
		it("Should send text from a POST to a matching GET", async () => {
			const path = "/stuff1";
			const url = `http://example.com${path}`;

			// The get request should wait for the post request to complete
			const getResponsePromise = worker.fetch(url);

			// The post request to the same path should receive a response that the text was consumed
			const postResponse = await worker.fetch(url, {
				method: "POST",
				body: "Hello World 12345",
			});
			expect(postResponse.status).toBe(200);
			const postText = await postResponse.text();
			expect(postText).toBe("The text was consumed!");

			// The get request should now receive the text
			const getResponse = await getResponsePromise;
			expect(getResponse.status).toBe(200);
			const text = await getResponse.text();
			expect(text).toBe("Hello World 12345");
		});

		it("Shouldn't send text from a POST to a different GET", async () => {
			const path1 = "/stuff1";
			const path2 = "/stuff2";
			const url = (p: string) => `http://example.com${p}`;

			// The get request should wait for the post request to complete
			const getResponsePromise1 = worker.fetch(url(path1));
			const getResponsePromise2 = worker.fetch(url(path2));

			// The post request to the same path should receive a response that the text was consumed
			const postResponse1 = await worker.fetch(url(path1), {
				method: "POST",
				body: "Hello World 12345",
			});
			expect(postResponse1.status).toBe(200);
			const postText1 = await postResponse1.text();
			expect(postText1).toBe("The text was consumed!");

			const postResponse2 = await worker.fetch(url(path2), {
				method: "POST",
				body: "Hello World 789",
			});
			expect(postResponse2.status).toBe(200);
			const postText2 = await postResponse2.text();
			expect(postText2).toBe("The text was consumed!");

			// The get request should now receive the text
			const getResponse1 = await getResponsePromise1;
			expect(getResponse1.status).toBe(200);
			const text1 = await getResponse1.text();
			expect(text1).toBe("Hello World 12345");

			const getResponse2 = await getResponsePromise2;
			expect(getResponse2.status).toBe(200);
			const text2 = await getResponse2.text();
			expect(text2).toBe("Hello World 789");
		});

		it("Should not send the same POST twice", async () => {
			const path = "/stuff1";
			const url = (p: string) => `http://example.com${p}`;

			// The get request should wait for the post request to complete
			const getResponsePromise1 = worker.fetch(url(path));

			// The post request to the same path should receive a response that the text was consumed
			const postResponse1 = await worker.fetch(url(path), {
				method: "POST",
				body: "Hello World 12345",
			});
			expect(postResponse1.status).toBe(200);
			const postText1 = await postResponse1.text();
			expect(postText1).toBe("The text was consumed!");

			// The get request should now receive the text
			const getResponse1 = await getResponsePromise1;
			expect(getResponse1.status).toBe(200);
			const text1 = await getResponse1.text();
			expect(text1).toBe("Hello World 12345");

			// The next get request should wait for the next post request to complete
			const getResponsePromise2 = worker.fetch(url(path));

			// Send a new POST with different text
			const postResponse2 = await worker.fetch(url(path), {
				method: "POST",
				body: "Hello World 789",
			});
			expect(postResponse2.status).toBe(200);
			const postText2 = await postResponse2.text();
			expect(postText2).toBe("The text was consumed!");

			// The get request should receive the new text, not the old text
			const getResponse2 = await getResponsePromise2;
			expect(getResponse2.status).toBe(200);
			const text2 = await getResponse2.text();
			expect(text2).toBe("Hello World 789");
		});
	});
});
```

Find the [full code for this example on GitHub](https://github.com/jahands/do-demo).

---

# Metrics and GraphQL analytics

URL: https://developers.cloudflare.com/durable-objects/observability/graphql-analytics/

import { GlossaryTooltip } from "~/components";

<GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> expose analytics for Durable Object namespace-level and request-level metrics.

The metrics displayed in the [Cloudflare dashboard](https://dash.cloudflare.com/) charts are queried from Cloudflare's [GraphQL Analytics API](/analytics/graphql-api/). You can access the metrics [programmatically via GraphQL](#query-via-the-graphql-api) or HTTP client.

:::note[Durable Object namespace]

A Durable Object namespace is a set of Durable Objects that can be addressed by name, backed by the same class. There is only one Durable Object namespace per class. A Durable Object namespace can contain any number of Durable Objects.
:::

## View metrics and analytics via the dashboard

Per-namespace analytics for Durable Objects are available in the Cloudflare dashboard. To view current and historical metrics for a namespace:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to [**Workers & Pages** > **Durable Objects**](https://dash.cloudflare.com/?to=/:account/workers/durable-objects).
3. View account-level Durable Objects usage.
4. Select an existing namespace.
5. Select the **Metrics** tab.

You can optionally select a time window to query. This defaults to the last 24 hours.

## Query via the GraphQL API

Durable Object metrics are powered by GraphQL.

The datasets that include Durable Object metrics include:

* `durableObjectsInvocationsAdaptiveGroups`
* `durableObjectsPeriodicGroups`
* `durableObjectsStorageGroups`
* `durableObjectsSubrequestsAdaptiveGroups`

Use [GraphQL Introspection](/analytics/graphql-api/features/discovery/introspection/) to get information on the fields exposed by each datasets.

### WebSocket metrics

Durable Objects using [WebSockets](/durable-objects/best-practices/websockets/) will see request metrics across several GraphQL datasets because WebSockets have different types of requests.

* Metrics for a WebSocket connection itself is represented in `durableObjectsInvocationsAdaptiveGroups` once the connection closes. Since WebSocket connections are long-lived, connections often do not terminate until the Durable Object terminates.
* Metrics for incoming and outgoing WebSocket messages on a WebSocket connection are available in `durableObjectsPeriodicGroups`. If a WebSocket connection uses [WebSocket Hibernation](/durable-objects/best-practices/websockets/#websocket-hibernation-api), incoming WebSocket messages are instead represented in `durableObjectsInvocationsAdaptiveGroups`.

## Example GraphQL query for Durable Objects

```js
  viewer {
    /*
    Replace with your account tag, the 32 hex character id visible at the beginning of any url
    when logged in to dash.cloudflare.com or under "Account ID" on the sidebar of the Workers & Pages Overview
    */
    accounts(filter: {accountTag: "your account tag here"}) {
      // Replace dates with a recent date
      durableObjectsInvocationsAdaptiveGroups(filter: {date_gt: "2023-05-23"}, limit: 1000) {
        sum {
          // Any other fields found through introspection can be added here
          requests
          responseBodySize
        }
      }
      durableObjectsPeriodicGroups(filter: {date_gt: "2023-05-23"}, limit: 1000) {
        sum {
          cpuTime
        }
      }
      durableObjectsStorageGroups(filter: {date_gt: "2023-05-23"}, limit: 1000) {
        max {
          storedBytes
        }
      }
    }
  }
```

Refer to the [Querying Workers Metrics with GraphQL](/analytics/graphql-api/tutorials/querying-workers-metrics/) tutorial for authentication and to learn more about querying Workers datasets.

## Additional resources

- For instructions on setting up a Grafana dashboard to query Cloudflare's GraphQL Analytics API, refer to [Grafana Dashboard starter for Durable Object metrics](https://github.com/TimoWilhelm/grafana-do-dashboard).

---

# Build a WebSocket server

URL: https://developers.cloudflare.com/durable-objects/examples/websocket-server/

import { TabItem, Tabs, GlossaryTooltip, WranglerConfig } from "~/components";

This example shows how to build a WebSocket server using <GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> and Workers. The example exposes an endpoint to create a new WebSocket connection. This WebSocket connection echos any message while including the total number of WebSocket connections currently established. For more information, refer to [Use Durable Objects with WebSockets](/durable-objects/best-practices/websockets/).

:::caution

WebSocket connections pin your Durable Object to memory, and so duration charges will be incurred so long as the WebSocket is connected (regardless of activity). To avoid duration charges during periods of inactivity, use the [WebSocket Hibernation API](/durable-objects/examples/websocket-hibernation-server/), which only charges for duration when JavaScript is actively executing.

:::

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { DurableObject } from "cloudflare:workers";

// Worker
export default {
	async fetch(request, env, ctx) {
		if (request.url.endsWith("/websocket")) {
			// Expect to receive a WebSocket Upgrade request.
			// If there is one, accept the request and return a WebSocket Response.
			const upgradeHeader = request.headers.get("Upgrade");
			if (!upgradeHeader || upgradeHeader !== "websocket") {
				return new Response("Durable Object expected Upgrade: websocket", {
					status: 426,
				});
			}

			// This example will refer to the same Durable Object,
			// since the name "foo" is hardcoded.
			let id = env.WEBSOCKET_SERVER.idFromName("foo");
			let stub = env.WEBSOCKET_SERVER.get(id);

			return stub.fetch(request);
		}

		return new Response(null, {
			status: 400,
			statusText: "Bad Request",
			headers: {
				"Content-Type": "text/plain",
			},
		});
	},
};

// Durable Object
export class WebSocketServer extends DurableObject {
	currentlyConnectedWebSockets;

	constructor(ctx, env) {
		// This is reset whenever the constructor runs because
		// regular WebSockets do not survive Durable Object resets.
		//
		// WebSockets accepted via the Hibernation API can survive
		// a certain type of eviction, but we will not cover that here.
		super(ctx, env);
		this.currentlyConnectedWebSockets = 0;
	}

	async fetch(request) {
		// Creates two ends of a WebSocket connection.
		const webSocketPair = new WebSocketPair();
		const [client, server] = Object.values(webSocketPair);

		// Calling `accept()` tells the runtime that this WebSocket is to begin terminating
		// request within the Durable Object. It has the effect of "accepting" the connection,
		// and allowing the WebSocket to send and receive messages.
		server.accept();
		this.currentlyConnectedWebSockets += 1;

		// Upon receiving a message from the client, the server replies with the same message,
		// and the total number of connections with the "[Durable Object]: " prefix
		server.addEventListener("message", (event) => {
			server.send(
				`[Durable Object] currentlyConnectedWebSockets: ${this.currentlyConnectedWebSockets}`,
			);
		});

		// If the client closes the connection, the runtime will close the connection too.
		server.addEventListener("close", (cls) => {
			this.currentlyConnectedWebSockets -= 1;
			server.close(cls.code, "Durable Object is closing WebSocket");
		});

		return new Response(null, {
			status: 101,
			webSocket: client,
		});
	}
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
	WEBSOCKET_SERVER: DurableObjectNamespace<WebSocketServer>;
}

// Worker
export default {
	async fetch(request, env, ctx): Promise<Response> {
		if (request.url.endsWith("/websocket")) {
			// Expect to receive a WebSocket Upgrade request.
			// If there is one, accept the request and return a WebSocket Response.
			const upgradeHeader = request.headers.get("Upgrade");
			if (!upgradeHeader || upgradeHeader !== "websocket") {
				return new Response("Durable Object expected Upgrade: websocket", {
					status: 426,
				});
			}

			// This example will refer to the same Durable Object,
			// since the name "foo" is hardcoded.
			let id = env.WEBSOCKET_SERVER.idFromName("foo");
			let stub = env.WEBSOCKET_SERVER.get(id);

			return stub.fetch(request);
		}

		return new Response(null, {
			status: 400,
			statusText: "Bad Request",
			headers: {
				"Content-Type": "text/plain",
			},
		});
	},
} satisfies ExportedHandler<Env>;

// Durable Object
export class WebSocketServer extends DurableObject {
	currentlyConnectedWebSockets: number;

	constructor(ctx: DurableObjectState, env: Env) {
		// This is reset whenever the constructor runs because
		// regular WebSockets do not survive Durable Object resets.
		//
		// WebSockets accepted via the Hibernation API can survive
		// a certain type of eviction, but we will not cover that here.
		super(ctx, env);
		this.currentlyConnectedWebSockets = 0;
	}

	async fetch(request: Request): Promise<Response> {
		// Creates two ends of a WebSocket connection.
		const webSocketPair = new WebSocketPair();
		const [client, server] = Object.values(webSocketPair);

		// Calling `accept()` tells the runtime that this WebSocket is to begin terminating
		// request within the Durable Object. It has the effect of "accepting" the connection,
		// and allowing the WebSocket to send and receive messages.
		server.accept();
		this.currentlyConnectedWebSockets += 1;

		// Upon receiving a message from the client, the server replies with the same message,
		// and the total number of connections with the "[Durable Object]: " prefix
		server.addEventListener("message", (event: MessageEvent) => {
			server.send(
				`[Durable Object] currentlyConnectedWebSockets: ${this.currentlyConnectedWebSockets}`,
			);
		});

		// If the client closes the connection, the runtime will close the connection too.
		server.addEventListener("close", (cls: CloseEvent) => {
			this.currentlyConnectedWebSockets -= 1;
			server.close(cls.code, "Durable Object is closing WebSocket");
		});

		return new Response(null, {
			status: 101,
			webSocket: client,
		});
	}
}
```

</TabItem> </Tabs>

Finally, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the <GlossaryTooltip term="namespace">namespace</GlossaryTooltip> and class name chosen previously.

<WranglerConfig>

```toml title="wrangler.toml"
name = "websocket-server"
main = "src/index.ts"

[[durable_objects.bindings]]
name = "WEBSOCKET_SERVER"
class_name = "WebSocketServer"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["WebSocketServer"]
```

</WranglerConfig>

### Related resources

- [Durable Objects: Edge Chat Demo](https://github.com/cloudflare/workers-chat-demo).

---

# Observability

URL: https://developers.cloudflare.com/durable-objects/observability/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Troubleshooting

URL: https://developers.cloudflare.com/durable-objects/observability/troubleshooting/

## Debugging

[`wrangler dev`](/workers/wrangler/commands/#dev) and [`wrangler tail`](/workers/wrangler/commands/#tail) are both available to help you debug your Durable Objects.

The `wrangler dev --remote` command opens a tunnel from your local development environment to Cloudflare's global network, letting you test your Durable Objects code in the Workers environment as you write it.

`wrangler tail` displays a live feed of console and exception logs for each request served by your Worker code, including both normal Worker requests and Durable Object requests. After running `npx wrangler deploy`, you can use `wrangler tail` in the root directory of your Worker project and visit your Worker URL to see console and error logs in your terminal.

## Common errors

### No event handlers were registered. This script does nothing.

In your Wrangler file, make sure the `dir` and `main` entries point to the correct file containing your Worker code, and that the file extension is `.mjs` instead of `.js` if using ES modules syntax.

### Cannot apply `--delete-class` migration to class.

When deleting a migration using `npx wrangler deploy --delete-class <ClassName>`, you may encounter this error: `"Cannot apply --delete-class migration to class <ClassName> without also removing the binding that references it"`. You should remove the corresponding binding under `[durable_objects]` in the [Wrangler configuration file](/workers/wrangler/configuration/) before attempting to apply `--delete-class` again.

### Durable Object is overloaded.

A single instance of a Durable Object cannot do more work than is possible on a single thread. These errors mean the Durable Object has too much work to keep up with incoming requests:

- `Error: Durable Object is overloaded. Too many requests queued.` The total count of queued requests is too high.
- `Error: Durable Object is overloaded. Too much data queued.` The total size of data in queued requests is too high.
- `Error: Durable Object is overloaded. Requests queued for too long.` The oldest request has been in the queue too long.
- `Error: Durable Object is overloaded. Too many requests for the same object within a 10 second window.` The number of requests for a Durable Object is too high within a short span of time (10 seconds). This error indicates a more extreme level of overload.

To solve this error, you can either do less work per request, or send fewer requests. For example, you can split the requests among more instances of the Durable Object.

These errors and others that are due to overload will have an [`.overloaded` property](/durable-objects/best-practices/error-handling) set on their exceptions, which can be used to avoid retrying overloaded operations.

### Your account is generating too much load on Durable Objects. Please back off and try again later.

There is a limit on how quickly you can create new [stubs](/durable-objects/api/stub) for new or existing Durable Objects. Those lookups are usually cached, meaning attempts for the same set of recently accessed Durable Objects should be successful, so catching this error and retrying after a short wait is safe. If possible, also consider spreading those lookups across multiple requests.

### Durable Object reset because its code was updated.

Reset in error messages refers to in-memory state. Any durable state that has already been successfully persisted via `state.storage` is not affected.

Refer to [Global Uniqueness](/durable-objects/platform/known-issues/#global-uniqueness).

### Durable Object storage operation exceeded timeout which caused object to be reset.

To prevent indefinite blocking, there is a limit on how much time storage operations can take. In Durable Objects containing a sufficiently large number of key-value pairs, `deleteAll()` may hit that time limit and fail. When this happens, note that each `deleteAll()` call does make progress and that it is safe to retry until it succeeds. Otherwise contact [Cloudflare support](/support/contacting-cloudflare-support/).

### Your account is doing too many concurrent storage operations. Please back off and try again later.

Besides the suggested approach of backing off, also consider changing your code to use `state.storage.get(keys Array<string>)` rather than multiple individual `state.storage.get(key)` calls where possible.

---

# Known issues

URL: https://developers.cloudflare.com/durable-objects/platform/known-issues/

import { GlossaryTooltip } from "~/components";

Durable Objects is generally available. However, there are some known issues.

## Global uniqueness

Global uniqueness guarantees there is only a single instance of a <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip> with a given ID running at once, across the world.

Uniqueness is enforced upon starting a new event (such as receiving an HTTP request), and upon accessing storage.

After an event is received, if the event takes some time to execute and does not ever access its durable storage, then it is possible that the Durable Object may no longer be current, and some other instance of the same Durable Object ID will have been created elsewhere. If the event accesses storage at this point, it will receive an [exception](/durable-objects/observability/troubleshooting/). If the event completes without ever accessing storage, it may not ever realize that the Durable Object was no longer current.

A Durable Object may be replaced in the event of a network partition or a software update (including either an update of the Durable Object's class code, or of the Workers system itself). Enabling `wrangler tail` or [Cloudflare dashboard](https://dash.cloudflare.com/) logs requires a software update.

## Code updates

Code changes for Workers and Durable Objects are released globally in an eventually consistent manner. Because each Durable Object is globally unique, the situation can arise that a request arrives to the latest version of your Worker (running in one part of the world), which then calls to a unique Durable Object running the previous version of your code for a short period of time (typically seconds to minutes). If you create a [gradual deployment](/workers/configuration/versions-and-deployments/gradual-deployments/), this period of time is determined by how long your live deployment is configured to use more than one version.

For this reason, it is best practice to ensure that API changes between your Workers and Durable Objects are forward and backward compatible across code updates.

## Development tools

[`wrangler tail`](/workers/wrangler/commands/#tail) logs from requests that are upgraded to WebSockets are delayed until the WebSocket is closed. `wrangler tail` should not be connected to a Worker that you expect will receive heavy volumes of traffic.

The Workers editor in the [Cloudflare dashboard](https://dash.cloudflare.com/) allows you to interactively edit and preview your Worker and Durable Objects. In the editor, Durable Objects can only be talked to by a preview request if the Worker being previewed both exports the Durable Object class and binds to it. Durable Objects exported by other Workers cannot be talked to in the editor preview.

[`wrangler dev`](/workers/wrangler/commands/#dev) has read access to Durable Object storage, but writes will be kept in memory and will not affect persistent data. However, if you specify the `script_name` explicitly in the [Durable Object binding](/workers/runtime-apis/bindings/), then writes will affect persistent data. Wrangler will emit a warning in that case.

## Alarms in local development

Currently, when developing locally (using `npx wrangler dev`), Durable Object [alarm methods](/durable-objects/api/alarms) may fail after a hot reload (if you edit the code while the code is running locally).

To avoid this issue, when using Durable Object alarms, close and restart your `wrangler dev` command after editing your code.

---

# Platform

URL: https://developers.cloudflare.com/durable-objects/platform/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Limits

URL: https://developers.cloudflare.com/durable-objects/platform/limits/

import { Render, GlossaryTooltip, Details, WranglerConfig } from "~/components";

Durable Objects are a special kind of Worker, so [Workers Limits](/workers/platform/limits/) apply according to your Workers plan. In addition, Durable Objects have specific limits as listed in this page.

## SQLite-backed Durable Objects general limits

| Feature                                  | Limit |
| ---------------------------------------- | ----------------------------------------------------------- |
| Number of Objects                        | Unlimited (within an account or of a given class)           |
| Maximum Durable Object classes           | 500 (Workers Paid) / 100 (Free) [^1]                        |
| Storage per account                      | Unlimited (Workers Paid) / 5GB (Free) [^2]                  |
| Storage per class                        | Unlimited [^3]                                              |
| Storage per Durable Object               | 10 GB [^3]                                                  |
| Key size                                 | Key and value combined cannot exceed 2 MB                   |
| Value size                               | Key and value combined cannot exceed 2 MB                   |
| WebSocket message size                   | 1 MiB (only for received messages)                          |
| CPU per request                          | 30 seconds (default) / configurable to 5 minutes of [active CPU time](/workers/platform/limits/#cpu-time) [^4] |

[^1]: Identical to the Workers [script limit](/workers/platform/limits/).
[^2]: Durable Objects both bills and measures storage based on a gigabyte <br/> (1 GB = 1,000,000,000 bytes) and not a gibibyte (GiB). <br/>
[^3]: Accounts on the Workers Free plan are limited to 5 GB total Durable Objects storage.
[^4]: Each incoming HTTP request or WebSocket *message* resets the remaining available CPU time to 30 seconds. This allows the Durable Object to consume up to 30 seconds of compute after each incoming network request, with each new network request resetting the timer. If you consume more than 30 seconds of compute between incoming network requests, there is a heightened chance that the individual Durable Object is evicted and reset. CPU time per request invocation [can be increased](/durable-objects/platform/limits/#increasing-durable-object-cpu-limits).

<Details header="Footnotes" open={true}>
1. Identical to the Workers [script limit](/workers/platform/limits/).

2. Durable Objects both bills and measures storage based on a gigabyte <br/> (1 GB = 1,000,000,000 bytes) and not a gibibyte (GiB). <br/>

3. Accounts on the Workers Free plan are limited to 5GB total Durable Objects storage.

4. Each incoming HTTP request or WebSocket *message* resets the remaining available CPU time to 30 seconds. This allows the Durable Object to consume up to 30 seconds of compute after each incoming network request, with each new network request resetting the timer. If you consume more than 30 seconds of compute between incoming network requests, there is a heightened chance that the individual Durable Object is evicted and reset. CPU time per request invocation [can be increased](/durable-objects/platform/limits/#increasing-durable-object-cpu-limits).
</Details>

### SQL storage limits

For Durable Object classes with [SQLite storage](/durable-objects/api/storage-api/#sql-storage) these SQL limits apply:

| SQL                                                      | Limit                                           |
| -------------------------------------------------------- | ----------------------------------------------- |
| Maximum number of columns per table                      | 100                                             |
| Maximum number of rows per table                         | Unlimited (excluding per-object storage limits) |
| Maximum string, `BLOB` or table row size                 | 2 MB                                            |
| Maximum SQL statement length                             | 100 KB                                          |
| Maximum bound parameters per query                       | 100                                             |
| Maximum arguments per SQL function                       | 32                                              |
| Maximum characters (bytes) in a `LIKE` or `GLOB` pattern | 50 bytes                                        |

## Key-value backed Durable Objects general limits

<Render file="do-plans-note"/>

| Feature                                  | Limit for class with key-value storage backend                   |
| ---------------------------------------- | ---------------------------------------------------------------- |
| Number of Objects                        | Unlimited (within an account or of a given class)                |
| Maximum Durable Object classes           | 500 (Workers Paid) / 100 (Free) [^5]                             |
| Storage per account                      | 50 GB (can be raised by contacting Cloudflare) [^6]              |
| Storage per class                        | Unlimited                                                        |
| Storage per Durable Object               | Unlimited                                                        |
| Key size                                 | 2 KiB (2048 bytes)                                               |
| Value size                               | 128 KiB (131072 bytes)                                           |
| WebSocket message size                   | 1 MiB (only for received messages)                               |
| CPU per request                          | 30s (including WebSocket messages) [^7]                          |

[^5]: Identical to the Workers [script limit](/workers/platform/limits/).
[^6]: Durable Objects both bills and measures storage based on a gigabyte <br/> (1 GB = 1,000,000,000 bytes) and not a gibibyte (GiB). <br/>
[^7]: Each incoming HTTP request or WebSocket *message* resets the remaining available CPU time to 30 seconds. This allows the Durable Object to consume up to 30 seconds of compute after each incoming network request, with each new network request resetting the timer. If you consume more than 30 seconds of compute between incoming network requests, there is a heightened chance that the individual Durable Object is evicted and reset. CPU time per request invocation [can be increased](/durable-objects/platform/limits/#increasing-durable-object-cpu-limits).

<Details header="Footnotes" open={true}>
5. Identical to the Workers [script limit](/workers/platform/limits/).

6. Durable Objects both bills and measures storage based on a gigabyte <br/> (1 GB = 1,000,000,000 bytes) and not a gibibyte (GiB). <br/>

7. Each incoming HTTP request or WebSocket *message* resets the remaining available CPU time to 30 seconds. This allows the Durable Object to consume up to 30 seconds of compute after each incoming network request, with each new network request resetting the timer. If you consume more than 30 seconds of compute between incoming network requests, there is a heightened chance that the individual Durable Object is evicted and reset. CPU time per request invocation [can be increased](/durable-objects/platform/limits/#increasing-durable-object-cpu-limits).
</Details>

<Render file="limits_increase" product="workers" />

## Frequently Asked Questions

### How much work can a single Durable Object do?

Durable Objects can scale horizontally across many Durable Objects. Each individual Object is inherently single-threaded.

- An individual Object has a soft limit of 1,000 requests per second. You can have an unlimited number of individual objects per namespace.
- A simple [storage](/durable-objects/api/storage-api/) `get()` on a small value that directly returns the response may realize a higher request throughput compared to a Durable Object that (for example) serializes and/or deserializes large JSON values.
- Similarly, a Durable Object that performs multiple `list()` operations may be more limited in terms of request throughput.

A Durable Object that receives too many requests will, after attempting to queue them, return an [overloaded](/durable-objects/observability/troubleshooting/#durable-object-is-overloaded) error to the caller.

### How many Durable Objects can I create?

Durable Objects are designed such that the number of individual objects in the system do not need to be limited, and can scale horizontally.

- You can create and run as many separate Durable Objects as you want within a given Durable Object <GlossaryTooltip term="namespace">namespace</GlossaryTooltip>.
- The main limit to your usage of Durable Objects is the total storage limit per account.
- If you need more storage, contact your account team or complete the [Limit Increase Request Form](https://forms.gle/ukpeZVLWLnKeixDu7) and we will contact you with next steps.

### Increasing Durable Object CPU limits

Durable Objects are Worker scripts, and have the same [per invocation CPU limits](/workers/platform/limits/#worker-limits) as any Workers do. Note that CPU time is active processing time: not time spent waiting on network requests, storage calls, or other general I/O, which don't count towards your CPU time or Durable Objects compute consumption.

By default, the maximum CPU time per Durable Objects invocation (HTTP request, WebSocket message, or Alarm) is set to 30 seconds, but can be increased for all Durable Objects associated with a Durable Object definition by setting `limits.cpu_ms` in your Wrangler configuration:

<WranglerConfig>

```jsonc
{
  // ...rest of your configuration...
  "limits": {
    "cpu_ms": 300000, // 300,000 milliseconds = 5 minutes
  },
  // ...rest of your configuration...
}
```

</WranglerConfig>

---

# Pricing

URL: https://developers.cloudflare.com/durable-objects/platform/pricing/

import { Render } from "~/components"

Durable Objects can incur two types of billing: compute and storage.

<Render file="do-plans-note"/>

On Workers Free plan:
- If you exceed any one of the free tier limits, further operations of that type will fail with an error.
- Daily free limits reset at 00:00 UTC.

<Render file="durable-objects-pricing" product="durable-objects" params={{product:"durable-objects"}}/>

## Compute billing examples

These examples exclude the costs for the Workers calling the Durable Objects. When modelling the costs of a Durable Object, note that:

* Inactive objects receiving no requests do not incur any duration charges.
* The [WebSocket Hibernation API](/durable-objects/best-practices/websockets/#websocket-hibernation-api) can dramatically reduce duration-related charges for Durable Objects communicating with clients over the WebSocket protocol, especially if messages are only transmitted occasionally at sparse intervals.

### Example 1

This example represents a simple Durable Object used as a co-ordination service invoked via HTTP.

* A single Durable Object was called by a Worker 1.5 million times
* It is active for 1,000,000 seconds in the month

In this scenario, the estimated monthly cost would be calculated as:

**Requests**:

* (1.5 million requests - included 1 million requests) x $0.15 / 1,000,000 = $0.075

**Compute Duration**:

* 1,000,000 seconds \* 128 MB / 1 GB = 128,000 GB-s
* (128,000 GB-s - included 400,000 GB-s) x $12.50 / 1,000,000 = $0.00

**Estimated total**: \~$0.075 (requests) + $0.00 (compute duration) + minimum $5/mo usage = $5.08 per month

### Example 2

This example represents a moderately trafficked Durable Objects based application using WebSockets to broadcast game, chat or real-time user state across connected clients:

* 100 Durable Objects have 50 WebSocket connections established to each of them.
* Clients send approximately one message a minute for eight active hours a day, every day of the month.

In this scenario, the estimated monthly cost would be calculated as:

**Requests**:

* 50 WebSocket connections \* 100 Durable Objects to establish the WebSockets = 5,000 connections created each day \* 30 days = 150,000 WebSocket connection requests.
* 50 messages per minute \* 100 Durable Objects \* 60 minutes \* 8 hours \* 30 days = 72,000,000 WebSocket message requests.
* 150,000 + (72 million requests / 20 for WebSocket message billing ratio) = 3.75 million billing request.
* (3.75 million requests - included 1 million requests) x $0.15 / 1,000,000 = $0.41.

**Compute Duration**:

* 100 Durable Objects \* 60 seconds \* 60 minutes \* 8 hours \* 30 days = 86,400,000 seconds.
* 86,400,000 seconds \* 128 MB / 1 GB = 11,059,200 GB-s.
* (11,059,200 GB-s - included 400,000 GB-s) x $12.50 / 1,000,000 = $133.24.

**Estimated total**: $0.41 (requests) + $133.24 (compute duration) + minimum $5/mo usage = $138.65 per month.

### Example 3

This example represents a horizontally scaled Durable Objects based application using WebSockets to communicate user-specific state to a single client connected to each Durable Object.

* 100 Durable Objects each have a single WebSocket connection established to each of them.
* Clients sent one message every second of the month so that the Durable Objects were active for the entire month.

In this scenario, the estimated monthly cost would be calculated as:

**Requests**:

* 100 WebSocket connection requests.
* 1 message per second \* 100 connections \* 60 seconds \* 60 minutes \* 24 hours \* 30 days = 259,200,000 WebSocket message requests.
* 100 + (259.2 million requests / 20 for WebSocket billing ratio) = 12,960,100 requests.
* (12.9 million requests - included 1 million requests) x $0.15 / 1,000,000 = $1.79.

**Compute Duration**:

* 100 Durable Objects \* 60 seconds \* 60 minutes \* 24 hours \* 30 days = 259,200,000 seconds
* 259,200,000 seconds \* 128 MB / 1 GB = 33,177,600 GB-s
* (33,177,600 GB-s - included 400,000 GB-s) x $12.50 / 1,000,000 = $409.72

**Estimated total**: $1.79 (requests) + $409.72 (compute duration) + minimum $5/mo usage = $416.51 per month

### Example 4

This example represents a moderately trafficked Durable Objects based application using WebSocket Hibernation to broadcast game, chat or real-time user state across connected clients:

* 100 Durable Objects each have 100 Hibernatable WebSocket connections established to each of them.
* Clients send one message per minute, and it takes 10ms to process a single message in the `webSocketMessage()` handler. Since each Durable Object handles 100 WebSockets, cumulatively each Durable Object will be actively executing JS for 1 second each minute (100 WebSockets \* 10ms).

In this scenario, the estimated monthly cost would be calculated as:

**Requests**:

* 100 WebSocket connections \* 100 Durable Objects to establish the WebSockets = 10,000 initial WebSocket connection requests.
* 100 messages per minute<sup>1</sup> \* 100 Durable Objects \* 60 minutes \* 24 hours \* 30 days = 432,000,000 requests.
* 10,000 + (432 million requests / 20 for WebSocket billing ratio) = 21,610,000 million requests.
* (21.6 million requests - included 1 million requests) x $0.15 / 1,000,000 = $3.09.

**Compute Duration**:

* 100 Durable Objects \* 1 second<sup>2</sup> \* 60 minutes \* 24 hours \* 30 days = 4,320,000 seconds
* 4,320,000 seconds \* 128 MB / 1 GB = 552,960 GB-s
* (552,960 GB-s - included 400,000 GB-s) x $12.50 / 1,000,000 = $1.91

**Estimated total**: $3.09 (requests) + $1.91 (compute duration) + minimum $5/mo usage = $10.00 per month

<sup>1</sup> 100 messages per minute comes from the fact that 100 clients connect to each DO, and each sends 1 message per minute.

<sup>2</sup> The example uses 1 second because each Durable Object is active for 1 second per minute. This can also be thought of as 432 million requests that each take 10 ms to execute (4,320,000 seconds).

## Frequently Asked Questions

### Does an empty table / SQLite database contribute to my storage?

Yes, although minimal. Empty tables can consume at least a few kilobytes, based on the number of columns (table width) in the table. An empty SQLite database consumes approximately 12 KB of storage.

### Does metadata stored in Durable Objects count towards my storage?

All writes to a SQLite-backed Durable Object stores nominal amounts of metadata in internal tables in the Durable Object, which counts towards your billable storage.

The metadata remains in the Durable Object until you call [`deleteAll()`](/durable-objects/api/storage-api/#deleteall).

---

# Data security

URL: https://developers.cloudflare.com/durable-objects/reference/data-security/

This page details the data security properties of Durable Objects, including:

* Encryption-at-rest (EAR).
* Encryption-in-transit (EIT).
* Cloudflare's compliance certifications.

## Encryption at Rest

All Durable Object data, including metadata, is encrypted at rest. Encryption and decryption are automatic, do not require user configuration to enable, and do not impact the effective performance of Durable Objects.

Encryption keys are managed by Cloudflare and securely stored in the same key management systems we use for managing encrypted data across Cloudflare internally.

Encryption at rest is implemented using the Linux Unified Key Setup (LUKS) disk encryption specification and [AES-256](https://www.cloudflare.com/learning/ssl/what-is-encryption/), a widely tested, highly performant and industry-standard encryption algorithm.

## Encryption in Transit

Data transfer between a Cloudflare Worker, and/or between nodes within the Cloudflare network and Durable Objects is secured using the same [Transport Layer Security](https://www.cloudflare.com/learning/ssl/transport-layer-security-tls/) (TLS/SSL).

API access via the HTTP API or using the [wrangler](/workers/wrangler/install-and-update/) command-line interface is also over TLS/SSL (HTTPS).

## Compliance

To learn more about Cloudflare's adherence to industry-standard security compliance certifications, visit the Cloudflare [Trust Hub](https://www.cloudflare.com/trust-hub/compliance-resources/).

---

# Data location

URL: https://developers.cloudflare.com/durable-objects/reference/data-location/

import { GlossaryTooltip } from "~/components";

## Restrict Durable Objects to a jurisdiction

Jurisdictions are used to create <GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> that only run and store data within a region to comply with local regulations such as the [GDPR](https://gdpr-info.eu/) or [FedRAMP](https://blog.cloudflare.com/cloudflare-achieves-fedramp-authorization/).

Workers may still access Durable Objects constrained to a jurisdiction from anywhere in the world. The jurisdiction constraint only controls where the Durable Object itself runs and persists data. Consider using [Regional Services](/data-localization/regional-services/) to control the regions from which Cloudflare responds to requests.

:::note[Logging]

A [`DurableObjectId`](/durable-objects/api/id) will be logged outside of the specified jurisdiction for billing and debugging purposes.

:::

Durable Objects can be restricted to a specific jurisdiction by creating a [`DurableObjectNamespace`](/durable-objects/api/namespace/) restricted to a jurisdiction. All [Durable Object ID methods](/durable-objects/api/id/) are valid on IDs within a namespace restricted to a jurisdiction.

```js
const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu");
const euId = euSubnamespace.newUniqueId();
```

- It is possible to have the same name represent different IDs in different jurisdictions.

  ```js
  const euId1 = env.MY_DURABLE_OBJECT.idFromName("my-name");
  const euId2 = env.MY_DURABLE_OBJECT.jurisdiction("eu").idFromName("my-name");
  console.assert(!euId1.equal(euId2), "This should always be true");
  ```

- You will run into an error if the jurisdiction on your [`DurableObjectNamespace`](/durable-objects/api/namespace/) and the jurisdiction on [`DurableObjectId`](/durable-objects/api/id) are different.
- You will not run into an error if the [`DurableObjectNamespace`](/durable-objects/api/namespace/) is not associated with a jurisdiction.
- All [Durable Object ID methods](/durable-objects/api/id/) are valid on IDs within a namespace restricted to a jurisdiction.

  ```js
  const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu");
  const euId = euSubnamespace.idFromName(name);
  const stub = env.MY_DURABLE_OBJECT.get(euId);
  ```

:::caution[Use `DurableObjectNamespace.jurisdiction`]

When specifying a jurisdiction, Cloudflare recommends you first create a namespace restricted to a jurisdiction, using `const euSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("eu")`.

Note that it is also possible to specify a jurisdiction by creating an individual [`DurableObjectId`](/durable-objects/api/id) restricted to a jurisdiction, using `const euId = env.MY_DURABLE_OBJECT.newUniqueId({ jurisdiction: "eu" })`.

**However, Cloudflare does not recommend this approach.**
:::

### Supported locations

| Parameter | Location                     |
| --------- | ---------------------------- |
| eu        | The European Union           |
| fedramp   | FedRAMP-compliant data centers |

## Provide a location hint

Durable Objects, as with any stateful API, will often add response latency as requests must be forwarded to the data center where the Durable Object, or state, is located.

Durable Objects do not currently change locations after they are created<sup>1</sup>. By default, a Durable Object is instantiated in a data center close to where the initial `get()` request is made. This may not be in the same data center that the `get()` request is made from, but in most cases, it will be in close proximity.

:::caution[Initial requests to Durable Objects]

It can negatively impact latency to pre-create Durable Objects prior to the first client request or when the first client request is not representative of where the majority of requests will come from. It is better for latency to create Durable Objects in response to actual production traffic or provide explicit location hints.

:::

Location hints are the mechanism provided to specify the location that a Durable Object should be located regardless of where the initial `get()` request comes from.

To manually create Durable Objects in another location, provide an optional `locationHint` parameter to `get()`. Only the first call to `get()` for a particular Object will respect the hint.

```js
let durableObjectStub = OBJECT_NAMESPACE.get(id, { locationHint: "enam" });
```

:::caution

Hints are a best effort and not a guarantee. Unlike with jurisdictions, Durable Objects will not necessarily be instantiated in the hinted location, but instead instantiated in a data center selected to minimize latency from the hinted location.
:::

### Supported locations

| Parameter | Location                   |
| --------- | -------------------------- |
| wnam      | Western North America      |
| enam      | Eastern North America      |
| sam       | South America <sup>2</sup> |
| weur      | Western Europe             |
| eeur      | Eastern Europe             |
| apac      | Asia-Pacific               |
| oc        | Oceania                    |
| afr       | Africa <sup>2</sup>        |
| me        | Middle East <sup>2</sup>   |

<sup>1</sup> Dynamic relocation of existing Durable Objects is planned for the future.

<sup>2</sup> Durable Objects currently do not spawn in this location. Instead, the Durable Object will spawn in a nearby location which does support Durable Objects. For example, Durable Objects hinted to South America spawn in Eastern North America instead.

## Additional resources

- You can find our more about where Durable Objects are located using the website: [Where Durable Objects Live](https://where.durableobjects.live/).

---

# Environments

URL: https://developers.cloudflare.com/durable-objects/reference/environments/

import { WranglerConfig } from "~/components";

Environments provide isolated spaces where your code runs with specific dependencies and configurations. This can be useful for a number of reasons, such as compatibility testing or version management. Using different environments can help with code consistency, testing, and production segregation, which reduces the risk of errors when deploying code.

## Wrangler environments

[Wrangler](/workers/wrangler/install-and-update/) allows you to deploy the same Worker application with different configuration for each [environment](/workers/wrangler/environments/).

If you are using Wrangler environments, you must specify any [Durable Object bindings](/workers/runtime-apis/bindings/) you wish to use on a per-environment basis.

Durable Object bindings are not inherited. For example, you can define an environment named `staging` as below:

<WranglerConfig>

```toml
[env.staging]
durable_objects.bindings = [
  {name = "EXAMPLE_CLASS", class_name = "DurableObjectExample"}
]
```

</WranglerConfig>

Because Wrangler appends the [environment name](/workers/wrangler/environments/) to the top-level name when publishing, for a Worker named `worker-name` the above example is equivalent to:



<WranglerConfig>

```toml
[env.staging]
durable_objects.bindings = [
  {name = "EXAMPLE_CLASS", class_name = "DurableObjectExample", script_name = "worker-name-staging"}
]
```

</WranglerConfig>

`"EXAMPLE_CLASS"` in the staging environment is bound to a different Worker code name compared to the top-level `"EXAMPLE_CLASS"` binding, and will therefore access different Durable Objects with different persistent storage.

If you want an environment-specific binding that accesses the same Objects as the top-level binding, specify the top-level Worker code name explicitly using `script_name`:



<WranglerConfig>

```toml
[env.another]
durable_objects.bindings = [
  {name = "EXAMPLE_CLASS", class_name = "DurableObjectExample", script_name = "worker-name"}
]
```

</WranglerConfig>

### Migration environments

You can define a Durable Object migration for each environment, as well as at the top level. Migrations at at the environment-level override migrations at the top level.

For more information, refer to [Migration Wrangler Configuration](/durable-objects/reference/durable-objects-migrations/#migration-wrangler-configuration).

## Local development

Local development sessions create a standalone, local-only environment that mirrors the production environment, so that you can test your Worker and Durable Objects before you deploy to production.

An existing Durable Object binding of `DB` would be available to your Worker when running locally.

Refer to Workers [Local development](/workers/development-testing/bindings-per-env/).

## Remote development

KV-backed Durable Objects support remote development using the dashboard playground. The dashboard playground uses a browser version of Visual Studio Code, allowing you to rapidly iterate on your Worker entirely in your browser.

To start remote development:

1. Log in to your Cloudflare dashboard, and go to [**Workers & Pages** > **Overview**](https://dash.cloudflare.com/?to=/:account/workers-and-pages).
2. Select an existing Worker.
3. Select the **Edit code** icon located on the upper-right of the screen.

:::caution
Remote development is only available for KV-backed Durable Objects. SQLite-backed Durable Objects do not support remote development.
:::

---

# Durable Objects migrations

URL: https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/

import {
	Render,
	GlossaryTooltip,
	WranglerConfig,
	Steps,
	Details,
} from "~/components";

A migration is a mapping process from a class name to a runtime state. This process communicates the changes to the Workers runtime and provides the runtime with instructions on how to deal with those changes.

To apply a migration, you need to:

1. Edit your `wrangler.toml / wrangler.json` file, as explained below.
2. Re-deploy your Worker using `npx wrangler deploy`.

You must initiate a migration process when you:

- Create a new <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip>.
- Rename a Durable Object class.
- Delete a Durable Object class.
- Transfer an existing Durable Objects class.

:::note

Updating the code for an existing Durable Object class does not require a migration. To update the code for an existing Durable Object class, run [`npx wrangler deploy`](/workers/wrangler/commands/#deploy). This is true even for changes to how the code interacts with persistent storage. Because of [global uniqueness](/durable-objects/platform/known-issues/#global-uniqueness), you do not have to be concerned about old and new code interacting with the same storage simultaneously. However, it is your responsibility to ensure that the new code is backwards compatible with existing stored data.

:::

## Create migration

The most common migration performed is a new class migration, which informs the runtime that a new Durable Object class is being uploaded. This is also the migration you need when creating your first Durable Object class.

To apply a Create migration:

<Steps>
1. Add the following lines to your `wrangler.toml / wrangler.json` file:

    <WranglerConfig>
    ```toml
    [[migrations]]
    tag = "<v1>" # Migration identifier. This should be unique for each migration entry
    new_sqlite_classes = ["<NewDurableObjectClass>"] # Array of new classes
    # For SQLite storage backend use new_sqlite_classes=["<NewDurableObjectClass>"] instead
    ```
    </WranglerConfig>
    The Create migration contains:

    - A `tag` to identify the migration.
    - The array `new_sqlite_classes`, which contains the new Durable Object class.

2. Ensure you reference the correct name of the Durable Object class in your Worker code.
3. Deploy the Worker.
</Steps>

<Details header="Create migration example">

To create a new Durable Object binding `DURABLE_OBJECT_A`, your `wrangler.toml / wrangler.json` file should look like the following:

<WranglerConfig>
```toml
# Creating a new Durable Object class
[[durable_objects.bindings]]
name = "DURABLE_OBJECT_A"
class_name = "DurableObjectAClass"

# Add the lines below for a Create migration.

[[migrations]]
tag = "v1"
new_sqlite_classes = ["DurableObjectAClass"]

```
</WranglerConfig>

</Details>

### Create Durable Object class with key-value storage

<Render file="recommend-sqlite-do" product="durable-objects"/>

Use `new_classes` on the migration in your Worker's Wrangler file to create a Durable Object class with the key-value storage backend:

<WranglerConfig>

```toml
[[migrations]]
tag = "v1" # Should be unique for each entry
new_classes = ["MyDurableObject"] # Array of new classes
```

</WranglerConfig>

<Render file="do-plans-note" />

## Delete migration

Running a Delete migration will delete all Durable Objects associated with the deleted class, including all of their stored data.

- Do not run a Delete migration on a class without first ensuring that you are not relying on the Durable Objects within that Worker anymore, that is, first remove the binding from the Worker.
- Copy any important data to some other location before deleting.
- You do not have to run a Delete migration on a class that was renamed or transferred.

To apply a Delete migration:

<Steps>
1. Remove the binding for the class you wish to delete from the `wrangler.toml / wrangler.json` file.
2. Remove references for the class you wish to delete from your Worker code.
3. Add the following lines to your `wrangler.toml / wrangler.json` file.

    <WranglerConfig>
    ```toml
    [[migrations]]
    tag = "<v2>" # Migration identifier. This should be unique for each migration entry
    deleted_classes = ["<ClassToDelete>"] # Array of deleted class names
    ```
    </WranglerConfig>
    The Delete migration contains:

    - A `tag` to identify the migration.
    - The array `deleted_classes`, which contains the deleted Durable Object classes.

4. Deploy the Worker.
</Steps>

<Details header = "Delete migration example">
To delete a Durable Object binding `DEPRECATED_OBJECT`, your `wrangler.toml / wrangler.json` file should look like the following:

<WranglerConfig>
```toml
# Remove the binding for the DeprecatedObjectClass DO
#[[durable_objects.bindings]]
#name = "DEPRECATED_OBJECT"
#class_name = "DeprecatedObjectClass"

[[migrations]]
tag = "v3" # Should be unique for each entry
deleted_classes = ["DeprecatedObjectClass"] # Array of deleted classes

```
</WranglerConfig>
</Details>

## Rename migration

Rename migrations are used to transfer stored Durable Objects between two Durable Object classes in the same Worker code file.

To apply a Rename migration:

<Steps>
1. Update the previous class name to the new class name by editing your `wrangler.toml / wrangler.json` file in the following way:

	<WranglerConfig>
	```toml
	[[durable_objects.bindings]]
	name = "<MY_DURABLE_OBJECT>"
	class_name = "<UpdatedDurableObject>" # Update the class name to the new class name

	[[migrations]]
	tag = "<v3>" # Migration identifier. This should be unique for each migration entry
	renamed_classes = [{from = "<OldDurableObject>", to = "<UpdatedDurableObject>" }] # Array of rename directives
	```
	</WranglerConfig>

	The Rename migration contains:
	- A `tag` to identify the migration.
	- The `renamed_classes` array, which contains objects with `from` and `to` properties.
		- `from` property is the old Durable Object class name.
		- `to` property is the renamed Durable Object class name.
2. Reference the new Durable Object class name in your Worker code.
3. Deploy the Worker.
</Steps>

<Details header = "Rename migration example">

To rename a Durable Object class, from `OldName` to `UpdatedName`, your `wrangler.toml / wrangler.json` file should look like the following:

<WranglerConfig>
```toml
# Before deleting the `DeprecatedClass` remove the binding for the `DeprecatedClass`.
# Update the binding for the `DurableObjectExample` to the new class name `UpdatedName`.
[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "UpdatedName"

# Renaming classes
[[migrations]]
tag = "v3"
renamed_classes = [{from = "OldName", to = "UpdatedName" }] # Array of rename directives
```

</WranglerConfig>

</Details>

## Transfer migration

Transfer migrations are used to transfer stored Durable Objects between two Durable Object classes in different Worker code files.

If you want to transfer stored Durable Objects between two Durable Object classes in the same Worker code file, use [Rename migrations](#rename-migration) instead.

:::note
Do not run a [Create migration](#create-migration) for the destination class before running a Transfer migration. The Transfer migration will create the destination class for you.
:::

To apply a Transfer migration:

<Steps>
1. Edit your `wrangler.toml / wrangler.json` file in the following way:

    <WranglerConfig>
    ```toml
    [[durable_objects.bindings]]
    name = "<MY_DURABLE_OBJECT>"
    class_name = "<DestinationDurableObjectClass>"

    [[migrations]]
    tag = "<v4>" # Migration identifier. This should be unique for each migration entry
    transferred_classes = [{from = "<SourceDurableObjectClass>", from_script = "<SourceWorkerScript>", to = "<DestinationDurableObjectClass>" }]
    ```
    </WranglerConfig>
    The Transfer migration contains:
    - A `tag` to identify the migration.
    - The `transferred_class` array, which contains objects with `from`, `from_script`, and `to` properties.
      - `from` property is the name of the source Durable Object class.
      - `from_script` property is the name of the source Worker script.
      - `to` property is the name of the destination Durable Object class.

2. Ensure you reference the name of the new, destination Durable Object class in your Worker code.
3. Deploy the Worker.
</Steps>

<Details header = "Transfer migration example">

You can transfer stored Durable Objects from `DurableObjectExample` to `TransferredClass` from a Worker script named `OldWorkerScript`. The configuration of the `wrangler.toml / wrangler.json` file for your new Worker code (destination Worker code) would look like this:

<WranglerConfig>
```toml
# destination worker
[[durable_objects.bindings]]
name = "MY_DURABLE_OBJECT"
class_name = "TransferredClass"

# Transferring class

[[migrations]]
tag = "v4"
transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerScript", to = "TransferredClass" }]

```
</WranglerConfig>

</Details>
## Migration Wrangler configuration

- Migrations are performed through the `[[migrations]]` configurations key in your `wrangler.toml` file or `migration` key in your `wrangler.json` file.

- Migrations require a migration tag, which is defined by the `tag` property in each migration entry.

- Migration tags are treated like unique names and are used to determine which migrations have already been applied. Once a given Worker code has a migration tag set on it, all future Worker code deployments must include a migration tag.

- The migration list is an ordered array of tables, specified as a key in your Wrangler configuration file.

- You can define the migration for each environment, as well as at the top level.
  - Top-level migration is specified at the top-level `migrations` key in the Wrangler configuration file.
  - Environment-level migration is specified by a `migrations` key inside the `env` key of the Wrangler configuration file (`[env.<environment_name>.migrations]`).
    - Example Wrangler file:
    ```jsonc title="wrangler.jsonc"
    {
    // top-level default migrations
    "migrations": [{ ... }],
    "env": {
    "staging": {
      // migration override for staging
      "migrations": [{...}]
      }
     }
    }
    ```
  - If a migration is only specified at the top-level, but not at the environment-level, the environment will inherit the top-level migration.
  - Migrations at at the environment-level override migrations at the top level.

- All migrations are applied at deployment. Each migration can only be applied once per [environment](/durable-objects/reference/environments/).

- Each migration in the list can have multiple directives, and multiple migrations can be specified as your project grows in complexity.

:::caution[Important]
- The destination class (the class that stored Durable Objects are being transferred to) for a Rename or Transfer migration must be exported by the deployed Worker.

- You should not create the destination Durable Object class before running a Rename or Transfer migration. The migration will create the destination class for you.

- After a Rename or Transfer migration, requests to the destination Durable Object class will have access to the source Durable Object's stored data.

- After a migration, any existing bindings to the original Durable Object class (for example, from other Workers) will automatically forward to the updated destination class. However, any Workers bound to the updated Durable Object class must update their Durable Object binding configuration in the `wrangler` configuration file for their next deployment.
:::

:::note
Note that `.toml` files do not allow line breaks in inline tables (the `{key = "value"}` syntax), but line breaks in the surrounding inline array are acceptable.
:::

You cannot enable a SQLite storage backend on an existing, deployed Durable Object class, so setting `new_sqlite_classes` on later migrations will fail with an error. Automatic migration of deployed classes from their key-value storage backend to SQLite storage backend will be available in the future.

:::caution[Important]
Durable Object migrations are atomic operations and cannot be gradually deployed. To provide early feedback to developers, new Worker versions with new migrations cannot be uploaded. Refer to [Gradual deployments for Durable Objects](/workers/configuration/versions-and-deployments/gradual-deployments/#gradual-deployments-for-durable-objects) for more information.
:::

---

# Glossary

URL: https://developers.cloudflare.com/durable-objects/reference/glossary/

import { Glossary } from "~/components"

Review the definitions for terms used across Cloudflare's Durable Objects documentation.

<Glossary product="durable-objects" />

---

# In-memory state in a Durable Object

URL: https://developers.cloudflare.com/durable-objects/reference/in-memory-state/

import { GlossaryTooltip } from "~/components";

In-memory state means that each <GlossaryTooltip term="Durable Object">Durable Object</GlossaryTooltip> has one active instance at any particular time. All requests sent to that Durable Object are handled by that same instance. You can store some state in memory.

Variables in a Durable Object will maintain state as long as your Durable Object is not evicted from memory.

A common pattern is to initialize a Durable Object from [persistent storage](/durable-objects/api/storage-api/) and set instance variables the first time it is accessed. Since future accesses are routed to the same Durable Object, it is then possible to return any initialized values without making further calls to persistent storage.

```js
export class Counter {
	constructor(state, env) {
		this.state = state;
		// `blockConcurrencyWhile()` ensures no requests are delivered until
		// initialization completes.
		this.state.blockConcurrencyWhile(async () => {
			let stored = await this.state.storage.get("value");
			// After initialization, future reads do not need to access storage.
			this.value = stored || 0;
		});
	}

	// Handle HTTP requests from clients.
	async fetch(request) {
		// use this.value rather than storage
	}
}
```

A given instance of a Durable Object may share global memory with other instances defined in the same Worker code.

In the example above, using a global variable `value` instead of the instance variable `this.value` would be incorrect. Two different instances of `Counter` will each have their own separate memory for `this.value`, but might share memory for the global variable `value`, leading to unexpected results. Because of this, it is best to avoid global variables.

:::note[Built-in caching]

The Durable Object's storage has a built-in in-memory cache of its own. If you use `get()` to retrieve a value that was read or written recently, the result will be instantly returned from cache. Instead of writing initialization code like above, you could use `get("value")` whenever you need it, and rely on the built-in cache to make this fast. Refer to the [Build a counter example](/durable-objects/examples/build-a-counter/) to learn more about this approach.

However, in applications with more complex state, explicitly storing state in your Object may be easier than making Storage API calls on every access. Depending on the configuration of your project, write your code in the way that is easiest for you.

:::

---

# Reference

URL: https://developers.cloudflare.com/durable-objects/reference/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Tutorials

URL: https://developers.cloudflare.com/durable-objects/tutorials/

import { GlossaryTooltip, ListTutorials } from "~/components";

View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Durable Objects.

<ListTutorials />

---

# Audit logs

URL: https://developers.cloudflare.com/email-routing/get-started/audit-logs/

Audit logs for Email Routing are available in the [Cloudflare dashboard](https://dash.cloudflare.com/?account=audit-log). The following changes to Email Routing will be displayed:

* Add/edit Rule
* Add address
* Address change status
* Enable/disable/unlock zone

Refer to [Review audit logs](/fundamentals/account/account-security/review-audit-logs/) for more information.

---

# Enable Email Routing

URL: https://developers.cloudflare.com/email-routing/get-started/enable-email-routing/

:::caution[Important]
Enabling Email Routing adds the appropriate `MX` records to the DNS settings of your zone in order for the service to work. You can [change these `MX` records](/email-routing/setup/email-routing-dns-records/) at any time. However, depending on how you configure them, Email Routing might stop working.
:::

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
2. Go to **Email** > **Email Routing**.
3. Review the records that will be added to your zone.
4. Select **Add records and enable**.
5. Go to **Routing rules**.
6. For **Custom addresses**, select **Create address**.
7. Enter the custom email address you want to use (for example, `my-new-email@example.com`).
8. In **Destination addresses**, enter the full email address you want your emails to be forwarded to — for example, `your-name@example.com`.

   :::note[Notes]

   If you have several destination addresses linked to the same custom email address (rule), Email Routing will only process the most recent rule. To avoid this, do not link several destination addresses to the same custom address.

   The current implementation of email forwarding only supports a single destination address per custom address. To forward a custom address to multiple destinations you must create a Workers script to redirect the email to each destination. All the destinations used in the Workers script must be already validated.

   :::

9. Select **Save**.
10. Cloudflare will send a verification email to the address provided in the **Destination address** field. You must verify your email address before being able to proceed.
11. In the verification email Cloudflare sent you, select **Verify email address** > **Go to Email Routing** to activate Email Routing.
12. Your Destination address should now show **Verified**, under **Status**. Select **Continue**.
13. Cloudflare needs to add the relevant `MX` and `TXT` records to DNS records for Email Routing to work. This step is automatic and is only needed the first time you configure Email Routing. It is meant to ensure you have the proper records configured in your zone. Select **Add records and finish**.

Email Routing is now enabled. You can add other custom addresses to your account.

:::note
When Email Routing is configured and running, no other email services can be active in the domain you are configuring. If there are other `MX` records already configured in DNS, Cloudflare will ask you if you wish to delete them. If you do not delete existing `MX` records, Email Routing will not be enabled.
:::

---

# Analytics

URL: https://developers.cloudflare.com/email-routing/get-started/email-routing-analytics/

The Overview page shows you a summary of your account. You can check details such as how many custom and destination addresses you have configured, as well as the status of your routing service.

## Email Routing summary

In Email Routing summary you can check metrics related the number of emails received, forwarded, dropped, and rejected. To filter this information by time interval, select the drop-down menu. You can choose preset periods between the previous 30 minutes and 30 days, as well as a custom date range.

## Activity Log

This section allows you to sort through emails received, and check Email Routing actions - for example, `Forwarded`, `Dropped`, or `Rejected`. Select a specific email to expand its details and check information regarding the [SPF](https://datatracker.ietf.org/doc/html/rfc7208), [DKIM](https://datatracker.ietf.org/doc/html/rfc6376), and [DMARC](https://datatracker.ietf.org/doc/html/rfc7489) statuses. Depending on the information shown, you can opt to mark an email as spam or block the sender.

---

# Get started

URL: https://developers.cloudflare.com/email-routing/get-started/

import { DirectoryListing } from "~/components"

To enable Email Routing, start by creating a custom email address linked to a destination address or Email Worker. This forms an **email rule**. You can enable or disable rules from the Cloudflare dashboard. Refer to [Enable Email Routing](/email-routing/get-started/enable-email-routing) for more details.

Custom addresses you create with Email Routing work as forward addresses only. Emails sent to custom addresses are forwarded by Email Routing to your destination inbox. Cloudflare does not process outbound email, and does not have an SMTP server.

The first time you access Email Routing, you will see a wizard guiding you through the process of creating email rules. You can skip the wizard and add rules manually.

If you need to pause Email Routing or offboard to another service, refer to [Disable Email Routing](/email-routing/setup/disable-email-routing/).

<DirectoryListing />

---

# Test Email Routing

URL: https://developers.cloudflare.com/email-routing/get-started/test-email-routing/

To test that your configuration is working properly, send an email to the custom address [you set up in the dashboard](/email-routing/get-started/enable-email-routing/). You should send your test email from a different address than the one you specified as the destination address.

For example, if you set up `your-name@gmail.com` as the destination address, do not send your test email from that same Gmail account. Send a test email to that destination address from another email account (for example, `your-name@outlook.com`).

The reason for this is that some email providers will discard what they interpret as an incoming duplicate email and will not show it in your inbox, making it seem like Email Routing is not working properly.

---

# Demos

URL: https://developers.cloudflare.com/email-routing/email-workers/demos/

import { ExternalResources, GlossaryTooltip } from "~/components"

Learn how you can use Email Workers within your existing architecture.

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Email Workers.

<ExternalResources type="apps" products={["Email Workers"]} />

---

# Edit Email Workers

URL: https://developers.cloudflare.com/email-routing/email-workers/edit-email-workers/

import { Render } from "~/components"

Adding or editing Email Workers is straightforward. You can rename, delete or edit Email Workers, as well as change the routes bound to a specific Email Worker.

## Add an Email worker

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.

2. Go to **Email** > **Email Routing** > **Email Workers**.

3. Select  **Create**.

<Render file="enable-create-worker" />

## Edit an Email Worker

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.

2. Go to **Email** > **Email Routing** > **Email Workers**.

3. Find the Email Worker you want to rename, and select the three-dot button next to it.

4. Select **Code editor**.

5. Make the appropriate changes to your code.

6. Select **Save and deploy** when you are finished editing.

## Rename Email Worker

When you rename an Email Worker, you will lose the route that was previously bound to it. You will need to configure the route again after renaming the Email Worker.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.

2. Go to **Email** > **Email Routing** > **Email workers**.

3. Find the Email Worker you want to rename, and select the three-dot button next to it.

4. From the drop-down menu, select **Manage Worker**.

5. Select **Manage Service** > **Rename service**, and fill in the new Email Worker’s name.

6. Select **Continue** > **Move**.

7. Acknowledge the warning and select **Finish**.

8. Now, go back to **Email** > **Email Routing**.

9. In **Routes** find the custom address you previously had associated with your Email Worker, and select **Edit**.

10. In the **Destination** drop-down menu, select your renamed Email Worker.

11. Select **Save**.

## Edit route

The following steps show how to change a route associated with an Email Worker.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.

2. Go to **Email** > **Email Routing** > **Email workers**.

3. Find the Email Worker you want to change the associated route, and select  **route** on its card.

4. Select **Edit** to make the required changes.

5. Select **Save** to finish.

## Delete an Email Worker

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.

2. Go to **Email** > **Email Routing** > **Email workers**.

3. Find the Email Worker you want to delete, and select the three-dot button next to it.

4. From the drop-down menu, select  **Manage Worker**.

5. Select **Manage Service** > **Delete**.

6. Type the name of the Email Worker to confirm you want to delete it, and select **Delete**.

---

# Enable Email Workers

URL: https://developers.cloudflare.com/email-routing/email-workers/enable-email-workers/

import { Render } from "~/components"

Follow these steps to enable and add your first Email Worker. If you have never used Cloudflare Workers before, Cloudflare will create a subdomain for you, and assign you to the Workers [free pricing plan](/workers/platform/pricing/).

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.

2. Go to **Email** > **Email Routing** > **Email Workers**.

3. Select  **Get started**.

<Render file="enable-create-worker" />

---

# Local Development

URL: https://developers.cloudflare.com/email-routing/email-workers/local-development/

import { Render, Type, MetaInfo, WranglerConfig } from "~/components";

You can test the behavior of an Email Worker script in local development using [wrangler dev](/workers/wrangler/commands/#dev).

This is the minimal wrangler configuration required to run an Email Worker locally:

<WranglerConfig>

```jsonc
{
  "send_email": [
    {
      "name": "EMAIL"
    }
  ]
}
```

</WranglerConfig>

:::note

If you want to deploy your script you need to [enable Email Routing](/email-routing/get-started/enable-email-routing/) and have at least one verified [destination address](/email-routing/setup/email-routing-addresses/#destination-addresses).

:::

You can now test receiving, replying, and sending emails in your local environment.

## Receive an email

Consider this example Email Worker script that uses the open source [`postal-mime`](https://www.npmjs.com/package/postal-mime) email parser:

```ts
import * as PostalMime from 'postal-mime';

export default {
	async email(message, env, ctx) {
		const parser = new PostalMime.default();
		const rawEmail = new Response(message.raw);
		const email = await parser.parse(await rawEmail.arrayBuffer());
		console.log(email);
	},
};
```

Now when you run `npx wrangler dev`, wrangler will expose a local `/cdn-cgi/handler/email` endpoint that you can `POST` email messages to and trigger your Worker's `email()` handler:

```bash
curl --request POST 'http://localhost:8787/cdn-cgi/handler/email' \
  --url-query 'from=sender@example.com' \
  --url-query 'to=recipient@example.com' \
  --header 'Content-Type: application/json' \
  --data-raw 'Received: from smtp.example.com (127.0.0.1)
        by cloudflare-email.com (unknown) id 4fwwffRXOpyR
        for <recipient@example.com>; Tue, 27 Aug 2024 15:50:20 +0000
From: "John" <sender@example.com>
Reply-To: sender@example.com
To: recipient@example.com
Subject: Testing Email Workers Local Dev
Content-Type: text/html; charset="windows-1252"
X-Mailer: Curl
Date: Tue, 27 Aug 2024 08:49:44 -0700
Message-ID: <6114391943504294873000@ZSH-GHOSTTY>

Hi there'
```

This is what you get in the console:

```json
{
  headers: [
    {
      key: 'received',
      value: 'from smtp.example.com (127.0.0.1) by cloudflare-email.com (unknown) id 4fwwffRXOpyR for <recipient@example.com>; Tue, 27 Aug 2024 15:50:20 +0000'
    },
    { key: 'from', value: '"John" <sender@example.com>' },
    { key: 'reply-to', value: 'sender@example.com' },
    { key: 'to', value: 'recipient@example.com' },
    { key: 'subject', value: 'Testing Email Workers Local Dev' },
    { key: 'content-type', value: 'text/html; charset="windows-1252"' },
    { key: 'x-mailer', value: 'Curl' },
    { key: 'date', value: 'Tue, 27 Aug 2024 08:49:44 -0700' },
    {
      key: 'message-id',
      value: '<6114391943504294873000@ZSH-GHOSTTY>'
    }
  ],
  from: { address: 'sender@example.com', name: 'John' },
  to: [ { address: 'recipient@example.com', name: '' } ],
  replyTo: [ { address: 'sender@example.com', name: '' } ],
  subject: 'Testing Email Workers Local Dev',
  messageId: '<6114391943504294873000@ZSH-GHOSTTY>',
  date: '2024-08-27T15:49:44.000Z',
  html: 'Hi there\n',
  attachments: []
}
```

## Send an email

Wrangler can also simulate sending emails locally. Consider this example Email Worker script that uses the [`mimetext`](https://www.npmjs.com/package/mimetext) npm package:

```ts
import { EmailMessage } from "cloudflare:email";
import { createMimeMessage } from 'mimetext';

export default {
	async fetch(request, env, ctx) {
		const msg = createMimeMessage();
		msg.setSender({ name: 'Sending email test', addr: 'sender@example.com' });
		msg.setRecipient('recipient@example.com');
		msg.setSubject('An email generated in a worker');
		msg.addMessage({
			contentType: 'text/plain',
			data: `Congratulations, you just sent an email from a worker.`,
		});

		var message = new EmailMessage('sender@example.com', 'recipient@example.com', msg.asRaw());
		await env.EMAIL.send(message);
		return Response.json({ ok: true });
	}
};
```

Now when you run `npx wrangler dev`, go to http://localhost:8787/ to trigger the `fetch()` handler and send the email. You will see the follow message in your terminal:

```txt
⎔ Starting local server...
[wrangler:inf] Ready on http://localhost:8787
[wrangler:inf] GET / 200 OK (19ms)
[wrangler:inf] send_email binding called with the following message:
  /var/folders/33/pn86qymd0w50htvsjp93rys40000gn/T/miniflare-f9be031ff417b2e67f2ac4cf94cb1b40/files/email/33e0a255-a7df-4f40-b712-0291806ed2b3.eml
```

Wrangler simulated `env.EMAIL.send()` by writing the email to a local file in [eml](https://datatracker.ietf.org/doc/html/rfc5322) format. The file contains the raw email message:

```
Date: Fri, 04 Apr 2025 12:27:08 +0000
From: =?utf-8?B?U2VuZGluZyBlbWFpbCB0ZXN0?= <sender@example.com>
To: <recipient@example.com>
Message-ID: <2s95plkazox@example.com>
Subject: =?utf-8?B?QW4gZW1haWwgZ2VuZXJhdGVkIGluIGEgd29ya2Vy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

Congratulations, you just sent an email from a worker.
```

## Reply to and forward messages

Likewise, [`EmailMessage`](/email-routing/email-workers/runtime-api/#emailmessage-definition)'s `forward()` and `reply()` methods are also simulated locally. Consider this Worker that receives an email, parses it, replies to the sender, and forwards the original message to one your verified recipient addresses:

```ts
import * as PostalMime from 'postal-mime';
import { createMimeMessage } from 'mimetext';
import { EmailMessage } from 'cloudflare:email';

export default {
	async email(message, env: any, ctx: any) {
		// parses incoming message
		const parser = new PostalMime.default();
		const rawEmail = new Response(message.raw);
		const email = await parser.parse(await rawEmail.arrayBuffer());

		// creates some ticket
		// const ticket = await createTicket(email);

		// creates reply message
		const msg = createMimeMessage();
		msg.setSender({ name: 'Thank you for your contact', addr: 'sender@example.com' });
		msg.setRecipient(message.from);
		msg.setHeader('In-Reply-To', message.headers.get('Message-ID'));
		msg.setSubject('An email generated in a worker');
		msg.addMessage({
			contentType: 'text/plain',
			data: `This is an automated reply. We received you email with the subject "${email.subject}", and will handle it as soon as possible.`,
		});

		const replyMessage = new EmailMessage('sender@example.com', message.from, msg.asRaw());

		await message.reply(replyMessage);
		await message.forward("recipient@example.com");
	},
};
```

Run `npx wrangler dev` and use curl to `POST` the same message from the [Receive an email](#receive-an-email) example. Your terminal will show you where to find the replied message in your local disk and to whom the email was forwarded:

```txt
⎔ Starting local server...
[wrangler:inf] Ready on http://localhost:8787
[wrangler:inf] Email handler replied to sender with the following message:
  /var/folders/33/pn86qymd0w50htvsjp93rys40000gn/T/miniflare-381a79d7efa4e991607b30a079f6b17d/files/email/a1db7ebb-ccb4-45ef-b315-df49c6d820c0.eml
[wrangler:inf] Email handler forwarded message with
  rcptTo: recipient@example.com
```

---

# Email Workers

URL: https://developers.cloudflare.com/email-routing/email-workers/

With Email Workers you can leverage the power of Cloudflare Workers to implement any logic you need to process your emails and create complex rules. These rules determine what happens when you receive an email.

Creating your own rules with Email Workers is as easy or complex as you want. You can begin using one of the starter templates that are pre-populated with code for popular use-cases. These templates allow you to create a blocklist, allowlist, or send notifications to Slack.

If you prefer, you can skip the templates and use custom code. You can, for example, create logic that only accepts messages from a specific address, and then forwards them to one or more of your verified email addresses, while also alerting you on Slack.

The following is an example of an allowlist Email Worker:

```js
export default {
	async email(message, env, ctx) {
		const allowList = ["friend@example.com", "coworker@example.com"];
		if (allowList.indexOf(message.from) == -1) {
			message.setReject("Address not allowed");
		} else {
			await message.forward("inbox@corp");
		}
	},
};
```

Refer to the [Workers Languages](/workers/languages/) for more information regarding the languages you can use with Workers.

## How to use Email Workers

To use Email Routing with Email Workers there are three steps involved:

1. Creating the Email Worker.
2. Adding the logic to your Email Worker (like email addresses allowed or blocked from sending you emails).
3. Binding the Email Worker to a route. This is the email address that forwards emails to the Worker.

The route, or email address, bound to the Worker forwards emails to your Email Worker. The logic in the Worker will then decide if the email is forwarded to its final destination or dropped, and what further actions (if any) will be applied.

For example, say that you create an allowlist Email Worker and bind it to a `hello@my-company.com` route. This route will be the email address you share with the world, to make sure that only email addresses on your allowlist are forwarded to your destination address. All other emails will be dropped.

## Resources

- [Limits](/email-routing/limits/#email-workers-size-limits)
- [Runtime API](/email-routing/email-workers/runtime-api/)
- [Local development](/email-routing/email-workers/local-development/)

---

# Reply to emails from Workers

URL: https://developers.cloudflare.com/email-routing/email-workers/reply-email-workers/

You can reply to incoming emails with another new message and implement smart auto-responders programmatically, adding any content and context in the main body of the message. Think of a customer support email automatically generating a ticket and returning the link to the sender, an out-of-office reply with instructions when you are on vacation, or a detailed explanation of why you rejected an email.

Reply to emails is a new method of the [`EmailMessage` object](/email-routing/email-workers/runtime-api/#emailmessage-definition) in the Runtime API. Here is how it works:

```js
import { EmailMessage } from "cloudflare:email";
import { createMimeMessage } from "mimetext";

export default {
  async email(message, env, ctx) {

    const ticket = createTicket(message);

    const msg = createMimeMessage();
    msg.setHeader("In-Reply-To", message.headers.get("Message-ID"));
    msg.setSender({ name: "Thank you for your contact", addr: "<SENDER>@example.com" });
    msg.setRecipient(message.from);
    msg.setSubject("Email Routing Auto-reply");
    msg.addMessage({
      contentType: 'text/plain',
      data: `We got your message, your ticket number is ${ ticket.id }`
    });

    const replyMessage = new EmailMessage(
      "<SENDER>@example.com",
      message.from,
      msg.asRaw()
    );

    await message.reply(replyMessage);
  }
}
```

To mitigate security risks and abuse, replying to incoming emails has a few requirements and limits:

* The incoming email has to have valid [DMARC](https://www.cloudflare.com/learning/dns/dns-records/dns-dmarc-record/).
* The email can only be replied to once in the same `EmailMessage` event.
* The recipient in the reply must match the incoming sender.
* The outgoing sender domain must match the same domain that received the email.
* Every time an email passes through Email Routing or another MTA, an entry is added to the `References` list. We stop accepting replies to emails with more than 100 `References` entries to prevent abuse or accidental loops.

If these and other internal conditions are not met, `reply()` will fail with an exception. Otherwise, you can freely compose your reply message, send it back to the original sender, and receive subsequent replies multiple times.

---

# Runtime API

URL: https://developers.cloudflare.com/email-routing/email-workers/runtime-api/

## Background

An `EmailEvent` is the event type to programmatically process your emails with a Worker. You can reject, forward, or drop emails according to the logic you construct in your Worker.

***

## Syntax: ES modules

`EmailEvent` can be handled in Workers functions written using the [ES modules format](/workers/reference/migrate-to-module-workers/) by adding an `email` function to your module's exported handlers:

```js
export default {
  async email(message, env, ctx) {
    await message.forward("<YOUR_EMAIL>");
  },
};
```

### Parameters



* `message` ForwardableEmailMessage

  * A [`ForwardableEmailMessage` object](#forwardableemailmessage-definition).

* `env` object

  * An object containing the bindings associated with your Worker using ES modules format, such as KV namespaces and Durable Objects.

* `ctx` object
  * An object containing the context associated with your Worker using ES modules format. Currently, this object just contains the `waitUntil` function.



***

## Syntax: Service Worker

:::caution[Service Workers are deprecated]

Service Workers are deprecated but still supported. We recommend using [Module Workers](/workers/reference/migrate-to-module-workers/) instead. New features may not be supported for Service Workers.

:::

`EmailEvent` can be handled in Workers functions written using the Service Worker syntax by attaching to the `email` event with `addEventListener`:

```js
addEventListener("email", async (event) => {
  await event.message.forward("<YOUR_EMAIL>");
});
```

### Properties



* `event.message` ForwardableEmailMessage

  * An [`ForwardableEmailMessage` object](#forwardableemailmessage-definition).



***

## `ForwardableEmailMessage` definition

```ts
 interface ForwardableEmailMessage<Body = unknown> {
  readonly from: string;
  readonly to: string;
  readonly headers: Headers;
  readonly raw: ReadableStream;
  readonly rawSize: number;

  public constructor(from: string, to: string, raw: ReadableStream | string);

  setReject(reason: string): void;
  forward(rcptTo: string, headers?: Headers): Promise<void>;
  reply(message: EmailMessage): Promise<void>;
}
```

An email message that is sent to a consumer Worker and can be rejected/forwarded.

* `from` string

  * `Envelope From` attribute of the email message.

* `to` string

  * `Envelope To` attribute of the email message.

* `headers` Headers

  * A [`Headers` object](https://developer.mozilla.org/en-US/docs/Web/API/Headers).

* `raw` ReadableStream

  * [Stream](/workers/runtime-apis/streams/readablestream) of the email message content.

* `rawSize` number

  * Size of the email message content.

* <code>setReject(reasonstring)</code> : void

  * Reject this email message by returning a permanent SMTP error back to the connecting client, including the given reason.

* <code>forward(rcptTostring, headersHeadersoptional)</code> : Promise

  * Forward this email message to a verified destination address of the account. If you want, you can add extra headers to the email message. Only `X-*` headers are allowed.
  * When the promise resolves, the message is confirmed to be forwarded to a verified destination address.

* <code>reply(EmailMessage)</code> : Promise

  * Reply to the sender of this email message with a new EmailMessage object.
  * When the promise resolves, the message is confirmed to be replied.


## `EmailMessage` definition

```ts
interface EmailMessage {
    readonly from: string;
    readonly to: string;
}
```

An email message that can be sent from a Worker.

* `from` string

  * `Envelope From` attribute of the email message.

* `to` string

  * `Envelope To` attribute of the email message.

---

# Send emails from Workers

URL: https://developers.cloudflare.com/email-routing/email-workers/send-email-workers/

import { Render, WranglerConfig } from "~/components"

<Render file="send-emails-workers-intro" params={{ one: "Then, create a new binding in the Wrangler configuration file:" }} />

<WranglerConfig>

```toml
send_email = [
    {name = "<NAME_FOR_BINDING>", destination_address = "<YOUR_EMAIL>@example.com"},
]
```

</WranglerConfig>

## Types of bindings

There are three types of bindings:

* **No attribute defined**: When you do not define an attribute, the binding has no restrictions in place. You can use it to send emails to any verified email address [through Email Routing](/email-routing/setup/email-routing-addresses/#destination-addresses).
* **`destination_address`**: When you define the `destination_address` attribute, you create a targeted binding. This means you can only send emails to the chosen email address. For example, `{type = "send_email", name = "<NAME_FOR_BINDING>", destination_address = "<YOUR_EMAIL>@example.com"}`. <br/> For this particular binding, when you call the `send_email` function you can pass `null` or `undefined` to your Worker and it will assume the email address specified in the binding.
* **`allowed_destination_addresses`**: When you specify this attribute, you create an allowlist, and can send emails to any email address on the list.

<Render file="types-bindings" />

## Example Worker

Refer to the example below to learn how to construct a Worker capable of sending emails. This example uses [MIMEText](https://www.npmjs.com/package/mimetext):

:::note
The sender has to be an email from the domain where you have Email Routing active.
:::

```js
import { EmailMessage } from "cloudflare:email";
import { createMimeMessage } from "mimetext";

export default {
 async fetch(request, env) {
   const msg = createMimeMessage();
   msg.setSender({ name: "GPT-4", addr: "<SENDER>@example.com" });
   msg.setRecipient("<RECIPIENT>@example.com");
   msg.setSubject("An email generated in a worker");
   msg.addMessage({
       contentType: 'text/plain',
       data: `Congratulations, you just sent an email from a worker.`
   });

   var message = new EmailMessage(
     "<SENDER>@example.com",
     "<RECIPIENT>@example.com",
     msg.asRaw()
   );
   try {
     await env.SEB.send(message);
   } catch (e) {
     return new Response(e.message);
   }

   return new Response("Hello Send Email World!");
 },
};
```

---

# Disable Email Routing

URL: https://developers.cloudflare.com/email-routing/setup/disable-email-routing/

Email Routing provides two options for disabling the service:

* **Delete and Disable**: This option will immediately disable Email Routing and remove its `MX` records. Your custom email addresses will stop working, and your email will not be routed to its final destination.
* **Unlock and keep DNS records**: (Advanced) This option is recommended if you plan to migrate to another provider. It allows you to add new `MX` records before disabling the service. Email Routing will stop working when you change your `MX` records.

## Delete and disable Email Routing

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
2. Go to **Email** > **Email Routing** > **Settings**.
3. Select **Start disabling** > **Delete and Disable**. Email Routing will show you the list of records associated with your account that will be deleted.
4. Select **Delete records**.

Email Routing is now disabled for your account and will stop forwarding email. To enable the service again, select **Enable Email Routing** and follow the wizard.

## Unlock and keep DNS records

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
2. Go to **Email** > **Email Routing** > **Settings**.
3. Select **Start disabling** > **Unlock records and continue**.
4. Select **Edit records on DNS**.

You now have the option to edit your DNS records to migrate your service to another provider.

:::caution

Changing your DNS records will make Email Routing stop working. If you changed your mind and want to keep Email Routing working with your account, select **Lock DNS records**. 
:::

---

# Configure rules and addresses

URL: https://developers.cloudflare.com/email-routing/setup/email-routing-addresses/

An email rule is a pair of a custom email address and a destination address, or a custom email address with an Email Worker. This allows you to route emails to your preferred inbox, or apply logic through Email Workers before deciding what should happen to your emails. You can have multiple custom addresses, to route email from specific providers to specific mail inboxes.

## Custom addresses

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
2. Go to **Email** > **Email Routing** > **Routes**.
3. Select **Create address**.
4. In **Custom address**, enter the custom email address you want to use (for example, `my-new-email`).
5. In the **Action** drop-down menu, choose what this email rule should do. Refer to [Email rule actions](#email-rule-actions) for more information.
6. In **Destination**, choose the email address or Email Worker you want your emails to be forwarded to — for example, `your-name@gmail.com`. You can only choose a destination address you have already verified. To add a new destination address, refer to [Destination addresses](#destination-addresses).

:::note

If you have more than one destination address linked to the same custom address, Email Routing will only process the most recent rule. This means only the most recent pair of custom address and destination address (rule) will receive your forwarded emails. To avoid this, do not link more than one destination address to the same custom address. 
:::

### Email rule actions

When creating an email rule, you must specify an **Action**:

* *Send to an email*: Emails will be routed to your destination address. This is the default action.
* *Send to a Worker*: Emails will be processed by the logic in your [Email Worker](/email-routing/email-workers).
* *Drop*: Deletes emails sent to the custom address without routing them. This can be useful if you want to make an email address appear valid for privacy reasons.

:::note


To prevent spamming unintended recipients, all email rules are automatically disabled until the destination address is validated by the user.


:::

### Disable an email rule

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
2. Go to **Email** > **Email Routing** > **Routes**.
3. In **Custom addresses**, identify the email rule you want to pause, and toggle the status button to **Disabled**.

Your email rule is now disabled. It will not forward emails to a destination address or Email Worker. To forward emails again, toggle the email rule status button to **Active**.

### Edit custom addresses

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
2. Go to **Email** > **Email Routing** > **Routes**.
3. In **Custom addresses**, identify the email rule you want to edit, and select **Edit**.
4. Make the appropriate changes to this custom address.

## Catch-all address

When you enable this feature, Email Routing will catch variations of email addresses to make them valid for the specified domain. For example, if you created an email rule for `info@example.com` and a sender accidentally types `ifno@example.com`, the email will still be correctly handled if you have **Catch-all addresses** enabled.

To enable Catch-all addresses:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
2. Go to **Email** > **Email Routing** > **Routes**.
3. Enable **Catch-all address**, so it shows as **Active**.
4. In the **Action** drop-down menu, select what to do with these emails. Refer to [Email rule actions](#email-rule-actions) for more information.
5. Select **Save**.

## Destination addresses

This section lets you manage your destination addresses. It lists all email addresses already verified, as well as email addresses pending verification. You can resend verification emails or delete destination addresses.

Destination addresses are shared at the account level, and can be reused with any other domain in your account. This means the same destination address will be available to different domains in your account.

To prevent spam, email rules do not become active until after the destination address has been verified. Cloudflare sends a verification email to destination addresses specified in **Custom addresses**. You have to select **Verify email address** in that email to activate a destination address.

:::note


Deleting a destination address automatically disables all email rules that use that email address as destination.


:::

---

# DNS records

URL: https://developers.cloudflare.com/email-routing/setup/email-routing-dns-records/

You can check the status of your DNS records in the **Settings** section of Email Routing. This section also allows you to troubleshoot any potential problems you might have with DNS records.

## Email DNS records

Check the status of your account's DNS records in the **Email DNS records** card:

* **Email DNS records configured** - DNS records are properly configured.
* **Email DNS records misconfigured** - There is a problem with your accounts DNS records. Select **Enable Email Routing** to [start troubleshooting problems](/email-routing/troubleshooting/).

### Start disabling

When you successfully configure Email Routing, your DNS records will be locked and the dashboard will show a **Start disabling** button in the Email DNS records card. This locked status is the recommended setting by Cloudflare. It means that the DNS records required for Email Routing to work are locked and can only be changed if you disable Email Routing on your domain.

If you need to delete Email Routing or migrate to another provider, select **Start disabling**. Refer to [Disable Email Routing](/email-routing/setup/disable-email-routing/) for more information.

### Lock DNS records

Depending on your zone configuration, you might have your DNS records unlocked. This will also be true if, for some reason, you have unlocked your DNS records. Select **Lock DNS records** to lock your DNS records and protect them from being accidentally changed or deleted.

## View DNS records

Select **View DNS records** for a list of the required `MX` and sender policy framework (SPF) records Email Routing is using.

If you are having trouble with your account's DNS records, refer to the [Troubleshooting](/email-routing/troubleshooting/) section.

---

# Setup

URL: https://developers.cloudflare.com/email-routing/setup/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Configure MTA-STS

URL: https://developers.cloudflare.com/email-routing/setup/mta-sts/

MTA Strict Transport Security ([MTA-STS](https://datatracker.ietf.org/doc/html/rfc8461)) was introduced by email service providers including Microsoft, Google and Yahoo as a solution to protect against downgrade and man-in-the-middle attacks in SMTP sessions, as well as solving the lack of security-first communication standards in email.

Suppose that `example.com` is your domain and uses Email Routing. Here is how you can enable MTA-STS for it.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
2. Go to **DNS** > **Records** and create a new CNAME record with the name `_mta-sts` that points to Cloudflare’s record `_mta-sts.mx.cloudflare.net`. Make sure to disable the proxy mode.

![MTA-STS CNAME record](~/assets/images/email-routing/mta-sts-record.png)

3. Confirm that the record was created:

```sh
dig txt _mta-sts.example.com
```

```sh output
_mta-sts.example.com. 300 IN  CNAME _mta-sts.mx.cloudflare.net.
_mta-sts.mx.cloudflare.net. 300 IN  TXT "v=STSv1; id=20230615T153000;"
```

This tells the other end client that is trying to connect to us that we support MTA-STS.

Next you need an HTTPS endpoint at `mta-sts.example.com` to serve your policy file. This file defines the mail servers in the domain that use MTA-STS. The reason why HTTPS is used here instead of DNS is because not everyone uses DNSSEC yet, so we want to avoid another MITM attack vector.

To do this you need to deploy a Worker that allows email clients to pull Cloudflare’s Email Routing policy file using the “well-known” URI convention.

4. Go to your **Account** > **Workers & Pages** and select **Create**. Pick the default "Hello World" option button, and replace the sample worker code with the following:

```js
export default {
  async fetch(request, env, ctx) {
    return await fetch("https://mta-sts.mx.cloudflare.net/.well-known/mta-sts.txt")
  },
};
```

This Worker proxies `https://mta-sts.mx.cloudflare.net/.well-known/mta-sts.txt` to your own domain. 

5. After deploying it, go to the Worker configuration, then **Settings** > **Domains & Routes** > **+Add**. Type the subdomain `mta-sts.example.com`.

![MTA-STS Worker Custom Domain](~/assets/images/email-routing/mta-sts-domain.png)

You can then confirm that your policy file is working with the following:

```sh
curl https://mta-sts.example.com/.well-known/mta-sts.txt
```

```sh output
version: STSv1
mode: enforce
mx: *.mx.cloudflare.net
max_age: 86400
```

This says that you domain `example.com` enforces MTA-STS. Capable email clients will only deliver email to this domain over a secure connection to the specified MX servers. If no secure connection can be established the email will not be delivered.

Email Routing also supports MTA-STS upstream, which greatly improves security when forwarding your Emails to service providers like Gmail, Microsoft, and others.

While enabling MTA-STS involves a few steps today, we aim to simplify things for you and automatically configure MTA-STS for your domains from the Email Routing dashboard as a future improvement.

---

# Subdomains

URL: https://developers.cloudflare.com/email-routing/setup/subdomains/

Email Routing is a [zone-level](/fundamentals/concepts/accounts-and-zones/#zones) feature. A zone has a top-level domain (the same as the zone name) and it can have subdomains (managed under the DNS feature.) As an example, you can have the `example.com` zone, and then the `mail.example.com` and `corp.example.com` sub-domains under it.

You can use Email Routing with any subdomain of any zone in your account. Follow these steps to add Email Routing features to a new subdomain:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and zone.
2. Go to **Email** > **Email Routing** > **Settings**, and select **Add subdomain**.

Once the subdomain is added and the DNS records are configured, you can see it in the **Settings** list under the **Subdomains** section.

Now you can go to **Email** > **Email Routing** > **Routing rules** and create new custom addresses that will show you the option of using either the top domain of the zone or any other configured subdomain.

---

# DNS records

URL: https://developers.cloudflare.com/email-routing/troubleshooting/email-routing-dns-records/

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
2. Go to **Email** > **Email Routing** > **Settings**. Email Routing will show you the status of your DNS records, such as `Missing`.
3. Select **Enable Email Routing**.
4. The next page will show you what kind of action is needed. For example, if you are missing DNS records, select **Add records and enable**.

If there is a problem with your SPF records, refer to [Troubleshooting SPF records](/email-routing/troubleshooting/email-routing-spf-records/).

---

# Troubleshooting

URL: https://developers.cloudflare.com/email-routing/troubleshooting/

import { DirectoryListing } from "~/components"

Email Routing warns you when your DNS records are not properly configured. In Email Routing's **Overview** page, you will see a message explaining what type of problem your account's DNS records have.

Refer to Email Routing's **Settings** tab on the dashboard for more information. Email Routing will list missing DNS records or warn you about duplicate sender policy framework (SPF) records, for example.

<DirectoryListing />

---

# SPF records

URL: https://developers.cloudflare.com/email-routing/troubleshooting/email-routing-spf-records/

Having multiple [sender policy framework (SPF) records](https://www.cloudflare.com/learning/dns/dns-records/dns-spf-record/) on your account is not allowed, and will prevent Email Routing from working properly. If your account has multiple SPF records, follow these steps to solve the issue:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
2. Go to **Email** > **Email Routing**. Email Routing will warn you that you have multiple SPF records.
3. Under **View DNS records**, select **Fix records**.
4. Delete the incorrect SPF record.

You should now have your SPF records correctly configured. If you are unsure of which SPF record to delete:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
2. Go to **Email** > **Email Routing**. Email Routing will warn you that you have multiple SPF records.
3. Under **View DNS records**, select **Fix records**.
4. Delete all SPF records.
5. Select **Add records and enable**.

---

# Examples

URL: https://developers.cloudflare.com/images/examples/

import { ListExamples } from "~/components";

<ListExamples directory="images/examples/" />

---

# Transcode images

URL: https://developers.cloudflare.com/images/examples/transcode-from-workers-ai/

```js
const stream = await env.AI.run(
  "@cf/bytedance/stable-diffusion-xl-lightning",
  {
    prompt: YOUR_PROMPT_HERE
  }
);

// Convert to AVIF
const image = (
  await env.IMAGES.input(stream)
    .output({format: "image/avif"})
).response();

const fileName = "image.avif";

// Upload to R2
await env.R2.put(fileName, image.body);
```

---

# Watermarks

URL: https://developers.cloudflare.com/images/examples/watermark-from-kv/

```ts
interface Env {
    BUCKET: R2Bucket,
    NAMESPACE: KVNamespace,
    IMAGES: ImagesBinding,
}
export default {
    async fetch(request, env, ctx): Promise<Response> {
        const watermarkKey = "my-watermark";
        const sourceKey = "my-source-image";

        const cache = await caches.open("transformed-images");
        const cacheKey = new URL(sourceKey + "/" + watermarkKey, request.url);
        const cacheResponse = await cache.match(cacheKey);

        if (cacheResponse) {
            return cacheResponse;
        }

        let watermark = await env.NAMESPACE.get(watermarkKey, "stream");
        let source = await env.BUCKET.get(sourceKey);

        if (!watermark || !source) {
            return new Response("Not found", { status: 404 });
        }

        const result = await env.IMAGES.input(source.body)
            .draw(watermark)
            .output({ format: "image/jpeg" });

        const response = result.response();

        ctx.waitUntil(cache.put(cacheKey, response.clone()));

        return result.response();
  },
} satisfies ExportedHandler<Env>;
```

---

# Apply blur

URL: https://developers.cloudflare.com/images/manage-images/blur-variants/

You can apply blur to image variants by creating a specific variant for this effect first or by editing a previously created variant. Note that you cannot blur an SVG file.

Refer to [Resize images](/images/manage-images/create-variants/) for help creating variants. You can also refer to the API to learn how to use blur using flexible variants.

To blur an image:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Select **Images** > **Variants**.
3. Find the variant you want to blur and select **Edit** > **Customization Options**.
4. Use the slider to adjust the blurring effect. You can use the preview image to see how strong the blurring effect will be.
5. Select **Save**.

The image should now display the blurred effect.

---

# Browser TTL

URL: https://developers.cloudflare.com/images/manage-images/browser-ttl/

Browser TTL controls how long an image stays in a browser's cache and specifically configures the `cache-control` response header.

### Default TTL

By default, an image's TTL is set to two days to meet user needs, such as re-uploading an image under the same [Custom ID](/images/upload-images/upload-custom-path/).

## Custom setting

You can use two custom settings to control the Browser TTL, an account or a named variant. To adjust how long a browser should keep an image in the cache, set the TTL in seconds, similar to how the `max-age` header is set. The value should be an interval between one hour to one year.

### Browser TTL for an account

Setting the Browser TTL per account overrides the default TTL.

```bash title="Example"
curl --request PATCH 'https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/config' \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "browser_ttl": 31536000
}'
```

When the Browser TTL is set to one year for all images, the response for the `cache-control` header is essentially `public`, `max-age=31536000`, `stale-while-revalidate=7200`.

### Browser TTL for a named variant

Setting the Browser TTL for a named variant is a more granular option that overrides all of the above when creating or updating an image variant, specifically the `browser_ttl` option in seconds.

```bash title="Example"
curl 'https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_TAG>/images/v1/variants' \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{
  "id":"avatar",
  "options": {
    "width":100,
    "browser_ttl": 86400
  }
}'
```

When the Browser TTL is set to one day for images requested with this variant, the response for the `cache-control` header is essentially `public`, `max-age=86400`, `stale-while-revalidate=7200`.

:::note


[Private images](/images/manage-images/serve-images/serve-private-images/) do not respect default or custom TTL settings. The private images cache time is set according to the expiration time and can be as short as one hour.


:::

---

# Configure webhooks

URL: https://developers.cloudflare.com/images/manage-images/configure-webhooks/

You can set up webhooks to receive notifications about your upload workflow. This will send an HTTP POST request to a specified endpoint when an image either successfully uploads or fails to upload.

Currently, webhooks are supported only for [direct creator uploads](/images/upload-images/direct-creator-upload/).

To receive notifications for direct creator uploads:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Go to **Notifications** > **Destinations**.
3. From the Webhooks card, select **Create**.
4. Enter information for your webhook and select **Save and Test**. The new webhook will appear in the **Webhooks** card and can be attached to notifications.
5. Next, go to **Notifications** > **All Notifications** and select **Add**.
6. Under the list of products, locate **Images** and select **Select**.
7. Give your notification a name and optional description.
8. Under the **Webhooks** field, select the webhook that you recently created.
9. Select **Save**.

---

# Create variants

URL: https://developers.cloudflare.com/images/manage-images/create-variants/

Variants let you specify how images should be resized for different use cases. By default, images are served with a `public` variant, but you can create up to 100 variants to fit your needs. Follow these steps to create a variant.

:::note

Cloudflare Images can deliver SVG files but will not resize them because it is an inherently scalable format.
Resize via the Cloudflare dashboard.
:::

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Select **Images** > **Variants**.
3. Name your variant and select **Add New Variant**.
4. Define variables for your new variant, such as resizing options, type of fit, and specific metadata options.

## Resize via the API

Make a `POST` request to [create a variant](/api/resources/images/subresources/v1/subresources/variants/methods/create/).

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/variants" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"id":"<NAME_OF_THE_VARIANT>","options":{"fit":"scale-down","metadata":"none","width":1366,"height":768},"neverRequireSignedURLs":true}
```

## Fit options

The `Fit` property describes how the width and height dimensions should be interpreted. The chart below describes each of the options.

| Fit Options | Behavior                                                                                                                                                                                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scale down  | The image is shrunk in size to fully fit within the given width or height, but will not be enlarged.                                                                                                                                                                            |
| Contain     | The image is resized (shrunk or enlarged) to be as large as possible within the given width or height while preserving the aspect ratio.                                                                                                                                        |
| Cover       | The image is resized to exactly fill the entire area specified by width and height and will be cropped if necessary.                                                                                                                                                            |
| Crop        | The image is shrunk and cropped to fit within the area specified by the width and height. The image will not be enlarged. For images smaller than the given dimensions, it is the same as `scale-down`. For images larger than the given dimensions, it is the same as `cover`. |
| Pad         | The image is resized (shrunk or enlarged) to be as large as possible within the given width or height while preserving the aspect ratio. The extra area is filled with a background color (white by default).                                                                   |

## Metadata options

Variants allow you to choose what to do with your image’s metadata information. From the **Metadata** dropdown, choose:

* Strip all metadata
* Strip all metadata except copyright
* Keep all metadata

## Public access

When the **Always allow public access** option is selected, particular variants will always be publicly accessible, even when images are made private through the use of [signed URLs](/images/manage-images/serve-images/serve-private-images).

---

# Delete images

URL: https://developers.cloudflare.com/images/manage-images/delete-images/

You can delete an image from the Cloudflare Images storage using the dashboard or the API.

## Delete images via the Cloudflare dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Select **Images**.
3. Find the image you want to remove and select **Delete**.
4. (Optional) To delete more than one image, select the checkbox next to the images you want to delete and then **Delete selected**.

Your image will be deleted from your account.

## Delete images via the API

Make a `DELETE` request to the [delete image endpoint](/api/resources/images/subresources/v1/methods/delete/). `{image_id}` must be fully URL encoded in the API call URL.

```bash
curl --request DELETE https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/{image_id} \
--header "Authorization: Bearer <API_TOKEN>"
```

After the image has been deleted, the response returns `"success": true`.

---

# Delete variants

URL: https://developers.cloudflare.com/images/manage-images/delete-variants/

You can delete variants via the Images dashboard or API. The only variant you cannot delete is public.

:::caution


Deleting a variant is a global action that will affect other images that contain that variant.


:::

## Delete variants via the Cloudflare dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Select **Images** > **Variants**.
3. Find the variant you want to remove and select **Delete**.

## Delete variants via the API

Make a `DELETE` request to the delete variant endpoint.

```bash
curl --request DELETE https://api.cloudflare.com/client/v4/account/{account_id}/images/v1/variants/{variant_name} \
--header "Authorization: Bearer <API_TOKEN>"
```

After the variant has been deleted, the response returns `"success": true.`

---

# Edit images

URL: https://developers.cloudflare.com/images/manage-images/edit-images/

The Edit option provides you available options to modify a specific image. After choosing to edit an image, you can:

* Require signed URLs to use with that particular image.
* Use a cURL command you can use as an example to access the image.
* Use fully-formed URLs for all the variants configured in your account.

To edit an image:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. In **Account Home**, select **Images**.
3. Locate the image you want to modify and select **Edit**.

---

# Enable flexible variants

URL: https://developers.cloudflare.com/images/manage-images/enable-flexible-variants/

Flexible variants allow you to create variants with dynamic resizing which can provide more options than regular variants allow. This option is not enabled by default.

## Enable flexible variants via the Cloudflare dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Select **Images** > **Variants**.
3. Enable **Flexible variants**.

## Enable flexible variants via the API

Make a `PATCH` request to the [Update a variant endpoint](/api/resources/images/subresources/v1/subresources/variants/methods/edit/).

```bash
curl --request PATCH https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/config \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"flexible_variants": true}'
```

After activation, you can use [transformation parameters](/images/transform-images/transform-via-url/#options) on any Cloudflare image. For example,

`https://imagedelivery.net/{account_hash}/{image_id}/w=400,sharpen=3`

Note that flexible variants cannot be used for images that require a [signed delivery URL](/images/manage-images/serve-images/serve-private-images).

---

# Manage uploaded images

URL: https://developers.cloudflare.com/images/manage-images/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Export images

URL: https://developers.cloudflare.com/images/manage-images/export-images/

Cloudflare Images supports image exports via the Cloudflare dashboard and API which allows you to get the original version of your image.

## Export images via the Cloudflare dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Select **Images**.
3. Find the image or images you want to export.
4. To export a single image, select **Export** from its menu. To export several images, select the checkbox next to each image and then select **Export selected**.

Your images are downloaded to your machine.

## Export images via the API

Make a `GET` request as shown in the example below. `<IMAGE_ID>` must be fully URL encoded in the API call URL.

`GET accounts/<ACCOUNT_ID>/images/v1/<IMAGE_ID>/blob`

---

# Changelog

URL: https://developers.cloudflare.com/images/platform/changelog/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/images.yaml. --> */}

<ProductReleaseNotes />

---

# Platform

URL: https://developers.cloudflare.com/images/platform/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Activate Polish

URL: https://developers.cloudflare.com/images/polish/activate-polish/

import { Render } from "~/components"

Images in the [cache must be purged](/cache/how-to/purge-cache/) or expired before seeing any changes in Polish settings.

:::caution


Do not activate Polish and [image transformations](/images/transform-images/) simultaneously. Image transformations already apply lossy compression, which makes Polish redundant.


:::

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select the account and domain where you want to activate Polish.
2. Go to **Speed** > **Optimization** > **Image Optimization**.
3. Under **Polish**, select *Lossy* or *Lossless* from the drop-down menu. [*Lossy*](/images/polish/compression/#lossy) gives greater file size savings.
4. (Optional) Select **WebP**. Enable this option if you want to further optimize PNG and JPEG images stored in the origin server, and serve them as WebP files to browsers that support this format.

To ensure WebP is not served from cache to a browser without WebP support, disable any WebP conversion utilities at your origin web server when using Polish.

<Render file="configuration-rule-promotion" product="rules" />

---

# Polish compression

URL: https://developers.cloudflare.com/images/polish/compression/

With Lossless and Lossy modes, Cloudflare attempts to strip as much metadata as possible. However, Cloudflare cannot guarantee stripping all metadata because other factors, such as caching status, might affect which metadata is finally sent in the response.

:::caution[Warning]

Polish may not be applied to origin responses that contain a `Vary` header. The only accepted `Vary` header is `Vary: Accept-Encoding`.

:::

## Compression options

### Off

Polish is disabled and no compression is applied. Disabling Polish does not revert previously polished images to original, until they expire or are purged from the cache.

### Lossless

The Lossless option attempts to reduce file sizes without changing any of the image pixels, keeping images identical to the original. It removes most metadata, like EXIF data, and losslessly recompresses image data. JPEG images may be converted to progressive format. On average, lossless compression reduces file sizes by 21 percent compared to unoptimized image files.

The Lossless option prevents conversion of JPEG to WebP, because this is always a lossy operation.

### Lossy

The Lossy option applies significantly better compression to images than the Lossless option, at a cost of small quality loss. When uncompressed, some of the redundant information from the original image is lost. On average, using Lossy mode reduces file sizes by 48 percent.

This option also removes metadata from images. The Lossy option mainly affects JPEG images, but PNG images may also be compressed in a lossy way, or converted to JPEG when this improves compression.

### WebP

When enabled, in addition to other optimizations, Polish creates versions of images converted to the WebP format.

WebP compression is quite effective on PNG images, reducing file sizes by approximately 26 percent.
It may reduce file sizes of JPEG images by around 17 percent, but this [depends on several factors](/images/polish/no-webp/).
WebP is supported in all browsers except for Internet Explorer and KaiOS. You can learn more in our [blog post](https://blog.cloudflare.com/a-very-webp-new-year-from-cloudflare/).

The WebP version is served only when the `Accept` header from the browser includes WebP, and the WebP image is significantly smaller than the lossy or lossless recompression of the original format:

```txt
Accept: image/avif,image/webp,image/*,*/*;q=0.8
```

Polish only converts standard image formats <em>to</em> the WebP format. If the origin server serves WebP images, Polish will not convert them, and will not optimize them.

#### File size, image quality, and WebP

Lossy formats like JPEG and WebP are able to generate files of any size, and every image could theoretically be made smaller. However, reduction in file size comes at a cost of reduction in image quality. Reduction of file sizes below each format's optimal size limit causes disproportionally large losses in quality. Re-encoding of files that are already optimized reduces their quality more than it reduces their file size.

Cloudflare will not convert from JPEG to WebP when the conversion would make the file bigger, or would reduce image quality by more than it would save in file size.

If you choose the Lossless Polish setting, then WebP will be used very rarely. This is due to the fact that, in this mode, WebP is only adequate for PNG images, and cannot improve compression for JPEG images.

Although WebP compresses better than JPEG on average, there are exceptions, and in some occasions JPEG compresses better than WebP. Cloudflare tries to detect these cases and keep the JPEG format.

If you serve low-quality JPEG images at the origin (quality setting 60 or lower), it may not be beneficial to convert them to WebP. This is because low-quality JPEG images have blocky edges and noise caused by compression, and these distortions increase file size of WebP images. We recommend serving high-quality JPEG images (quality setting between 80 and 90) at your origin server to avoid this issue.

If your server or Content Management System (CMS) has a built-in image converter or optimizer, it may interfere with Polish. It does not make sense to apply lossy optimizations twice to images, because quality degradation will be larger than the savings in file size.

## Polish interaction with Image optimization

Polish will not be applied to URLs using image transformations. Resized images already have lossy compression applied where possible, so they do not need the optimizations provided by Polish. Use the `format=auto` option to allow use of WebP and AVIF formats.

---

# Cf-Polished statuses

URL: https://developers.cloudflare.com/images/polish/cf-polished-statuses/

If a `Cf-Polished` header is not returned, try [using single-file cache purge](/cache/how-to/purge-cache) to purge the image. The `Cf-Polished` header may also be missing if the origin is sending non-image `Content-Type`, or non-cacheable `Cache-Control`.

* `input_too_large`: The input image is too large or complex to process, and needs a lower resolution. Cloudflare recommends using PNG or JPEG images that are less than 4,000 pixels in any dimension, and smaller than 20 MB.
* `not_compressed` or `not_needed`: The image was fully optimized at the origin server and no compression was applied.
* `webp_bigger`: Polish attempted to convert to WebP, but the WebP image was not better than the original format. Because the WebP version does not exist, the status is set on the JPEG/PNG version of the response. Refer to [the reasons why Polish chooses not to use WebP](/images/polish/no-webp/).
* `cannot_optimize` or `internal_error`: The input image is corrupted or incomplete at the origin server. Upload a new version of the image to the origin server.
* `format_not_supported`: The input image format is not supported (for example, BMP or TIFF) or the origin server is using additional optimization software that is not compatible with Polish. Try converting the input image to a web-compatible format (like PNG or JPEG) and/or disabling additional optimization software at the origin server.
* `vary_header_present`: The origin web server has sent a `Vary` header with a value other than `accept-encoding`. If the origin web server is attempting to support WebP, disable WebP at the origin web server and let Polish perform the WebP conversion. Polish will still work if `accept-encoding` is the only header listed within the `Vary` header. Polish skips image URLs processed by [Cloudflare Images](/images/transform-images/).

---

# Cloudflare Polish

URL: https://developers.cloudflare.com/images/polish/

import { FeatureTable } from "~/components"

Cloudflare Polish is a one-click image optimization product that automatically optimizes images in your site. Polish strips metadata from images and reduces image size through lossy or lossless compression to accelerate the speed of image downloads.

When an image is fetched from your origin, our systems automatically optimize it in Cloudflare's cache. Subsequent requests for the same image will get the smaller, faster, optimized version of the image, improving the speed of your website.

![Example of Polish compression's quality.](~/assets/images/images/polish.png)

## Comparison

* <b>Polish</b> automatically optimizes all images served from your origin server. It keeps the same image URLs, and does not require changing markup of your pages.
* <b>Cloudflare Images</b> API allows you to create new images with resizing, cropping, watermarks, and other processing applied. These images get their own new URLs, and you need to embed them on your pages to take advantage of this service. Images created this way are already optimized, and there is no need to apply Polish to them.

## Availability

<FeatureTable id="speed.polish" />

---

# WebP may be skipped

URL: https://developers.cloudflare.com/images/polish/no-webp/

Polish avoids converting images to the WebP format when such conversion would increase the file size, or significantly degrade image quality.
Polish also optimizes JPEG images, and the WebP format is not always better than a well-optimized JPEG.

To enhance the use of WebP in Polish, enable the [Lossy option](/images/polish/compression/#lossy). When you create new JPEG images, save them with a slightly higher quality than usually necessary.
We recommend JPEG quality settings between 85 and 95, but not higher. This gives Polish enough headroom for lossy conversion to WebP and optimized JPEG.

## In the **lossless** mode, it is not feasible to convert JPEG to WebP

WebP is actually a name for two quite different image formats: WebP-lossless (similar to PNG) and WebP-VP8 (similar to JPEG).

When the [Lossless option](/images/polish/compression/#lossless) is enabled, Polish will not perform any optimizations that change image pixels. This allows Polish to convert only between lossless image formats, such as PNG, GIF, and WebP-lossless. JPEG images will not be converted though, because the WebP-VP8 format does not support the conversion from JPEG without quality loss, and the WebP-lossless format does not compress images as heavily as JPEG.

In the lossless mode, Polish can still apply lossless optimizations to JPEG images. This is a unique feature of the JPEG format that does not have an equivalent in WebP.

## Low-quality JPEG images do not convert well to WebP

When JPEG files are already heavily compressed (for example, saved with a low quality setting like `q=50`, or re-saved many times), the conversion to WebP may not be beneficial, and may actually increase the file size. This is because lossy formats add distortions to images (for example, JPEG makes images blocky and adds noise around sharp edges), and the WebP format can not tell the difference between details of the image it needs to preserve and unwanted distortions caused by a previous compression. This forces WebP to wastefully use bytes on keeping the added noise and blockyness, which increases the file size, and makes compression less beneficial overall.

Polish never makes files larger. When we see that the conversion to WebP increases the file size, we skip it, and keep the smaller original file format.

## For some images conversion to WebP can degrade quality too much

The WebP format, in its more efficient VP8 mode, always loses some quality when compressing images. This means that the conversion from JPEG always makes WebP images look slightly worse. Polish ensures that file size savings from the conversion outweigh the quality loss.

Lossy WebP has a significant limitation: it can only keep one shade of color per 4 pixels. The color information is always stored at half of the image resolution. In high-resolution photos this degradation is rarely noticeable. However, in images with highly saturated colors and sharp edges, this limitation can result in the WebP format having noticeably pixelated or smudged edges.

Additionally, the WebP format applies smoothing to images. This feature hides blocky distortions that are a characteristic of low-quality JPEG images, but on the other hand it can cause loss of fine textures and details in high-quality images, making them look airbrushed.

Polish tries to avoid degrading images for too little gain. Polish keeps the JPEG format when it has about the same size as WebP, but better quality.

## Sometimes older formats are better than WebP

The WebP format has an advantage over JPEG when saving images with soft or blurry content, and when using low quality settings. WebP has fewer advantages when storing high-quality images with fine textures or noise. Polish applies optimizations to JPEG images too, and sometimes well-optimized JPEG is simply better than WebP, and gives a better quality and smaller file size at the same time. We try to detect these cases, and keep the JPEG format when it works better.
Sometimes animations with little motion are more efficient as GIF than animated WebP.

The WebP format does not support progressive rendering. With [HTTP/2 prioritization](/speed/optimization/protocol/enhanced-http2-prioritization/) enabled, progressive JPEG images may appear to load quicker, even if their file sizes are larger.

## Beware of compression that is not better, only more of the same

With a lossy format like JPEG or WebP, it is always possible to take an existing image, save it with a slightly lower quality, and get an image that looks *almost* the same, but has a smaller file size.
It is the [heap paradox](https://en.wikipedia.org/wiki/Sorites_paradox): you can remove a grain of sand from a heap, and still have a heap of sand. There is no point when you can not make the heap smaller, except when there is no sand left. It is always possible to make an image with a slightly lower quality, all the way until all the accumulated losses degrade the image beyond recognition.

Avoid applying multiple lossy optimization tools to images, before or after Polish. Multiple lossy operations degrade quality disproportionally more than what they save in file sizes.

For this reason Polish will not create the smallest possible file sizes. Instead, Polish aims to maximize the quality to file size ratio, to create the smallest possible files while preserving good quality. The quality level we stop at is carefully chosen to minimize visual distortion, while still having a high compression ratio.

---

# Reference

URL: https://developers.cloudflare.com/images/reference/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Security

URL: https://developers.cloudflare.com/images/reference/security/

To further ensure the security and efficiency of image optimization services, you can adopt Cloudflare products that safeguard against malicious activities.

Cloudflare security products like [Cloudflare WAF](/waf/), [Cloudflare Bot Management](/bots/get-started/bot-management/) and [Cloudflare Rate Limiting](/waf/rate-limiting-rules/) can enhance the protection of your image optimization requests against abuse. This proactive approach ensures a reliable and efficient experience for all legitimate users.

---

# Troubleshooting

URL: https://developers.cloudflare.com/images/reference/troubleshooting/

## Requests without resizing enabled

Does the response have a `Cf-Resized` header? If not, then resizing has not been attempted. Possible causes:

* The feature is not enabled in the Cloudflare Dashboard.
* There is another Worker running on the same request. Resizing is "forgotten" as soon as one Worker calls another. Do not use Workers scoped to the entire domain `/*`.
* Preview in the Editor in Cloudflare Dashboard does not simulate image resizing. You must deploy the Worker and test from another browser tab instead.

***

## Error responses from resizing

When resizing fails, the response body contains an error message explaining the reason, as well as the `Cf-Resized` header containing `err=code`:

* 9401 — The required arguments in `{cf:image{…}}` options are missing or are invalid. Try again. Refer to [Fetch options](/images/transform-images/transform-via-workers/#fetch-options) for supported arguments.
* 9402 — The image was too large or the connection was interrupted. Refer to [Supported formats and limitations](/images/transform-images/) for more information.
* 9403 — A [request loop](/images/transform-images/transform-via-workers/#prevent-request-loops) occurred because the image was already resized or the Worker fetched its own URL. Verify your Worker path and image path on the server do not overlap.
* 9406 & 9419 — The image URL is a non-HTTPS URL or the URL has spaces or unescaped Unicode. Check your URL and try again.
* 9407 — A lookup error occurred with the origin server's domain name. Check your DNS settings and try again.
* 9404 — The image does not exist on the origin server or the URL used to resize the image is wrong. Verify the image exists and check the URL.
* 9408 — The origin server returned an HTTP 4xx status code and may be denying access to the image. Confirm your image settings and try again.
* 9509 — The origin server returned an HTTP 5xx status code. This is most likely a problem with the origin server-side software, not the resizing.
* 9412 — The origin server returned a non-image, for example, an HTML page. This usually happens when an invalid URL is specified or server-side software has printed an error or presented a login page.
* 9413 — The image exceeds the maximum image area of 100 megapixels. Use a smaller image and try again.
* 9420 — The origin server redirected to an invalid URL. Confirm settings at your origin and try again.
* 9421 — The origin server redirected too many times. Confirm settings at your origin and try again.
* 9422 - The transformation request is rejected because the usage limit was reached. If you need to request more than 5,000 unique transformations, upgrade to an Images Paid plan.
* 9432 — The Images Binding is not available using legacy billing. Your account is using the legacy Image Resizing subscription. To bind Images to your Worker, you will need to update your plan to the Images subscription in the dashboard.
* 9504, 9505, & 9510 — The origin server could not be contacted because the origin server may be down or overloaded. Try again later.
* 9523 — The `/cdn-cgi/image/` resizing service could not perform resizing. This may happen when an image has invalid format. Use correctly formatted image and try again.
* 9524 — The `/cdn-cgi/image/` resizing service could not perform resizing. This may happen when an image URL is intercepted by a Worker. As an alternative you can [resize within the Worker](/images/transform-images/transform-via-workers/). This can also happen when using a `pages.dev` URL of a [Cloudflare Pages](/pages/) project. In that case, you can use a [Custom Domain](/pages/configuration/custom-domains/) instead.
* 9520 — The image format is not supported. Refer to [Supported formats and limitations](/images/transform-images/) to learn about supported input and output formats.
* 9522 — The image exceeded the processing limit. This may happen briefly after purging an entire zone or when files with very large dimensions are requested. If the problem persists, contact support.
* 9422, 9424, 9516, 9517, 9518, 9522 & 9523 — Internal errors. Please contact support if you encounter these errors.

***

## Limits

* Maximum image size is 100 megapixels (meaning 10.000×10.000 pixels large). Maximum file size is 100 MB. GIF/WebP animations are limited to 50 megapixels total (sum of sizes of all frames).
* Image Resizing is not compatible with [Bringing Your Own IPs (BYOIP)](/byoip/).
* When Polish can't optimize an image the Response Header `Warning: cf-images 299 "original is smaller"` is returned.

***

## Authorization and cookies are not supported

Image requests to the origin will be anonymized (no cookies, no auth, no custom headers). This is because we have to have one public cache for resized images, and it would be unsafe to share images that are personalized for individual visitors.

However, in cases where customers agree to store such images in public cache, Cloudflare supports resizing images through Workers [on authenticated origins](/images/transform-images/transform-via-workers/).

***

## Caching and purging

Changes to image dimensions or other resizing options always take effect immediately — no purging necessary.

Image requests consists of two parts: running Worker code, and image processing. The Worker code is always executed and uncached. Results of image processing are cached for one hour or longer if origin server's `Cache-Control` header allows. Source image is cached using regular caching rules. Resizing follows redirects internally, so the redirects are cached too.

Because responses from Workers themselves are not cached at the edge, purging of *Worker URLs* does nothing. Resized image variants are cached together under their source’s URL. When purging, use the (full-size) source image’s URL, rather than URLs of the Worker that requested resizing.

If the origin server sends an `Etag` HTTP header, the resized images will have an `Etag` HTTP header that has a format `cf-<gibberish>:<etag of the original image>`. You can compare the second part with the `Etag` header of the source image URL to check if the resized image is up to date.

---

# Tutorials

URL: https://developers.cloudflare.com/images/tutorials/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Transform user-uploaded images before uploading to R2

URL: https://developers.cloudflare.com/images/tutorials/optimize-user-uploaded-image/

import { WranglerConfig, Render } from "~/components"


In this guide, you will build an app that accepts image uploads, overlays the image with a visual watermark, then stores the transformed image in your R2 bucket.

---

With Images, you have the flexibility to choose where your original images are stored. You can transform images that are stored outside of the Images product, like in [R2](/r2/).

When you store user-uploaded media in R2, you may want to optimize or manipulate images before they are uploaded to your R2 bucket.

You will learn how to connect Developer Platform services to your Worker through bindings, as well as use various optimization features in the Images API.

## Prerequisites

Before you begin, you will need to do the following:

* Add an [Images Paid](/images/pricing/#images-paid) subscription to your account. This allows you to bind the Images API to your Worker.
* Create an [R2 bucket](/r2/get-started/#2-create-a-bucket), where the transformed images will be uploaded.
* Create a new Worker project.

If you are new, review how to [create your first Worker](/workers/get-started/guide/).


## 1: Set up your Worker project

To start, you will need to set up your project to use the following resources on the Developer Platform:

* [Images](/images/transform-images/bindings/) to transform, resize, and encode images directly from your Worker.
* [R2](/r2/api/workers/workers-api-usage/) to connect the bucket for storing transformed images.
* [Assets](/workers/static-assets/binding/) to access a static image that will be used as the visual watermark.


### Add the bindings to your Wrangler configuration

Configure your `wrangler.toml` file to add the Images, R2, and Assets bindings:

<WranglerConfig>
```toml
[images]
binding = "IMAGES"

[[r2_buckets]]
binding = "R2"
bucket_name = "<BUCKET>"

[assets]
directory = "./<DIRECTORY>"
binding = "ASSETS"
```

</WranglerConfig>
Replace `<BUCKET>` with the name of the R2 bucket where you will upload the images after they are transformed. In your Worker code, you will be able to refer to this bucket using `env.R2.`

Replace `./<DIRECTORY>` with the name of the project's directory where the overlay image will be stored. In your Worker code, you will be able to refer to these assets using `env.ASSETS`.

### Set up your assets directory

Because we want to apply a visual watermark to every uploaded image, you need a place to store the overlay image.

The assets directory of your project lets you upload static assets as part of your Worker. When you deploy your project, these uploaded files, along with your Worker code, are deployed to Cloudflare's infrastructure in a single operation.

After you configure your Wrangler file, upload the overlay image to the specified directory. In our example app, the directory `./assets` contains the overlay image.


## 2: Build your frontend

You will need to build the interface for the app that lets users upload images.

In this example, the frontend is rendered directly from the Worker script.

To do this, make a new `html` variable, which contains a `form` element for accepting uploads. In `fetch`, construct a new `Response` with a `Content-Type: text/html` header to serve your static HTML site to the client:

```js
const html = `
<!DOCTYPE html>
        <html>
          <head>
            <meta charset="UTF-8">
            <title>Upload Image</title>
          </head>
          <body>
            <h1>Upload an image</h1>
            <form method="POST" enctype="multipart/form-data">
              <input type="file" name="image" accept="image/*" required />
              <button type="submit">Upload</button>
            </form>
          </body>
        </html>
`;

export default {
  async fetch(request, env) {
    if (request.method === "GET") {
      return new Response(html, {headers:{'Content-Type':'text/html'},})
    }
    if (request.method ==="POST") {
      // This is called when the user submits the form
    }
  }
};
```

## 3: Read the uploaded image

After you have a `form`, you need to make sure you can transform the uploaded images.

Because the `form` lets users upload directly from their disk, you cannot use `fetch()` to get an image from a URL. Instead, you will operate on the body of the image as a stream of bytes.

To do this, parse the data from the `form` as an array buffer:

```js
export default {
  async fetch(request, env) {
    if (request.method === "GET") {
      return new Response(html, {headers:{'Content-Type':'text/html'},})
    }
    if (request.method === "POST") {
      try {
        // Parse form data
        const formData = await request.formData();
        const file = formData.get("image");
        if (!file || typeof file.arrayBuffer !== "function") {
          return new Response("No image file provided", { status: 400 });
        }

        // Read uploaded image as array buffer
        const fileBuffer = await file.arrayBuffer();
      } catch (err) {
        console.log(err.message)
      }
    }
  }
};
```

<Render file="request-dot-clone-warning" product="workers" />

## 4: Transform the image

For every uploaded image, you want to perform the following actions:

- Overlay the visual watermark that we added to our assets directory.
- Transcode the image — with its watermark — to `AVIF`. This compresses the image and reduces its file size.
- Upload the transformed image to R2.

### Set up the overlay image

To fetch the overlay image from the assets directory, create a function `assetUrl` then use `env.ASSETS` to retrieve the `watermark.png` image:

```js
var __defProp = Object.defineProperty;
var __name = (target, value) => __defProp(target, "name", { value, configurable: true });

function assetUrl(request, path) {
	const url = new URL(request.url);
	url.pathname = path;
	return url;
}
__name(assetUrl, "assetUrl");

export default {
  async fetch(request, env) {
    if (request.method === "GET") {
      return new Response(html, {headers:{'Content-Type':'text/html'},})
    }
    if (request.method === "POST") {
      try {
        // Parse form data
        const formData = await request.formData();
        const file = formData.get("image");
        if (!file || typeof file.arrayBuffer !== "function") {
          return new Response("No image file provided", { status: 400 });
        }

        // Read uploaded image as array buffer
        const fileBuffer = await file.arrayBuffer();

	      // Fetch image as watermark
        let watermarkStream = (await env.ASSETS.fetch(assetUrl(request, "watermark.png"))).body;
      } catch (err) {
        console.log(err.message)
      }
    }
  }
};
```

### Watermark and transcode the image

You can interact with the Images binding through `env.IMAGES`.

This is where you will put all of the optimization operations you want to perform on the image. Here, you will use the `.draw()` function to apply a visual watermark over the uploaded image, then use `.output()` to encode the image as AVIF:

```js
var __defProp = Object.defineProperty;
var __name = (target, value) => __defProp(target, "name", { value, configurable: true });

function assetUrl(request, path) {
	const url = new URL(request.url);
	url.pathname = path;
	return url;
}
__name(assetUrl, "assetUrl");

export default {
  async fetch(request, env) {
    if (request.method === "GET") {
      return new Response(html, {headers:{'Content-Type':'text/html'},})
    }
    if (request.method === "POST") {
      try {
        // Parse form data
        const formData = await request.formData();
        const file = formData.get("image");
        if (!file || typeof file.arrayBuffer !== "function") {
          return new Response("No image file provided", { status: 400 });
        }

        // Read uploaded image as array buffer
        const fileBuffer = await file.arrayBuffer();

	      // Fetch image as watermark
        let watermarkStream = (await env.ASSETS.fetch(assetUrl(request, "watermark.png"))).body;

        // Apply watermark and convert to AVIF
        const imageResponse = (
          await env.IMAGES.input(fileBuffer)
              // Draw the watermark on top of the image
              .draw(
                env.IMAGES.input(watermarkStream)
                  .transform({ width: 100, height: 100 }),
                { bottom: 10, right: 10, opacity: 0.75 }
              )
              // Output the final image as AVIF
              .output({ format: "image/avif" })
          ).response();
      } catch (err) {
        console.log(err.message)
      }
    }
  }
};
```

## 5: Upload to R2

Upload the transformed image to R2.

By creating a `fileName` variable, you can specify the name of the transformed image. In this example, you append the date to the name of the original image before uploading to R2.

Here is the full code for the example:

```js
var __defProp = Object.defineProperty;
var __name = (target, value) => __defProp(target, "name", { value, configurable: true });

function assetUrl(request, path) {
	const url = new URL(request.url);
	url.pathname = path;
	return url;
}
__name(assetUrl, "assetUrl");

export default {
  async fetch(request, env) {
    if (request.method === "GET") {
      return new Response(html, {headers:{'Content-Type':'text/html'},})
    }
    if (request.method === "POST") {
      try {
        // Parse form data
        const formData = await request.formData();
        const file = formData.get("image");
        if (!file || typeof file.arrayBuffer !== "function") {
          return new Response("No image file provided", { status: 400 });
        }

        // Read uploaded image as array buffer
        const fileBuffer = await file.arrayBuffer();

	      // Fetch image as watermark
        let watermarkStream = (await env.ASSETS.fetch(assetUrl(request, "watermark.png"))).body;

        // Apply watermark and convert to AVIF
        const imageResponse = (
          await env.IMAGES.input(fileBuffer)
              // Draw the watermark on top of the image
              .draw(
                env.IMAGES.input(watermarkStream)
                  .transform({ width: 100, height: 100 }),
                { bottom: 10, right: 10, opacity: 0.75 }
              )
              // Output the final image as AVIF
              .output({ format: "image/avif" })
          ).response();

          // Add timestamp to file name
          const fileName = `image-${Date.now()}.avif`;

          // Upload to R2
          await env.R2.put(fileName, imageResponse.body)

          return new Response(`Image uploaded successfully as ${fileName}`, { status: 200 });
      } catch (err) {
        console.log(err.message)
      }
    }
  }
};
```

## Next steps

In this tutorial, you learned how to connect your Worker to various resources on the Developer Platform to build an app that accepts image uploads, transform images, and uploads the output to R2.

Next, you can [set up a transformation URL](/images/transform-images/transform-via-url/) to dynamically optimize images that are stored in R2.

---

# Bind to Workers API

URL: https://developers.cloudflare.com/images/transform-images/bindings/

import { WranglerConfig } from "~/components";

A [binding](/workers/runtime-apis/bindings/) connects your [Worker](/workers/) to external resources on the Developer Platform, like [Images](/images/transform-images/transform-via-workers/), [R2 buckets](/r2/buckets/), or [KV Namespaces](/kv/concepts/kv-namespaces/).

You can bind the Images API to your Worker to transform, resize, and encode images without requiring them to be accessible through a URL.

For example, when you allow Workers to interact with Images, you can:

- Transform an image, then upload the output image directly into R2 without serving to the browser.
- Optimize an image stored in R2 by passing the blob of bytes representing the image, instead of fetching the public URL for the image.
- Resize an image, overlay the output over a second image as a watermark, then resize this output into a final result.

Bindings can be configured in the Cloudflare dashboard for your Worker or in the `wrangler.toml` file in your project's directory.

## Setup

The Images binding is enabled on a per-Worker basis.

You can define variables in the `wrangler.toml` file of your Worker project's directory. These variables are bound to external resources at runtime, and you can then interact with them through this variable.

To bind Images to your Worker, add the following to the end of your `wrangler.toml` file:

<WranglerConfig>

```jsonc
{
	"images": {
		"binding": "IMAGES", // i.e. available in your Worker on env.IMAGES
	},
}
```

</WranglerConfig>

Within your Worker code, you can interact with this binding by using `env.IMAGES.input()` to build an object that can manipulate the image (passed as a `ReadableStream`).

## Methods

### `.transform()`

- Defines how an image should be optimized and manipulated through [parameters](/images/transform-images/transform-via-workers/#fetch-options) such as `width`, `height`, and `blur`.

### `.draw()`

- Allows [drawing an image](/images/transform-images/draw-overlays/) over another image.
- The drawn image can be a stream, or another image returned from `.input()` that has been manipulated.
- The overlaid image can be manipulated using `opacity`, `repeat`, `top`, `left`, `bottom`, and `right`. To apply other parameters, you can pass a child `.transform()` function inside this method.

For example, to draw a resized watermark on an image:

```ts
// Fetch the watermark from Workers Assets, R2, KV etc
const watermark: ReadableStream = ...

// Fetch the main image
const image: ReadableStream = ...

const response = (
  await env.IMAGES.input(image)
    .draw(
        env.IMAGES.input(watermark)
          .transform({ width: 32, height: 32}),
        { bottom: 32, right: 32 }
    )
    .output({ format: "image/avif" })
).response()

return response;
```

### `.output()`

- Defines the [output format](/images/transform-images/) for the transformed image such as AVIF, WebP, and JPEG.

For example, to rotate, resize, and blur an image, then output the image as AVIF:

```ts
const info = await env.IMAGES.info(stream);
// stream contains a valid image, and width/height is available on the info object

const response = (
	await env.IMAGES.input(stream)
		.transform({ rotate: 90 })
		.transform({ width: 128 })
		.transform({ blur: 20 })
		.output({ format: "image/avif" })
).response();

return response;
```

### `.info()`

- Outputs information about the image, such as `format`, `fileSize`, `width`, and `height`.

Responses from the Images binding are not automatically cached. Workers lets you interact directly with the Cache API to customize cache behavior using Workers. You can implement logic in your script to store transformations in Cloudflare’s cache.

## Interact with your Images binding locally

The Images API can be used in local development through [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Workers. Using the Images binding in local development will not incur usage charges.

Wrangler supports two different versions of the Images API:

- A high-fidelity version that supports all features that are available through the Images API. This is the same version that Cloudflare runs globally in production.
- A low-fidelity offline version that supports only a subset of features, such as resizing and rotation.

To test the high-fidelity version of Images, you can run `wrangler dev`:

```txt
npx wrangler dev
```

This creates a local-only environment that mirrors the production environment where Cloudflare runs the Images API. You can test your Worker with all available transformation features before deploying to production.

To test the low-fidelity offline version of Images, add the `--experimental-images-local-mode` flag:

```txt
npm wrangler dev --experimental-images-local-mode
```

Currently, this version supports only `width`, `height`, `rotate`, and `format`.

When testing with the [Workers Vitest integration](/workers/testing/vitest-integration/), the low-fidelity offline version is used by default, to avoid hitting the Cloudflare API in tests.

---

# Control origin access

URL: https://developers.cloudflare.com/images/transform-images/control-origin-access/

You can serve resized images without giving access to the original image. Images can be hosted on another server outside of your zone, and the true source of the image can be entirely hidden. The origin server may require authentication to disclose the original image, without needing visitors to be aware of it. Access to the full-size image may be prevented by making it impossible to manipulate resizing parameters.

All these behaviors are completely customizable, because they are handled by custom code of a script running [on the edge in a Cloudflare Worker](/images/transform-images/transform-via-workers/).

```js
export default {
	async fetch(request, env, ctx) {
		// Here you can compute arbitrary imageURL and
		// resizingOptions from any request data ...
		return fetch(imageURL, { cf: { image: resizingOptions } });
	},
};
```

This code will be run for every request, but the source code will not be accessible to website visitors. This allows the code to perform security checks and contain secrets required to access the images in a controlled manner.

The examples below are only suggestions, and do not have to be followed exactly. You can compute image URLs and resizing options in many other ways.

:::caution[Warning]

When testing image transformations, make sure you deploy the script and test it from a regular web browser window. The preview in the dashboard does not simulate transformations.

:::

## Hiding the image server

```js
export default {
	async fetch(request, env, ctx) {
		const resizingOptions = {
			/* resizing options will be demonstrated in the next example */
		};

		const hiddenImageOrigin = "https://secret.example.com/hidden-directory";
		const requestURL = new URL(request.url);
		// Append the request path such as "/assets/image1.jpg" to the hiddenImageOrigin.
		// You could also process the path to add or remove directories, modify filenames, etc.
		const imageURL = hiddenImageOrigin + requestURL.path;
		// This will fetch image from the given URL, but to the website's visitors this
		// will appear as a response to the original request. Visitor’s browser will
		// not see this URL.
		return fetch(imageURL, { cf: { image: resizingOptions } });
	},
};
```

## Preventing access to full-size images

On top of protecting the original image URL, you can also validate that only certain image sizes are allowed:

```js
export default {
  async fetch(request, env, ctx) {
  const imageURL = … // detail omitted in this example, see the previous example

  const requestURL = new URL(request.url)
  const resizingOptions = {
    width: requestURL.searchParams.get("width"),
  }
  // If someone tries to manipulate your image URLs to reveal higher-resolution images,
  // you can catch that and refuse to serve the request (or enforce a smaller size, etc.)
  if (resizingOptions.width > 1000) {
    throw Error("We don’t allow viewing images larger than 1000 pixels wide")
  }
  return fetch(imageURL, {cf:{image:resizingOptions}})
},};
```

## Avoid image dimensions in URLs

You do not have to include actual pixel dimensions in the URL. You can embed sizes in the Worker script, and select the size in some other way — for example, by naming a preset in the URL:

```js
export default {
	async fetch(request, env, ctx) {
		const requestURL = new URL(request.url);
		const resizingOptions = {};

		// The regex selects the first path component after the "images"
		// prefix, and the rest of the path (e.g. "/images/first/rest")
		const match = requestURL.path.match(/images\/([^/]+)\/(.+)/);

		// You can require the first path component to be one of the
		// predefined sizes only, and set actual dimensions accordingly.
		switch (match && match[1]) {
			case "small":
				resizingOptions.width = 300;
				break;
			case "medium":
				resizingOptions.width = 600;
				break;
			case "large":
				resizingOptions.width = 900;
				break;
			default:
				throw Error("invalid size");
		}

		// The remainder of the path may be used to locate the original
		// image, e.g. here "/images/small/image1.jpg" would map to
		// "https://storage.example.com/bucket/image1.jpg" resized to 300px.
		const imageURL = "https://storage.example.com/bucket/" + match[2];
		return fetch(imageURL, { cf: { image: resizingOptions } });
	},
};
```

## Authenticated origin

Cloudflare image transformations cache resized images to aid performance. Images stored with restricted access are generally not recommended for resizing because sharing images customized for individual visitors is unsafe. However, in cases where the customer agrees to store such images in public cache, Cloudflare supports resizing images through Workers. At the moment, this is supported on authenticated AWS, Azure, Google Cloud, SecureAuth origins and origins behind Cloudflare Access.

```js null {9}
// generate signed headers (application specific)
const signedHeaders = generatedSignedHeaders();

fetch(private_url, {
  headers: signedHeaders
  cf: {
    image: {
      format: "auto",
      "origin-auth": "share-publicly"
     }
  }
})
```

When using this code, the following headers are passed through to the origin, and allow your request to be successful:

- `Authorization`
- `Cookie`
- `x-amz-content-sha256`
- `x-amz-date`
- `x-ms-date`
- `x-ms-version`
- `x-sa-date`
- `cf-access-client-id`
- `cf-access-client-secret`

For more information, refer to:

- [AWS docs](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)
- [Azure docs](https://docs.microsoft.com/en-us/rest/api/storageservices/List-Containers2#request-headers)
- [Google Cloud docs](https://cloud.google.com/storage/docs/aws-simple-migration)
- [Cloudflare Zero Trust docs](/cloudflare-one/identity/service-tokens/)
- [SecureAuth docs](https://docs.secureauth.com/2104/en/authentication-api-guide.html)

---

# Draw overlays and watermarks

URL: https://developers.cloudflare.com/images/transform-images/draw-overlays/

You can draw additional images on top of a resized image, with transparency and blending effects. This enables adding of watermarks, logos, signatures, vignettes, and other effects to resized images.

This feature is available only in [Workers](/images/transform-images/transform-via-workers/). To draw overlay images, add an array of drawing commands to options of `fetch()` requests. The drawing options are nested in `options.cf.image.draw`, like in the following example:

```js
fetch(imageURL, {
  cf: {
    image: {
      width: 800,
      height: 600,
      draw: [
        {
          url: 'https://example.com/branding/logo.png', // draw this image
          bottom: 5, // 5 pixels from the bottom edge
          right: 5, // 5 pixels from the right edge
          fit: 'contain', // make it fit within 100x50 area
          width: 100,
          height: 50,
          opacity: 0.8, // 20% transparent
        },
      ],
    },
  },
});
```

## Draw options

The `draw` property is an array. Overlays are drawn in the order they appear in the array (the last array entry is the topmost layer). Each item in the `draw` array is an object, which can have the following properties:



* `url`
  * Absolute URL of the image file to use for the drawing. It can be any of the supported file formats. For drawing watermarks or non-rectangular overlays, Cloudflare recommends that you use PNG or WebP images.

* `width` and `height`
  * Maximum size of the overlay image, in pixels. It must be an integer.

* `fit` and `gravity`
  * Affects interpretation of `width` and `height`. Same as [for the main image](/images/transform-images/transform-via-workers/#fetch-options).

* `opacity`
  * Floating-point number between `0` (transparent) and `1` (opaque). For example, `opacity: 0.5` makes overlay semitransparent.

* `repeat`
  * If set to `true`, the overlay image will be tiled to cover the entire area. This is useful for stock-photo-like watermarks.
  * If set to `"x"`, the overlay image will be tiled horizontally only (form a line).
  * If set to `"y"`, the overlay image will be tiled vertically only (form a line).

* `top`, `left`, `bottom`, `right`
  * Position of the overlay image relative to a given edge. Each property is an offset in pixels. `0` aligns exactly to the edge. For example, `left: 10` positions left side of the overlay 10 pixels from the left edge of the image it is drawn over. `bottom: 0` aligns bottom of the overlay with bottom of the background image.

    Setting both `left` and `right`, or both `top` and `bottom` is an error.

    If no position is specified, the image will be centered.

* `background`
  * Background color to add underneath the overlay image. Same as [for the main image](/images/transform-images/transform-via-workers/#fetch-options).

* `rotate`
  * Number of degrees to rotate the overlay image by. Same as [for the main image](/images/transform-images/transform-via-workers/#fetch-options).

## Draw using the Images binding

When [interacting with Images through a binding](/images/transform-images/bindings/), the Images API supports a `.draw()` method.

The accepted options for the overlaid image are `opacity`, `repeat`, `top`, `left`, `bottom`, and `right`.

```js
// Fetch image and watermark
const img = await fetch('https://example.com/image.png');
const watermark = await fetch('https://example.com/watermark.png');

const response = await env.IMAGES.input(img.body)
  .transform({ width: 1024 })
  .draw(watermark.body, { "opacity": 0.25, "repeat": true })
  .output({ format: "image/avif" })
  .response();

return response;
```

To apply [parameters](/images/transform-images/transform-via-workers/) to the overlaid image, you can pass a child `.transform()` function inside the `.draw()` request.

In the example below, the watermark is manipulated with `rotate` and `width` before being drawn over the base image with the `opacity` and `rotate` options.

```js
// Fetch image and watermark
const response = (
  await env.IMAGES.input(img.body)
    .transform({ width: 1024 })
    .draw(watermark.body, { "opacity": 0.25, "repeat": true })
    .output({ format: "image/avif" })
).response();
```

## Examples

### Stock Photo Watermark

```js
image: {
  draw: [
    {
      url: 'https://example.com/watermark.png',
      repeat: true, // Tiled over entire image
      opacity: 0.2, // and subtly blended
    },
  ];
}
```

### Signature

```js
image: {
  draw: [
    {
      url: 'https://example.com/by-me.png', // Predefined logo/signature
      bottom: 5, // Positioned near bottom right corner
      right: 5,
    },
  ];
}
```

### Centered icon

```js
image: {
  draw: [
    {
      url: 'https://example.com/play-button.png',
      // Center position is the default
    },
  ];
}
```

### Combined

Multiple operations can be combined in one image:

```js
image: {
  draw: [
    { url: 'https://example.com/watermark.png', repeat: true, opacity: 0.2 },
    { url: 'https://example.com/play-button.png' },
    { url: 'https://example.com/by-me.png', bottom: 5, right: 5 },
  ];
}
```

---

# Transform images

URL: https://developers.cloudflare.com/images/transform-images/

import { Render } from "~/components"

Transformations let you optimize and manipulate images stored outside of the Cloudflare Images product. Transformed images are served from one of your zones on Cloudflare.

To transform an image, you must [enable transformations for your zone](/images/get-started/#enable-transformations-on-your-zone).

You can transform an image by using a [specially-formatted URL](/images/transform-images/transform-via-url/) or [through Workers](/images/transform-images/transform-via-workers/).

## Supported formats and limitations

### Supported input formats

* JPEG
* PNG
* GIF (including animations)
* WebP (including animations)
* SVG

### Supported output formats

* JPEG
* PNG
* GIF (including animations)
* WebP (including animations)
* SVG
* AVIF

### Supported features

Transformations can:

* Resize and generate JPEG and PNG images, and optionally AVIF or WebP.
* Save animations as GIF or animated WebP.
* Support ICC color profiles in JPEG and PNG images.
* Preserve JPEG metadata (metadata of other formats is discarded).
* Convert the first frame of GIF/WebP animations to a still image.

<Render file="svg" />

### Format limitations

Since some image formats require longer computational times than others, Cloudflare has to find a proper balance between the time it takes to generate an image and to transfer it over the Internet.

Resizing requests might not be fulfilled with the format the user expects due to these trade-offs Cloudflare has to make. Images differ in size, transformations, codecs and all of these different aspects influence what compression codecs are used.

Cloudflare tries to choose the requested codec, but we operate on a best-effort basis and there are limits that our system needs to follow to satisfy all customers.

AVIF encoding, in particular, can be an order of magnitude slower than encoding to other formats. Cloudflare will fall back to WebP or JPEG if the image is too large to be encoded quickly.

#### Limits per format

Hard limits refers to the maximum image size to process. Soft limits refers to the limits existing when the system is overloaded.

| File format | Hard limits on the longest side (width or height) | Soft limits on the longest side (width or height) |
| ----------- | ------------------------------------------------- | ------------------------------------------------- |
| AVIF        | 1,200 pixels<sup>1</sup>                          | 640 pixels                                        |
| Other       | 12,000 pixels                                     | N/A                                               |
| WebP        | N/A                                               | 2,560 pixels for lossy; 1920 pixels for lossless  |

<sup>1</sup>Hard limit is 1,600 pixels when `format=avif` is explicitly used with [image transformations](/images/transform-images/).

All images have to be less than 70 MB. The maximum image area is limited to 100 megapixels (for example, 10,000 x 10,000 pixels large).

GIF/WebP animations are limited to a total of 50 megapixels (the sum of sizes of all frames). Animations that exceed this will be passed through unchanged without applying any transformations. Note that GIF is an outdated format and has very inefficient compression. High-resolution animations will be slow to process and will have very large file sizes. For video clips, Cloudflare recommends using [video formats like MP4 and WebM instead](/stream/).

:::caution[Important]

SVG files are passed through without resizing. This format is inherently scalable and does not need resizing. Cloudflare does not support the HEIC (HEIF) format and does not plan to support it.

AVIF format is supported on a best-effort basis. Images that cannot be compressed as AVIF will be served as WebP instead.


:::

#### Progressive JPEG

While you can use the `format=jpeg` option to generate images in an interlaced progressive JPEG format, we will fallback to the baseline JPEG format for small and large images specified when:

* The area calculated by width x height is less than 150 x 150.
* The area calculated by width x height is greater than 3000 x 3000.

For example, a 50 x 50 tiny image is always formatted by `baseline-jpeg` even if you specify progressive jpeg (`format=jpeg`).

---

# Integrate with frameworks

URL: https://developers.cloudflare.com/images/transform-images/integrate-with-frameworks/

## Next.js

Image transformations can be used automatically with the Next.js [`<Image />` component](https://nextjs.org/docs/api-reference/next/image).

To use image transformations, define a global image loader or multiple custom loaders for each `<Image />` component.

Next.js will request the image with the correct parameters for width and quality.

Image transformations will be responsible for caching and serving an optimal format to the client.

### Global Loader

To use Images with **all** your app's images, define a global [loaderFile](https://nextjs.org/docs/pages/api-reference/components/image#loaderfile) for your app.

Add the following settings to the **next.config.js** file located at the root our your Next.js application.

```ts
module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './imageLoader.ts',
  },
}
```

Next, create the `imageLoader.ts` file in the specified path (relative to the root of your Next.js application).

```ts
const normalizeSrc = (src: string) => {
    return src.startsWith("/") ? src.slice(1) : src;
};

export default function cloudflareLoader({
    src,
    width,
    quality,
}: { src: string; width: number; quality?: number }) {
    if (process.env.NODE_ENV === "development") {
        return src;
    }
    const params = [`width=${width}`];
    if (quality) {
        params.push(`quality=${quality}`);
    }
    const paramsString = params.join(",");
    return `/cdn-cgi/image/${paramsString}/${normalizeSrc(src)}`;
}
```

### Custom Loaders

Alternatively, define a loader for each `<Image />` component.

```js
import Image from 'next/image';

const normalizeSrc = src => {
  return src.startsWith('/') ? src.slice(1) : src;
};

const cloudflareLoader = ({ src, width, quality }) => {
  if (process.env.NODE_ENV === "development") {
  	return src;
  }
  const params = [`width=${width}`];
  if (quality) {
    params.push(`quality=${quality}`);
  }
  const paramsString = params.join(',');
  return `/cdn-cgi/image/${paramsString}/${normalizeSrc(src)}`;
};

const MyImage = props => {
  return (
    <Image
      loader={cloudflareLoader}
      src="/me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  );
};
```

:::note


For local development, you can enable [Resize images from any origin checkbox](/images/get-started/) for your zone. Then, replace `/cdn-cgi/image/${paramsString}/${normalizeSrc(src)}` with an absolute URL path:

`https://<YOUR_DOMAIN.COM>/cdn-cgi/image/${paramsString}/${normalizeSrc(src)}`


:::

---

# Make responsive images

URL: https://developers.cloudflare.com/images/transform-images/make-responsive-images/

You can serve responsive images in two different ways:
- Use the HTML `srcset` feature to allow browsers to choose the most optimal image. This is the most reliable solution to serve responsive images.
- Use the `width=auto` option to serve the most optimal image based on the available browser and device information. This is a server-side solution that is supported only by Chromium-based browsers.

## Transform with HTML `srcset`

The `srcset` [feature of HTML](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images) allows browsers to automatically choose an image that is best suited for user’s screen resolution.

`srcset` requires providing multiple resized versions of every image, and with Cloudflare’s image transformations this is an easy task to accomplish.

There are two different scenarios where it is useful to use `srcset`:

* Images with a fixed size in terms of CSS pixels, but adapting to high-DPI screens (also known as Retina displays). These images take the same amount of space on the page regardless of screen size, but are sharper on high-resolution displays. This is appropriate for icons, thumbnails, and most images on pages with fixed-width layouts.
* Responsive images that stretch to fill a certain percentage of the screen (usually full width). This is best for hero images and pages with fluid layouts, including pages using media queries to adapt to various screen sizes.

### `srcset` for high-DPI displays

For high-DPI display you need two versions of every image. One for `1x` density, suitable for typical desktop displays (such as HD/1080p monitors or low-end laptops), and one for `2x` high-density displays used by almost all mobile phones, high-end laptops, and 4K desktop displays. Some mobile phones have very high-DPI displays and could use even a `3x` resolution. However, while the jump from `1x` to `2x` is a clear improvement, there are diminishing returns from increasing the resolution further. The difference between `2x` and `3x` is visually insignificant, but `3x` files are two times larger than `2x` files.

Assuming you have an image `product.jpg` in the `assets` folder and you want to display it at a size of `960px`, the code is as follows:

```html
<img
  src="/cdn-cgi/image/fit=contain,width=960/assets/product.jpg"
  srcset="/cdn-cgi/image/fit=contain,width=1920/assets/product.jpg 2x"
/>
```

In the URL path used in this example, the `src` attribute is for images with the usual "1x" density. `/cdn-cgi/image/` is a special path for resizing images. This is followed by `width=960` which resizes the image to have a width of 960 pixels. `/assets/product.jpg` is a URL to the source image on the server.

The `srcset` attribute adds another, high-DPI image. The browser will automatically select between the images in the `src` and `srcset`. In this case, specifying `width=1920` (two times 960 pixels) and adding `2x` at the end, informs the browser that this is a double-density image. It will be displayed at the same size as a 960 pixel image, but with double the number of pixels which will make it look twice as sharp on high-DPI displays.

Note that it does not make sense to scale images up for use in `srcset`. That would only increase file sizes without improving visual quality. The source images you should use with `srcset` must be high resolution, so that they are only scaled down for `1x` displays, and displayed as-is or also scaled down for `2x` displays.

### `srcset` for responsive images

When you want to display an image that takes a certain percentage of the window or screen width, the image should have dimensions that are appropriate for a visitor’s screen size. Screen sizes vary a lot, typically from 320 pixels to 3840 pixels, so there is not a single image size that fits all cases. With `<img srcset>` you can offer the browser several possible sizes and let it choose the most appropriate size automatically.

By default, the browser assumes the image will be stretched to the full width of the screen, and will pick a size that is closest to a visitor’s screen size. In the `src` attribute the browser will pick any size that is a good fallback for older browsers that do not understand `srcset`.

```html
<img
  width="100%"
  srcset="
    /cdn-cgi/image/fit=contain,width=320/assets/hero.jpg   320w,
    /cdn-cgi/image/fit=contain,width=640/assets/hero.jpg   640w,
    /cdn-cgi/image/fit=contain,width=960/assets/hero.jpg   960w,
    /cdn-cgi/image/fit=contain,width=1280/assets/hero.jpg 1280w,
    /cdn-cgi/image/fit=contain,width=2560/assets/hero.jpg 2560w
  "
  src="/cdn-cgi/image/width=960/assets/hero.jpg"
/>
```

In the previous case, the number followed by `x` described *screen* density. In this case the number followed by `w` describes the *image* size. There is no need to specify screen density here (`2x`, etc.), because the browser automatically takes it into account and picks a higher-resolution image when necessary.

If the image is not displayed at full width of the screen (or browser window), you have two options:

* If the image is displayed at full width of a fixed-width column, use the first technique that uses one specific image size.
* If it takes a specific percentage of the screen, or stretches to full width only sometimes (using CSS media queries), then add the `sizes` attribute as described below.

#### The `sizes` attribute

If the image takes 50% of the screen (or window) width:

```html
<img style="width: 50vw" srcset="<SAME_AS_BEFORE>" sizes="50vw" />
```

The `vw` unit is a percentage of the viewport (screen or window) width. If the image can have a different size depending on media queries or other CSS properties, such as `max-width`, then specify all the conditions in the `sizes` attribute:

```html
<img
  style="max-width: 640px"
  srcset="
    /cdn-cgi/image/fit=contain,width=320/assets/hero.jpg   320w,
    /cdn-cgi/image/fit=contain,width=480/assets/hero.jpg   480w,
    /cdn-cgi/image/fit=contain,width=640/assets/hero.jpg   640w,
    /cdn-cgi/image/fit=contain,width=1280/assets/hero.jpg 1280w
  "
  sizes="(max-width: 640px) 100vw, 640px"
/>
```

In this example, `sizes` says that for screens smaller than 640 pixels the image is displayed at full viewport width; on all larger screens the image stays at 640px. Note that one of the options in `srcset` is 1280 pixels, because an image displayed at 640 CSS pixels may need twice as many image pixels on a high-dpi (`2x`) display.

## WebP images

`srcset` is useful for pixel-based formats such as PNG, JPEG, and WebP. It is unnecessary for vector-based SVG images.

HTML also [supports the `<picture>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture) that can optionally request an image in the WebP format, but you do not need it. Cloudflare can serve WebP images automatically whenever you use `/cdn-cgi/image/format=auto` URLs in `src` or `srcset`.

If you want to use WebP images, but do not need resizing, you have two options:

* You can enable the automatic [WebP conversion in Polish](/images/polish/activate-polish/). This will convert all images on the site.
* Alternatively, you can change specific image paths on the site to start with `/cdn-cgi/image/format=auto/`. For example, change `https://example.com/assets/hero.jpg` to `https://example.com/cdn-cgi/image/format=auto/assets/hero.jpg`.

## Transform with `width` parameter

When setting up a [transformation URL](/images/transform-images/transform-via-url/#width), you can apply the `width=auto` option to serve the most optimal image based on the available information about the user's browser and device.

This method can serve multiple sizes from a single URL. Currently, images will be served in one of four sizes:

- 1200 (large desktop/monitor)
- 960 (desktop)
- 768 (tablet)
- 320 (mobile)

Each width is counted as a separate transformation. For example, if you use `width=auto` and the image is delivered with a width of 320px to one user and 960px to another user, then this counts as two unique transformations.

By default, this feature uses information from the user agent, which detects the platform type (for example, iOS or Android) and browser.

### Client hints

For more accurate results, you can use client hints to send the user's browser information as request headers.

This method currently works only on Chromium-based browsers such as Chrome, Edge, and Opera.

You can enable client hints via HTML by adding the following tag in the `<head>` tag of your page before any other elements:

```txt
<meta http-equiv="Delegate-CH" content="sec-ch-dpr https://example.com; sec-ch-viewport-width https://example.com"/>
```

Replace `https://example.com` with your Cloudflare zone where transformations are enabled.

Alternatively, you can enable client hints via HTTP by adding the following headers to your HTML page's response:

```txt
critical-ch: sec-ch-viewport-width, sec-ch-dpr

permissions-policy: ch-dpr=("https://example.com"), ch-viewport-width=("https://example.com")
```

Replace `https://example.com` with your Cloudflare zone where transformations are enabled.

---

# Preserve Content Credentials

URL: https://developers.cloudflare.com/images/transform-images/preserve-content-credentials/

[Content Credentials](https://contentcredentials.org/) (or C2PA metadata) are a type of metadata that includes the full provenance chain of a digital asset. This provides information about an image's creation, authorship, and editing flow. This data is cryptographically authenticated and can be verified using an [open-source verification service](https://contentcredentials.org/verify).

You can preserve Content Credentials when optimizing images stored in remote sources.

## Enable

You can configure how Content Credentials are handled for each zone where transformations are served.

In the Cloudflare dashboard under **Images** > **Transformations**, navigate to a specific zone and enable the toggle to preserve Content Credentials:

![Enable Preserving Content Credentials in the dashboard](~/assets/images/images/preserve-content-credentials.png)

The behavior of this setting is determined by the [`metadata`](/images/transform-images/transform-via-url/#metadata) parameter for each transformation.

For example, if a transformation specifies `metadata=copyright`, then the EXIF copyright tag and all Content Credentials will be preserved in the resulting image and all other metadata will be discarded.

When Content Credentials are preserved in a transformation, Cloudflare will keep any existing Content Credentials embedded in the source image and automatically append and cryptographically sign additional actions.

When this setting is disabled, any existing Content Credentials will always be discarded.

---

# Serve images from custom paths

URL: https://developers.cloudflare.com/images/transform-images/serve-images-custom-paths/

You can use Transform Rules to rewrite URLs for every image that you transform through Images.

This page covers examples for the following scenarios:

- Serve images from custom paths
- Modify existing URLs to be compatible with transformations in Images
- Transform every image requested on your zone with Images

To create a rule, log in to the Cloudflare dashboard and select your account and website. Then, go to **Rules** > **Overview** and select **Create rule** next to **URL Rewrite Rules**.

## Before you start

Every rule runs before and after the transformation request.

If the path for the request matches the path where the original images are stored on your server, this may cause the request to fetch the original image to loop.

To direct the request to the origin server, you can check for the string `image-resizing` in the `Via` header:

`...and (not (any(http.request.headers["via"][*] contains "image-resizing")))`

## Serve images from custom paths

By default, requests to transform images through Images are served from the `/cdn-cgi/image/` path.
You can use Transform Rules to rewrite URLs.

### Basic version

Free and Pro plans support string matching rules (including wildcard operations) that do not require regular expressions.

This example lets you rewrite a request from `example.com/images` to `example.com/cdn-cgi/image/`:

```txt title="Text in Expression Editor"
(starts_with(http.request.uri.path, "/images")) and (not (any(http.request.headers["via"][*] contains "image-resizing")))
```

```txt title="Text in Path > Rewrite to > Dynamic"
concat("/cdn-cgi/image", substring(http.request.uri.path, 7))
```

### Advanced version

:::note
This feature requires a Business or Enterprise plan to enable regex in Transform Rules. Refer to [Cloudflare Transform Rules Availability](/rules/transform/#availability) for more information.
:::

There is an advanced version of Transform Rules supporting regular expressions.

This example lets you rewrite a request from `example.com/images` to `example.com/cdn-cgi/image/`:

```txt title="Text in Expression Editor"
(http.request.uri.path matches "^/images/.*$") and (not (any(http.request.headers["via"][*] contains "image-resizing")))
```

```txt title="Text in Path > Rewrite to > Dynamic"
regex_replace(http.request.uri.path, "^/images/", "/cdn-cgi/image/")
```

## Modify existing URLs to be compatible with transformations in Images

:::note
This feature requires a Business or Enterprise plan to enable regex in Transform Rules. Refer to [Cloudflare Transform Rules Availability](/rules/transform/#availability) for more information.
:::

This example lets you rewrite your URL parameters to be compatible with Images:

```txt
(http.request.uri matches "^/(.*)\\?width=([0-9]+)&height=([0-9]+)$")
```

```txt title="Text in Path > Rewrite to > Dynamic"
regex_replace(
  http.request.uri,
  "^/(.*)\\?width=([0-9]+)&height=([0-9]+)$",
  "/cdn-cgi/image/width=${2},height=${3}/${1}"
)
```

Leave the **Query** > **Rewrite to** > _Static_ field empty.

## Pass every image requested on your zone through Images

:::note
This feature requires a Business or Enterprise plan to enable regular expressions in Transform Rules. Refer to [Cloudflare Transform Rules Availability](/rules/transform/#availability) for more information.
:::

This example lets you transform every image that is requested on your zone with the `format=auto` option:

```txt
(http.request.uri.path.extension matches "(jpg)|(jpeg)|(png)|(gif)") and (not (any(http.request.headers["via"][*] contains "image-resizing")))
```

```txt title="Text in Path > Rewrite to > Dynamic"
regex_replace(http.request.uri.path, "/(.*)", "/cdn-cgi/image/format=auto/${1}")
```

---

# Define source origin

URL: https://developers.cloudflare.com/images/transform-images/sources/

When optimizing remote images, you can specify which origins can be used as the source for transformed images. By default, Cloudflare accepts only source images from the zone where your transformations are served.

On this page, you will learn how to define and manage the origins for the source images that you want to optimize.

:::note
The allowed origins setting applies to requests from Cloudflare Workers.

If you use a Worker to optimize remote images via a `fetch()` subrequest, then this setting may conflict with existing logic that handles source images.
:::

## How it works

In the Cloudflare dashboard, go to **Images** > **Transformations** and select the zone where you want to serve transformations.

To get started, you must have [transformations enabled on your zone](/images/get-started/#enable-transformations-on-your-zone).

In **Sources**, you can configure the origins for transformations on your zone.

![Enable allowed origins from the Cloudflare dashboard](~/assets/images/images/allowed-origins.png)

## Allow source images only from allowed origins

You can restrict source images to **allowed origins**, which applies transformations only to source images from a defined list.

By default, your accepted sources are set to **allowed origins**. Cloudflare will always allow source images from the same zone where your transformations are served.

If you request a transformation with a source image from outside your **allowed origins**, then the image will be rejected. For example, if you serve transformations on your zone `a.com` and do not define any additional origins, then `a.com/image.png` can be used as a source image, but `b.com/image.png` will return an error.

To define a new origin:

1. From **Sources**, select **Add origin**.
2. Under **Domain**, specify the domain for the source image. Only valid web URLs will be accepted.

![Add the origin for source images in the Cloudflare dashboard](~/assets/images/images/add-origin.png)

  When you add a root domain, subdomains are not accepted. In other words, if you add `b.com`, then source images from `media.b.com` will be rejected.

  To support individual subdomains, define an additional origin such as `media.b.com`. If you add only `media.b.com` and not the root domain, then source images from the root domain (`b.com`) and other subdomains (`cdn.b.com`) will be rejected.

  To support all subdomains, use the `*` wildcard at the beginning of the root domain. For example, `*.b.com` will accept source images from the root domain (like `b.com/image.png`) as well as from subdomains (like `media.b.com/image.png` or `cdn.b.com/image.png`).

3. Optionally, you can specify the **Path** for the source image. If no path is specified, then source images from all paths on this domain are accepted.

  Cloudflare checks whether the defined path is at the beginning of the source path. If the defined path is not present at the beginning of the path, then the source image will be rejected.

  For example, if you define an origin with domain `b.com` and path `/themes`, then `b.com/themes/image.png` will be accepted but `b.com/media/themes/image.png` will be rejected.

4. Select **Add**. Your origin will now appear in your list of allowed origins.
5. Select **Save**. These changes will take effect immediately.

When you configure **allowed origins**, only the initial URL of the source image is checked. Any redirects, including URLs that leave your zone, will be followed, and the resulting image will be transformed.

If you change your accepted sources to **any origin**, then your list of sources will be cleared and reset to default.

## Allow source images from any origin

When your accepted sources are set to **any origin**, any publicly available image can be used as the source image for transformations on this zone.

**Any origin** is less secure and may allow third parties to serve transformations on your zone.

---

# Transform via URL

URL: https://developers.cloudflare.com/images/transform-images/transform-via-url/

import { Render, Tabs, TabItem } from "~/components"

You can convert and resize images by requesting them via a specially-formatted URL. This way you do not need to write any code, only change HTML markup of your website to use the new URLs. The format is:

```txt
https://<ZONE>/cdn-cgi/image/<OPTIONS>/<SOURCE-IMAGE>
```

Here is a breakdown of each part of the URL:



* `<ZONE>`
  * Your domain name on Cloudflare. Unlike other third-party image resizing services, image transformations do not use a separate domain name for an API. Every Cloudflare zone with image transformations enabled can handle resizing itself. In URLs used on your website this part can be omitted, so that URLs start with `/cdn-cgi/image/`.

* `/cdn-cgi/image/`
  * A fixed prefix that identifies that this is a special path handled by Cloudflare's built-in Worker.

* `<OPTIONS>`
  * A comma-separated list of options such as `width`, `height`, and `quality`.

* `<SOURCE-IMAGE>`
  * An absolute path on the origin server, or an absolute URL (starting with `https://` or `http://`), pointing to an image to resize. The path is not URL-encoded, so the resizing URL can be safely constructed by concatenating `/cdn-cgi/image/options` and the original image URL. For example: `/cdn-cgi/image/width=100/https://s3.example.com/bucket/image.png`.


Here is an example of an URL with `<OPTIONS>` set to `width=80,quality=75` and a `<SOURCE-IMAGE>` of `uploads/avatar1.jpg`:

```html
<img src="/cdn-cgi/image/width=80,quality=75/uploads/avatar1.jpg" />
```

<Render file="ir-svg-aside" />

## Options

You must specify at least one option. Options are comma-separated (spaces are not allowed anywhere). Names of options can be specified in full or abbreviated.

### `anim`

<Render file="anim" />

### `background`

<Render file="background" />

### `blur`

<Render file="blur" />

### `border`

<Render file="border" />

### `brightness`

<Render file="brightness" />

### `compression`

<Render file="compression" />

### `contrast`

<Render file="contrast" />

### `dpr`

<Render file="dpr" />

### `fit`

<Render file="fit" />

### `flip`

<Render file="flip" />

### `format`

<Render file="format" />

### `gamma`

<Render file="gamma" />

### `gravity`

<Render file="gravity" />

### `height`

<Render file="height" />

### `metadata`

<Render file="metadata" />

### `onerror`

<Render file="onerror" />

### `quality`

<Render file="quality" />

### `rotate`

<Render file="rotate" />

### `saturation`

<Render file="saturation" />

### `sharpen`

<Render file="sharpen" />

### `slow-connection-quality`

<Render file="slow-connection-quality" />

### `trim`

<Render file="trim" />

### `width`

<Render file="width" />

## Recommended image sizes

Ideally, image sizes should match exactly the size they are displayed on the page. If the page contains thumbnails with markup such as `<img width="200" …>`, then images should be resized to `width=200`. If the exact size is not known ahead of time, use the [responsive images technique](/images/manage-images/create-variants/).

If you cannot use the `<img srcset>` markup, and have to hardcode specific maximum sizes, Cloudflare recommends the following sizes:

* Maximum of 1920 pixels for desktop browsers.
* Maximum of 960 pixels for tablets.
* Maximum of 640 pixels for mobile phones.

Here is an example of markup to configure a maximum size for your image:

```txt
/cdn-cgi/image/fit=scale-down,width=1920/<YOUR-IMAGE>
```

The `fit=scale-down` option ensures that the image will not be enlarged unnecessarily.

You can detect device type by enabling the `CF-Device-Type` header [via Cache Rule](/cache/how-to/cache-rules/examples/cache-device-type/).

## Caching

Resizing causes the original image to be fetched from the origin server and cached — following the usual rules of HTTP caching, `Cache-Control` header, etc.. Requests for multiple different image sizes are likely to reuse the cached original image, without causing extra transfers from the origin server.

:::note


If Custom Cache Keys are used for the origin image, the origin image might not be cached and might result in more calls to the origin.


:::

Resized images follow the same caching rules as the original image they were resized from, except the minimum cache time is one hour. If you need images to be updated more frequently, add `must-revalidate` to the `Cache-Control` header. Resizing supports cache revalidation, so we recommend serving images with the `Etag` header. Refer to the [Cache docs for more information](/cache/concepts/cache-control/#revalidation).

Cloudflare Images does not support purging resized variants individually. URLs starting with `/cdn-cgi/` cannot be purged. However, purging of the original image's URL will also purge all of its resized variants.

---

# Transform via Workers

URL: https://developers.cloudflare.com/images/transform-images/transform-via-workers/

import { Render } from "~/components"

Using Cloudflare Workers to transform with a custom URL scheme gives you powerful programmatic control over every image request.

Here are a few examples of the flexibility Workers give you:

* **Use a custom URL scheme**. Instead of specifying pixel dimensions in image URLs, use preset names such as `thumbnail` and `large`.
* **Hide the actual location of the original image**. You can store images in an external S3 bucket or a hidden folder on your server without exposing that information in URLs.
* **Implement content negotiation**. This is useful to adapt image sizes, formats and quality dynamically based on the device and condition of the network.

The resizing feature is accessed via the [options](/workers/runtime-apis/request/#the-cf-property-requestinitcfproperties) of a `fetch()` [subrequest inside a Worker](/workers/runtime-apis/fetch/).

:::note


You can use Cloudflare Images to sanitize SVGs but not to resize them.


:::

## Fetch options

The `fetch()` function accepts parameters in the second argument inside the `{cf: {image: {…}}}` object.

### `anim`

<Render file="anim" />

### `background`

<Render file="background" />

### `blur`

<Render file="blur" />

### `border`

<Render file="border" />

### `brightness`

<Render file="brightness" />

### `compression`

<Render file="compression" />

### `contrast`

<Render file="contrast" />

### `dpr`

<Render file="dpr" />

### `fit`

<Render file="fit" />

### `flip`

<Render file="flip" />

### `format`

<Render file="format" />

### `gamma`

<Render file="gamma" />

### `gravity`

<Render file="gravity" />

### `height`

<Render file="height" />

### `metadata`

<Render file="metadata" />

### `onerror`

<Render file="onerror" />

### `quality`

<Render file="quality" />

### `rotate`

<Render file="rotate" />

### `saturation`

<Render file="saturation" />

### `sharpen`

<Render file="sharpen" />

### `trim`

<Render file="trim" />

### `width`

<Render file="width" />

In your worker, where you would fetch the image using `fetch(request)`, add options like in the following example:

```js
fetch(imageURL, {
  cf: {
    image: {
      fit: "scale-down",
      width: 800,
      height: 600
    }
  }
})
```

These typings are also available in [our Workers TypeScript definitions library](https://github.com/cloudflare/workers-types).

## Configure a Worker

Create a new script in the Workers section of the Cloudflare dashboard. Scope your Worker script to a path dedicated to serving assets, such as `/images/*` or `/assets/*`. Only supported image formats can be resized. Attempting to resize any other type of resource (CSS, HTML) will result in an error.

:::caution[Warning]


Do not set up the Image Resizing worker for the entire zone (`/*`). This will block all non-image requests and make your website inaccessible.


:::

It is best to keep the path handled by the Worker separate from the path to original (unresized) images, to avoid request loops caused by the image resizing worker calling itself. For example, store your images in `example.com/originals/` directory, and handle resizing via `example.com/thumbnails/*` path that fetches images from the `/originals/` directory. If source images are stored in a location that is handled by a Worker, you must prevent the Worker from creating an infinite loop.

### Prevent request loops

To perform resizing and optimizations, the Worker must be able to fetch the original, unresized image from your origin server. If the path handled by your Worker overlaps with the path where images are stored on your server, it could cause an infinite loop by the Worker trying to request images from itself.

You must detect which requests must go directly to the origin server. When the `image-resizing` string is present in the `Via` header, it means that it is a request coming from another Worker and should be directed to the origin server:

```js
addEventListener("fetch", event => {
  // If this request is coming from image resizing worker,
  // avoid causing an infinite loop by resizing it again:
  if (/image-resizing/.test(event.request.headers.get("via"))) {
    return fetch(event.request)
  }

  // Now you can safely use image resizing here
}
```

## Lack of preview in the dashboard

:::note[Note]


Image transformations are not simulated in the preview of in the Workers dashboard editor.


:::

The script preview of the Worker editor ignores `fetch()` options, and will always fetch unresized images. To see the effect of image transformations you must deploy the Worker script and use it outside of the editor.

## Error handling

When an image cannot be resized — for example, because the image does not exist or the resizing parameters were invalid — the response will have an HTTP status indicating an error (for example, `400`, `404`, or `502`).

By default, the error will be forwarded to the browser, but you can decide how to handle errors. For example, you can redirect the browser to the original, unresized image instead:

```js
const response = await fetch(imageURL, options)

if (response.ok || response.redirected) { // fetch() may respond with status 304
  return response
} else {
  return response.redirect(imageURL, 307)
}
```

Keep in mind that if the original images on your server are very large, it may be better not to display failing images at all, than to fall back to overly large images that could use too much bandwidth, memory, or break page layout.

You can also replace failed images with a placeholder image:

```js
const response = await fetch(imageURL, options)
if (response.ok || response.redirected) {
  return response
} else {
  // Change to a URL on your server
  return fetch("https://img.example.com/blank-placeholder.png")
}
```

## An example worker

Assuming you [set up a Worker](/workers/get-started/guide/) on `https://example.com/image-resizing` to handle URLs like `https://example.com/image-resizing?width=80&image=https://example.com/uploads/avatar1.jpg`:

```js
/**
 * Fetch and log a request
 * @param {Request} request
 */
export default {
  async fetch(request) {
    // Parse request URL to get access to query string
    let url = new URL(request.url)

    // Cloudflare-specific options are in the cf object.
    let options = { cf: { image: {} } }

    // Copy parameters from query string to request options.
    // You can implement various different parameters here.
    if (url.searchParams.has("fit")) options.cf.image.fit = url.searchParams.get("fit")
    if (url.searchParams.has("width")) options.cf.image.width = url.searchParams.get("width")
    if (url.searchParams.has("height")) options.cf.image.height = url.searchParams.get("height")
    if (url.searchParams.has("quality")) options.cf.image.quality = url.searchParams.get("quality")

    // Your Worker is responsible for automatic format negotiation. Check the Accept header.
    const accept = request.headers.get("Accept");
    if (/image\/avif/.test(accept)) {
      options.cf.image.format = 'avif';
    } else if (/image\/webp/.test(accept)) {
      options.cf.image.format = 'webp';
    }

    // Get URL of the original (full size) image to resize.
    // You could adjust the URL here, e.g., prefix it with a fixed address of your server,
    // so that user-visible URLs are shorter and cleaner.
    const imageURL = url.searchParams.get("image")
    if (!imageURL) return new Response('Missing "image" value', { status: 400 })

    try {
      // TODO: Customize validation logic
      const { hostname, pathname } = new URL(imageURL)

      // Optionally, only allow URLs with JPEG, PNG, GIF, or WebP file extensions
      // @see https://developers.cloudflare.com/images/url-format#supported-formats-and-limitations
      if (!/\.(jpe?g|png|gif|webp)$/i.test(pathname)) {
        return new Response('Disallowed file extension', { status: 400 })
      }

      // Demo: Only accept "example.com" images
      if (hostname !== 'example.com') {
        return new Response('Must use "example.com" source images', { status: 403 })
      }
    } catch (err) {
      return new Response('Invalid "image" value', { status: 400 })
    }

    // Build a request that passes through request headers
    const imageRequest = new Request(imageURL, {
      headers: request.headers
    })

    // Returning fetch() with resizing options will pass through response with the resized image.
    return fetch(imageRequest, options)
  }
}
```

When testing image resizing, please deploy the script first. Resizing will not be active in the online editor in the dashboard.

## Warning about `cacheKey`

Resized images are always cached. They are cached as additional variants under a cache entry for the URL of the full-size source image in the `fetch` subrequest. Do not worry about using many different Workers or many external URLs — they do not influence caching of resized images, and you do not need to do anything for resized images to be cached correctly.

If you use the `cacheKey` fetch option to unify caches of multiple different source URLs, you must not add any resizing options to the `cacheKey`, as this will fragment the cache and hurt caching performance. The `cacheKey` option is meant for the full-size source image URL only, not for its resized variants.

---

# Accept user-uploaded images

URL: https://developers.cloudflare.com/images/upload-images/direct-creator-upload/

The Direct Creator Upload feature in Cloudflare Images lets your users upload images with a one-time upload URL without exposing your API key or token to the client. Using a direct creator upload also eliminates the need for an intermediary storage bucket and the storage/egress costs associated with it.

You can set up [webhooks](/images/manage-images/configure-webhooks/) to receive notifications on your direct creator upload workflow.

## Request a one-time upload URL

Make a `POST` request to the `direct_upload` endpoint using the example below as reference.

:::note
The `metadata` included in the request is never shared with end users.
:::

```bash
curl --request POST \
https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v2/direct_upload \
--header "Authorization: Bearer <API_TOKEN>" \
--form 'requireSignedURLs=true' \
--form 'metadata={"key":"value"}'
```

After a successful request, you will receive a response similar to the example below. The `id` field is a future image identifier that will be uploaded by a creator.

```json
{
  "result": {
    "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
    "uploadURL": "https://upload.imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901"
  },
  "result_info": null,
  "success": true,
  "errors": [],
  "messages": []
}
```

After calling the endpoint, a new draft image record is created, but the image will not appear in the list of images. If you want to check the status of the image record, you can make a request to the one-time upload URL using the `direct_upload` endpoint.

## Check the image record status

To check the status of a new draft image record, use the one-time upload URL as shown in the example below.

```bash
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/{image_id} \
--header "Authorization: Bearer <API_TOKEN>"
```

After a successful request, you should receive a response similar to the example below. The `draft` field is set to `true` until a creator uploads an image. After an image is uploaded, the draft field is removed.

```json
{
  "result": {
    "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
    "metadata": {
      "key": "value"
    },
    "uploaded": "2022-01-31T16:39:28.458Z",
    "requireSignedURLs": true,
    "variants": [
      "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/public",
      "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/thumbnail"
    ],
    "draft": true
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

The backend endpoint should return the `uploadURL` property to the client, which uploads the image without needing to pass any authentication information with it.

Below is an example of an HTML page that takes a one-time upload URL and uploads any image the user selects.

```html
<!DOCTYPE html>
<html>
<body>
<form
action="INSERT_UPLOAD_URL_HERE"
method="post"
enctype="multipart/form-data"
>
<input type="file" id="myFile" name="file" />
<input type="submit" />
</form>
</body>
</html>
```

By default, the `uploadURL` expires after 30 minutes if unused. To override this option, add the following argument to the cURL command:

```txt
--data '{"expiry":"2021-09-14T16:00:00Z"}'
```

The expiry value must be a minimum of two minutes and maximum of six hours in the future.

## Direct Creator Upload with custom ID

You can specify a [custom ID](/images/upload-images/upload-custom-path/) when you first request a one-time upload URL, instead of using the automatically generated ID for your image. Note that images with a custom ID cannot be made private with the [signed URL tokens](/images/manage-images/serve-images/serve-private-images) feature (`--requireSignedURLs=true`).

To specify a custom ID, pass a form field with the name ID and corresponding custom ID value as shown in the example below.

```txt
--form 'id=this/is/my-customid'
```

---

# Upload via batch API

URL: https://developers.cloudflare.com/images/upload-images/images-batch/

The Images batch API lets you make several requests in sequence while bypassing Cloudflare’s global API rate limits.

To use the Images batch API, you will need to obtain a batch token and use the token to make several requests. The requests authorized by this batch token are made to a separate endpoint and do not count toward the global API rate limits. Each token is subject to a rate limit of 200 requests per second. You can use multiple tokens if you require higher throughput to the Cloudflare Images API.

To obtain a token, you can use the new `images/v1/batch_token` endpoint as shown in the example below.

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/batch_token" \
--header "Authorization: Bearer <API_TOKEN>"

# Response:
{
  "result": {
    "token": "<BATCH_TOKEN>",
    "expiresAt": "2023-08-09T15:33:56.273411222Z"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

After getting your token, use it to make requests for:

- [Upload an image](/api/resources/images/subresources/v1/methods/create/) - `POST /images/v1`
- [Delete an image](/api/resources/images/subresources/v1/methods/delete/) - `DELETE /images/v1/{identifier}`
- [Image details](/api/resources/images/subresources/v1/methods/get/) - `GET /images/v1/{identifier}`
- [Update image](/api/resources/images/subresources/v1/methods/edit/) - `PATCH /images/v1/{identifier}`
- [List images V2](/api/resources/images/subresources/v2/methods/list/) - `GET /images/v2`
- [Direct upload V2](/api/resources/images/subresources/v2/subresources/direct_uploads/methods/create/) - `POST /images/v2/direct_upload`

These options use a different host and a different path with the same method, request, and response bodies.

```bash title="Request for list images V2 against api.cloudflare.com"
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v2" \
--header "Authorization: Bearer <API_TOKEN>"
```

```bash title="Example request using a batch token"
curl "https://batch.imagedelivery.net/images/v1" \
--header "Authorization: Bearer <BATCH_TOKEN>"
```

---

# Upload images

URL: https://developers.cloudflare.com/images/upload-images/

Cloudflare Images allows developers to upload images using different methods, for a wide range of use cases.

## Supported image formats

You can upload the following image formats to Cloudflare Images:

* PNG
* GIF (including animations)
* JPEG
* WebP (Cloudflare Images also supports uploading animated WebP files)
* SVG

:::note


Cloudflare Images does not support the HEIC (HEIF) format.


:::

## Dimensions and sizes

These are the maximum allowed sizes and dimensions Cloudflare Images supports:

* Maximum image dimension is 12,000 pixels.
* Maximum image area is limited to 100 megapixels (for example, 10,000×10,000 pixels).
* Image metadata is limited to 1024 bytes.
* Images have a 10 megabyte (MB) size limit.
* Animated GIFs/WebP, including all frames, are limited to 50 megapixels (MP).

---

# Upload via URL

URL: https://developers.cloudflare.com/images/upload-images/upload-url/

Before you upload an image, check the list of [supported formats and dimensions](/images/upload-images/#supported-image-formats) to confirm your image will be accepted.

You can use the Images API to use a URL of an image instead of uploading the data.

Make a `POST` request using the example below as reference. Keep in mind that the `--form 'file=<FILE>'` and `--form 'url=<URL>'` fields are mutually exclusive.

:::note
The `metadata` included in the request is never shared with end users.
:::

```bash
curl --request POST \
https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1 \
--header "Authorization: Bearer <API_TOKEN>" \
--form 'url=https://[user:password@]example.com/<PATH_TO_IMAGE>' \
--form 'metadata={"key":"value"}' \
--form 'requireSignedURLs=false'
```

After successfully uploading the image, you will receive a response similar to the example below.

```json
{
    "result": {
        "id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
        "filename": "image.jpeg",
        "metadata": {
            "key": "value"
        },
        "uploaded": "2022-01-31T16:39:28.458Z",
        "requireSignedURLs": false,
        "variants": [
            "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/public",
            "https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/thumbnail"
        ]
    },
    "success": true,
    "errors": [],
    "messages": []
}
```

If your origin server returns an error while fetching the images, the API response will return a 4xx error.

---

# Upload via custom path

URL: https://developers.cloudflare.com/images/upload-images/upload-custom-path/

You can use a custom ID path to upload an image instead of the path automatically generated by Cloudflare Images’ Universal Unique Identifier (UUID).

Custom paths support:

* Up to 1,024 characters.
* Any number of subpaths.
* The [UTF-8 encoding standard](https://en.wikipedia.org/wiki/UTF-8) for characters.

:::note

Images with custom ID paths cannot be made private using [signed URL tokens](/images/manage-images/serve-images/serve-private-images). Additionally, when [serving images](/images/manage-images/serve-images/), any `%` characters present in Custom IDs must be encoded to `%25` in the image delivery URLs.
:::

Make a `POST` request using the example below as reference. You can use custom ID paths when you upload via a URL or with a direct file upload.

```bash
curl --request POST https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1 \
--header "Authorization: Bearer <API_TOKEN>" \
--form 'url=https://<REMOTE_PATH_TO_IMAGE>' \
--form 'id=<PATH_TO_YOUR_IMAGE>'
```

After successfully uploading the image, you will receive a response similar to the example below.

```json
{
  "result": {
    "id": "<PATH_TO_YOUR_IMAGE>",
    "filename": "<YOUR_IMAGE>",
    "uploaded": "2022-04-20T09:51:09.559Z",
    "requireSignedURLs": false,
    "variants": ["https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/<PATH_TO_YOUR_IMAGE>/public"]
  },
  "result_info": null,
  "success": true,
  "errors": [],
  "messages": []
}
```

---

# Upload via dashboard

URL: https://developers.cloudflare.com/images/upload-images/upload-dashboard/

Before you upload an image, check the list of [supported formats and dimensions](/images/upload-images/#supported-image-formats) to confirm your image will be accepted.

To upload an image from the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Select **Images**.
3. Drag and drop your image into the **Quick Upload** section. Alternatively, you can select **Drop images here** or browse to select your image locally.
4. After the upload finishes, your image appears in the list of files.

---

# Upload via a Worker

URL: https://developers.cloudflare.com/images/upload-images/upload-file-worker/

You can use a Worker to upload your image to Cloudflare Images.

Refer to the example below or refer to the [Workers documentation](/workers/) for more information.

```ts
const API_URL = "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/images/v1";
const TOKEN = "<YOUR_TOKEN_HERE>";

const image = await fetch("https://example.com/image.png");
const bytes = await image.bytes();

const formData = new FormData();
formData.append('file', new File([bytes], 'image.png'));

const response = await fetch(API_URL, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
  },
  body: formData,
});
```
## Upload from AI generated images

You can use an AI Worker to generate an image and then upload that image to store it in Cloudflare Images. For more information about using Workers AI to generate an image, refer to the [SDXL-Lightning Model](/workers-ai/models/stable-diffusion-xl-lightning).

```ts
const API_URL = "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/images/v1";
const TOKEN = "YOUR_TOKEN_HERE";

const stream = await env.AI.run(
  "@cf/bytedance/stable-diffusion-xl-lightning",
  {
    prompt: YOUR_PROMPT_HERE
  }
);
const bytes = await (new Response(stream)).bytes();

const formData = new FormData();
formData.append('file', new File([bytes], 'image.jpg');

const response = await fetch(API_URL, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TOKEN}`,
  },
  body: formData,
});
```

---

# Connect to a private database using Tunnel

URL: https://developers.cloudflare.com/hyperdrive/configuration/connect-to-private-database/

import { TabItem, Tabs, Render } from "~/components";

Hyperdrive can securely connect to your private databases using [Cloudflare Tunnel](/cloudflare-one/connections/connect-networks/) and [Cloudflare Access](/cloudflare-one/policies/access/).

## How it works

When your database is isolated within a private network (such as a [virtual private cloud](https://www.cloudflare.com/learning/cloud/what-is-a-virtual-private-cloud) or an on-premise network), you must enable a secure connection from your network to Cloudflare.

- [Cloudflare Tunnel](/cloudflare-one/connections/connect-networks/) is used to establish the secure tunnel connection.
- [Cloudflare Access](/cloudflare-one/policies/access/) is used to restrict access to your tunnel such that only specific Hyperdrive configurations can access it.

A request from the Cloudflare Worker to the origin database goes through Hyperdrive, Cloudflare Access, and the Cloudflare Tunnel established by `cloudflared`. `cloudflared` must be running in the private network in which your database is accessible.

The Cloudflare Tunnel will establish an outbound bidirectional connection from your private network to Cloudflare. Cloudflare Access will secure your Cloudflare Tunnel to be only accessible by your Hyperdrive configuration.

![A request from the Cloudflare Worker to the origin database goes through Hyperdrive, Cloudflare Access and the Cloudflare Tunnel established by `cloudflared`.](~/assets/images/hyperdrive/configuration/hyperdrive-private-database-architecture.png)

<Render file="tutorials-before-you-start" product="workers" />

:::caution[Warning]

If your organization also uses [Super Bot Fight Mode](/bots/get-started/super-bot-fight-mode/), keep **Definitely Automated** set to **Allow**. Otherwise, tunnels might fail with a `websocket: bad handshake` error.
:::

## Prerequisites

- A database in your private network, [configured to use TLS/SSL](/hyperdrive/examples/connect-to-postgres/#supported-tls-ssl-modes).
- A hostname on your Cloudflare account, which will be used to route requests to your database.

## 1. Create a tunnel in your private network

### 1.1. Create a tunnel

First, create a [Cloudflare Tunnel](/cloudflare-one/connections/connect-networks/) in your private network to establish a secure connection between your network and Cloudflare. Your network must be configured such that the tunnel has permissions to egress to the Cloudflare network and access the database within your network.

<Render file="tunnel/create-tunnel" product="cloudflare-one" />

### 1.2. Connect your database using a public hostname

Your tunnel must be configured to use a public hostname so that Hyperdrive can route requests to it. If you don't have a hostname on Cloudflare yet, you will need to [register a new hostname](/registrar/get-started/register-domain/) or [add a zone](/dns/zone-setups/) to Cloudflare to proceed.

1. In the **Public Hostnames** tab, choose a **Domain** and specify any subdomain or path information. This will be used in your Hyperdrive configuration to route to this tunnel.

2. In the **Service** section, specify **Type** `TCP` and the URL and configured port of your database, such as `localhost:5432` or `my-database-host.database-provider.com:5432`. This address will be used by the tunnel to route requests to your database.

3. Select **Save tunnel**.

:::note
If you are setting up the tunnel through the CLI instead ([locally-managed tunnel](/cloudflare-one/connections/connect-networks/do-more-with-tunnels/local-management/)), you will have to complete these steps manually. Follow the Cloudflare Zero Trust documentation to [add a public hostname to your tunnel](/cloudflare-one/connections/connect-networks/routing-to-tunnel/dns/) and [configure the public hostname to route to the address of your database](/cloudflare-one/connections/connect-networks/do-more-with-tunnels/local-management/configuration-file/).
:::

## 2. Create and configure Hyperdrive to connect to the Cloudflare Tunnel

To restrict access to the Cloudflare Tunnel to Hyperdrive, a [Cloudflare Access application](/cloudflare-one/applications/) must be configured with a [Policy](/cloudflare-one/policies/) that requires requests to contain a valid [Service Auth token](/cloudflare-one/policies/access/#service-auth).

The Cloudflare dashboard can automatically create and configure the underlying [Cloudflare Access application](/cloudflare-one/applications/), [Service Auth token](/cloudflare-one/policies/access/#service-auth), and [Policy](/cloudflare-one/policies/) on your behalf. Alternatively, you can manually create the Access application and configure the Policies.

<Tabs> <TabItem label="Automatic creation">

### 2.1 Create a Hyperdrive configuration in the Cloudflare dashboard

Create a Hyperdrive configuration in the Cloudflare dashboard to automatically configure Hyperdrive to connect to your Cloudflare Tunnel.

1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive), navigate to **Storage & Databases > Hyperdrive** and click **Create configuration**.
2. Select **Private database**.
3. In the **Networking details** section, select the tunnel you are connecting to.
4. In the **Networking details** section, select the hostname associated to the tunnel. If there is no hostname for your database, return to step [1.2. Connect your database using a public hostname](/hyperdrive/configuration/connect-to-private-database/#12-connect-your-database-using-a-public-hostname).
5. In the **Access Service Authentication Token** section, select **Create new (automatic)**.
6. In the **Access Application** section, select **Create new (automatic)**.
7. In the **Database connection details** section, enter the database **name**, **user**, and **password**.

</TabItem>
<TabItem label="Manual creation">
### 2.1 Create a service token

The service token will be used to restrict requests to the tunnel, and is needed for the next step.

1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Access** > **Service auth** > **Service Tokens**.

2. Select **Create Service Token**.

3. Name the service token. The name allows you to easily identify events related to the token in the logs and to revoke the token individually.

4. Set a **Service Token Duration** of `Non-expiring`. This prevents the service token from expiring, ensuring it can be used throughout the life of the Hyperdrive configuration.

5. Select **Generate token**. You will see the generated Client ID and Client Secret for the service token, as well as their respective request headers.

6. Copy the Access Client ID and Access Client Secret. These will be used when creating the Hyperdrive configuration.

   :::caution
   This is the only time Cloudflare Access will display the Client Secret. If you lose the Client Secret, you must regenerate the service token.
   :::

### 2.2 Create an Access application to secure the tunnel

[Cloudflare Access](/cloudflare-one/policies/access/) will be used to verify that requests to the tunnel originate from Hyperdrive using the service token created above.

1. In [Zero Trust](https://one.dash.cloudflare.com), go to **Access** > **Applications**.

2. Select **Add an application**.

3. Select **Self-hosted**.

4. Enter any name for the application.

5. In **Session Duration**, select `No duration, expires immediately`.

6. Select **Add public hostname**. and enter the subdomain and domain that was previously set for the tunnel application.

7. Select **Create new policy**.

8. Enter a **Policy name** and set the **Action** to _Service Auth_.

9. Create an **Include** rule. Specify a **Selector** of _Service Token_ and the **Value** of the service token you created in step [2. Create a service token](#21-create-a-service-token).

10. Save the policy.

11. Go back to the application configuration and add the newly created Access policy.

12. In **Login methods**, turn off _Accept all available identity providers_ and clear all identity providers.

13. Select **Next**.

14. In **Application Appearance**, turn off **Show application in App Launcher**.

15. Select **Next**.

16. Select **Next**.

17. Save the application.

### 2.3 Create a Hyperdrive configuration

To create a Hyperdrive configuration for your private database, you'll need to specify the Access application and Cloudflare Tunnel information upon creation.

<Tabs> <TabItem label="Wrangler">

```sh
# wrangler v3.65 and above required
npx wrangler hyperdrive create <NAME-OF-HYPERDRIVE-CONFIGURATION-FOR-DB-VIA-TUNNEL> --host=<HOSTNAME-FOR-THE-TUNNEL> --user=<USERNAME-FOR-YOUR-DATABASE> --password=<PASSWORD-FOR-YOUR-DATABASE> --database=<DATABASE-TO-CONNECT-TO> --access-client-id=<YOUR-ACCESS-CLIENT-ID> --access-client-secret=<YOUR-SERVICE-TOKEN-CLIENT-SECRET>
```

</TabItem> <TabItem label="Terraform">

```terraform
resource "cloudflare_hyperdrive_config"  "<TERRAFORM_VARIABLE_NAME_FOR_CONFIGURATION>" {
  account_id = "<YOUR_ACCOUNT_ID>"
  name       = "<NAME_OF_HYPERDRIVE_CONFIGURATION>"
  origin     = {
    host     = "<HOSTNAME_OF_TUNNEL>"
    database = "<NAME_OF_DATABASE>"
    user     = "<NAME_OF_DATABASE_USER>"
    password = "<DATABASE_PASSWORD>"
    scheme   = "postgres"
    access_client_id     = "<ACCESS_CLIENT_ID>"
    access_client_secret = "<ACCESS_CLIENT_SECRET>"
  }
  caching = {
    disabled = false
  }
}
```

</TabItem> </Tabs>

This will create a Hyperdrive configuration using the usual database information (database name, database host, database user, and database password).

In addition, it will also set the Access Client ID and the Access Client Secret of the Service Token. When Hyperdrive makes requests to the tunnel, requests will be intercepted by Access and validated using the credentials of the Service Token.

:::note
When creating the Hyperdrive configuration for the private database, you must enter the `access-client-id` and the `access-client-id`, and omit the `port`. Hyperdrive will route database messages to the public hostname of the tunnel, and the tunnel will rely on its service configuration (as configured in [1.2. Connect your database using a public hostname](#12-connect-your-database-using-a-public-hostname)) to route requests to the database within your private network.
:::

</TabItem> </Tabs>

## 3. Query your Hyperdrive configuration from a Worker (optional)

To test your Hyperdrive configuration to the database using Cloudflare Tunnel and Access, use the Hyperdrive configuration ID in your Worker and deploy it.

### Create a Hyperdrive binding

<Render file="create-hyperdrive-binding" product="hyperdrive" />

### Query your database

Validate that you can connect to your database from Workers and make queries.

<Tabs>
<TabItem label="PostgreSQL">

Use Postgres.js to send a test query to validate that the connection has been successful.

<Render file="use-postgres-js-to-make-query" product="hyperdrive" />

Now, deploy your Worker:

```bash
npx wrangler deploy
```

If you successfully receive the list of `pg_tables` from your database when you access your deployed Worker, your Hyperdrive has now been configured to securely connect to a private database using [Cloudflare Tunnel](/cloudflare-one/connections/connect-networks/) and [Cloudflare Access](/cloudflare-one/policies/access/).

</TabItem>
<TabItem label="MySQL">

Use [mysql2](https://github.com/sidorares/node-mysql2) to send a test query to validate that the connection has been successful.

<Render file="use-mysql2-to-make-query" product="hyperdrive" />

Now, deploy your Worker:

```bash
npx wrangler deploy
```

If you successfully receive the list of tables from your database when you access your deployed Worker, your Hyperdrive has now been configured to securely connect to a private database using [Cloudflare Tunnel](/cloudflare-one/connections/connect-networks/) and [Cloudflare Access](/cloudflare-one/policies/access/).

</TabItem>
</Tabs>

## Troubleshooting

If you encounter issues when setting up your Hyperdrive configuration with tunnels to a private database, consider these common solutions, in addition to [general troubleshooting steps](/hyperdrive/observability/troubleshooting/) for Hyperdrive:

- Ensure your database is configured to use TLS (SSL). Hyperdrive requires TLS (SSL) to connect.

---

# Firewall and networking configuration

URL: https://developers.cloudflare.com/hyperdrive/configuration/firewall-and-networking-configuration/

import { TabItem, Tabs, Render, WranglerConfig } from "~/components";

Hyperdrive uses the [Cloudflare IP address ranges](https://www.cloudflare.com/ips/) to connect to your database. If you decide to restrict the IP addresses that can access your database with firewall rules, the IP address ranges listed in this reference need to be allow-listed in your database's firewall and networking configurations.

You can connect to your database from Hyperdrive using any of the 3 following networking configurations:

1. Configure your database to allow inbound connectivity from the public Internet (all IP address ranges).
2. Configure your database to allow inbound connectivity from the public Internet, with only the IP address ranges used by Hyperdrive allow-listed in an IP access control list (ACL).
3. Configure your database to allow inbound connectivity from a private network, and run a Cloudflare Tunnel instance in your private network to enable Hyperdrive to connect from the Cloudflare network to your private network. Refer to [documentation on connecting to a private database using Tunnel](/hyperdrive/configuration/connect-to-private-database/).

---

# Configuration

URL: https://developers.cloudflare.com/hyperdrive/configuration/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# How Hyperdrive works

URL: https://developers.cloudflare.com/hyperdrive/configuration/how-hyperdrive-works/

Connecting to traditional centralized databases from Cloudflare's global network which consists of over [300 data center locations](https://www.cloudflare.com/network/) presents a few challenges as queries can originate from any of these locations.

If your database is centrally located, queries can take a long time to get to the database and back. Queries can take even longer in situations where you have to establish a connection and make multiple round trips.

Traditional databases usually handle a maximum number of connections. With any reasonably large amount of distributed traffic, it becomes easy to exhaust these connections.

Hyperdrive solves these challenges by managing the number of global connections to your origin database, selectively parsing and choosing which query response to cache while reducing loading on your database and accelerating your database queries.

## How Hyperdrive makes databases fast globally

Hyperdrive accelerates database queries by:

- Performing the connection setup for new database connections near your Workers
- Pooling existing connections near your database
- Caching query results

This ensures you have optimal performance when connecting to your database from Workers (whether your queries are cached or not).

![Hyperdrive connection](~/assets/images/hyperdrive/configuration/hyperdrive-comparison.svg)

### 1. Edge connection setup

When a database driver connects to a database from a Cloudflare Worker **directly**, it will first go through the connection setup. This may require multiple round trips to the database in order to verify and establish a secure connection. This can incur additional network latency due to the distance between your Cloudflare Worker and your database.

**With Hyperdrive**, this connection setup occurs between your Cloudflare Worker and Hyperdrive on the edge, as close to your Worker as possible (see diagram, label _1. Connection setup_). This incurs significantly less latency, since the connection setup is completed within the same location.

### 2. Connection Pooling

Hyperdrive creates a pool of connections to your database that can be reused as your application executes queries against your database.

The pool of database connections is placed in one or more regions closest to your origin database. This minimizes the latency incurred by roundtrips between your Cloudflare Workers and database to establish new connections. This also ensures that as little network latency is incurred for uncached queries.

If the connection pool has pre-existing connections, the connection pool will try and reuse that connection (see diagram, label _2. Existing warm connection_).
If the connection pool does not have pre-existing connections, it will establish a new connection to your database and use that to route your query. This aims at reusing and creating the least number of connections possible as required to operate your application.

:::note

Hyperdrive automatically manages the connection pool properties for you, including limiting the total number of connections to your origin database. Refer to [Limits](/hyperdrive/platform/limits/) to learn more.
:::

### 3. Query Caching

Hyperdrive supports caching of non-mutating (read) queries to your database.

When queries are sent via Hyperdrive, Hyperdrive parses the query and determines whether the query is a mutating (write) or non-mutating (read) query.

For non-mutating queries, Hyperdrive will cache the response for the configured `max_age`, and whenever subsequent queries are made that match the original, Hyperdrive will return the cached response, bypassing the need to issue the query back to the origin database.

Caching reduces the burden on your origin database and accelerates the response times for your queries.

## Pooling mode

The Hyperdrive connection pooler operates in transaction mode, where the client that executes the query communicates through a single connection for the duration of a transaction. When that transaction has completed, the connection is returned to the pool.

Hyperdrive supports [`SET` statements](https://www.postgresql.org/docs/current/sql-set.html) for the duration of a transaction or a query. For instance, if you manually create a transaction with `BEGIN`/`COMMIT`, `SET` statements within the transaction will take effect. Moreover, a query that includes a `SET` command (`SET X; SELECT foo FROM bar;`) will also apply the `SET` command. When a connection is returned to the pool, the connection is `RESET` such that the `SET` commands will not take effect on subsequent queries.

This implies that a single Worker invocation may obtain multiple connections to perform its database operations and may need to `SET` any configurations for every query or transaction. It is not recommended to wrap multiple database operations with a single transaction to maintain the `SET` state. Doing so will affect the performance and scaling of Hyperdrive as the connection cannot be reused by other Worker isolates for the duration of the transaction.

Hyperdrive supports named prepared statements as implemented in the `postgres.js` and `node-postgres` drivers. Named prepared statements in other drivers may have worse performance or may not be supported.

## Related resources

- [Query caching](/hyperdrive/configuration/query-caching/)

---

# Local development

URL: https://developers.cloudflare.com/hyperdrive/configuration/local-development/

import { WranglerConfig } from "~/components";

Hyperdrive can be used when developing and testing your Workers locally by connecting to a local database instance running on your machine directly, or a remote database instance. Local development uses [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Workers, to manage local development sessions and state.

:::note[Note]

You can connect to a local database for local development using the local connection string configurations for Wrangler, as detailed below. This allows you to connect to a local database instance running on your machine directly.

You can also connect to a remote database for remote development using the `npx wrangler dev --remote` command, which will use the remote database configured for your Hyperdrive configuration.

:::

## Configure local development

To specify a database to connect to when developing locally, you can:

- **Recommended:** Create a `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` [environmental variable](/workers/configuration/environment-variables/) with the connection string of your database. `<BINDING_NAME>` is the name of the binding assigned to your Hyperdrive in your [Wrangler configuration file](/workers/wrangler/configuration/) or Pages configuration. This allows you to avoid committing potentially sensitive credentials to source control in your Wrangler configuration file, if your test/development database is not ephemeral. If you have configured multiple Hyperdrive bindings, replace `<BINDING_NAME>` with the unique binding name for each.
- Set `localConnectionString` in the Wrangler configuration file.

If both the `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` [environmental variable](/workers/configuration/environment-variables/) and `localConnectionString` in the Wrangler configuration file are set, `wrangler dev` will use the environmental variable instead. Use `unset WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` to unset any existing environmental variables.

For example, to use the environmental variable, export the environmental variable before running `wrangler dev`:

```sh
# Your configured Hyperdrive binding is "TEST_DB"
export WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_TEST_DB="postgres://user:password@localhost:5432/databasename"
# Start a local development session referencing this local instance
npx wrangler dev
```

To configure a `localConnectionString` in the [Wrangler configuration file](/workers/wrangler/configuration/), ensure your Hyperdrive bindings have a `localConnectionString` property set:

<WranglerConfig>

```toml
[[hyperdrive]]
binding = "TEST_DB"
id = "c020574a-5623-407b-be0c-cd192bab9545"
localConnectionString = "postgres://user:password@localhost:5432/databasename"
```

</WranglerConfig>

## Use `wrangler dev`

The following example shows you how to check your wrangler version, set a `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_TEST_DB` [environmental variable](/workers/configuration/environment-variables/), and run a `wrangler dev` session:

```sh
# Confirm you are using wrangler v3.0+
npx wrangler --version
```

```sh output
⛅️ wrangler 3.27.0
```

```sh
# Set your environmental variable: your configured Hyperdrive binding is "TEST_DB".
export WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_TEST_DB="postgres://user:password@localhost:5432/databasename"
```

```sh
# Start a local dev session:
npx wrangler dev
```

```sh output
------------------
Found a non-empty WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_TEST_DB variable. Hyperdrive will connect to this database
during local development.

wrangler dev now uses local mode by default, powered by 🔥 Miniflare and 👷 workerd.
To run an edge preview session for your Worker, use wrangler dev --remote
Your worker has access to the following bindings:
- Hyperdrive configs:
  - TEST_DB: c020574a-5623-407b-be0c-cd192bab9545
⎔ Starting local server...

[mf:inf] Ready on http://127.0.0.1:8787/
[b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit
```

`wrangler dev` separates local and production (remote) data. A local session does not have access to your production data by default. To access your production (remote) Hyperdrive configuration, pass the `--remote` flag when calling `wrangler dev`. Any changes you make when running in `--remote` mode cannot be undone.

Refer to the [`wrangler dev` documentation](/workers/wrangler/commands/#dev) to learn more about how to configure a local development session.

## Related resources

- Use [`wrangler dev`](/workers/wrangler/commands/#dev) to run your Worker and Hyperdrive locally and debug issues before deploying.
- Learn [how Hyperdrive works](/hyperdrive/configuration/how-hyperdrive-works/).
- Understand how to [configure query caching in Hyperdrive](/hyperdrive/configuration/query-caching/).

---

# Query caching

URL: https://developers.cloudflare.com/hyperdrive/configuration/query-caching/

import { TabItem, Tabs } from "~/components";

Hyperdrive automatically caches the most popular queries executed against your database, reducing the need to go back to your database (incurring latency and database load) for every query.

## What does Hyperdrive cache?

Because Hyperdrive uses database protocols, it can differentiate between a mutating query (a query that writes to the database) and a non-mutating query (a read-only query), allowing Hyperdrive to safely cache read-only queries.

Besides determining the difference between a `SELECT` and an `INSERT`, Hyperdrive also parses the database wire-protocol and uses it to differentiate between a mutating or non-mutating query.

For example, a read query that populates the front page of a news site would be cached:

<Tabs>
	<TabItem label="PostgreSQL">
```sql
-- Cacheable
SELECT * FROM articles WHERE DATE(published_time) =
CURRENT_DATE() ORDER BY published_time DESC LIMIT 50
```
</TabItem>
<TabItem label="MySQL">
```sql
-- Cacheable
SELECT * FROM articles WHERE DATE(published_time) =
CURDATE() ORDER BY published_time DESC LIMIT 50
```
</TabItem>
</Tabs>

Mutating queries (including `INSERT`, `UPSERT`, or `CREATE TABLE`) and queries that use [functions designated as `volatile` by PostgreSQL](https://www.postgresql.org/docs/current/xfunc-volatility.html) are not cached:

<Tabs>
  <TabItem label="PostgreSQL">
    ```sql
    -- Not cached
    INSERT INTO users(id, name, email) VALUES(555, 'Matt', 'hello@example.com');

    SELECT LASTVAL(), * FROM articles LIMIT 50;
    ```

  </TabItem>
  <TabItem label="MySQL">
    ```sql
    -- Not cached
    INSERT INTO users(id, name, email) VALUES(555, 'Thomas', 'hello@example.com');

    SELECT LAST_INSERT_ID(), * FROM articles LIMIT 50;
    ```

  </TabItem>
</Tabs>

## Default cache settings

The default caching behaviour for Hyperdrive is defined as below:

- `max_age` = 60 seconds (1 minute)
- `stale_while_revalidate` = 15 seconds

The `max_age` setting determines the maximum lifetime a query response will be served from cache. Cached responses may be evicted from the cache prior to this time if they are rarely used.

The `stale_while_revalidate` setting allows Hyperdrive to continue serving stale cache results for an additional period of time while it is revalidating the cache. In most cases, revalidation should happen rapidly.

You can set a maximum `max_age` of 1 hour.

## Disable caching

Disable caching on a per-Hyperdrive basis by using the [Wrangler](/workers/wrangler/install-and-update/) CLI to set the `--caching-disabled` option to `true`.

For example:

```sh
# wrangler v3.11 and above required
npx wrangler hyperdrive update my-hyperdrive-id --origin-password my-db-password --caching-disabled true
```

You can also configure multiple Hyperdrive connections from a single application: one connection that enables caching for popular queries, and a second connection where you do not want to cache queries, but still benefit from Hyperdrive's latency benefits and connection pooling.

For example, using database drivers:

<Tabs>
<TabItem label="PostgreSQL">
```ts title="index.ts"
const client = postgres(env.HYPERDRIVE.connectionString);
// ...
const clientNoCache = postgres(env.HYPERDRIVE_CACHE_DISABLED.connectionString);
```
</TabItem>

<TabItem label="MySQL">
```ts title="index.ts"
const connection = createConnection({
		host: env.HYPERDRIVE.host,
		user: env.HYPERDRIVE.user,
		password: env.HYPERDRIVE.password,
		database: env.HYPERDRIVE.database,
		port: env.HYPERDRIVE.port
});
// ...
const connectionNoCache = createConnection({
		host: env.HYPERDRIVE_CACHE_DISABLED.host,
		user: env.HYPERDRIVE_CACHE_DISABLED.user,
		password: env.HYPERDRIVE_CACHE_DISABLED.password,
		database: env.HYPERDRIVE_CACHE_DISABLED.database,
		port: env.HYPERDRIVE_CACHE_DISABLED.port
});
```
  </TabItem>
</Tabs>

The Wrangler configuration remains the same both for PostgreSQL and MySQL.

```jsonc title="wrangler.jsonc"
		{
			// Rest of file
			"hyperdrive": [
				{
					"binding": "HYPERDRIVE",
					"id": "<YOUR_HYPERDRIVE_CACHE_ENABLED_CONFIGURATION_ID>"
				},
				{
					"binding": "HYPERDRIVE_CACHE_DISABLED",
					"id": "<YOUR_HYPERDRIVE_CACHE_DISABLED_CONFIGURATION_ID>"
				}
			]
		}
		```

## Next steps

- Learn more about [How Hyperdrive works](/hyperdrive/configuration/how-hyperdrive-works/).
- Learn how to [Connect to PostgreSQL](/hyperdrive/examples/connect-to-postgres/) from Hyperdrive.
- Review [Troubleshooting common issues](/hyperdrive/observability/troubleshooting/) when connecting a database to Hyperdrive.

---

# SSL/TLS certificates

URL: https://developers.cloudflare.com/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive/

import { TabItem, Tabs, Render, WranglerConfig } from "~/components";

Hyperdrive provides additional ways to secure connectivity to your database. Hyperdrive supports:

1. **Server certificates** for TLS (SSL) modes such as `verify-ca` and `verify-full` for increased security. When configured, Hyperdrive will verify that the certificates have been signed by the expected certificate authority (CA) to avoid man-in-the-middle attacks.
2. **Client certificates** for Hyperdrive to authenticate itself to your database with credentials beyond beyond username/password. To properly use client certificates, your database must be configured to verify the client certificates provided by a client, such as Hyperdrive, to allow access to the database.

Hyperdrive can be configured to use only server certificates, only client certificates, or both depending on your security requirements and database configurations.

:::note

Support for server certificates and client certificates is not available for MySQL (beta). Support for server certificates and client certificates is only available for local development using `npx wrangler dev --remote` which runs your Workers and Hyperdrive in Cloudflare's network with local debugging.

:::

## Server certificates (TLS/SSL modes)

Hyperdrive supports 3 common encryption [TLS/SSL modes](https://www.postgresql.org/docs/current/libpq-ssl.html) to connect to your database:

- `require` (default): TLS is required for encrypted connectivity and server certificates are validated (based on WebPKI).
- `verify-ca`: Hyperdrive will verify that the database server is trustworthy by verifying that the certificates of the server have been signed by the expected root certificate authority or intermediate certificate authority.
- `verify-full`: Identical to `verify-ca`, but Hyperdrive also requires the database hostname to match a Subject Alternative Name (SAN) present on the certificate.

By default, all Hyperdrive configurations are encrypted with SSL/TLS (`require`). This requires your database to be configured to accept encrypted connections (with SSL/TLS).

You can configure Hyperdrive to use `verify-ca` and `verify-full` for a more stringent security configuration, which provide additional verification checks of the server's certificates. This helps guard against man-in-the-middle attacks.

To configure Hyperdrive to verify the certificates of the server, you must provide Hyperdrive with the certificate of the root certificate authority (CA) or an intermediate certificate which has been used to sign the certificate of your database.

### Step 1: Upload your the root certificate authority (CA) certificate

Using Wrangler, you can upload your root certificate authority (CA) certificate:

```bash
# requires Wrangler 4.9.0 or greater
npx wrangler cert upload certificate-authority --ca-cert \<ROUTE_TO_CA_PEM_FILE\>.pem --name \<CUSTOM_NAME_FOR_CA_CERT\>

---

Uploading CA Certificate tmp-cert...
Success! Uploaded CA Certificate <CUSTOM_NAME_FOR_CA_CERT>
ID: <YOUR_ID_FOR_THE_CA_CERTIFICATE>
...
```

:::note

You must use the CA certificate bundle that is for your specific region. You can not use a CA certificate bundle that contains more than one CA certificate, such as a global bundle of CA certificates containing each region's certificate.

:::

### Step 2: Create your Hyperdrive configuration using the CA certificate and the SSL mode

Once your CA certificate has been created, you can create a Hyperdrive configuration with the newly created certificates using either the dashboard or Wrangler. You must also specify the SSL mode of `verify-ca` or `verify-full` to use.

<Tabs>

<TabItem label="Wrangler">

Using Wrangler, enter the following command in your terminal to create a Hyperdrive configuration with the CA certificate and a `verify-full` SSL mode:

```bash
npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --ca-certificate-id <YOUR_CA_CERT_ID> --sslmode verify-full
```
</TabItem>

<TabItem label="Dashboard">

From the dashboard, follow these steps to create a Hyperdrive configuration with server certificates:

1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive), navigate to **Storage & Databases > Hyperdrive** and click **Create configuration**.
2. Select **Server certificates**.
3. Specify a SSL mode of **Verify CA** or **Verify full**
4. Select the SSL certificate of the certificate authority (CA) of your database that you have previously uploaded with Wrangler.

</TabItem>

</Tabs>



When creating the Hyperdrive configuration, Hyperdrive will attempt to connect to the database with the provided credentials. If the command provides successful results, you have properly configured your Hyperdrive configuration to verify the certificates provided by your database server.

:::note

Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](/hyperdrive/observability/troubleshooting/) to debug possible causes.

:::

## Client certificates

Your database can be configured to [verify a certificate provided by the client](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-CLIENTCERT), in this case, Hyperdrive. This serves as an additional factor to authenticate clients (in addition to the username and password).

For the database server to be able to verify the client certificates, Hyperdrive must be configured to provide a certificate file (`client-cert.pem`) and a private key with which the certificate was generated (`private-key.pem`).

### Step 1: Upload your client certificates (mTLS certificates)

Upload your client certificates to be used by Hyperdrive using Wrangler:

```bash
# requires Wrangler 4.9.0 or greater
npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>

---

Uploading client certificate <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>...
Success! Uploaded client certificate <CUSTOM_NAME_FOR_CLIENT_CERTIFICATE>
ID: <YOUR_ID_FOR_THE_CLIENT_CERTIFICATE_PAIR>
...
```

### Step 2: Create a Hyperdrive configuration

You can now create a Hyperdrive configuration using the newly created client certificate bundle using the dashboard or Wrangler.


<Tabs>

<TabItem label="Wrangler">

Using Wrangler, enter the following command in your terminal to create a Hyperdrive configuration with using the client certificate pair:

```bash
npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" --mtls-certificate-id <YOUR_CLIENT_CERT_PAIR_ID>
```
</TabItem>

<TabItem label="Dashboard">

From the dashboard, follow these steps to create a Hyperdrive configuration with server certificates:

1. In the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive), navigate to **Storage & Databases > Hyperdrive** and click **Create configuration**.
2. Select **Client certificates**.
3. Select the SSL client certificate and private key pair for Hyperdrive to use during the connection setup with your database server.

</TabItem>

</Tabs>


When Hyperdrive connects to your database, it will provide a client certificate signed with the private key to the database server. This allows the database server to confirm that the client, in this case Hyperdrive, has both the private key and the client certificate. By using client certificates, you can add an additional authentication layer for your database to ensures that only Hyperdrive can connect to it.

:::note

Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](/hyperdrive/observability/troubleshooting/) to debug possible causes.

:::

---

# Examples

URL: https://developers.cloudflare.com/hyperdrive/examples/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Rotating database credentials

URL: https://developers.cloudflare.com/hyperdrive/configuration/rotate-credentials/

import { TabItem, Tabs, Render, WranglerConfig } from "~/components";

You can change the connection information and credentials of your Hyperdrive configuration in one of two ways:

1. Create a new Hyperdrive configuration with the new connection information, and update your Worker to use the new Hyperdrive configuration.
2. Update the existing Hyperdrive configuration with the new connection information and credentials.

## Use a new Hyperdrive configuration

Creating a new Hyperdrive configuration to update your database credentials allows you to keep your existing Hyperdrive configuration unchanged, gradually migrate your Worker to the new Hyperdrive configuration, and easily roll back to the previous configuration if needed.

To create a Hyperdrive configuration that connects to an existing PostgreSQL or MySQL database, use the [Wrangler](/workers/wrangler/install-and-update/) CLI or the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive).

```sh
# wrangler v3.11 and above required
npx wrangler hyperdrive create my-updated-hyperdrive --connection-string="<YOUR_CONNECTION_STRING>"
```

The command above will output the ID of your Hyperdrive. Set this ID in the [Wrangler configuration file](/workers/wrangler/configuration/) for your Workers project:

<WranglerConfig>

```toml
# required for database drivers to function
compatibility_flags = [ "nodejs_compat" ]
compatibility_date = "2024-09-23"

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"
```

</WranglerConfig>

To update your Worker to use the new Hyperdrive configuration, redeploy your Worker or use [gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/).

## Update the existing Hyperdrive configuration

You can update the configuration of an existing Hyperdrive configuration using the [wrangler CLI](/workers/wrangler/install-and-update/).

```sh
# wrangler v3.11 and above required
npx wrangler hyperdrive update <HYPERDRIVE_CONFIG_ID> --origin-host <YOUR_ORIGIN_HOST> --origin-password <YOUR_ORIGIN_PASSWORD> --origin-user <YOUR_ORIGIN_USERNAME> --database <YOUR_DATABASE> --origin-port <YOUR_ORIGIN_PORT>
```

:::note
Updating the settings of an existing Hyperdrive configuration does not purge Hyperdrive's cache and does not tear down the existing database connection pool. New connections will be established using the new connection information.
:::

---

# Observability

URL: https://developers.cloudflare.com/hyperdrive/observability/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Metrics and analytics

URL: https://developers.cloudflare.com/hyperdrive/observability/metrics/

Hyperdrive exposes analytics that allow you to inspect query volume, query latency and cache ratios size across all and/or each Hyperdrive configuration in your account.

## Metrics

Hyperdrive currently exports the below metrics as part of the `hyperdriveQueriesAdaptiveGroups` GraphQL dataset:

| Metric             | GraphQL Field Name  | Description                                                                                                                                                                                                       |
| ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Queries            | `count`             | The number of queries issued against your Hyperdrive in the given time period.                                                                                                                                    |
| Cache Status       | `cacheStatus`       | Whether the query was cached or not. Can be one of `disabled`, `hit`, `miss`, `uncacheable`, `multiplestatements`, `notaquery`, `oversizedquery`, `oversizedresult`, `parseerror`, `transaction`, and `volatile`. |
| Query Bytes        | `queryBytes`        | The size of your queries, in bytes.                                                                                                                                                                               |
| Result Bytes       | `resultBytes`       | The size of your query _results_, in bytes.                                                                                                                                                                       |
| Connection Latency | `connectionLatency` | The time (in milliseconds) required to establish new connections from Hyperdrive to your database, as measured from your Hyperdrive connection pool(s).                                                           |
| Query Latency      | `queryLatency`      | The time (in milliseconds) required to query (and receive results) from your database, as measured from your Hyperdrive connection pool(s).                                                                       |
| Event Status       | `eventStatus`       | Whether a query responded successfully (`complete`) or failed (`error`).                                                                                                                                          |

Metrics can be queried (and are retained) for the past 31 days.

## View metrics in the dashboard

Per-database analytics for Hyperdrive are available in the Cloudflare dashboard. To view current and historical metrics for a Hyperdrive configuration:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to [**Workers & Pages** > **Hyperdrive**](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive).
3. Select an existing Hyperdrive configuration.
4. Select the **Metrics** tab.

You can optionally select a time window to query. This defaults to the last 24 hours.

## Query via the GraphQL API

You can programmatically query analytics for your Hyperdrive configurations via the [GraphQL Analytics API](/analytics/graphql-api/). This API queries the same datasets as the Cloudflare dashboard, and supports GraphQL [introspection](/analytics/graphql-api/features/discovery/introspection/).

Hyperdrives's GraphQL datasets require an `accountTag` filter with your Cloudflare account ID. Hyperdrive exposes the `hyperdriveQueriesAdaptiveGroups` dataset.

## Write GraphQL queries

Examples of how to explore your Hyperdrive metrics.

### Get the number of queries handled via your Hyperdrive config by cache status

```graphql graphql-api-explorer
query HyperdriveQueries(
	$accountTag: string!
	$configId: string!
	$datetimeStart: Time!
	$datetimeEnd: Time!
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			hyperdriveQueriesAdaptiveGroups(
				limit: 10000
				filter: {
					configId: $configId
					datetime_geq: $datetimeStart
					datetime_leq: $datetimeEnd
				}
			) {
				count
				dimensions {
					cacheStatus
				}
			}
		}
	}
}
```

### Get the average query and connection latency for queries handled via your Hyperdrive config within a range of time, excluding queries that failed due to an error

```graphql graphql-api-explorer
query AverageHyperdriveLatencies(
	$accountTag: string!
	$configId: string!
	$datetimeStart: Time!
	$datetimeEnd: Time!
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			hyperdriveQueriesAdaptiveGroups(
				limit: 10000
				filter: {
					configId: $configId
					eventStatus: "complete"
					datetime_geq: $datetimeStart
					datetime_leq: $datetimeEnd
				}
			) {
				avg {
					connectionLatency
					queryLatency
				}
			}
		}
	}
}
```

### Get the total amount of query and result bytes flowing through your Hyperdrive config

```graphql graphql-api-explorer
query HyperdriveQueryAndResultBytesForSuccessfulQueries(
	$accountTag: string!
	$configId: string!
	$datetimeStart: Date!
	$datetimeEnd: Date!
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			hyperdriveQueriesAdaptiveGroups(
				limit: 10000
				filter: {
					configId: $configId
					datetime_geq: $datetimeStart
					datetime_leq: $datetimeEnd
				}
			) {
				sum {
					queryBytes
					resultBytes
				}
			}
		}
	}
}
```

---

# Troubleshoot and debug

URL: https://developers.cloudflare.com/hyperdrive/observability/troubleshooting/

Troubleshoot and debug errors commonly associated with connecting to a database with Hyperdrive.

## Configuration errors

When creating a new Hyperdrive configuration, or updating the connection parameters associated with an existing configuration, Hyperdrive performs a test connection to your database in the background before creating or updating the configuration.

Hyperdrive will also issue an empty test query, a `;` in PostgreSQL, to validate that it can pass queries to your database.

| Error Code | Details                                                                                          | Recommended fixes                                                                                                                                              |
| ---------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `2008`     | Bad hostname.                                                                                    | Hyperdrive could not resolve the database hostname. Confirm it exists in public DNS.                                                                           |
| `2009`     | The hostname does not resolve to a public IP address, or the IP address is not a public address. | Hyperdrive can only connect to public IP addresses. Private IP addresses, like `10.1.5.0` or `192.168.2.1`, are not currently supported.                       |
| `2010`     | Cannot connect to the host:port.                                                                 | Hyperdrive could not route to the hostname: ensure it has a public DNS record that resolves to a public IP address. Check that the hostname is not misspelled. |
| `2011`     | Connection refused.                                                                              | A network firewall or access control list (ACL) is likely rejecting requests from Hyperdrive. Ensure you have allowed connections from the public Internet.    |
| `2012`     | TLS (SSL) not supported by the database.                                                         | Hyperdrive requires TLS (SSL) to connect. Configure TLS on your database.                                                                                      |
| `2013`     | Invalid database credentials.                                                                    | Ensure your username is correct (and exists), and the password is correct (case-sensitive).                                                                    |
| `2014`     | The specified database name does not exist.                                                      | Check that the database (not table) name you provided exists on the database you are asking Hyperdrive to connect to.                                          |
| `2015`     | Generic error.                                                                                   | Hyperdrive failed to connect and could not determine a reason. Open a support ticket so Cloudflare can investigate.                                            |
| `2016`     | Test query failed.                                                                               | Confirm that the user Hyperdrive is connecting as has permissions to issue read and write queries to the given database.                                       |

### Failure to connect

Hyperdrive may also emit `Failed to connect to the provided database` when it fails to connect to the database when attempting to create a Hyperdrive configuration. This is possible when the TLS (SSL) certificates are misconfigured. Here is a non-exhaustive table of potential failure to connect errors:

| Error message | Details               | Recommended fixes |
| ---------- | -------------------- | --------------------- |
| Server return error and closed connection. | This message occurs when you attempt to connect to a database that has client certificate verification enabled. | Ensure you are configuring your Hyperdrive with [client certificates](/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive/) if your database requires them. |
| TLS handshake failed: cert validation failed. | This message occurs when Hyperdrive has been configured with server CA certificates and is indicating that the certificate provided by the server has not been signed by the expected CA certificate. | Ensure you are using the expected the correct CA certificate for Hyperdrive, or ensure you are connecting to the right database. |

## Connection errors

Hyperdrive may also return errors at runtime. This can happen during initial connection setup, or in response to a query or other wire-protocol command sent by your driver.

These errors are returned as `ErrorResponse` wire protocol messages, which are handled by most drivers by throwing from the responsible query or by triggering an error event.
Hyperdrive errors that do not map 1:1 with an error message code [documented by PostgreSQL](https://www.postgresql.org/docs/current/errcodes-appendix.html) use the `58000` error code.

Hyperdrive may also encounter `ErrorResponse` wire protocol messages sent by your database. Hyperdrive will pass these errors through unchanged when possible.



### Hyperdrive specific errors

| Error Message                                          | Details                                                                                         | Recommended fixes                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Internal error.`                                      | Something is broken on our side.                                                                | Check for an ongoing incident affecting Hyperdrive, and contact Cloudflare Support. Retrying the query is appropriate, if it makes sense for your usage pattern.                                                                                                                               |
| `Failed to acquire a connection from the pool.`        | Hyperdrive timed out while waiting for a connection to your database, or cannot connect at all. | If you are seeing this error intermittently, your Hyperdrive pool is being exhausted because too many connections are being held open for too long by your worker. This can be caused by a myriad of different issues, but long-running queries/transactions are a common offender.            |
| `Server connection attempt failed: connection_refused` | Hyperdrive is unable to create new connections to your origin database.                         | A network firewall or access control list (ACL) is likely rejecting requests from Hyperdrive. Ensure you have allowed connections from the public Internet. Sometimes, this can be caused by your database host provider refusing incoming connections when you go over your connection limit. |
| `Hyperdrive does not currently support MySQL COM_STMT_PREPARE messages` | Hyperdrive does not support prepared statements for MySQL databases. | Remove prepared statements from your MySQL queries. |

### Node errors

| Error Message                                    | Details                                                                                                               | Recommended fixes                                                                                                            |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `Uncaught Error: No such module "node:<module>"` | Your Cloudflare Workers project or a library that it imports is trying to access a Node module that is not available. | Enable [Node.js compatibility](/workers/runtime-apis/nodejs/) for your Cloudflare Workers project to maximize compatibility. |

### Driver errors

If your queries are not getting cached despite Hyperdrive having caching enabled, your driver may be configured such that your queries are not cacheable by Hyperdrive. This may happen if you are using the [Postgres.js](https://github.com/porsager/postgres) driver with [`prepare: false:`](https://github.com/porsager/postgres?tab=readme-ov-file#prepared-statements). To resolve this, enable prepared statements with `prepare: true`.

| Error Message                                    | Details                                                                                                               | Recommended fixes                                                                                                            |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `Code generation from strings disallowed for this context` | The database driver you are using is attempting to use the `eval()` command, which is unsupported on Cloudflare Workers (common in `mysql2` driver). | Configure the database driver to not use `eval()`. See how to [configure `mysql2` to disable the usage of `eval()`](/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql2/). |

### Improve performance

Having query traffic written as transactions can limit performance. This is because in the case of a transaction, the connection must be held for the duration of the transaction, which limits connection multiplexing. If there are multiple queries per transaction, this can be particularly impactful on connection multiplexing. Where possible, we recommend not wrapping queries in transactions to allow the connections to be shared more aggressively.

---

# FAQ

URL: https://developers.cloudflare.com/hyperdrive/reference/faq/

Below you will find answers to our most commonly asked questions regarding Hyperdrive.

## Connectivity

### Does Hyperdrive use specific IP addresses to connect to my database?

Hyperdrive connects to your database using [Cloudflare's IP address ranges](https://www.cloudflare.com/ips/). These are shared by all Hyperdrive configurations and other Cloudflare products.

You can use this to configure restrictions in your database firewall to restrict the IP addresses that can access your database.

### Does Hyperdrive support connecting to D1 databases?

Hyperdrive does not support [D1](/d1) because D1 provides fast connectivity from Workers by design.

Hyperdrive is designed to speed up connectivity to traditional, regional SQL databases such as PostgreSQL. These databases are typically accessed using database drivers that communicate over TCP/IP.
Unlike D1, creating a secure database connection to a traditional SQL database
involves multiple round trips between the client (your Worker) and your database server.
See [How Hyperdrive works](/hyperdrive/configuration/how-hyperdrive-works/) for more detail on why round trips are needed
and how Hyperdrive solves this.

D1 does not require round trips to create database connections. D1 is designed to be performant for access from Workers by default, without needing Hyperdrive.

## Pricing

### Does Hyperdrive charge for data transfer / egress?

No.

### Is Hyperdrive available on the [Workers Free](/workers/platform/pricing/#workers) plan?

Yes. Refer to [pricing](/hyperdrive/platform/pricing/).

### Does Hyperdrive charge for additional compute?

Hyperdrive itself does not charge for compute (CPU) or processing (wall clock) time. Workers querying Hyperdrive and computing results: for example, serializing results into JSON and/or issuing queries, are billed per [Workers pricing](/workers/platform/pricing/#workers).

## Limits

### Are there any limits to Hyperdrive?

Refer to the published [limits](/hyperdrive/platform/limits/) documentation.

---

# Reference

URL: https://developers.cloudflare.com/hyperdrive/reference/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Supported databases and features

URL: https://developers.cloudflare.com/hyperdrive/reference/supported-databases-and-features/

## Database support

The following table shows which database engines and/or specific database providers are supported.

| Database Engine | Supported                | Known supported versions | Details                                                                                                             |
| --------------- | ------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| PostgreSQL      | ✅                       | `9.0` to `17.x`          | Both self-hosted and managed (AWS, Azure, Google Cloud, Oracle) instances are supported.                            |
| MySQL           | ✅                       | `5.7` to `8.x`           | Both self-hosted and managed (AWS, Azure, Google Cloud, Oracle) instances are supported. MariaDB is also supported. |
| SQL Server      | Not currently supported. |                          |                                                                                                                     |
| MongoDB         | Not currently supported. |                          |                                                                                                                     |

## Supported database providers

Hyperdrive supports managed Postgres and MySQL databases provided by various providers, including AWS, Azure, and GCP. Refer to [Examples](/hyperdrive/examples/connect-to-postgres/) to see how to connect to various database providers.

Hyperdrive also supports databases that are compatible with the Postgres or MySQL protocol. The following is a non-exhaustive list of Postgres or MySQL-compatible database providers:

| Database Engine | Supported | Known supported versions | Details                                                                                                                  |
| --------------- | --------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| AWS Aurora            | ✅        | All                      | Postgres-compatible and MySQL-compatible. Refer to AWS Aurora examples for [MySQL](/hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora/) and [Postgres](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora/).                                                                                       |
| Neon            | ✅        | All                      | Neon currently runs Postgres 15.x                                                                                        |
| Supabase        | ✅        | All                      | Supabase currently runs Postgres 15.x                                                                                    |
| Timescale       | ✅        | All                      | See the [Timescale guide](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale/) to connect.                               |
| Materialize     | ✅        | All                      | Postgres-compatible. Refer to the [Materialize guide](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize/) to connect. |
| CockroachDB     | ✅        | All                      | Postgres-compatible. Refer to the [CockroachDB](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb/) guide to connect. |
| Planetscale     | ✅        | All                      | Planetscale currently runs MySQL 8.x                                                                                     |
| MariaDB         | ✅        | All                      | MySQL-compatible.                                                                                                        |

## Supported TLS (SSL) modes

Hyperdrive supports the following [PostgreSQL TLS (SSL)](https://www.postgresql.org/docs/current/libpq-ssl.html) connection modes when connecting to your origin database:

| Mode          | Supported          | Details                                                                                                                                   |
| ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `none`        | No                 | Hyperdrive does not support insecure plain text connections.                                                                              |
| `prefer`      | No (use `require`) | Hyperdrive will always use TLS.                                                                                                           |
| `require`     | Yes (default)      | TLS is required, and server certificates are validated (based on WebPKI).                                                                 |
| `verify-ca`   | Yes                | Verifies the server's TLS certificate is signed by a root CA on the client. This ensures the server has a certificate the client trusts.  |
| `verify-full` | Yes                | Identical to `verify-ca`, but also requires the database hostname must match a Subject Alternative Name (SAN) present on the certificate. |

Refer to [SSL/TLS certificates](/hyperdrive/configuration/tls-ssl-certificates-for-hyperdrive/) documentation for details on how to configure `verify-ca` or `verify-full` TLS (SSL) modes for Hyperdrive.
:::note

Hyperdrive support for `verify-ca` and `verify-full` is not available for MySQL (beta).

:::

## Supported PostgreSQL authentication modes

Hyperdrive supports the following [authentication modes](https://www.postgresql.org/docs/current/auth-methods.html) for connecting to PostgreSQL databases:

- Password Authentication (`md5`)
- Password Authentication (`password`) (clear-text password)
- SASL Authentication (`SCRAM-SHA-256`)

## Unsupported PostgreSQL features:

Hyperdrive does not support the following PostgreSQL features:

- SQL-level management of prepared statements, such as using `PREPARE`, `DISCARD`, `DEALLOCATE`, or `EXECUTE`.
- Advisory locks ([PostgreSQL documentation](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)).
- `LISTEN` and `NOTIFY`.
- `PREPARE` and `DEALLOCATE`.
- Any modification to per-session state not explicitly documented as supported elsewhere.

## Unsupported MySQL features:

Hyperdrive does not support the following MySQL features:

- Non-UTF8 characters in queries
- `USE` statements
- Multi-statement queries
- Prepared statement queries via SQL (using `PREPARE` and `EXECUTE` statements) and [protocol-level prepared statements](https://sidorares.github.io/node-mysql2/docs/documentation/prepared-statements).
- `COM_INIT_DB` messages
- [Authentication plugins](https://dev.mysql.com/doc/refman/8.4/en/authentication-plugins.html) other than `caching_sha2_password` or `mysql_native_password`

In cases where you need to issue these unsupported statements from your application, the Hyperdrive team recommends setting up a second, direct client without Hyperdrive.

---

# Wrangler commands

URL: https://developers.cloudflare.com/hyperdrive/reference/wrangler-commands/

import { Render } from "~/components";

<Render file="hyperdrive" product="workers/wrangler-commands"/>

---

# Limits

URL: https://developers.cloudflare.com/hyperdrive/platform/limits/

The following limits apply to Hyperdrive configuration, connections, and queries made to your configured origin databases.

| Feature                                            | Free                     | Paid                      |
| -------------------------------------------------- | ------------------------ | ------------------------- |
| Maximum configured databases                       | 10 per account           | 25 per account            |
| Initial connection timeout                         | 15 seconds               | 15 seconds                |
| Idle connection timeout                            | 10 minutes               | 10 minutes                |
| Maximum cached query response size                 | 50 MB                    | 50 MB                     |
| Maximum query (statement) duration                 | 60 seconds               | 60 seconds                |
| Maximum username length [^1]                       | 63 characters (bytes)    | 63 characters (bytes)     |
| Maximum database name length [^1]                  | 63 characters (bytes)    | 63 characters (bytes)     |
| Maximum potential origin database connections [^2] | approx. \~20 connections | approx. \~100 connections |

:::note
Hyperdrive does not have a hard limit on the number of concurrent _client_ connections made from your Workers.

As many hosted databases have limits on the number of unique connections they can manage, Hyperdrive attempts to keep number of concurrent pooled connections to your origin database lower.
:::

[^1]: This is a limit enforced by PostgreSQL. Some database providers may enforce smaller limits.

[^2]: Hyperdrive is a distributed system, so it is possible for a client to be unable to reach an existing pool. In this scenario, a new pool will be established, with its own allocation of connections. This favors availability over strictly enforcing limits, but does mean that it is possible in edge cases to overshoot the normal connection limit.

:::note
You can request adjustments to limits that conflict with your project goals by contacting Cloudflare. Not all limits can be increased. To request an increase, submit a [Limit Increase Request](https://forms.gle/ukpeZVLWLnKeixDu7) and we will contact you with next steps.
:::

---

# Platform

URL: https://developers.cloudflare.com/hyperdrive/platform/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Release notes

URL: https://developers.cloudflare.com/hyperdrive/platform/release-notes/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/hyperdrive.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Pricing

URL: https://developers.cloudflare.com/hyperdrive/platform/pricing/

import { Render } from "~/components";

<Render file="hyperdrive_pricing" product="workers" />

Hyperdrive limits are automatically adjusted when subscribed to a Workers Paid plan. Hyperdrive's [connection pooling and query caching](/hyperdrive/configuration/how-hyperdrive-works/) are included in Workers Paid plan, so do not incur any additional charges.

## Pricing FAQ

### Does connection pooling or query caching incur additional charges?

No. Hyperdrive's built-in cache and connection pooling are included within the stated plans above. There are no hidden limits other than those [published](/hyperdrive/platform/limits/).

### Are cached queries counted the same as uncached queries?

Yes, any query made through Hyperdrive, whether cached or uncached, whether query or mutation, is counted according to the limits above.

### Does Hyperdrive charge for data transfer / egress?

No.

:::note

For questions about pricing, refer to the [pricing FAQs](/hyperdrive/reference/faq/#pricing).

:::

---

# Tutorials

URL: https://developers.cloudflare.com/hyperdrive/tutorials/

import { GlossaryTooltip, ListTutorials } from "~/components"

View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Hyperdrive.

<ListTutorials />

---

# Workers Binding API

URL: https://developers.cloudflare.com/kv/api/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Delete key-value pairs

URL: https://developers.cloudflare.com/kv/api/delete-key-value-pairs/

import { GlossaryTooltip } from "~/components"

To delete a key-value pair, call the `delete()` method of the [KV binding](/kv/concepts/kv-bindings/) on any [KV namespace](/kv/concepts/kv-namespaces/) you have bound to your Worker code:

```js
env.NAMESPACE.delete(key);
```

#### Example

An example of deleting a key-value pair from within a Worker:

```js
export default {
  async fetch(request, env, ctx) {
    try {
      await env.NAMESPACE.delete("first-key");

      return new Response("Successful delete", {
        status: 200
      });
    }
    catch (e)
    {
      return new Response(e.message, {status: 500});
    }
  },
};
```

## Reference

The following method is provided to delete from KV:
- [delete()](#delete-method)

### `delete()` method

To delete a key-value pair, call the `delete()` method of the [KV binding](/kv/concepts/kv-bindings/) on any KV namespace you have bound to your Worker code:

```js
env.NAMESPACE.delete(key);
```

#### Parameters

* `key`: `string`
  * The key to associate with the value.

#### Response

* `response`: `Promise<void>`
  * A `Promise` that resolves if the delete is successful.


This method returns a promise that you should `await` on to verify successful deletion. Calling `delete()` on a non-existing key is returned as a successful delete.

Calling the `delete()` method will remove the key and value from your KV namespace. As with any operations, it may take some time for the key to be deleted from various points in the Cloudflare global network.

## Guidance

### Delete data in bulk

Delete more than one key-value pair at a time with Wrangler or [via the REST API](/api/resources/kv/subresources/namespaces/subresources/keys/methods/bulk_delete/).

The bulk REST API can accept up to 10,000 KV pairs at once. Bulk writes are not supported using the [KV binding](/kv/concepts/kv-bindings/).

## Other methods to access KV
You can also [delete key-value pairs from the command line with Wrangler](/kv/reference/kv-commands/#kv-namespace-delete) or [with the REST API](/api/resources/kv/subresources/namespaces/subresources/values/methods/delete/).

---

# List keys

URL: https://developers.cloudflare.com/kv/api/list-keys/

To list all the keys in your KV namespace, call the `list()` method of the [KV binding](/kv/concepts/kv-bindings/) on any [KV namespace](/kv/concepts/kv-namespaces/) you have bound to your Worker code:


```js
env.NAMESPACE.list();
```

The `list()` method returns a promise you can `await` on to get the value.

#### Example

An example of listing keys from within a Worker:

```js
export default {
  async fetch(request, env, ctx) {
    try {
      const value = await env.NAMESPACE.list();

      return new Response(JSON.stringify(value.keys), {
        status: 200
      });
    }
    catch (e)
    {
      return new Response(e.message, {status: 500});
    }
  },
};
```

## Reference

The following method is provided to list the keys of KV:
- [list()](#list-method)

### `list()` method

To list all the keys in your KV namespace, call the `list()` method of the [KV binding](/kv/concepts/kv-bindings/) on any KV namespace you have bound to your Worker code:

```ts
env.NAMESPACE.list(options?)
```
#### Parameters
* `options`: `{
  prefix?: string,
  limit?: string,
  cursor?: string
}`
  * An object with attributes `prefix` (optional), `limit` (optional), or `cursor` (optional).
    * `prefix` is a `string` that represents a prefix you can use to filter all keys.
    * `limit` is the maximum number of keys returned. The default is 1,000, which is the maximum. It is unlikely that you will want to change this default but it is included for completeness.
    * `cursor` is a `string` used for paginating responses.

#### Response
* `response`: `Promise<{
  keys: {
    name: string,
    expiration?: number,
    metadata?: object
  }[],
  list_complete: boolean,
  cursor: string
}>`
  * A `Promise` that resolves to an object containing `keys`, `list_complete`, and `cursor` attributes.
    * `keys` is an array that contains an object for each key listed. Each object has attributes `name`, `expiration` (optional), and `metadata` (optional). If the key-value pair has an expiration set, the expiration will be present and in absolute value form (even if it was set in TTL form). If the key-value pair has non-null metadata set, the metadata will be present.
    * `list_complete` is a boolean, which will be `false` if there are more keys to fetch, even if the `keys` array is empty.
    * `cursor` is a `string` used for paginating responses.

The `list()` method returns a promise which resolves with an object that looks like the following:

```json
{
  "keys": [
    {
      "name": "foo",
      "expiration": 1234,
      "metadata": { "someMetadataKey": "someMetadataValue" }
    }
  ],
  "list_complete": false,
  "cursor": "6Ck1la0VxJ0djhidm1MdX2FyD"
}
```

The `keys` property will contain an array of objects describing each key. That object will have one to three keys of its own: the `name` of the key, and optionally the key's `expiration` and `metadata` values.

The `name` is a `string`, the `expiration` value is a number, and `metadata` is whatever type was set initially. The `expiration` value will only be returned if the key has an expiration and will be in the absolute value form, even if it was set in the TTL form. Any `metadata` will only be returned if the given key has non-null associated metadata.

If `list_complete` is `false`, there are more keys to fetch, even if the `keys` array is empty. You will use the `cursor` property to get more keys. Refer to [Pagination](#pagination) for more details.

Consider storing your values in metadata if your values fit in the [metadata-size limit](/kv/platform/limits/). Storing values in metadata is more efficient than a `list()` followed by a `get()` per key. When using `put()`, leave the `value` parameter empty and instead include a property in the metadata object:

```js
await NAMESPACE.put(key, "", {
  metadata: { value: value },
});
```

Changes may take up to 60 seconds (or the value set with `cacheTtl` of the `get()` or `getWithMetadata()` method) to be reflected on the application calling the method on the KV namespace.

## Guidance

### List by prefix

List all the keys starting with a particular prefix.

For example, you may have structured your keys with a user, a user ID, and key names, separated by colons (such as `user:1:<key>`). You could get the keys for user number one by using the following code:

```js
export default {
  async fetch(request, env, ctx) {
    const value = await env.NAMESPACE.list({ prefix: "user:1:" });
    return new Response(value.keys);
  },
};
```

This will return all keys starting with the `"user:1:"` prefix.

### Ordering

Keys are always returned in lexicographically sorted order according to their UTF-8 bytes.

### Pagination

If there are more keys to fetch, the `list_complete` key will be set to `false` and a `cursor` will also be returned. In this case, you can call `list()` again with the `cursor` value to get the next batch of keys:

```js
const value = await NAMESPACE.list();

const cursor = value.cursor;

const next_value = await NAMESPACE.list({ cursor: cursor });
```

Checking for an empty array in `keys` is not sufficient to determine whether there are more keys to fetch. Instead, use `list_complete`.

It is possible to have an empty array in `keys`, but still have more keys to fetch, because [recently expired or deleted keys](https://en.wikipedia.org/wiki/Tombstone_%28data_store%29) must be iterated through but will not be included in the returned `keys`.

When de-paginating a large result set while also providing a `prefix` argument, the `prefix` argument must be provided in all subsequent calls along with the initial arguments.

### Optimizing storage with metadata for `list()` operations

Consider storing your values in metadata if your values fit in the [metadata-size limit](/kv/platform/limits/). Storing values in metadata is more efficient than a `list()` followed by a `get()` per key. When using `put()`, leave the `value` parameter empty and instead include a property in the metadata object:

```js
await NAMESPACE.put(key, "", {
  metadata: { value: value },
});
```

## Other methods to access KV
You can also [list keys on the command line with Wrangler](/kv/reference/kv-commands/#kv-namespace-list) or [with the REST API](/api/resources/kv/subresources/namespaces/subresources/keys/methods/list/).

---

# Write key-value pairs

URL: https://developers.cloudflare.com/kv/api/write-key-value-pairs/

To create a new key-value pair, or to update the value for a particular key, call the `put()` method of the [KV binding](/kv/concepts/kv-bindings/) on any [KV namespace](/kv/concepts/kv-namespaces/) you have bound to your Worker code:

```js
env.NAMESPACE.put(key, value);
```

#### Example

An example of writing a key-value pair from within a Worker:

```js
export default {
	async fetch(request, env, ctx) {
		try {
			await env.NAMESPACE.put("first-key", "This is the value for the key");

			return new Response("Successful write", {
				status: 201,
			});
		} catch (e) {
			return new Response(e.message, { status: 500 });
		}
	},
};
```

## Reference

The following method is provided to write to KV:

- [put()](#put-method)

### `put()` method

To create a new key-value pair, or to update the value for a particular key, call the `put()` method on any KV namespace you have bound to your Worker code:

```js
env.NAMESPACE.put(key, value, options?);
```

#### Parameters

- `key`: `string`
  - The key to associate with the value. A key cannot be empty or be exactly equal to `.` or `..`. All other keys are valid. Keys have a maximum length of 512 bytes.
- `value`: `string` | `ReadableStream` | `ArrayBuffer`

  - The value to store. The type is inferred. The maximum size of a value is 25 MiB.

- `options`: `{
  expiration?: number,
  expirationTtl?: number,
  metadata?: object
}`
  - Optional. An object containing the `expiration` (optional), `expirationTtl` (optional), and `metadata` (optional) attributes.
    - `expiration` is the number that represents when to expire the key-value pair in seconds since epoch.
    - `expirationTtl` is the number that represents when to expire the key-value pair in seconds from now. The minimum value is 60.
    - `metadata` is an object that must serialize to JSON. The maximum size of the serialized JSON representation of the metadata object is 1024 bytes.

#### Response

- `response`: `Promise<void>`
  - A `Promise` that resolves if the update is successful.

The put() method returns a Promise that you should `await` on to verify a successful update.

## Guidance

### Concurrent writes to the same key

Due to the eventually consistent nature of KV, concurrent writes to the same key can end up overwriting one another. It is a common pattern to write data from a single process with Wrangler, Durable Objects, or the API. This avoids competing concurrent writes because of the single stream. All data is still readily available within all Workers bound to the namespace.

If concurrent writes are made to the same key, the last write will take precedence.

Writes are immediately visible to other requests in the same global network location, but can take up to 60 seconds (or the value of the `cacheTtl` parameter of the `get()` or `getWithMetadata()` methods) to be visible in other parts of the world.

Refer to [How KV works](/kv/concepts/how-kv-works/) for more information on this topic.

### Write data in bulk

Write more than one key-value pair at a time with Wrangler or [via the REST API](/api/resources/kv/subresources/namespaces/subresources/keys/methods/bulk_update/).

The bulk API can accept up to 10,000 KV pairs at once.

A `key` and a `value` are required for each KV pair. The entire request size must be less than 100 megabytes. Bulk writes are not supported using the [KV binding](/kv/concepts/kv-bindings/).

### Expiring keys

KV offers the ability to create keys that automatically expire. You may configure expiration to occur either at a particular point in time (using the `expiration` option), or after a certain amount of time has passed since the key was last modified (using the `expirationTtl` option).

Once the expiration time of an expiring key is reached, it will be deleted from the system. After its deletion, attempts to read the key will behave as if the key does not exist. The deleted key will not count against the KV namespace’s storage usage for billing purposes.

:::note

An `expiration` setting on a key will result in that key being deleted, even in cases where the `cacheTtl` is set to a higher (longer duration) value. Expiration always takes precedence.

:::

There are two ways to specify when a key should expire:

- Set a key's expiration using an absolute time specified in a number of [seconds since the UNIX epoch](https://en.wikipedia.org/wiki/Unix_time). For example, if you wanted a key to expire at 12:00AM UTC on April 1, 2019, you would set the key’s expiration to `1554076800`.

- Set a key's expiration time to live (TTL) using a relative number of seconds from the current time. For example, if you wanted a key to expire 10 minutes after creating it, you would set its expiration TTL to `600`.

Expiration targets that are less than 60 seconds into the future are not supported. This is true for both expiration methods.

#### Create expiring keys

To create expiring keys, set `expiration` in the `put()` options to a number representing the seconds since epoch, or set `expirationTtl` in the `put()` options to a number representing the seconds from now:

```js
await env.NAMESPACE.put(key, value, {
	expiration: secondsSinceEpoch,
});

await env.NAMESPACE.put(key, value, {
	expirationTtl: secondsFromNow,
});
```

These assume that `secondsSinceEpoch` and `secondsFromNow` are variables defined elsewhere in your Worker code.

### Metadata

To associate metadata with a key-value pair, set `metadata` in the `put()` options to an object (serializable to JSON):

```js
await env.NAMESPACE.put(key, value, {
	metadata: { someMetadataKey: "someMetadataValue" },
});
```

### Limits to KV writes to the same key

Workers KV has a maximum of 1 write to the same key per second. Writes made to the same key within 1 second will cause rate limiting (`429`) errors to be thrown.

You should not write more than once per second to the same key. Consider consolidating your writes to a key within a Worker invocation to a single write, or wait at least 1 second between writes.

The following example serves as a demonstration of how multiple writes to the same key may return errors by forcing concurrent writes within a single Worker invocation. This is not a pattern that should be used in production.

```typescript
export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Rest of code omitted
		const key = "common-key";
		const parallelWritesCount = 20;

		// Helper function to attempt a write to KV and handle errors
		const attemptWrite = async (i: number) => {
			try {
				await env. YOUR_KV_NAMESPACE.put(key, `Write attempt #${i}`);
				return { attempt: i, success: true };
			} catch (error) {
				// An error may be thrown if a write to the same key is made within 1 second with a message. For example:
				// error: {
				//	"message": "KV PUT failed: 429 Too Many Requests"
				// }

				return {
					attempt: i,
					success: false,
					error: { message: (error as Error).message },
				};
			}
		};

		// Send all requests in parallel and collect results
		const results = await Promise.all(
			Array.from({ length: parallelWritesCount }, (_, i) =>
				attemptWrite(i + 1),
			),
		);
		// Results will look like:
		// [
		// 	  {
		// 		  "attempt": 1,
		// 		  "success": true
		// 	  },
		//    {
		// 		  "attempt": 2,
		// 		  "success": false,
		// 		  "error": {
		// 			  "message": "KV PUT failed: 429 Too Many Requests"
		// 		  }
		// 	  },
		// 	  ...
		// ]

		return new Response(JSON.stringify(results), {
			headers: { "Content-Type": "application/json" },
		});
	},
};
```

To handle these errors, we recommend implementing a retry logic, with exponential backoff. Here is a simple approach to add retries to the above code.

```typescript
export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Rest of code omitted
		const key = "common-key";
		const parallelWritesCount = 20;

		// Helper function to attempt a write to KV with retries
		const attemptWrite = async (i: number) => {
			return await retryWithBackoff(async () => {
				await env.YOUR_KV_NAMESPACE.put(key, `Write attempt #${i}`);
				return { attempt: i, success: true };
			});
		};

		// Send all requests in parallel and collect results
		const results = await Promise.all(
			Array.from({ length: parallelWritesCount }, (_, i) =>
				attemptWrite(i + 1),
			),
		);

		return new Response(JSON.stringify(results), {
			headers: { "Content-Type": "application/json" },
		});
	},
};

async function retryWithBackoff(
	fn: Function,
	maxAttempts = 5,
	initialDelay = 1000,
) {
	let attempts = 0;
	let delay = initialDelay;

	while (attempts < maxAttempts) {
		try {
			// Attempt the function
			return await fn();
		} catch (error) {
			// Check if the error is a rate limit error
			if (
				(error as Error).message.includes(
					"KV PUT failed: 429 Too Many Requests",
				)
			) {
				attempts++;
				if (attempts >= maxAttempts) {
					throw new Error("Max retry attempts reached");
				}

				// Wait for the backoff period
				console.warn(`Attempt ${attempts} failed. Retrying in ${delay} ms...`);
				await new Promise((resolve) => setTimeout(resolve, delay));

				// Exponential backoff
				delay *= 2;
			} else {
				// If it's a different error, rethrow it
				throw error;
			}
		}
	}
}
```

## Other methods to access KV

You can also [write key-value pairs from the command line with Wrangler](/kv/reference/kv-commands/#kv-namespace-create) and [write data via the REST API](/api/resources/kv/subresources/namespaces/subresources/values/methods/update/).

---

# Read key-value pairs

URL: https://developers.cloudflare.com/kv/api/read-key-value-pairs/

To get the value for a given key, call the `get()` method of the [KV binding](/kv/concepts/kv-bindings/) on any [KV namespace](/kv/concepts/kv-namespaces/) you have bound to your Worker code:

```js
// Read individual key
env.NAMESPACE.get(key);

// Read multiple keys
env.NAMESPACE.get(keys);
```

The `get()` method returns a promise you can `await` on to get the value.

If you request a single key as a string, you will get a single response in the promise. If the key is not found, the promise will resolve with the literal value `null`.

You can also request an array of keys. The return value with be a `Map` of the key-value pairs found,
with keys not found having `null` values.

```js
export default {
	async fetch(request, env, ctx) {
		try {
			// Read single key, returns value or null
			const value = await env.NAMESPACE.get("first-key");

			// Read multiple keys, returns Map of values
			const values = await env.NAMESPACE.get(["first-key", "second-key"]);

			// Read single key with metadata, returns value or null
			const valueWithMetadata = await env.NAMESPACE.getWithMetadata("first-key");

			// Read multiple keys with metadata, returns Map of values
			const valuesWithMetadata = await env.NAMESPACE.getWithMetadata(["first-key", "second-key"]);

			return new Response({
				value: value,
				values: Object.fromEntries(values),
				valueWithMetadata: valueWithMetadata,
				valuesWithMetadata: Object.fromEntries(valuesWithMetadata)
			});
		} catch (e) {
			return new Response(e.message, { status: 500 });
		}
	},
};
```

:::note

`get()` and `getWithMetadata()` methods may return stale values. If a given key has recently been read in a given location, writes or updates to the key made in other locations may take up to 60 seconds (or the duration of the `cacheTtl`) to display.

:::


## Reference

The following methods are provided to read from KV:

- [get()](#request-a-single-key-with-getkey-string)
- [getWithMetadata()](#request-multiple-keys-with-getkeys-string)

### `get()` method

Use the `get()` method to get a single value, or multiple values if given multiple keys:

- Read single keys with [get(key: string)](#request-a-single-key-with-getkey-string)
- Read multiple keys with [get(keys: string[])](#request-multiple-keys-with-getkeys-string)

#### Request a single key with `get(key: string)`

To get the value for a single key, call the `get()` method on any KV namespace you have bound to your Worker code with:

```js
env.NAMESPACE.get(key, type?);
// OR
env.NAMESPACE.get(key, options?);
```

##### Parameters

- `key`: `string`
  - The key of the KV pair.
- `type`: `"text" | "json" | "arrayBuffer" | "stream"`
  - Optional. The type of the value to be returned. `text` is the default.
- `options`: `{
    cacheTtl?: number,
    type?: "text" | "json" | "arrayBuffer" | "stream"
}`
  - Optional. Object containing the optional `cacheTtl` and `type` properties. The `cacheTtl` property defines the length of time in seconds that a KV result is cached in the global network location it is accessed from (minimum: 60). The `type` property defines the type of the value to be returned.

##### Response

- `response`: `Promise<string | Object | ArrayBuffer | ReadableStream | null>`
  - The value for the requested KV pair. The response type will depend on the `type` parameter provided for the `get()` command as follows:
    - `text`: A `string` (default).
    - `json`: An object decoded from a JSON string.
    - `arrayBuffer`: An [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) instance.
    - `stream`: A [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).

#### Request multiple keys with `get(keys: string[])`

To get the values for multiple keys, call the `get()` method on any KV namespace you have bound to your Worker code with:

```js
env.NAMESPACE.get(keys, type?);
// OR
env.NAMESPACE.get(keys, options?);
```

##### Parameters

- `keys`: `string[]`
  - The keys of the KV pairs. Max: 100 keys
- `type`: `"text" | "json"`
  - Optional. The type of the value to be returned. `text` is the default.
- `options`: `{
    cacheTtl?: number,
    type?: "text" | "json"
}`
  - Optional. Object containing the optional `cacheTtl` and `type` properties. The `cacheTtl` property defines the length of time in seconds that a KV result is cached in the global network location it is accessed from (minimum: 60). The `type` property defines the type of the value to be returned.

:::note

The `.get()` function to read multiple keys does not support `arrayBuffer` or `stream` return types. If you need to read multiple keys of `arrayBuffer` or `stream` types, consider using the `.get()` function to read individual keys in parallel with `Promise.all()`.

:::

##### Response

- `response`: `Promise<Map<string, string | Object | null>>`
  - The value for the requested KV pair. If no key is found, `null` is returned for the key. The response type will depend on the `type` parameter provided for the `get()` command as follows:
    - `text`: A `string` (default).
    - `json`: An object decoded from a JSON string.

The limit of the response size is 25 MB. Responses above this size will fail with a `413 Error` error message.

### `getWithMetadata()` method

Use the `getWithMetadata()` method to get a single value along with its metadata, or multiple values with their metadata:

- Read single keys with [getWithMetadata(key: string)](#request-a-single-key-with-getwithmetadatakey-string)
- Read multiple keys with [getWithMetadata(keys: string[])](#request-multiple-keys-with-getwithmetadatakeys-string)

#### Request a single key with `getWithMetadata(key: string)`

To get the value for a given key along with its metadata, call the `getWithMetadata()` method on any KV namespace you have bound to your Worker code:

```js
env.NAMESPACE.getWithMetadata(key, type?);
// OR
env.NAMESPACE.getWithMetadata(key, options?);
```

Metadata is a serializable value you append to each KV entry.

##### Parameters

- `key`: `string`
  - The key of the KV pair.
- `type`: `"text" | "json" | "arrayBuffer" | "stream"`
  - Optional. The type of the value to be returned. `text` is the default.
- `options`: `{
    cacheTtl?: number,
    type?: "text" | "json" | "arrayBuffer" | "stream"
}`
  - Optional. Object containing the optional `cacheTtl` and `type` properties. The `cacheTtl` property defines the length of time in seconds that a KV result is cached in the global network location it is accessed from (minimum: 60). The `type` property defines the type of the value to be returned.

##### Response

- `response`: `Promise<{
value: string | Object | ArrayBuffer | ReadableStream | null,
metadata: string | null
}>`

  - An object containing the value and the metadata for the requested KV pair. The type of the value attribute will depend on the `type` parameter provided for the `getWithMetadata()` command as follows:
    - `text`: A `string` (default).
    - `json`: An object decoded from a JSON string.
    - `arrayBuffer`: An [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) instance.
    - `stream`: A [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).

If there is no metadata associated with the requested key-value pair, `null` will be returned for metadata.

#### Request multiple keys with `getWithMetadata(keys: string[])`

To get the values for a given set of keys along with their metadata, call the `getWithMetadata()` method on any KV namespace you have bound to your Worker code with:

```js
env.NAMESPACE.getWithMetadata(keys, type?);
// OR
env.NAMESPACE.getWithMetadata(keys, options?);
```

##### Parameters

- `keys`: `string[]`
  - The keys of the KV pairs. Max: 100 keys
- `type`: `"text" | "json"`
  - Optional. The type of the value to be returned. `text` is the default.
- `options`: `{
    cacheTtl?: number,
    type?: "text" | "json"
}`
  - Optional. Object containing the optional `cacheTtl` and `type` properties. The `cacheTtl` property defines the length of time in seconds that a KV result is cached in the global network location it is accessed from (minimum: 60). The `type` property defines the type of the value to be returned.

:::note
The `.get()` function to read multiple keys does not support `arrayBuffer` or `stream` return types. If you need to read multiple keys of `arrayBuffer` or `stream` types, consider using the `.get()` function to read individual keys in parallel with `Promise.all()`.
:::

##### Response

- `response`: `Promise<Map<string, {
value: string | Object | null,
metadata: string | Object | null
}>`

  - An object containing the value and the metadata for the requested KV pair. The type of the value attribute will depend on the `type` parameter provided for the `getWithMetadata()` command as follows:
    - `text`: A `string` (default).
    - `json`: An object decoded from a JSON string.
  - The type of the metadata will just depend on what is stored, which can be either a string or an object.

If there is no metadata associated with the requested key-value pair, `null` will be returned for metadata.

The limit of the response size is 25 MB. Responses above this size will fail with a `413 Error` error message.

## Guidance

### Type parameter

For simple values, use the default `text` type which provides you with your value as a `string`. For convenience, a `json` type is also specified which will convert a JSON value into an object before returning the object to you. For large values, use `stream` to request a `ReadableStream`. For binary values, use `arrayBuffer` to request an `ArrayBuffer`.

For large values, the choice of `type` can have a noticeable effect on latency and CPU usage. For reference, the `type` can be ordered from fastest to slowest as `stream`, `arrayBuffer`, `text`, and `json`.

### CacheTtl parameter

`cacheTtl` is a parameter that defines the length of time in seconds that a KV result is cached in the global network location it is accessed from.

Defining the length of time in seconds is useful for reducing cold read latency on keys that are read relatively infrequently. `cacheTtl` is useful if your data is write-once or write-rarely.

:::note[Hot and cold read]

A hot read means that the data is cached on Cloudflare's edge network using the [CDN](https://developers.cloudflare.com/cache/), whether it is in a local cache or a regional cache. A cold read means that the data is not cached, so the data must be fetched from the central stores. Both existing key-value pairs and non-existent key-value pairs (also known as negative lookups) are cached at the edge.
:::

`cacheTtl` is not recommended if your data is updated often and you need to see updates shortly after they are written, because writes that happen from other global network locations will not be visible until the cached value expires.

The `cacheTtl` parameter must be an integer greater than or equal to `60`, which is the default.

The effective `cacheTtl` of an already cached item can be reduced by getting it again with a lower `cacheTtl`. For example, if you did `NAMESPACE.get(key, {cacheTtl: 86400})` but later realized that caching for 24 hours was too long, you could `NAMESPACE.get(key, {cacheTtl: 300})` or even `NAMESPACE.get(key)` and it would check for newer data to respect the provided `cacheTtl`, which defaults to 60 seconds.

### Requesting more keys per Worker invocation with bulk requests

Workers are limited to 1,000 operations to external services per invocation. This applies to Workers KV, as documented in [Workers KV limits](/kv/platform/limits/).

To read more than 1,000 keys per operation, you can use the bulk read operations to read multiple keys in a single operation. These count as a single operation against the 1,000 operation limit.

### Reducing cardinality by coalescing keys

If you have a set of related key-value pairs that have a mixed usage pattern (some hot keys and some cold keys), consider coalescing them. By coalescing cold keys with hot keys, cold keys will be cached alongside hot keys which can provide faster reads than if they were uncached as individual keys.

#### Merging into a "super" KV entry

One coalescing technique is to make all the keys and values part of a super key-value object. An example is shown below.

```
key1: value1
key2: value2
key3: value3
```

becomes

```
coalesced: {
  key1: value1,
  key2: value2,
  key3: value3,
}
```

By coalescing the values, the cold keys benefit from being kept warm in the cache because of access patterns of the warmer keys.

This works best if you are not expecting the need to update the values independently of each other, which can pose race conditions.

- **Advantage**: Infrequently accessed keys are kept in the cache.
- **Disadvantage**: Size of the resultant value can push your worker out of its memory limits. Safely updating the value requires a [locking mechanism](/kv/api/write-key-value-pairs/#concurrent-writes-to-the-same-key) of some kind.


## Other methods to access KV

You can [read key-value pairs from the command line with Wrangler](/kv/reference/kv-commands/#kv-key-get) and [from the REST API](/api/resources/kv/subresources/namespaces/subresources/values/methods/get/).

---

# Key concepts

URL: https://developers.cloudflare.com/kv/concepts/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# How KV works

URL: https://developers.cloudflare.com/kv/concepts/how-kv-works/

KV is a global, low-latency, key-value data store. It stores data in a small number of centralized data centers, then caches that data in Cloudflare's data centers after access.

KV supports exceptionally high read volumes with low latency, making it possible to build dynamic APIs that scale thanks to KV's built-in caching and global distribution.
Requests which are not in cache and need to access the central stores can experience higher latencies.

## Write data to KV and read data from KV

When you write to KV, your data is written to central data stores. Your data is not sent automatically to every location's cache.

![Your data is written to central data stores when you write to KV.](~/assets/images/kv/kv-write.svg)

Initial reads from a location do not have a cached value. Data must be read from the nearest regional tier, followed by a central tier, degrading finally to the central stores for a truly cold global read. While the first access is slow globally, subsequent requests are faster, especially if requests are concentrated in a single region.

:::note[Hot and cold read]

A hot read means that the data is cached on Cloudflare's edge network using the [CDN](https://developers.cloudflare.com/cache/), whether it is in a local cache or a regional cache. A cold read means that the data is not cached, so the data must be fetched from the central stores.
:::

![Initial reads will miss the cache and go to the nearest central data store first.](~/assets/images/kv/kv-slow-read.svg)

Frequent reads from the same location return the cached value without reading from anywhere else, resulting in the fastest response times. KV operates diligently to update the cached values by refreshing from upper tier caches and central data stores before cache expires in the background.

Refreshing from upper tiers and the central data stores in the background is done carefully so that assets that are being accessed continue to be kept served from the cache without any stalls.

![As mentioned above, frequent reads will return a cached value.](~/assets/images/kv/kv-fast-read.svg)

KV is optimized for high-read applications. It stores data centrally and uses a hybrid push/pull-based replication to store data in cache. KV is suitable for use cases where you need to write relatively infrequently, but read quickly and frequently. Infrequently read values are pulled from other data centers or the central stores, while more popular values are cached in the data centers they are requested from.

## Performance

To improve KV performance, increase the [`cacheTtl` parameter](/kv/api/read-key-value-pairs/#cachettl-parameter) up from its default 60 seconds.

KV achieves high performance by [caching](https://www.cloudflare.com/en-gb/learning/cdn/what-is-caching/) which makes reads eventually-consistent with writes.

Changes are usually immediately visible in the Cloudflare global network location at which they are made. Changes may take up to 60 seconds or more to be visible in other global network locations as their cached versions of the data time out.

Negative lookups indicating that the key does not exist are also cached, so the same delay exists noticing a value is created as when a value is changed.

## Consistency

KV achieves high performance by being eventually-consistent. At the Cloudflare global network location at which changes are made, these changes are usually immediately visible. However, this is not guaranteed and therefore it is not advised to rely on this behaviour. In other global network locations changes may take up to 60 seconds or more to be visible as their cached versions of the data time-out.

Visibility of changes takes longer in locations which have recently read a previous version of a given key (including reads that indicated the key did not exist, which are also cached locally).

:::note

KV is not ideal for applications where you need support for atomic operations or where values must be read and written in a single transaction.
If you need stronger consistency guarantees, consider using [Durable Objects](/durable-objects/).
:::

An approach to achieve write-after-write consistency is to send all of your writes for a given KV key through a corresponding instance of a Durable Object, and then read that value from KV in other Workers. This is useful if you need more control over writes, but are satisfied with KV's read characteristics described above.

## Guidance

Workers KV is an eventually-consistent edge key-value store. That makes it ideal for **read-heavy**, highly cacheable workloads such as:

- Serving static assets
- Storing application configuration
- Storing user preferences
- Implementing allow-lists/deny-lists
- Caching

In these scenarios, Workers are invoked in a data center closest to the user and Workers KV data will be cached in that region for subsequent requests to minimize latency.

If you have a **write-heavy** [Redis](https://redis.io)-type workload where you are updating the same key tens or hundreds of times per second, KV will not be an ideal fit.
If you can revisit how your application writes to single key-value pairs and spread your writes across several discrete keys, Workers KV can suit your needs.
Alternatively, [Durable Objects](/durable-objects/) provides a key-value API with higher writes per key rate limits.

## Security

Refer to [Data security documentation](/kv/reference/data-security/) to understand how Workers KV secures data.

---

# KV bindings

URL: https://developers.cloudflare.com/kv/concepts/kv-bindings/

import { WranglerConfig } from "~/components";

KV [bindings](/workers/runtime-apis/bindings/) allow for communication between a Worker and a KV namespace.

Configure KV bindings in the [Wrangler configuration file](/workers/wrangler/configuration/).

## Access KV from Workers

A [KV namespace](/kv/concepts/kv-namespaces/) is a key-value database replicated to Cloudflare's global network.

To connect to a KV namespace from within a Worker, you must define a binding that points to the namespace's ID.

The name of your binding does not need to match the KV namespace's name. Instead, the binding should be a valid JavaScript identifier, because the identifier will exist as a global variable within your Worker.

A KV namespace will have a name you choose (for example, `My tasks`), and an assigned ID (for example, `06779da6940b431db6e566b4846d64db`).

To execute your Worker, define the binding.

In the following example, the binding is called `TODO`. In the `kv_namespaces` portion of your Wrangler configuration file, add:

<WranglerConfig>

```toml
name = "worker"

# ...

kv_namespaces = [
  { binding = "TODO", id = "06779da6940b431db6e566b4846d64db" }
]
```

</WranglerConfig>

With this, the deployed Worker will have a `TODO` field in their environment object (the second parameter of the `fetch()` request handler). Any methods on the `TODO` binding will map to the KV namespace with an ID of `06779da6940b431db6e566b4846d64db` – which you called `My Tasks` earlier.

```js
export default {
	async fetch(request, env, ctx) {
		// Get the value for the "to-do:123" key
		// NOTE: Relies on the `TODO` KV binding that maps to the "My Tasks" namespace.
		let value = await env.TODO.get("to-do:123");

		// Return the value, as is, for the Response
		return new Response(value);
	},
};
```

## Use KV bindings when developing locally

When you use Wrangler to develop locally with the `wrangler dev` command, Wrangler will default to using a local version of KV to avoid interfering with any of your live production data in KV. This means that reading keys that you have not written locally will return `null`.

To have `wrangler dev` connect to your Workers KV namespace running on Cloudflare's global network, call `wrangler dev --remote` instead. This will use the `preview_id` of the KV binding configuration in the Wrangler file. This is how a Wrangler file looks with the `preview_id` specified.



<WranglerConfig>

```toml title="wrangler.toml"
name = "worker"

# ...

kv_namespaces = [
  { binding = "TODO", id = "06779da6940b431db6e566b4846d64db", preview_id="06779da6940b431db6e566b484a6a769a7a" }
]
```

</WranglerConfig>

## Access KV from Durable Objects and Workers using ES modules format

[Durable Objects](/durable-objects/) use ES modules format. Instead of a global variable, bindings are available as properties of the `env` parameter [passed to the constructor](/durable-objects/get-started/#2-write-a-durable-object-class).

An example might look like:

```js
export class DurableObject {
	constructor(state, env) {
		this.state = state;
		this.env = env;
	}

	async fetch(request) {
		const valueFromKV = await this.env.NAMESPACE.get("someKey");
		return new Response(valueFromKV);
	}
}
```

---

# KV namespaces

URL: https://developers.cloudflare.com/kv/concepts/kv-namespaces/

import { Type, MetaInfo, WranglerConfig } from "~/components";

A KV namespace is a key-value database replicated to Cloudflare’s global network.

Bind your KV namespaces through Wrangler or via the Cloudflare dashboard.

:::note

KV namespace IDs are public and bound to your account.

:::

## Bind your KV namespace through Wrangler

To bind KV namespaces to your Worker, assign an array of the below object to the `kv_namespaces` key.

* `binding` <Type text="string" /> <MetaInfo text="required" />

  * The binding name used to refer to the KV namespace.

* `id` <Type text="string" /> <MetaInfo text="required" />

  * The ID of the KV namespace.

* `preview_id` <Type text="string" /> <MetaInfo text="optional" />

  * The ID of the KV namespace used during `wrangler dev`.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
kv_namespaces = [
  { binding = "<TEST_NAMESPACE>", id = "<TEST_ID>" }
]
```

</WranglerConfig>

## Bind your KV namespace via the dashboard

To bind the namespace to your Worker in the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com).
2. Go to **Workers & Pages**.
3. Select your **Worker**.
4. Select **Settings** > **Bindings**.
5. Select **Add**.
6. Select **KV Namespace**.
7. Enter your desired variable name (the name of the binding).
8. Select the KV namespace you wish to bind the Worker to.
9. Select **Deploy**.

---

# Cache data with Workers KV

URL: https://developers.cloudflare.com/kv/examples/cache-data-with-workers-kv/

import { Render, PackageManagers, Tabs, TabItem } from "~/components";

Workers KV can be used as a persistent, single, global cache accessible from Cloudflare Workers to speed up your application.
Data cached in Workers KV is accessible from all other Cloudflare locations as well, and persists until expiry or deletion.

After fetching data from external resources in your Workers application, you can write the data to Workers KV.
On subsequent Worker requests (in the same region or in other regions), you can read the cached data from Workers KV instead of calling the external API.
This improves your Worker application's performance and resilience while reducing load on external resources.

This example shows how you can cache data in Workers KV and read cached data from Workers KV in a Worker application.

:::note[Note]

You can also cache data in Workers with the [Cache API](/workers/runtime-apis/cache/). With the Cache API,
the contents of the cache do not replicate outside of the originating data center and the cache is ephemeral (can be evicted).

With Workers KV, the data is persisted by default to [central stores](/kv/concepts/how-kv-works/) (or can be set to [expire](/kv/api/write-key-value-pairs/#expiring-keys), and can be accessed from other Cloudflare locations.
:::

## Cache data in Workers KV from your Worker application

In the following `index.ts` file, the Worker fetches data from an external server and caches the response in Workers KV. If the data is already cached in Workers KV, the Worker reads the cached data from Workers KV instead of calling the external API.

<Tabs>
<TabItem label="index.ts">
```js title="index.ts" collapse={42-1000}
interface Env {
  CACHE_KV: KVNamespace;
}

export default {
  async fetch(request, env, ctx): Promise<Response> {

    const EXPIRATION_TTL = 60; // Cache expiration in seconds
    const url = 'https://example.com';
    const cacheKey = "cache-json-example";

    // Try to get data from KV cache first
    let data = await env.CACHE_KV.get(cacheKey, { type: 'json' });
    let fromCache = true;

    // If data is not in cache, fetch it from example.com
    if (!data) {
      console.log('Cache miss. Fetching fresh data from example.com');
      fromCache = false;

    		// In this example, we are fetching HTML content but it can also be API responses or any other data
      const response = await fetch(url);
    		const htmlData = await response.text();

    		// In this example, we are converting HTML to JSON to demonstrate caching JSON data with Workers KV
    		// You could cache any type of data, or even cache the HTML data directly
    		data = helperConvertToJSON(htmlData);
    		// The expirationTtl option is used to set the expiration time for the cache entry (in seconds), otherwise it will be stored indefinitely
    		await env.CACHE_KV.put(cacheKey, JSON.stringify(data), { expirationTtl: EXPIRATION_TTL });
    }

    // Return the appropriate response format
    	return new Response(JSON.stringify({
    		data,
    		fromCache
    	}), {
    		headers: { 'Content-Type': 'application/json' }
    	});

}
} satisfies ExportedHandler<Env>;

// Helper function to convert HTML to JSON
function helperConvertToJSON(html: string) {
// Parse HTML and extract relevant data
const title = helperExtractTitle(html);
const content = helperExtractContent(html);
const lastUpdated = new Date().toISOString();

    return { title, content, lastUpdated };

}

// Helper function to extract title from HTML
function helperExtractTitle(html: string) {
const titleMatch = html.match(/<title>(.\*?)<\/title>/i);
return titleMatch ? titleMatch[1] : 'No title found';
}

// Helper function to extract content from HTML
function helperExtractContent(html: string) {
const bodyMatch = html.match(/<body>(.\*?)<\/body>/is);
if (!bodyMatch) return 'No content found';

    // Strip HTML tags for a simple text representation
    const textContent = bodyMatch[1].replace(/<[^>]*>/g, ' ')
    	.replace(/\s+/g, ' ')
    	.trim();

    return textContent;

}

````
</TabItem>
<TabItem label="wrangler.jsonc">
```json
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<ENTER_WORKER_NAME>",
	"main": "src/index.ts",
	"compatibility_date": "2025-03-03",
	"observability": {
		"enabled": true
	},
	"kv_namespaces": [
		{
			"binding": "CACHE_KV",
			"id": "<YOUR_BINDING_ID>"
		}
	]
}
````

</TabItem>
</Tabs>

This code snippet demonstrates how to read and update cached data in Workers KV from your Worker.
If the data is not in the Workers KV cache, the Worker fetches the data from an external server and caches it in Workers KV.

In this example, we convert HTML to JSON to demonstrate how to cache JSON data with Workers KV, but any type of data
can be cached in Workers KV. For instance, you could cache API responses, HTML content, or any other data that you want to persist across requests.

## Related resources

- [Rust support in Workers](/workers/languages/rust/).
- [Using KV in Workers](/kv/get-started/).

---

# Examples

URL: https://developers.cloudflare.com/kv/examples/

import { GlossaryTooltip, ListExamples } from "~/components";

Explore the following <GlossaryTooltip term="code example">examples</GlossaryTooltip> for KV.

<ListExamples directory="kv/examples/" />

---

# Build a distributed configuration store

URL: https://developers.cloudflare.com/kv/examples/distributed-configuration-with-workers-kv/

import { Render, PackageManagers, Tabs, TabItem } from "~/components";

Storing application configuration data is an ideal use case for Workers KV. Configuration data can include data to personalize an application for each user or tenant, enable features for user groups, restrict access with allow-lists/deny-lists, etc. These use-cases can have high read volumes that are highly cacheable by Workers KV, which can ensure low-latency reads from your Workers application.

In this example, application configuration data is used to personalize the Workers application for each user. The configuration data is stored in an external application and database, and written to Workers KV using the REST API.

## Write your configuration from your external application to Workers KV

In some cases, your source-of-truth for your configuration data may be stored elsewhere than Workers KV.
If this is the case, use the Workers KV REST API to write the configuration data to your Workers KV namespace.

The following external Node.js application demonstrates a simple scripts that reads user data from a database and writes it to Workers KV using the REST API library.

<Tabs>
<TabItem label="index.js">
```js title="index.js"
const postgres = require('postgres');
const { Cloudflare } = require('cloudflare');
const { backOff } = require('exponential-backoff');

if(!process.env.DATABASE_CONNECTION_STRING || !process.env.CLOUDFLARE_EMAIL || !process.env.CLOUDFLARE_API_KEY || !process.env.CLOUDFLARE_WORKERS_KV_NAMESPACE_ID || !process.env.CLOUDFLARE_ACCOUNT_ID) {
console.error('Missing required environment variables.');
process.exit(1);
}

// Setup Postgres connection
const sql = postgres(process.env.DATABASE_CONNECTION_STRING);

// Setup Cloudflare REST API client
const client = new Cloudflare({
apiEmail: process.env.CLOUDFLARE_EMAIL,
apiKey: process.env.CLOUDFLARE_API_KEY,
});

// Function to sync Postgres data to Workers KV
async function syncPreviewStatus() {
console.log('Starting sync of user preview status...');

    try {
    	// Get all users and their preview status
    	const users = await sql`SELECT id, preview_features_enabled FROM users`;

    	console.log(users);

    	// Create the bulk update body
    	const bulkUpdateBody = users.map(user => ({
    		key: user.id,
    		value: JSON.stringify({
    			preview_features_enabled: user.preview_features_enabled
    		})
    	}));

    	const response = await backOff(async () => {
    		console.log("trying to update")
    		try{
    			const response = await client.kv.namespaces.bulkUpdate(process.env.CLOUDFLARE_WORKERS_KV_NAMESPACE_ID, {
    				account_id: process.env.CLOUDFLARE_ACCOUNT_ID,
    				body: bulkUpdateBody
    			});
    		}
    		catch(e){
    			// Implement your error handling and logging here
    			console.log(e);
    			throw e; // Rethrow the error to retry
    		}
    	});

    	console.log(`Sync complete. Updated ${users.length} users.`);
    } catch (error) {
    	console.error('Error syncing preview status:', error);
    }

}

// Run the sync function
syncPreviewStatus()
.catch(console.error)
.finally(() => process.exit(0));

````
</TabItem>
<TabItem label=".env">
```md title=".env"
DATABASE_CONNECTION_STRING = <DB_CONNECTION_STRING_HERE>
CLOUDFLARE_EMAIL = <CLOUDFLARE_EMAIL_HERE>
CLOUDFLARE_API_KEY = <CLOUDFLARE_API_KEY_HERE>
CLOUDFLARE_ACCOUNT_ID = <CLOUDFLARE_ACCOUNT_ID_HERE>
CLOUDFLARE_WORKERS_KV_NAMESPACE_ID = <CLOUDFLARE_WORKERS_KV_NAMESPACE_ID_HERE>
````

</TabItem>
<TabItem label="db.sql">
```sql title="db.sql"
-- Create users table with preview_features_enabled flag
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  username VARCHAR(100) NOT NULL,
  email VARCHAR(255) NOT NULL,
  preview_features_enabled BOOLEAN DEFAULT false
);

-- Insert sample users
INSERT INTO users (username, email, preview_features_enabled) VALUES
('alice', 'alice@example.com', true),
('bob', 'bob@example.com', false),
('charlie', 'charlie@example.com', true);

````
</TabItem>
</Tabs>

In this code snippet, the Node.js application reads user data from a Postgres database and writes the user data to be used for configuration in our Workers application to Workers KV using the Cloudflare REST API Node.js library.
The application also uses exponential backoff to handle retries in case of errors.

## Use configuration data from Workers KV in your Worker application

With the configuration data now in the Workers KV namespace, we can use it in our Workers application to personalize the application for each user.

<Tabs>
<TabItem label="index.ts">
```js title="index.ts"
// Example configuration data stored in Workers KV:
// Key: "user-id-abc" | Value: {"preview_features_enabled": false}
// Key: "user-id-def" | Value: {"preview_features_enabled": true}

interface Env {
  USER_CONFIGURATION: KVNamespace;
}

export default {
  async fetch(request, env) {
    // Get user ID from query parameter
    const url = new URL(request.url);
    const userId = url.searchParams.get('userId');

    if (!userId) {
      return new Response('Please provide a userId query parameter', {
        status: 400,
        headers: { 'Content-Type': 'text/plain' }
      });
    }


		const userConfiguration = await env.USER_CONFIGURATION.get<{
			preview_features_enabled: boolean;
		}>(userId, {type: "json"});

		console.log(userConfiguration);

    // Build HTML response
    const html = `
      <!DOCTYPE html>
      <html>
        <head>
          <title>My App</title>
          <style>
            body {
              font-family: Arial, sans-serif;
              max-width: 800px;
              margin: 0 auto;
              padding: 20px;
            }
            .preview-banner {
              background-color: #ffeb3b;
              padding: 10px;
              text-align: center;
              margin-bottom: 20px;
              border-radius: 4px;
            }
          </style>
        </head>
        <body>
          ${userConfiguration?.preview_features_enabled ? `
            <div class="preview-banner">
              🎉 You have early access to preview features! 🎉
            </div>
          ` : ''}
          <h1>Welcome to My App</h1>
          <p>This is the regular content everyone sees.</p>
        </body>
      </html>
    `;

    return new Response(html, {
			headers: { "Content-Type": "text/html; charset=utf-8" }
    });
  }
} satisfies ExportedHandler<Env>;

```
</TabItem>
<TabItem label="wrangler.jsonc">
```json
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<ENTER_WORKER_NAME>",
	"main": "src/index.ts",
	"compatibility_date": "2025-03-03",
	"observability": {
		"enabled": true
	},
	"kv_namespaces": [
		{
			"binding": "USER_CONFIGURATION",
			"id": "<YOUR_BINDING_ID>"
		}
	]
}
````

</TabItem>
</Tabs>

This code will use the path within the URL and find the file associated to the path within the KV store. It also sets the proper MIME type in the response to inform the browser how to handle the response. To retrieve the value from the KV store, this code uses `arrayBuffer` to properly handle binary data such as images, documents, and video/audio files.

## Optimize performance for configuration

To optimize performance, you may opt to consolidate values in fewer key-value pairs. By doing so, you may benefit from higher caching efficiency and lower latency.

For example, instead of storing each user's configuration in a separate key-value pair, you may store all users' configurations in a single key-value pair. This approach may be suitable for use-cases where the configuration data is small and can be easily managed in a single key-value pair (the [size limit for a Workers KV value is 25 MiB](/kv/platform/limits/)).

## Related resources

- [Rust support in Workers](/workers/languages/rust/)
- [Using KV in Workers](/kv/get-started/)

---

# Route requests across various web servers

URL: https://developers.cloudflare.com/kv/examples/routing-with-workers-kv/

import { Render, PackageManagers, Tabs, TabItem } from "~/components";

Using Workers KV to store routing data to route requests across various web servers with Workers is an ideal use case for Workers KV. Routing workloads can have high read volume, and Workers KV's low-latency reads can help ensure that routing decisions are made quickly and efficiently.

Routing can be helpful to route requests coming into a single Cloudflare Worker application to different web servers based on the request's path, hostname, or other request attributes.

In single-tenant applications, this can be used to route requests to various origin servers based on the business domain (for example, requests to `/admin` routed to administration server, `/store` routed to storefront server, `/api` routed to the API server).

In multi-tenant applications, requests can be routed to the tenant's respective origin resources (for example, requests to `tenantA.your-worker-hostname.com` routed to server for Tenant A, `tenantB.your-worker-hostname.com` routed to server for Tenant B).

Routing can also be used to implement [A/B testing](/reference-architecture/diagrams/serverless/a-b-testing-using-workers/), canary deployments, or [blue-green deployments](https://en.wikipedia.org/wiki/Blue%E2%80%93green_deployment) for your own external applications.
If you are looking to implement canary or blue-green deployments of applications built fully on Cloudflare Workers, see [Workers gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/).

## Route requests with Workers KV

In this example, a multi-tenant e-Commerce application is built on Cloudflare Workers. Each storefront is a different tenant and has its own external web server.
Our Cloudflare Worker is responsible for receiving all requests for all storefronts and routing requests to the correct origin web server according to the storefront ID.

For simplicity of demonstration, the storefront will be identified with a path element containing the storefront ID, where
`https://<WORKER_HOSTNAME>/<STOREFRONT_ID>/...` is the URL pattern for the storefront. You may prefer to use subdomains to identify storefronts in a real-world scenario.

<Tabs>
<TabItem label="index.ts">
```js title="index.ts" collapse={17-22, 34-39, 69-73}

// Example routing data stored in Workers KV:
// Key: "storefrontA" | Value: {"origin": "https://storefrontA-server.example.com"}
// Key: "storefrontB" | Value: {"origin": "https://storefrontB-server.example.com"}

interface Env {
ROUTING_CONFIG: KVNamespace;
}

export default {
  async fetch(request, env, ctx) {

    // Parse the URL to extract the storefront ID from the path
    const url = new URL(request.url);
    const pathParts = url.pathname.split('/').filter(part => part !== '');

    // Check if a storefront ID is provided in the path, otherwise return 400
    if (pathParts.length === 0) {
      return new Response('Welcome to our multi-tenant platform. Please specify a storefront ID in the URL path.', {
        status: 400,
        headers: { 'Content-Type': 'text/plain' }
      });
    }

    // Extract the storefront ID from the first path segment
    const storefrontId = pathParts[0];

    try {
      // Look up the storefront configuration in KV using env.ROUTING_CONFIG
      const storefrontConfig = await env.ROUTING_CONFIG.get<{
    			origin: string;
    		}>(storefrontId, {type: "json"});

      // If no configuration is found, return a 404
      if (!storefrontConfig) {
        return new Response(`Storefront "${storefrontId}" not found.`, {
          status: 404,
          headers: { 'Content-Type': 'text/plain' }
        });
      }

      // Construct the new URL for the origin server
      // Remove the storefront ID from the path when forwarding
      const newPathname = '/' + pathParts.slice(1).join('/');
      const originUrl = new URL(newPathname, storefrontConfig.origin);
      originUrl.search = url.search;

      // Create a new request to the origin server
      const originRequest = new Request(originUrl, {
        method: request.method,
        headers: request.headers,
        body: request.body,
        redirect: 'follow'
      });

      // Send the request to the origin server
      const response = await fetch(originRequest);

    		console.log(response.status)

      // Clone the response and add a custom header
      const modifiedResponse = new Response(response.body, response);
      modifiedResponse.headers.set('X-Served-By', 'Cloudflare Worker');
      modifiedResponse.headers.set('X-Storefront-ID', storefrontId);

      return modifiedResponse;

    } catch (error) {
      // Handle any errors
      console.error(`Error processing request for storefront ${storefrontId}:`, error);
      return new Response('An error occurred while processing your request.', {
        status: 500,
        headers: { 'Content-Type': 'text/plain' }
      });
    }

}
} satisfies ExportedHandler<Env>;

````
</TabItem>
<TabItem label="wrangler.jsonc">
```json
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<ENTER_WORKER_NAME>",
	"main": "src/index.ts",
	"compatibility_date": "2025-03-03",
	"observability": {
		"enabled": true
	},
	"kv_namespaces": [
		{
			"binding": "ROUTING_CONFIG",
			"id": "<YOUR_BINDING_ID>"
		}
	]
}
````

</TabItem>
</Tabs>

In this example, the Cloudflare Worker receives a request and extracts the storefront ID from the URL path.
The storefront ID is used to look up the origin server URL from Workers KV using the `get()` method.
The request is then forwarded to the origin server, and the response is modified to include custom headers before being returned to the client.

## Related resources

- [Rust support in Workers](/workers/languages/rust/).
- [Using KV in Workers](/kv/get-started/).

---

# Store and retrieve static assets

URL: https://developers.cloudflare.com/kv/examples/workers-kv-to-serve-assets/

import { Render, PackageManagers, TabItem, Tabs } from "~/components";

By storing static assets in Workers KV, you can retrieve these assets globally with low-latency and high throughput. You can then serve these assets directly, or use them to dynamically generate responses. This can be useful when serving files such as custom scripts, small images that fit within [KV limits](/kv/platform/limits/), or when generating dynamic HTML responses from static assets such as translations.

:::note[Note]
If you need to **host a front-end or full-stack web application**, **use [Cloudflare Workers static assets](/workers/static-assets/) or [Cloudflare Pages](/pages/)**, which provide a purpose-built deployment experience for web applications and their assets. 

[Workers KV](/kv/) provides a more flexible API which allows you to access, edit, and store assets directly from your [Worker](/workers/) without requiring deployments. This can be helpful for serving custom assets that are not included in your deployment bundle, such as uploaded media assets or custom scripts and files generated at runtime.
:::

## Write static assets to Workers KV using Wrangler

To store static assets in Workers KV, you can use the [Wrangler CLI](/workers/wrangler/) (commonly used during development), the [Workers KV binding](/kv/concepts/kv-bindings/) from a Workers application, or the [Workers KV REST API](/api/resources/kv/subresources/namespaces/methods/list/) (commonly used to access Workers KV from an external application). We will demonstrate how to use the Wrangler CLI.

For this scenario, we will store a sample HTML file within our Workers KV store.

Create a new file `index.html` with the following content:

```html title="index.html"
Hello World!
```

We can then use the following Wrangler commands to create a KV pair for this file within our production and preview namespaces:

```sh
npx wrangler kv key put index.html --path index.html --namespace-id=<ENTER_NAMESPACE_ID_HERE>
```

This will create a KV pair with the filename as key and the file content as value, within the our production and preview namespaces specified by your binding in your Wrangler file.

## Serve static assets from KV from your Worker application

In this example, our Workers application will accept any key name as the path of the HTTP request and return the value stored in the KV store for that key.

<Tabs>
<TabItem label="index.ts">
```js

import mime from "mime";

interface Env {
assets: KVNamespace;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Return error if not a get request
		if(request.method !== 'GET'){
			return new Response('Method Not Allowed', {
				status: 405,
			})
		}

    	// Get the key from the url & return error if key missing
    	const parsedUrl = new URL(request.url)
    	const key = parsedUrl.pathname.replace(/^\/+/, '') // Strip any preceding /'s
    	if(!key){
    		return new Response('Missing path in URL', {
    			status: 400
    		})
    	}

    	// Get the mimetype from the key path
    	const extension = key.split('.').pop();
    	let mimeType = mime.getType(key) || "text/plain";
    	if (mimeType.startsWith("text") || mimeType === "application/javascript") {
    		mimeType += "; charset=utf-8";
    	}

    	// Get the value from the Workers KV store and return it if found
    	const value = await env.assets.get(key, 'arrayBuffer')
    	if(!value){
    		return new Response("Not found", {
    			status: 404
    		})
    	}

    	// Return the response from the Workers application with the value from the KV store
    	return new Response(value, {
    		status: 200,
    		headers: new Headers({
    			"Content-Type": mimeType
    		})
    	});
    },

} satisfies ExportedHandler<Env>;

````
</TabItem>
<TabItem label="wrangler.jsonc">
```json
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<ENTER_WORKER_NAME>",
	"main": "src/index.ts",
	"compatibility_date": "2025-03-03",
	"observability": {
		"enabled": true
	},
	"kv_namespaces": [
		{
			"binding": "assets",
			"id": "<YOUR_BINDING_ID>"
		}
	]
}
````

</TabItem>
</Tabs>

This code parses the key name for the key-value pair to fetch from the HTTP request. Then, it determines the proper MIME type for the response to inform the browser how to handle the response.
To retrieve the value from the KV store, this code uses `arrayBuffer` to properly handle binary data such as images, documents, and video/audio files.

Given a sample key-value pair with key `index.html` with value containing some HTML content in our Workers KV namespace store, we can access our Workers application
at `https://<YOUR-WORKER-HOSTNAME>/index.html` to see the contents of the `index.html` file.

Try it out with an image or a document and you will see that this Worker is also properly serving those assets from KV.

## Generate dynamic responses from your key-value pairs

In addition to serving static assets, we can also generate dynamic HTML or API responses based on the values stored in our KV store.

1. Start by creating this file in the root of your project:

```json title="hello-world.json"
[
	{
		"language_code": "en",
		"message": "Hello World!"
	},
	{
		"language_code": "es",
		"message": "¡Hola Mundo!"
	},
	{
		"language_code": "fr",
		"message": "Bonjour le monde!"
	},
	{
		"language_code": "de",
		"message": "Hallo Welt!"
	},
	{
		"language_code": "zh",
		"message": "你好，世界！"
	},
	{
		"language_code": "ja",
		"message": "こんにちは、世界！"
	},
	{
		"language_code": "hi",
		"message": "नमस्ते दुनिया!"
	},
	{
		"language_code": "ar",
		"message": "مرحبا بالعالم!"
	}
]
```

2. Open a terminal and enter the following KV command to create a KV entry for the translations file:

```sh
npx wrangler kv key put hello-world.json --path hello-world.json --namespace-id=<ENTER_NAMESPACE_ID_HERE>
```

3. Update your Workers code to add logic to serve a translated HTML file based on the language of the Accept-Language header of the request:

<Tabs>
<TabItem label="index.ts">
```js {2, 26-63}
import mime from 'mime';
import parser from 'accept-language-parser'

interface Env {
assets: KVNamespace;
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    // Return error if not a get request
    if(request.method !== 'GET'){
      return new Response('Method Not Allowed', {
        status: 405,
      })
    }

    // Get the key from the url & return error if key missing
    const parsedUrl = new URL(request.url)
    const key = parsedUrl.pathname.replace(/^\/+/, '') // Strip any preceding /'s
    if(!key){
      return new Response('Missing path in URL', {
        status: 400
      })
    }

    	// Add handler for translation path (with early return)
    	if(key === 'hello-world'){
    		// Retrieve the language header from the request and the translations from Workers KV
    		const languageHeader = request.headers.get('Accept-Language') || 'en' // Default to English
    		const translations : {
    			"language_code": string,
    			"message": string
    		}[] = await env.assets.get('hello-world.json', 'json') || [];

    		// Extract the requested language
    		const supportedLanguageCodes = translations.map(item => item.language_code)
    		const languageCode = parser.pick(supportedLanguageCodes, languageHeader, {
    			loose: true
    		})

    		// Get the message for the selected language
    		let selectedTranslation = translations.find(item => item.language_code === languageCode)
    		if(!selectedTranslation) selectedTranslation = translations.find(item => item.language_code === "en")
    		const helloWorldTranslated = selectedTranslation!['message'];

    		// Generate and return the translated html
    		const html = `<!DOCTYPE html>
    		<html>
    			<head>
    				<title>Hello World translation</title>
    			</head>
    			<body>
    				<h1>${helloWorldTranslated}</h1>
    			</body>
    		</html>
    		`
    		return new Response(html, {
    			status: 200,
    			headers: {
    				'Content-Type': 'text/html; charset=utf-8'
    			}
    		})
    	}

    // Get the mimetype from the key path
    const extension = key.split('.').pop();
    let mimeType = mime.getType(key) || "text/plain";
    if (mimeType.startsWith("text") || mimeType === "application/javascript") {
      mimeType += "; charset=utf-8";
    }

    // Get the value from the Workers KV store and return it if found
    const value = await env.assets.get(key, 'arrayBuffer')
    if(!value){
      return new Response("Not found", {
        status: 404
      })
    }

    // Return the response from the Workers application with the value from the KV store
    return new Response(value, {
      status: 200,
      headers: new Headers({
        "Content-Type": mimeType
      })
    });

},
} satisfies ExportedHandler<Env>;

````
</TabItem>
<TabItem label="wrangler.jsonc">
```json
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "<ENTER_WORKER_NAME>",
	"main": "src/index.ts",
	"compatibility_date": "2025-03-03",
	"observability": {
		"enabled": true
	},
	"kv_namespaces": [
		{
			"binding": "assets",
			"id": "<YOUR_BINDING_ID>"
		}
	]
}
````

</TabItem>
</Tabs>

This new code provides a specific endpoint, `/hello-world`, which will provide translated responses. When this URL is accessed, our Worker code will first retrieve the language that is requested by the client in the `Accept-Language` request header and the translations from our KV store for the `hello-world.json` key. It then gets the translated message and returns the generated HTML.

When accessing the Worker application at `https://<YOUR-WORKER-HOSTNAME>/hello-world`, we can notice that our application is now returning the properly translated "Hello World" message.

From your browser's developer console, change the locale language (on Chromium browsers, Run `Show Sensors` to get a dropdown selection for locales). You will see that the Worker is now returning the translated message based on the locale language.

## Related resources

- [Rust support in Workers](/workers/languages/rust/).
- [Using KV in Workers](/kv/get-started/).

---

# Observability

URL: https://developers.cloudflare.com/kv/observability/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Platform

URL: https://developers.cloudflare.com/kv/platform/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Metrics and analytics

URL: https://developers.cloudflare.com/kv/observability/metrics-analytics/

KV exposes analytics that allow you to inspect requests and storage across all namespaces in your account.

The metrics displayed in the [Cloudflare dashboard](https://dash.cloudflare.com/) charts are queried from Cloudflare’s [GraphQL Analytics API](/analytics/graphql-api/). You can access the metrics [programmatically](#query-via-the-graphql-api) via GraphQL or HTTP client.

## Metrics

KV currently exposes the below metrics:

| Dataset    | GraphQL Dataset Name         | Description                                                         |
| ---------- | ---------------------------- | ------------------------------------------------------------------- |
| Operations | `kvOperationsAdaptiveGroups` | This dataset consists of the operations made to your KV namespaces. |
| Storage    | `kvStorageAdaptiveGroups`    | This dataset consists of the storage details of your KV namespaces. |

Metrics can be queried (and are retained) for the past 31 days.

## View metrics in the dashboard

Per-namespace analytics for KV are available in the Cloudflare dashboard. To view current and historical metrics for a database:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to [**Workers & Pages** > **KV**](https://dash.cloudflare.com/?to=/:account/workers/kv/namespaces).
3. Select an existing namespace.
4. Select the **Metrics** tab.

You can optionally select a time window to query. This defaults to the last 24 hours.

## Query via the GraphQL API

You can programmatically query analytics for your KV namespaces via the [GraphQL Analytics API](/analytics/graphql-api/). This API queries the same datasets as the Cloudflare dashboard, and supports GraphQL [introspection](/analytics/graphql-api/features/discovery/introspection/).

To get started using the [GraphQL Analytics API](/analytics/graphql-api/), follow the documentation to setup [Authentication for the GraphQL Analytics API](/analytics/graphql-api/getting-started/authentication/).

To use the GraphQL API to retrieve KV's datasets, you must provide the `accountTag` filter with your Cloudflare Account ID. The GraphQL datasets for KV include:

- `kvOperationsAdaptiveGroups`
- `kvStorageAdaptiveGroups`

### Examples

The following are common GraphQL queries that you can use to retrieve information about KV analytics. These queries make use of variables `$accountTag`, `$date_geq`, `$date_leq`, and `$namespaceId`, which should be set as GraphQL variables or replaced in line. These variables should look similar to these:

```json
{
	"accountTag": "<YOUR_ACCOUNT_ID>",
	"namespaceId": "<YOUR_KV_NAMESPACE_ID>",
	"date_geq": "2024-07-15",
	"date_leq": "2024-07-30"
}
```

#### Operations

To query the sum of read, write, delete, and list operations for a given `namespaceId` and for a given date range (`start` and `end`), grouped by `date` and `actionType`:

```graphql graphql-api-explorer
query KvOperationsSample(
	$accountTag: string!
	$namespaceId: string
	$start: Date
	$end: Date
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			kvOperationsAdaptiveGroups(
				filter: { namespaceId: $namespaceId, date_geq: $start, date_leq: $end }
				limit: 10000
				orderBy: [date_DESC]
			) {
				sum {
					requests
				}
				dimensions {
					date
					actionType
				}
			}
		}
	}
}
```

To query the distribution of the latency for read operations for a given `namespaceId` within a given date range (`start`, `end`):

```graphql graphql-api-explorer
query KvOperationsSample2(
	$accountTag: string!
	$namespaceId: string
	$start: Date
	$end: Date
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			kvOperationsAdaptiveGroups(
				filter: {
					namespaceId: $namespaceId
					date_geq: $start
					date_leq: $end
					actionType: "read"
				}
				limit: 10000
			) {
				sum {
					requests
				}
				dimensions {
					actionType
				}
				quantiles {
					latencyMsP25
					latencyMsP50
					latencyMsP75
					latencyMsP90
					latencyMsP99
					latencyMsP999
				}
			}
		}
	}
}
```

To query your account-wide read, write, delete, and list operations across all KV namespaces:

```graphql graphql-api-explorer
query KvOperationsAllSample($accountTag: string!, $start: Date, $end: Date) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			kvOperationsAdaptiveGroups(
				filter: { date_geq: $start, date_leq: $end }
				limit: 10000
			) {
				sum {
					requests
				}
				dimensions {
					actionType
				}
			}
		}
	}
}
```

#### Storage

To query the storage details (`keyCount` and `byteCount`) of a KV namespace for every day of a given date range:

```graphql graphql-api-explorer
query Viewer(
	$accountTag: string!
	$namespaceId: string
	$start: Date
	$end: Date
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			kvStorageAdaptiveGroups(
				filter: { date_geq: $start, date_leq: $end, namespaceId: $namespaceId }
				limit: 10000
				orderBy: [date_DESC]
			) {
				max {
					keyCount
					byteCount
				}
				dimensions {
					date
				}
			}
		}
	}
}
```

---

# Limits

URL: https://developers.cloudflare.com/kv/platform/limits/

import { Render } from "~/components"

| Feature                           | Free                  | Paid         |
| --------------------------------- | --------------------- | ------------ |
| Reads                             | 100,000 reads per day | Unlimited    |
| Writes to different keys          | 1,000 writes per day  | Unlimited    |
| Writes to same key                | 1 per second          | 1 per second |
| Operations/Worker invocation [^1] | 1000                  | 1000         |
| Namespaces                        | 1000                  | 1000         |
| Storage/account                   | 1 GB                  | Unlimited    |
| Storage/namespace                 | 1 GB                  | Unlimited    |
| Keys/namespace                    | Unlimited             | Unlimited    |
| Key size                          | 512 bytes             | 512 bytes    |
| Key metadata                      | 1024 bytes            | 1024 bytes   |
| Value size                        | 25 MiB                | 25 MiB       |
| Minimum [`cacheTtl`](/kv/api/read-key-value-pairs/#cachettl-parameter)         | 60 seconds            | 60 seconds   |

[^1]: Within a single invocation, a Worker can make up to 1,000 operations to external services (for example, 500 Workers KV reads and 500 R2 reads). A bulk request to Workers KV counts for 1 request to an external service.

<Render file="limits_increase" product="workers" />

:::note[Free versus Paid plan pricing]

Refer to [KV pricing](/kv/platform/pricing/) to review the specific KV operations you are allowed under each plan with their pricing.

:::

:::note[Workers KV REST API limits]

Using the REST API to access Cloudflare Workers KV is subject to the [rate limits that apply to all operations of the Cloudflare REST API](/fundamentals/api/reference/limits).

:::

---

# Pricing

URL: https://developers.cloudflare.com/kv/platform/pricing/

import { Render } from "~/components"

<Render file="kv_pricing" product="workers" />

## Pricing FAQ

### When writing via KV's [REST API](/api/resources/kv/subresources/namespaces/subresources/keys/methods/bulk_update/), how are writes charged?

Each key-value pair in the `PUT` request is counted as a single write, identical to how each call to `PUT` in the Workers API counts as a write. Writing 5,000 keys via the REST API incurs the same write costs as making 5,000 `PUT` calls in a Worker.

### Do queries I issue from the dashboard or wrangler (the CLI) count as billable usage?

Yes, any operations via the Cloudflare dashboard or wrangler, including updating (writing) keys, deleting keys, and listing the keys in a namespace count as billable KV usage.

### Does Workers KV charge for data transfer / egress?

No.

---

# Release notes

URL: https://developers.cloudflare.com/kv/platform/release-notes/

import { ProductReleaseNotes } from "~/components";

{/* Actual content lives in /src/content/release-notes/kv.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file */}

<ProductReleaseNotes />

---

# Data security

URL: https://developers.cloudflare.com/kv/reference/data-security/

This page details the data security properties of KV, including:

* Encryption-at-rest (EAR).
* Encryption-in-transit (EIT).
* Cloudflare's compliance certifications.

## Encryption at Rest

All values stored in KV are encrypted at rest. Encryption and decryption are automatic, do not require user configuration to enable, and do not impact the effective performance of KV.

Values are only decrypted by the process executing your Worker code or responding to your API requests.

Encryption keys are managed by Cloudflare and securely stored in the same key management systems we use for managing encrypted data across Cloudflare internally.

Objects are encrypted using [AES-256](https://www.cloudflare.com/learning/ssl/what-is-encryption/), a widely tested, highly performant and industry-standard encryption algorithm. KV uses GCM (Galois/Counter Mode) as its preferred mode.

## Encryption in Transit

Data transfer between a Cloudflare Worker, and/or between nodes within the Cloudflare network and KV is secured using the same [Transport Layer Security](https://www.cloudflare.com/learning/ssl/transport-layer-security-tls/) (TLS/SSL).

API access via the HTTP API or using the [wrangler](/workers/wrangler/install-and-update/) command-line interface is also over TLS/SSL (HTTPS).

## Compliance

To learn more about Cloudflare's adherence to industry-standard security compliance certifications, refer to Cloudflare's [Trust Hub](https://www.cloudflare.com/trust-hub/compliance-resources/).

---

# Environments

URL: https://developers.cloudflare.com/kv/reference/environments/

import { WranglerConfig } from "~/components";

KV namespaces can be used with [environments](/workers/wrangler/environments/). This is useful when you have code in your Worker that refers to a KV binding like `MY_KV`, and you want to have these bindings point to different KV namespaces (for example, one for staging and one for production).

The following code in the Wrangler file shows you how to have two environments that have two different KV namespaces but the same binding name:

<WranglerConfig>

```toml
[env.staging]
kv_namespaces = [
  { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }
]

[env.production]
kv_namespaces = [
  { binding = "MY_KV", id = "a825455ce00f4f7282403da85269f8ea" }
]
```

</WranglerConfig>

Using the same binding name for two different KV namespaces keeps your Worker code more readable.

In the `staging` environment, `MY_KV.get("KEY")` will read from the namespace ID `e29b263ab50e42ce9b637fa8370175e8`. In the `production` environment, `MY_KV.get("KEY")` will read from the namespace ID `a825455ce00f4f7282403da85269f8ea`.

To insert a value into a `staging` KV namespace, run:

```sh
wrangler kv key put --env=staging --binding=<YOUR_BINDING> "<KEY>" "<VALUE>"
```

Since `--namespace-id` is always unique (unlike binding names), you do not need to specify an `--env` argument:

```sh
wrangler kv key put --namespace-id=<YOUR_ID> "<KEY>" "<VALUE>"
```

:::caution

Since version 3.60.0, Wrangler KV commands support the `kv ...` syntax. If you are using versions of Wrangler below 3.60.0, the command follows the `kv:...` syntax. Learn more about the deprecation of the `kv:...` syntax in the [Wrangler commands](/kv/reference/kv-commands/) for KV page.
:::

Most `kv` subcommands also allow you to specify an environment with the optional `--env` flag.

Specifying an environment with the optional `--env` flag allows you to publish Workers running the same code but with different KV namespaces.

For example, you could use separate staging and production KV namespaces for KV data in your Wrangler file:



<WranglerConfig>

```toml
type = "webpack"
name = "my-worker"
account_id = "<account id here>"
route = "staging.example.com/*"
workers_dev = false

kv_namespaces = [
  { binding = "MY_KV", id = "06779da6940b431db6e566b4846d64db" }
]

[env.production]
route = "example.com/*"
kv_namespaces = [
  { binding = "MY_KV", id = "07bc1f3d1f2a4fd8a45a7e026e2681c6" }
]
```

</WranglerConfig>

With the Wrangler file above, you can specify `--env production` when you want to perform a KV action on the KV namespace `MY_KV` under `env.production`.

For example, with the Wrangler file above, you can get a value out of a production KV instance with:

```sh
wrangler kv key get --binding "MY_KV" --env=production "<KEY>"
```

---

# FAQ

URL: https://developers.cloudflare.com/kv/reference/faq/

import { Glossary } from "~/components"

Frequently asked questions regarding Workers KV.

## General

### Can I use Workers KV without using Workers?

Yes, you can use Workers KV outside of Workers by using the [REST API](/api/resources/kv/) or the associated Cloudflare SDKs for the REST API. It is important to note the [limits of the REST API](/fundamentals/api/reference/limits/) that apply.

### Why can I not immediately see the updated value of a key-value pair?

Workers KV heavily caches data across the Cloudflare network. Therefore, it is possible that you read a cached value for up to the [cache TTL](/kv/api/read-key-value-pairs/#cachettl-parameter) duration.

### Is Workers KV eventually consistent or strongly consistent?

Workers KV is eventually consistent.

Workers KV stores data in central stores and replicates the data to all Cloudflare locations through a hybrid push/pull replication approach. This means that the previous value of the key-value pair may be seen in a location for as long as the [cache TTL](/kv/api/read-key-value-pairs/#cachettl-parameter). This means that Workers KV is eventually consistent.

Refer to [How KV works](/kv/concepts/how-kv-works/).

### If a Worker makes a bulk request to Workers KV, would each individual key get counted against the [Worker subrequest limit (of 1000)](/kv/platform/limits/)?

No. A bulk request to Workers KV, regardless of the amount of keys included in the request, will count as a single operation. For example, you could make
500 bulk KV requests and 500 R2 requests for a total of 1000 operations. 

## Pricing

### When writing via Workers KV's [REST API](/api/resources/kv/subresources/namespaces/subresources/keys/methods/bulk_update/), how are writes charged?

Each key-value pair in the `PUT` request is counted as a single write, identical to how each call to `PUT` in the Workers API counts as a write. Writing 5,000 keys via the REST API incurs the same write costs as making 5,000 `PUT` calls in a Worker.

### Do queries I issue from the dashboard or wrangler (the CLI) count as billable usage?

Yes, any operations via the Cloudflare dashboard or wrangler, including updating (writing) keys, deleting keys, and listing the keys in a namespace count as billable Workers KV usage.

### Does Workers KV charge for data transfer / egress?

No.

---

# Reference

URL: https://developers.cloudflare.com/kv/reference/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Tutorials

URL: https://developers.cloudflare.com/kv/tutorials/

import { GlossaryTooltip, ListTutorials, YouTubeVideos } from "~/components";

View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with KV.

## Docs

<ListTutorials />

## Videos

<YouTubeVideos products={["KV"]} />

---

# Wrangler KV commands

URL: https://developers.cloudflare.com/kv/reference/kv-commands/

import {Render} from "~/components"

<Render file="wrangler-commands/kv" product="workers"/>

## Deprecations

Below are deprecations to Wrangler commands for Workers KV.

### `kv:...` syntax deprecation

Since version 3.60.0, Wrangler supports the `kv ...` syntax. If you are using versions below 3.60.0, the command follows the `kv:...` syntax.

The `kv:...` syntax is deprecated in versions 3.60.0 and beyond and will be removed in a future major version.

For example, commands using the `kv ...` syntax look as such:

```sh
wrangler kv namespace list
wrangler kv key get <KEY>
wrangler kv bulk put <FILENAME>
```

The same commands using the `kv:...` syntax look as such:

```sh
wrangler kv:namespace list
wrangler kv:key get <KEY>
wrangler kv:bulk put <FILENAME>
```

---

# REST API

URL: https://developers.cloudflare.com/pages/configuration/api/

The [Pages API](/api/resources/pages/subresources/projects/methods/list/) empowers you to build automations and integrate Pages with your development workflow. At a high level, the API endpoints let you manage deployments and builds and configure projects. Cloudflare supports [Deploy Hooks](/pages/configuration/deploy-hooks/) for headless CMS deployments. Refer to the [API documentation](https://api.cloudflare.com/) for a full breakdown of object types and endpoints.

## How to use the API

### Get an API token

To create an API token:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com).
2. Select the user icon on the top right of your dashboard > **My Profile**.
3. Select [**API Tokens**](https://dash.cloudflare.com/profile/api-tokens) > **Create Token**.
4. You can go to **Edit Cloudflare Workers** template > **Use template** or go to **Create Custom Token** > **Get started**. If you create a custom token, you will need to make sure to add the **Cloudflare Pages** permission with **Edit** access.

### Make requests

After creating your token, you can authenticate and make requests to the API using your API token in the request headers. For example, here is an API request to get all deployments in a project.

```bash
curl 'https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects/{project_name}/deployments' \
--header 'Authorization: Bearer <API_TOKEN>'
```

Try it with one of your projects by replacing `{account_id}`, `{project_name}`, and `<API_TOKEN>`. Refer to [Find your account ID](/fundamentals/account/find-account-and-zone-ids/) for more information.

## Examples

The API is even more powerful when combined with Cloudflare Workers: the easiest way to deploy serverless functions on Cloudflare's global network. The following section includes three code examples on how to use the Pages API. To build and deploy these samples, refer to the [Get started guide](/workers/get-started/guide/).

### Triggering a new build every hour

Suppose we have a CMS that pulls data from live sources to compile a static output. You can keep the static content as recent as possible by triggering new builds periodically using the API.

```js
const endpoint =
	"https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects/{project_name}/deployments";

export default {
	async scheduled(_, env) {
		const init = {
			method: "POST",
			headers: {
				"Content-Type": "application/json;charset=UTF-8",
				// We recommend you store the API token as a secret using the Workers dashboard or using Wrangler as documented here: https://developers.cloudflare.com/workers/wrangler/commands/#secret
				Authorization: `Bearer ${env.API_TOKEN}`,
			},
		};

		await fetch(endpoint, init);
	},
};
```

After you have deployed the JavaScript Worker, set a cron trigger in your Worker to run this script periodically. Refer to [Cron Triggers](/workers/configuration/cron-triggers/) for more details.

### Deleting old deployments after a week

Cloudflare Pages hosts and serves all project deployments on preview links. Suppose you want to keep your project private and prevent access to your old deployments. You can use the API to delete deployments after a month, so that they are no longer public online. The latest deployment for a branch cannot be deleted.

```js
const endpoint =
	"https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects/{project_name}/deployments";
const expirationDays = 7;

export default {
	async scheduled(_, env) {
		const init = {
			headers: {
				"Content-Type": "application/json;charset=UTF-8",
				// We recommend you store the API token as a secret using the Workers dashboard or using Wrangler as documented here: https://developers.cloudflare.com/workers/wrangler/commands/#secret
				Authorization: `Bearer ${env.API_TOKEN}`,
			},
		};

		const response = await fetch(endpoint, init);
		const deployments = await response.json();

		for (const deployment of deployments.result) {
			// Check if the deployment was created within the last x days (as defined by `expirationDays` above)
			if (
				(Date.now() - new Date(deployment.created_on)) / 86400000 >
				expirationDays
			) {
				// Delete the deployment
				await fetch(`${endpoint}/${deployment.id}`, {
					method: "DELETE",
					headers: {
						"Content-Type": "application/json;charset=UTF-8",
						Authorization: `Bearer ${env.API_TOKEN}`,
					},
				});
			}
		}
	},
};
```

After you have deployed the JavaScript Worker, you can set a cron trigger in your Worker to run this script periodically. Refer to the [Cron Triggers guide](/workers/configuration/cron-triggers/) for more details.

### Sharing project information

Imagine you are working on a development team using Pages to build your websites. You would want an easy way to share deployment preview links and build status without having to share Cloudflare accounts. Using the API, you can easily share project information, including deployment status and preview links, and serve this content as HTML from a Cloudflare Worker.

```js
const deploymentsEndpoint =
	"https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects/{project_name}/deployments";
const projectEndpoint =
	"https://api.cloudflare.com/client/v4/accounts/{account_id}/pages/projects/{project_name}";

export default {
	async fetch(request, env) {
		const init = {
			headers: {
				"content-type": "application/json;charset=UTF-8",
				// We recommend you store the API token as a secret using the Workers dashboard or using Wrangler as documented here: https://developers.cloudflare.com/workers/wrangler/commands/#secret
				Authorization: `Bearer ${env.API_TOKEN}`,
			},
		};

		const style = `body { padding: 6em; font-family: sans-serif; } h1 { color: #f6821f }`;
		let content = "<h2>Project</h2>";

		let response = await fetch(projectEndpoint, init);
		const projectResponse = await response.json();
		content += `<p>Project Name: ${projectResponse.result.name}</p>`;
		content += `<p>Project ID: ${projectResponse.result.id}</p>`;
		content += `<p>Pages Subdomain: ${projectResponse.result.subdomain}</p>`;
		content += `<p>Domains: ${projectResponse.result.domains}</p>`;
		content += `<a href="${projectResponse.result.canonical_deployment.url}"><p>Latest preview: ${projectResponse.result.canonical_deployment.url}</p></a>`;

		content += `<h2>Deployments</h2>`;
		response = await fetch(deploymentsEndpoint, init);
		const deploymentsResponse = await response.json();

		for (const deployment of deploymentsResponse.result) {
			content += `<a href="${deployment.url}"><p>Deployment: ${deployment.id}</p></a>`;
		}

		let html = `
      <!DOCTYPE html>
      <head>
        <title>Example Pages Project</title>
      </head>
      <body>
        <style>${style}</style>
        <div id="container">
          ${content}
        </div>
      </body>`;

		return new Response(html, {
			headers: {
				"Content-Type": "text/html;charset=UTF-8",
			},
		});
	},
};
```

## Related resources

- [Pages API Docs](/api/resources/pages/subresources/projects/methods/list/)
- [Workers Getting Started Guide](/workers/get-started/guide/)
- [Workers Cron Triggers](/workers/configuration/cron-triggers/)

---

# Branch deployment controls

URL: https://developers.cloudflare.com/pages/configuration/branch-build-controls/

import { Render } from "~/components";

When connected to your git repository, Pages allows you to control which environments and branches you would like to automatically deploy to. By default, Pages will trigger a deployment any time you commit to either your production or preview environment. However, with branch deployment controls, you can configure automatic deployments to suit your preference on a per project basis.

## Production branch control

:::caution[Direct Upload]

<Render file="prod-branch-update" />

:::

To configure deployment options, go to your Pages project > **Settings** > **Builds & deployments** > **Configure Production deployments**. Pages will default to setting your production environment to the branch you first push, but you can set your production to another branch if you choose.

You can also enable or disable automatic deployment behavior on the production branch by checking the **Enable automatic production branch deployments** box. You must save your settings in order for the new production branch controls to take effect.

## Preview branch control

When configuring automatic preview deployments, there are three options to choose from.

- **All non-Production branches**: By default, Pages will automatically deploy any and every commit to a preview branch.
- **None**: Turns off automatic builds for all preview branches.
- **Custom branches**: Customize the automatic deployments of certain preview branches.

### Custom preview branch control

By selecting **Custom branches**, you can specify branches you wish to include and exclude from automatic deployments in the provided configuration fields. The configuration fields can be filled in two ways:

- **Static branch names**: Enter the precise name of the branch you are looking to include or exclude (for example, staging or dev).
- **Wildcard syntax**: Use wildcards to match multiple branches. You can specify wildcards at the start or end of your rule. The order of execution for the configuration is (1) Excludes, (2) Includes, (3) Skip. Pages will process the exclude configuration first, then go to the include configuration. If a branch does not match either then it will be skipped.

:::note[Wildcard syntax]

A wildcard (`*`) is a character that is used within rules. It can be placed alone to match anything or placed at the start or end of a rule to allow for better control over branch configuration. A wildcard will match zero or more characters.For example, if you wanted to match all branches that started with `fix/` then you would create the rule `fix/*` to match strings like `fix/1`, `fix/bugs`or `fix/`.

:::

**Example 1:**

If you want to enforce branch prefixes such as `fix/`, `feat/`, or `chore/` with wildcard syntax, you can include and exclude certain branches with the following rules:

- Include Preview branches:
  `fix/*`, `feat/*`, `chore/*`

- Exclude Preview branches:
  \`\`

Here Pages will include any branches with the indicated prefixes and exclude everything else. In this example, the excluding option is left empty.

**Example 2:**

If you wanted to prevent [dependabot](https://github.com/dependabot) from creating a deployment for each PR it creates, you can exclude those branches with the following:

- Include Preview branches:
  `*`

- Exclude Preview branches:
  `dependabot/*`

Here Pages will include all branches except any branch starting with `dependabot`. In this example, the excluding option means any `dependabot/` branches will not be built.

**Example 3:**

If you only want to deploy release-prefixed branches, then you could use the following rules:

- Include Preview branches:
  `release/*`

- Exclude Preview branches:
  `*`

This will deploy only branches starting with `release/`.

---

# Build caching

URL: https://developers.cloudflare.com/pages/configuration/build-caching/

Improve Pages build times by caching dependencies and build output between builds with a project-wide shared cache.

The first build to occur after enabling build caching on your Pages project will save to cache. Every subsequent build will restore from cache unless configured otherwise.

## About build cache

When enabled, the build cache will automatically detect and cache data from each build. Refer to [Frameworks](/pages/configuration/build-caching/#frameworks) to review what directories are automatically saved and restored from the build cache.

### Requirements

Build caching requires the [V2 build system](/pages/configuration/build-image/#v2-build-system) or later. To update from V1, refer to the [V2 build system migration instructions](/pages/configuration/build-image/#v1-to-v2-migration).

### Package managers

Pages will cache the global cache directories of the following package managers:

| Package Manager               | Directories cached   |
| ----------------------------- | -------------------- |
| [npm](https://www.npmjs.com/) | `.npm`               |
| [yarn](https://yarnpkg.com/)  | `.cache/yarn`        |
| [pnpm](https://pnpm.io/)      | `.pnpm-store`        |
| [bun](https://bun.sh/)        | `.bun/install/cache` |

### Frameworks

Some frameworks provide a cache directory that is typically populated by the framework with intermediate build outputs or dependencies during build time. Pages will automatically detect the framework you are using and cache this directory for reuse in subsequent builds.

The following frameworks support build output caching:

| Framework  | Directories cached                            |
| ---------- | --------------------------------------------- |
| Astro      | `node_modules/.astro`                         |
| Docusaurus | `node_modules/.cache`, `.docusaurus`, `build` |
| Eleventy   | `.cache`                                      |
| Gatsby     | `.cache`, `public`                            |
| Next.js    | `.next/cache`                                 |
| Nuxt       | `node_modules/.cache/nuxt`                    |

### Limits

The following limits are imposed for build caching:

- **Retention**: Cache is purged seven days after its last read date. Unread cache artifacts are purged seven days after creation.
- **Storage**: Every project is allocated 10 GB. If the project cache exceeds this limit, the project will automatically start deleting artifacts that were read least recently.

## Enable build cache

To enable build caching :

1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard.
2. Find your Pages project.
3. Go to **Settings** > **Build** > **Build cache**.
4. Select **Enable** to turn on build caching.

## Clear build cache

The build cache can be cleared for a project if needed, such as when debugging build issues. To clear the build cache:

1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard.
2. Find your Pages project.
3. Go to **Settings** > **Build** > **Build cache**.
4. Select **Clear Cache** to clear the build cache.

---

# Build configuration

URL: https://developers.cloudflare.com/pages/configuration/build-configuration/

import { Details, PagesBuildPresetsTable } from "~/components";

You may tell Cloudflare Pages how your site needs to be built as well as where its output files will be located.

## Build commands and directories

You should provide a build command to tell Cloudflare Pages how to build your application. For projects not listed here, consider reading the tool's documentation or framework, and submit a pull request to add it here.

Build directories indicates where your project's build command outputs the built version of your Cloudflare Pages site. Often, this defaults to the industry-standard `public`, but you may find that you need to customize it.

<Details header="Understanding your build configuration">

The build command is provided by your framework. For example, the Gatsby framework uses `gatsby build` as its build command. When you are working without a framework, leave the **Build command** field blank. Pages determines whether a build has succeeded or failed by reading the exit code returned from the user supplied build command. Any non-zero return code will cause a build to be marked as failed. An exit code of 0 will cause the Pages build to be marked as successful and assets will be uploaded regardless of if error logs are written to standard error.

The build directory is generated from the build command. Each framework has its own naming convention, for example, the build output directory is named `/public` for many frameworks.

The root directory is where your site’s content lives. If not specified, Cloudflare assumes that your linked git repository is the root directory. The root directory needs to be specified in cases like monorepos, where there may be multiple projects in one repository.

</Details>

## Framework presets

Cloudflare maintains a list of build configurations for popular frameworks and tools. These are accessible during project creation. Below are some standard build commands and directories for popular frameworks and tools.

If you are not using a preset, use `exit 0` as your **Build command**.

<PagesBuildPresetsTable />

## Environment variables

If your project makes use of environment variables to build your site, you can provide custom environment variables:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. In **Overview**, select your Pages project.
4. Select **Settings** > **Environment variables**.

The following system environment variables are injected by default (but can be overridden):

| Environment Variable  | Injected value                        | Example use-case                                                                        |
| --------------------- | ------------------------------------- | --------------------------------------------------------------------------------------- |
| `CI`                  | `true`                                | Changing build behaviour when run on CI versus locally                                  |
| `CF_PAGES`            | `1`                                   | Changing build behaviour when run on Pages versus locally                               |
| `CF_PAGES_COMMIT_SHA` | `<sha1-hash-of-current-commit>`       | Passing current commit ID to error reporting, for example, Sentry                       |
| `CF_PAGES_BRANCH`     | `<branch-name-of-current-deployment>` | Customizing build based on branch, for example, disabling debug logging on `production` |
| `CF_PAGES_URL`        | `<url-of-current-deployment>`         | Allowing build tools to know the URL the page will be deployed at                       |

---

# Custom domains

URL: https://developers.cloudflare.com/pages/configuration/custom-domains/

import { Render } from "~/components";

When deploying your Pages project, you may wish to point custom domains (or subdomains) to your site.

## Add a custom domain

<Render file="custom-domain-steps" />

### Add a custom apex domain

If you are deploying to an apex domain (for example, `example.com`), then you will need to add your site as a Cloudflare zone and [configure your nameservers](#configure-nameservers).

#### Configure nameservers

To use a custom apex domain (for example, `example.com`) with your Pages project, [configure your nameservers to point to Cloudflare's nameservers](/dns/zone-setups/full-setup/setup/). If your nameservers are successfully pointed to Cloudflare, Cloudflare will proceed by creating a CNAME record for you.

### Add a custom subdomain

If you are deploying to a subdomain, it is not necessary for your site to be a Cloudflare zone. You will need to [add a custom CNAME record](#add-a-custom-cname-record) to point the domain to your Cloudflare Pages site. To deploy your Pages project to a custom apex domain, that custom domain must be a zone on the Cloudflare account you have created your Pages project on.

:::note

If the zone is on the Enterprise plan, make sure that you [release the zone hold](/fundamentals/account/account-security/zone-holds/#release-zone-holds) before adding the custom domain. A zone hold would prevent the custom subdomain from activating.

:::

#### Add a custom CNAME record

If you do not want to point your nameservers to Cloudflare, you must create a custom CNAME record to use a subdomain with Cloudflare Pages. After logging in to your DNS provider, add a CNAME record for your desired subdomain, for example, `shop.example.com`. This record should point to your custom Pages subdomain, for example, `<YOUR_SITE>.pages.dev`.

| Type    | Name               | Content                 |
| ------- | ------------------ | ----------------------- |
| `CNAME` | `shop.example.com` | `<YOUR_SITE>.pages.dev` |

If your site is already managed as a Cloudflare zone, the CNAME record will be added automatically after you confirm your DNS record.

:::note

To ensure a custom domain is added successfully, you must go through the [Add a custom domain](#add-a-custom-domain) process described above. Manually adding a custom CNAME record pointing to your Cloudflare Pages site - without first associating the domain (or subdomains) in the Cloudflare Pages dashboard - will result in your domain failing to resolve at the CNAME record address, and display a [`522` error](/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/error-522/).

:::

## Delete a custom domain

To detach a custom domain from your Pages project, you must modify your zone's DNS records.

First, log in to the Cloudflare dashboard > select your account in **Account Home** > select your website > **DNS**.

Then, in **DNS** > **Records**:

1. Locate your Pages project's CNAME record.
2. Select **Edit**.
3. Select **Delete**.

Next, in Account Home, go to **Workers & Pages**:

1. In **Overview**, select your Pages project.
2. Go to **Custom domains**.
3. Select the **three dot icon** next to your custom domain > **Remove domain**.

After completing these steps, your Pages project will only be accessible through the `*.pages.dev` subdomain you chose when creating your project.

## Disable access to `*.pages.dev` subdomain

To disable access to your project's provided `*.pages.dev` subdomain:

1. Use Cloudflare Access over your previews (`*.{project}.pages.dev`). Refer to [Customize preview deployments access](/pages/configuration/preview-deployments/#customize-preview-deployments-access).

2. Redirect the `*.pages.dev` URL associated with your production Pages project to a custom domain. You can use the account-level [Bulk Redirect](/rules/url-forwarding/bulk-redirects/) feature to redirect your `*.pages.dev` URL to a custom domain.

## Caching

For guidelines on caching, refer to [Caching and performance](/pages/configuration/serving-pages/#caching-and-performance).

## Known issues

### CAA records

Certification Authority Authorization (CAA) records allow you to restrict certificate issuance to specific Certificate Authorities (CAs).

This can cause issues when adding a [custom domain](/pages/configuration/custom-domains/) to your Pages project if you have CAA records that do not allow Cloudflare to issue a certificate for your custom domain.

To resolve this, add the necessary CAA records to allow Cloudflare to issue a certificate for your custom domain.

```
example.com.            300     IN      CAA     0 issue "letsencrypt.org"
example.com.            300     IN      CAA     0 issue "pki.goog; cansignhttpexchanges=yes"
example.com.            300     IN      CAA     0 issue "ssl.com"
example.com.            300     IN      CAA     0 issuewild "letsencrypt.org"
example.com.            300     IN      CAA     0 issuewild "pki.goog; cansignhttpexchanges=yes"
example.com.            300     IN      CAA     0 issuewild "ssl.com"
```

Refer to the [Certification Authority Authorization (CAA) FAQ](/ssl/edge-certificates/troubleshooting/caa-records/) for more information.

### Change DNS entry away from Pages and then back again

Once a custom domain is set up, if you change the DNS entry to point to something else (for example, your origin), the custom domain will become inactive. If you then change that DNS entry to point back at your custom domain, anybody using that DNS entry to visit your website will get errors until it becomes active again. If you want to redirect traffic away from your Pages project temporarily instead of changing the DNS entry, it would be better to use an [Origin rule](/rules/origin-rules/) or a [redirect rule](/rules/url-forwarding/single-redirects/create-dashboard/) instead.

## Relevant resources

- [Debugging Pages](/pages/configuration/debugging-pages/) - Review common errors when deploying your Pages project.

---

# Build watch paths

URL: https://developers.cloudflare.com/pages/configuration/build-watch-paths/

When you connect a git repository to Pages, by default a change to any file in the repository will trigger a Pages build. You can configure Pages to include or exclude specific paths to specify if Pages should skip a build for a given path. This can be especially helpful if you are using a monorepo project structure and want to limit the amount of builds being kicked off.

## Configure paths

To configure which paths are included and excluded:

1. In **Overview**, select your Pages project.
2. Go to **Settings** > **Build** > **Build watch paths**. Pages will default to setting your project’s includes paths to everything (\[\*]) and excludes paths to nothing (`[]`).

The configuration fields can be filled in two ways:

- **Static filepaths**: Enter the precise name of the file you are looking to include or exclude (for example, `docs/README.md`).
- **Wildcard syntax:** Use wildcards to match multiple path directories. You can specify wildcards at the start or end of your rule.

:::note[Wildcard syntax]

A wildcard (`*`) is a character that is used within rules. It can be placed alone to match anything or placed at the start or end of a rule to allow for better control over branch configuration. A wildcard will match zero or more characters.For example, if you wanted to match all branches that started with `fix/` then you would create the rule `fix/*` to match strings like `fix/1`, `fix/bugs`or `fix/`.

:::

For each path in a push event, build watch paths will be evaluated as follows:

- Paths satisfying excludes conditions are ignored first
- Any remaining paths are checked against includes conditions
- If any matching path is found, a build is triggered. Otherwise the build is skipped

Pages will bypass the path matching for a push event and default to building the project if:

- A push event contains 0 file changes, in case a user pushes a empty push event to trigger a build
- A push event contains 3000+ file changes or 20+ commits

## Examples

### Example 1

If you want to trigger a build from all changes within a set of directories, such as all changes in the folders `project-a/` and `packages/`

- Include paths: `project-a/*, packages/*`
- Exclude paths: \`\`

### Example 2

If you want to trigger a build for any changes, but want to exclude changes to a certain directory, such as all changes in a docs/ directory

- Include paths: `*`
- Exclude paths: `docs/*`

### Example 3

If you want to trigger a build for a specific file or specific filetype, for example all files ending in `.md`.

- Include paths: `*.md`
- Exclude paths: \`\`

---

# Build image

URL: https://developers.cloudflare.com/pages/configuration/build-image/

import {
	PagesBuildEnvironment,
	PagesBuildEnvironmentLanguages,
	PagesBuildEnvironmentTools,
} from "~/components";

Cloudflare Pages' build environment has broad support for a variety of languages, such as Ruby, Node.js, Python, PHP, and Go.

If you need to use a [specific version](#override-default-versions) of a language, (for example, Node.js or Ruby) you can specify it by providing an associated environment variable in your build configuration, or setting the relevant file in your source code.

## Supported languages and tools

In the following tables, review the preinstalled versions for languages and tools included in the Cloudflare Pages' build image, and the environment variables and/or files available for [overriding the preinstalled version](#override-default-versions):

### Languages and runtime

<PagesBuildEnvironmentLanguages />

:::note[Any version]
Under Supported versions, "Any version" refers to support for all versions of the language or tool including versions newer than the Default version.
:::

### Tools

<PagesBuildEnvironmentTools />

:::note[Any version]
Under Supported versions, "Any version" refers to support for all versions of the language or tool including versions newer than the Default version.
:::

### Frameworks

To use a specific version of a framework, specify it in the project's package manager configuration file.
For example, if you use Gatsby, your `package.json` should include the following:

```
"dependencies": {
	"gatsby": "^5.13.7",
}
```

When your build starts, if not already [cached](/pages/configuration/build-caching/), version 5.13.7 of Gatsby will be installed using `npm install`.

## Advanced Settings

### Override default versions

To override default versions of languages and tools in the build system, you can either set the desired version through environment variables or by adding files to your project.

To set the version using environment variables, you can:

1. Find the environment variable name for the language or tool in [this table](/pages/configuration/build-image/#supported-languages-and-tools).
2. Add the environment variable on the dashboard by going to **Settings** > **Environment variables** in your Pages project, or [add the environment variable via Wrangler](/workers/configuration/environment-variables/#add-environment-variables-via-wrangler).

Or, to set the version by adding a file to your project, you can:

1. Find the file name for the language or tool in [this table](/pages/configuration/build-image/#supported-languages-and-tools).
2. Add the specified file name to the root directory of your project, and add the desired version number as the contents of the file.

For example, if you were previously relying on the default version of Node.js in the v1 build system, to migrate to v2, you must specify that you need Node.js `12.18.0` by setting a `NODE_VERSION = 12.18.0` environment variable or by adding a `.node-version` or `.nvmrc` file to your project with `12.18.0` added as the contents to the file.

### Skip dependency install

You can add the following environment variable to disable automatic dependency installation, and run a custom install command instead.

| Build variable            | Value         |
| ------------------------- | ------------- |
| `SKIP_DEPENDENCY_INSTALL` | `1` or `true` |

## v3 build system

The v3 build system updates the default tools, libraries and languages to their LTS versions, as of May 2025.

### v2 to v3 Migration

To migrate to this new version, configure your Pages project settings in the dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages** > in **Overview**, select your Pages project.
3. Go to **Settings** > **Build & deployments** > **Build system version** and select the latest version.

If you were previously relying on the default versions of any languages or tools in the build system, your build may fail when migrating to v3. To fix this, you must specify the version you wish to use by [overriding](/pages/configuration/build-image/#overriding-default-versions) the default versions.

### Limitations

The following features are not currently supported when using the v3 build system:

- Specifying Node.js versions as codenames (for example, `hydrogen` or `lts/hydrogen`).
- Detecting Yarn version from `yarn.lock` file version.
- Detecting pnpm version detection based `pnpm-lock.yaml` file version.
- Detecting Node.js and package managers from `package.json` -> `"engines"`.
- `pipenv` and `Pipfile` support.

## Build environment

Cloudflare Pages builds are run in a [gVisor](https://gvisor.dev/docs/) container.

<PagesBuildEnvironment />

---

# Debugging Pages

URL: https://developers.cloudflare.com/pages/configuration/debugging-pages/

When setting up your Pages project, you may encounter various errors that prevent you from successfully deploying your site. This guide gives an overview of some common errors and solutions.

## Check your build log

You can review build errors in your Pages build log. To access your build log:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com).
2. In **Account Home**, go to **Workers & Pages**.
3. In **Overview**, select your Pages project > **View build**.

![After logging in to the Cloudflare dashboard, access the build log by following the instructions above](~/assets/images/pages/platform/pages-build-log.png)

Possible errors in your build log are included in the following sections.

### Initializing build environment

Possible errors in this step could be caused by improper installation during Git integration.

To fix this in GitHub:

1. Log in to your GitHub account.
2. Go to **Settings** from your user icon > find **Applications** under Integrations.
3. Find **Cloudflare Pages** > **Configure** > scroll down and select **Uninstall**.
4. Re-authorize your GitHub user/organization on the Cloudflare dashboard.

To fix this in GitLab:

1. Log in to your GitLab account.
2. Go to **Preferences** from your user icon > **Applications**.
3. Find **Cloudflare Pages** > scroll down and select **Revoke**.

Be aware that you need a role of **Maintainer** or above to successfully link your repository, otherwise the build will fail.

### Cloning git repository

Possible errors in this step could be caused by lack of Git Large File Storage (LFS). Check your LFS usage by referring to the [GitHub](https://docs.github.com/en/billing/managing-billing-for-git-large-file-storage/viewing-your-git-large-file-storage-usage) and [GitLab](https://docs.gitlab.com/ee/topics/git/lfs/) documentation.

Make sure to also review your submodule configuration by going to the `.gitmodules` file in your root directory. This file needs to contain both a `path` and a `url` property.

Example of a valid configuration:

```js
[submodule "example"]
	path = example/path
	url = git://github.com/example/repo.git
```

Example of an invalid configuration:

```js
[submodule "example"]
	path = example/path
```

or

```js
[submodule "example"]
        url = git://github.com/example/repo.git
```

### Building application

Possible errors in this step could be caused by faulty setup in your Pages project. Review your build command, output folder and environment variables for any incorrect configuration.

:::note

Make sure there are no emojis or special characters as part of your commit message in a Pages project that is integrated with GitHub or GitLab as it can potentially cause issues when building the project.

:::

### Deploying to Cloudflare's global network

Possible errors in this step could be caused by incorrect Pages Functions configuration. Refer to the [Functions](/pages/functions/) documentation for more information on Functions setup.

If you are not using Functions or have reviewed that your Functions configuration does not contain any errors, review the [Cloudflare Status site](https://www.cloudflarestatus.com/) for Cloudflare network issues that could be causing the build failure.

## Differences between `pages.dev` and custom domains

If your custom domain is proxied (orange-clouded) through Cloudflare, your zone's settings, like caching, will apply.

If you are experiencing issues with new content not being shown, go to **Rules** > **Page Rules** in the Cloudflare dashboard and check for a Page Rule with **Cache Everything** enabled. If present, remove this rule as Pages handles its own cache.

If you are experiencing errors on your custom domain but not on your `pages.dev` domain, go to **DNS** > **Records** in the Cloudflare dashboard and set the DNS record for your project to be **DNS Only** (grey cloud). If the error persists, review your zone's configuration.

## Domain stuck in verification

If your [custom domain](/pages/configuration/custom-domains/) has not moved from the **Verifying** stage in the Cloudflare dashboard, refer to the following debugging steps.

### Blocked HTTP validation

Pages uses HTTP validation and needs to hit an HTTP endpoint during validation. If another Cloudflare product is in the way (such as [Access](/cloudflare-one/policies/access/), [a redirect](/rules/url-forwarding/), [a Worker](/workers/), etc.), validation cannot be completed.

To check this, run a `curl` command against your domain hitting `/.well-known/acme-challenge/randomstring`. For example:

```sh
curl -I https://example.com/.well-known/acme-challenge/randomstring
```

```sh output

HTTP/2 302
date: Mon, 03 Apr 2023 08:37:39 GMT
location: https://example.cloudflareaccess.com/cdn-cgi/access/login/example.com?kid=...&redirect_url=%2F.well-known%2Facme-challenge%2F...
access-control-allow-credentials: true
cache-control: private, max-age=0, no-store, no-cache, must-revalidate, post-check=0, pre-check=0
server: cloudflare
cf-ray: 7b1ffdaa8ad60693-MAN
```

In the example above, you are redirecting to Cloudflare Access (as shown by the `Location` header). In this case, you need to disable Access over the domain until the domain is verified. After the domain is verified, Access can be re-enabled.

You will need to do the same kind of thing for Redirect Rules or a Worker example too.

### Missing CAA records

If nothing is blocking the HTTP validation, then you may be missing Certification Authority Authorization (CAA) records. This is likely if you have disabled [Universal SSL](/ssl/edge-certificates/universal-ssl/) or use an external provider.

To check this, run a `dig` on the custom domain's apex (or zone, if this is a [subdomain zone](/dns/zone-setups/subdomain-setup/)). For example:

```sh
dig CAA example.com
```

```sh output

; <<>> DiG 9.10.6 <<>> CAA example.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 59018
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;example.com.		IN	CAA

;; ANSWER SECTION:
example.com.	300	IN	CAA	0 issue "amazon.com"

;; Query time: 92 msec
;; SERVER: 127.0.2.2#53(127.0.2.2)
;; WHEN: Mon Apr 03 10:15:51 BST 2023
;; MSG SIZE  rcvd: 76
```

In the above example, there is only a single CAA record which is allowing Amazon to issue ceritficates.

To resolve this, you will need to add the following CAA records which allows all of the Certificate Authorities (CAs) Cloudflare uses to issue certificates:

```
example.com.            300     IN      CAA     0 issue "letsencrypt.org"
example.com.            300     IN      CAA     0 issue "pki.goog; cansignhttpexchanges=yes"
example.com.            300     IN      CAA     0 issue "ssl.com"
example.com.            300     IN      CAA     0 issuewild "letsencrypt.org"
example.com.            300     IN      CAA     0 issuewild "pki.goog; cansignhttpexchanges=yes"
example.com.            300     IN      CAA     0 issuewild "ssl.com"
```

### Zone holds

A [zone hold](/fundamentals/account/account-security/zone-holds/) will prevent Pages from adding a custom domain for a hostname under a zone hold.

To add a custom domain for a hostname with a zone hold, temporarily [release the zone hold](/fundamentals/account/account-security/zone-holds/#release-zone-holds) during the custom domain setup process.

Once the custom domain has been successfully completed, you may [reinstate the zone hold](/fundamentals/account/account-security/zone-holds/#enable-zone-holds).

:::caution[Still having issues]

If you have done the steps above and your domain is still verifying after 15 minutes, join our [Discord](https://discord.cloudflare.com) for support or contact our support team through the [Support Portal](https://dash.cloudflare.com/?to=/:account/support).

:::

## Resources

If you need additional guidance on build errors, contact your Cloudflare account team (Enterprise) or refer to the [Support Center](/support/contacting-cloudflare-support/) for guidance on contacting Cloudflare Support.

You can also ask questions in the Pages section of the [Cloudflare Developers Discord](https://discord.com/invite/cloudflaredev).

---

# Deploy Hooks

URL: https://developers.cloudflare.com/pages/configuration/deploy-hooks/

With Deploy Hooks, you can trigger deployments using event sources beyond commits in your source repository. Each event source may obtain its own unique URL, which will receive HTTP POST requests in order to initiate new deployments. This feature allows you to integrate Pages with new or existing workflows. For example, you may:

- Automatically deploy new builds whenever content in a Headless CMS changes
- Implement a fully customized CI/CD pipeline, deploying only under desired conditions
- Schedule a CRON trigger to update your website on a fixed timeline

To create a Deploy Hook:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In Account Home, select **Workers & Pages**.
3. In **Overview**, select your Pages project.
4. Go to **Settings** > **Builds & deployments** and select **Add deploy hook** to start configuration.

![Add a deploy hook on the Cloudflare dashboard](~/assets/images/pages/platform/deploy-hooks-add.png)

## Parameters needed

To configure your Deploy Hook, you must enter two key parameters:

1. **Deploy hook name:** a unique identifier for your Deploy Hook (for example, `contentful-site`)
2. **Branch to build:** the repository branch your Deploy Hook should build

![Choosing Deploy Hook name and branch to build on Cloudflare dashboard](~/assets/images/pages/platform/deploy-hooks-configure.png)

## Using your Deploy Hook

Once your configuration is complete, the Deploy Hook’s unique URL is ready to be used. You will see both the URL as well as the POST request snippet available to copy.

![Reviewing the Deploy Hook's newly generated unique URL](~/assets/images/pages/platform/deploy-hooks-details.png)

Every time a request is sent to your Deploy Hook, a new build will be triggered. Review the **Source** column of your deployment log to see which deployment were triggered by a Deploy Hook.

![Reviewing which deployment was triggered by a Deploy Hook](~/assets/images/pages/platform/deploy-hooks-deployment-logs.png)

## Security Considerations

Deploy Hooks are uniquely linked to your project and do not require additional authentication to be used. While this does allow for complete flexibility, it is important that you protect these URLs in the same way you would safeguard any proprietary information or application secret.

If you suspect unauthorized usage of a Deploy Hook, you should delete the Deploy Hook and generate a new one in its place.

## Integrating Deploy Hooks with common CMS platforms

Every CMS provider is different and will offer different pathways in integrating with Pages' Deploy Hooks. The following section contains step-by-step instructions for a select number of popular CMS platforms.

### Contentful

Contentful supports integration with Cloudflare Pages via its **Webhooks** feature. In your Contentful project settings, go to **Webhooks**, create a new Webhook, and paste in your unique Deploy Hook URL in the **URL** field. Optionally, you can specify events that the Contentful Webhook should forward. By default, Contentful will trigger a Pages deployment on all project activity, which may be a bit too frequent. You can filter for specific events, such as Create, Publish, and many others.

![Configuring Deploy Hooks with Contentful](~/assets/images/pages/platform/contentful.png)

### Ghost

You can configure your Ghost website to trigger Pages deployments by creating a new **Custom Integration**. In your Ghost website’s settings, create a new Custom Integration in the **Integrations** page.

Each custom integration created can have multiple **webhooks** attached to it. Create a new webhook by selecting **Add webhook** and **Site changed (rebuild)** as the **Event**. Then paste your unique Deploy Hook URL as the **Target URL** value. After creating this webhook, your Cloudflare Pages application will redeploy whenever your Ghost site changes.

![Configuring Deploy Hooks with Ghost](~/assets/images/pages/platform/ghost.png)

### Sanity

In your Sanity project's Settings page, find the **Webhooks** section, and add the Deploy Hook URL, as seen below. By default, the Webhook will trigger your Pages Deploy Hook for all datasets inside of your Sanity project. You can filter notifications to individual datasets, such as production, using the **Dataset** field:

![Configuring Deploy Hooks with Sanity](~/assets/images/pages/platform/sanity.png)

### WordPress

You can configure WordPress to trigger a Pages Deploy Hook by installing the free **WP Webhooks** plugin. The plugin includes a number of triggers, such as **Send Data on New Post, Send Data on Post Update** and **Send Data on Post Deletion**, all of which allow you to trigger new Pages deployments as your WordPress data changes. Select a trigger on the sidebar of the plugin settings and then [**Add Webhook URL**](https://wordpress.org/plugins/wp-webhooks/), pasting in your unique Deploy Hook URL.

![Configuring Deploy Hooks with WordPress](~/assets/images/pages/platform/wordpress.png)

### Strapi

In your Strapi Admin Panel, you can set up and configure webhooks to enhance your experience with Cloudflare Pages. In the Strapi Admin Panel:

1. Navigate to **Settings**.
2. Select **Webhooks**.
3. Select **Add New Webhook**.
4. In the **Name** form field, give your new webhook a unique name.
5. In the **URL** form field, paste your unique Cloudflare Deploy Hook URL.

In the Strapi Admin Panel, you can configure your webhook to be triggered based on events. You can adjust these settings to create a new deployment of your Cloudflare Pages site automatically when a Strapi entry or media asset is created, updated, or deleted.

Be sure to add the webhook configuration to the [production](https://strapi.io/documentation/developer-docs/latest/setup-deployment-guides/installation.html) Strapi application that powers your Cloudflare site.

![Configuring Deploy Hooks with Strapi](~/assets/images/pages/platform/strapi.png)

### Storyblok

You can set up and configure deploy hooks in Storyblok to trigger events. In your Storyblok space, go to **Settings** and scroll down to **Webhooks**. Paste your deploy hook into the **Story published & unpublished** field and select **Save**.

![Configuring Deploy Hooks with Storyblok](https://user-images.githubusercontent.com/53130544/161367254-ff475f3b-2821-4ee8-a175-8e96e779aa08.png)

---

# Configuration

URL: https://developers.cloudflare.com/pages/configuration/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Early Hints

URL: https://developers.cloudflare.com/pages/configuration/early-hints/

[Early Hints](/cache/advanced-configuration/early-hints/) help the browser to load webpages faster. Early Hints is enabled automatically on all `pages.dev` domains and custom domains.

Early Hints automatically caches any [`preload`](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/preload) and [`preconnect`](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/preconnect) type [`Link` headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Link) to send as Early Hints to the browser. The hints are sent to the browser before the full response is prepared, and the browser can figure out how to load the webpage faster for the end user. There are two ways to create these `Link` headers in Pages:

## Configure Early Hints

Early Hints can be created with either of the two methods detailed below.

### 1. Configure your `_headers` file

Create custom headers using the [`_headers` file](/pages/configuration/headers/). If you include a particular stylesheet on your `/blog/` section of your website, you would create the following rule:

```txt
/blog/*
  Link: </styles.css>; rel=preload; as=style
```

Pages will attach this `Link: </styles.css>; rel=preload; as=style` header. Early Hints will then emit this header as an Early Hint once cached.

### 2. Automatic `Link` header generation

In order to make the authoring experience easier, Pages also automatically generates `Link` headers from any `<link>` HTML elements with the following attributes:

- `href`
- `as` (optional)
- `rel` (one of `preconnect`, `preload`, or `modulepreload`)

`<link>` elements which contain any other additional attributes (for example, `fetchpriority`, `crossorigin` or `data-do-not-generate-a-link-header`) will not be used to generate `Link` headers in order to prevent accidentally losing any custom prioritization logic that would otherwise be dropped as an Early Hint.

This allows you to directly create Early Hints as you are writing your document, without needing to alternate between your HTML and `_headers` file.

```html
<html>
	<head>
		<link rel="preload" href="/style.css" as="style" />
		<link rel="stylesheet" href="/style.css" />
	</head>
</html>
```

### Disable automatic `Link` header generation Automatic `Link` header

Remove any automatically generated `Link` headers by adding the following to your `_headers` file:

```txt
/*
  ! Link
```

:::caution

Automatic `Link` header generation should not have any negative performance impact on your website. If you need to disable this feature, contact us by letting us know about your circumstance in our [Discord server](https://discord.com/invite/cloudflaredev).

:::

---

# Headers

URL: https://developers.cloudflare.com/pages/configuration/headers/

import { Render } from "~/components";

<Render product="workers" file="custom_headers" params={{ product: "pages" }} />

---

# Monorepos

URL: https://developers.cloudflare.com/pages/configuration/monorepos/

While some apps are built from a single repository, Pages also supports apps with more complex setups. A monorepo is a repository that has multiple subdirectories each containing its own application.

## Set up

You can create multiple projects using the same repository, [in the same way that you would create any other Pages project](/pages/get-started/git-integration). You have the option to vary the build command and/or root directory of your project to tell Pages where you would like your build command to run. All project names must be unique even if connected to the same repository.

## Builds

When you connect a git repository to Pages, by default a change to any file in the repository will trigger a Pages build.

![Monorepo example diagram](~/assets/images/pages/configuration/pages-path.png)

Take for example `my-monorepo` above with two associated Pages projects (`marketing-app` and `ecommerce-app`) and their listed dependencies. By default, if you change a file in the project directory for `marketing-app`, then a build for the `ecommerce-app` project will also be triggered, even though `ecommerce-app` and its dependencies have not changed. To avoid such duplicate builds, you can include and exclude both [build watch paths](/pages/configuration/build-watch-paths) or [branches](/pages/configuration/branch-build-controls) to specify if Pages should skip a build for a given project.

## Git integration

Once you've created a separate Pages project for each of the projects within your Git repository, each Git push will issue a new build and deployment for all connected projects unless specified in your build configuration.

GitHub will display separate comments for each project with the updated project and deployment URL if there is a Pull Request associated with the branch.

### GitHub check runs and GitLab commit statuses

If you have multiple projects associated with your repository, your [GitHub check run](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks#checks) or [Gitlab commit status](https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html) will appear like the following on your repository:

![GitHub check run](~/assets/images/pages/configuration/ghcheckrun.png)
![GitLab commit status](~/assets/images/pages/configuration/glcommitstatus.png)

If a build skips for any reason (i.e. CI Skip, build watch paths, or branch deployment controls), the check run/commit status will not appear.

## Monorepo management tools:

While Pages does not provide specialized tooling for dependency management in monorepos, you may choose to bring additional tooling to help manage your repository. For simple subpackage management, you can utilize tools like [npm](https://docs.npmjs.com/cli/v8/using-npm/workspaces), [pnpm](https://pnpm.io/workspaces), and [Yarn](https://yarnpkg.com/features/workspaces) workspaces. You can also use more powerful tools such as [Turborepo](https://turbo.build/repo/docs), [NX](https://nx.dev/getting-started/intro), or [Lerna](https://lerna.js.org/docs/getting-started) to additionally manage dependencies and task execution.

## Limitations

- You must be using [Build System V2](/pages/configuration/build-image/#v2-build-system) or later in order for monorepo support to be enabled.
- You can configure a maximum of 5 Pages projects per repository. If you need this limit raised, contact your Cloudflare account team or use the [Limit Increase Request Form](https://docs.google.com/forms/d/e/1FAIpQLSd_fwAVOboH9SlutMonzbhCxuuuOmiU1L_I5O2CFbXf_XXMRg/viewform).

---

# Preview deployments

URL: https://developers.cloudflare.com/pages/configuration/preview-deployments/

Preview deployments allow you to preview new versions of your project without deploying it to production. To view preview deployments:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your project and find the deployment you would like to view.

Every time you open a new pull request on your GitHub repository, Cloudflare Pages will create a unique preview URL, which will stay updated as you continue to push new commits to the branch. This is only true when pull requests originate from the repository itself.

![GitHub Preview URLs](~/assets/images/pages/configuration/ghpreviewurls.png)

For example, if you have a repository called `user-example` connected to Pages, this will give you a `user-example.pages.dev` subdomain. If `main` is your default branch, then any commits to the `main` branch will update your `user-example.pages.dev` content, as well as any [custom domains](/pages/configuration/custom-domains/) attached to the project.

![User-example repository's deployment status and preview](~/assets/images/pages/platform/preview-deployment-mergedone.png)

While developing `user-example`, you may push new changes to a `development` branch, for example.

In this example, after you create the new `development` branch, Pages will automatically generate a preview deployment for these changes available at `373f31e2.user-example.pages.dev` - where `373f31e2` is a randomly generated hash.

Each new branch you create will receive a new, randomly-generated hash in front of your `pages.dev` subdomain.

![User-example repository's newly generated preview deployment link and status](~/assets/images/pages/platform/preview-deployment-generated.png)

Any additional changes to the `development` branch will continue to update this `373f31e2.user-example.pages.dev` preview address until the `development` branch is merged with the `main` production branch.

Any custom domains, as well as your `user-example.pages.dev` site, will not be affected by preview deployments.

## Customize preview deployments access

You can use [Cloudflare Access](/cloudflare-one/policies/access/) to manage access to your deployment previews. By default, these deployment URLs are public. Enabling the access policy will restrict viewing project deployments to your Cloudflare account.

Once enabled, you can [set up a multi-user account](/fundamentals/manage-members/) to allow other members of your team to view preview deployments.

By default, preview deployments are enabled and available publicly. In your project's settings, you can require visitors to authenticate to view preview deployment. This allows you to lock down access to these preview deployments to your teammates, organization, or anyone else you specify via [Access policies](/cloudflare-one/policies/).

To protect your preview deployments behind Cloudflare Access:

1. Log in to [Cloudflare dashboard](https://dash.cloudflare.com/login).
2. In Account Home, select **Workers & Pages**.
3. In **Overview**, select your Pages project.
4. Go to **Settings** > **General** > and select **Enable access policy**.

Note that this will only protect your preview deployments (for example, `373f31e2.user-example.pages.dev` and every other randomly generated preview link) and not your `*.pages.dev` domain or custom domain.

:::note

If you want to enable Access for your `*.pages.dev` domain and your custom domain along with your preview deployments, review [Known issues](/pages/platform/known-issues/#enable-access-on-your-pagesdev-domain) for instructions.

:::

## Preview aliases

When a preview deployment is published, it is given a unique, hash-based address — for example, `<hash>.<project>.pages.dev`. These are atomic and may always be visited in the future. However, Pages also creates an alias for `git` branch's name and updates it so that the alias always maps to the latest commit of that branch.

For example, if you push changes to a `development` branch (which is not associated with your Production environment), then Pages will deploy to `abc123.<project>.pages.dev` and alias `development.<project>.pages.dev` to it. Later, you may push new work to the `development` branch, which creates the `xyz456.<project>.pages.dev` deployment. At this point, the `development.<project>.pages.dev` alias points to the `xyz456` deployment, but `abc123.<project>.pages.dev` remains accessible directly.

Branch name aliases are lowercased and non-alphanumeric characters are replaced with a hyphen — for example, the `fix/api` branch creates the `fix-api.<project>.pages.dev` alias.

To view branch aliases within your Pages project, select **View build** for any preview deployment. **Deployment details** will display all aliases associated with that deployment.

You can attach a Preview alias to a custom domain by [adding a custom domain to a branch](https://developers.cloudflare.com/pages/how-to/custom-branch-aliases/).

---

# Redirects

URL: https://developers.cloudflare.com/pages/configuration/redirects/

import { Render } from "~/components";

<Render product="workers" file="redirects" params={{ product: "pages" }} />

---

# Rollbacks

URL: https://developers.cloudflare.com/pages/configuration/rollbacks/

Rollbacks allow you to instantly revert your project to a previous production deployment.

Any production deployment that has been successfully built is a valid rollback target. When your project has rolled back to a previous deployment, you may still rollback to deployments that are newer than your current version. Note that preview deployments are not valid rollback targets.

In order to perform a rollback, go to **Deployments** in your Pages project. Browse the **All deployments** list and select the three dotted actions menu for the desired target. Select **Rollback to this deployment** for a confirmation window to appear. When confirmed, your project's production deployment will change instantly.

![Deployments for your Pages project that can be used for rollbacks](~/assets/images/pages/platform/rollbacks.png)

## Related resources

- [Preview Deployments](/pages/configuration/preview-deployments/)
- [Branch deployment controls](/pages/configuration/branch-build-controls/)

---

# Serving Pages

URL: https://developers.cloudflare.com/pages/configuration/serving-pages/

Cloudflare Pages includes a number of defaults for serving your Pages sites. This page details some of those decisions, so you can understand how Pages works, and how you might want to override some of the default behaviors.

## Route matching

If an HTML file is found with a matching path to the current route requested, Pages will serve it. Pages will also redirect HTML pages to their extension-less counterparts: for instance, `/contact.html` will be redirected to `/contact`, and `/about/index.html` will be redirected to `/about/`.

## Not Found behavior

You can define a custom page to be displayed when Pages cannot find a requested file by creating a `404.html` file. Pages will then attempt to find the closest 404 page. If one is not found in the same directory as the route you are currently requesting, it will continue to look up the directory tree for a matching `404.html` file, ending in `/404.html`. This means that you can define custom 404 paths for situations like `/blog/404.html` and `/404.html`, and Pages will automatically render the correct one depending on the situation.

## Single-page application (SPA) rendering

If your project does not include a top-level `404.html` file, Pages assumes that you are deploying a single-page application. This includes frameworks like React, Vue, and Angular. Pages' default single-page application behavior matches all incoming paths to the root (`/`), allowing you to capture URLs like `/about` or `/help` and respond to them from within your SPA.

## Caching and performance

### Recommendations

In most situations, you should avoid setting up any custom caching on your site. Pages comes with built in caching defaults that are optimized for caching as much as possible, while providing the most up to date content. Every time you deploy an asset to Pages, the asset remains cached on the Cloudflare CDN until your next deployment.

Therefore, if you add caching to your [custom domain](/pages/configuration/custom-domains/), it may lead to stale assets being served after a deployment.

In addition, adding caching to your custom domain may cause issues with [Pages redirects](/pages/configuration/redirects/) or [Pages functions](/pages/functions/). These issues can occur because the cached response might get served to your end user before Pages can act on the request.

However, there are some situations where [Cache Rules](/cache/how-to/cache-rules/) on your custom domain does make sense. For example, you may have easily cacheable locations for immutable assets, such as CSS or JS files with content hashes in their file names. Custom caching can help in this case, speeding up the user experience until the file (and associated filename) changes. Just make sure that your caching does not interfere with any redirects or Functions.

Note that when you use Cloudflare Pages, the static assets that you upload as part of your Pages project are automatically served from [Tiered Cache](/cache/how-to/tiered-cache/). You do not need to separately enable Tiered Cache for the custom domain that your Pages project runs on.

:::note[Purging the cache]

If you notice stale assets being served after a new deployment, go to your zone and then **Caching** > **Configuration** > [**Purge Everything**](/cache/how-to/purge-cache/purge-everything/) to ensure the latest deployment gets served.

:::

### Behavior

For browser caching, Pages always sends `Etag` headers for `200 OK` responses, which the browser then returns in an `If-None-Match` header on subsequent requests for that asset. Pages compares the `If-None-Match` header from the request with the `Etag` it's planning to send, and if they match, Pages instead responds with a `304 Not Modified` that tells the browser it's safe to use what is stored in local cache.

Pages currently returns `200` responses for HTTP range requests; however, the team is working on adding spec-compliant `206` partial responses.

Pages will also serve Gzip and Brotli responses whenever possible.

## Asset retention

We will insert assets into the cache on a per-data center basis. Assets have a time-to-live (TTL) of one week but can also disappear at any time. If you do a new deploy, the assets could exist in that data center up to one week.

## Headers

By default, Pages automatically adds several [HTTP response headers](https://developer.mozilla.org/en-US/docs/Glossary/Response_header) when serving assets, including:

```txt title="Headers always added"
Access-Control-Allow-Origin: *
Cf-Ray: $CLOUDFLARE_RAY_ID
Referrer-Policy: strict-origin-when-cross-origin
Etag: $ETAG
Content-Type: $CONTENT_TYPE
X-Content-Type-Options: nosniff
Server: cloudflare
```

:::note

The [`Cf-Ray`](/fundamentals/reference/cloudflare-ray-id/) header is unique to Cloudflare.

:::

```txt title="Headers sometimes added"
// if the asset has been encoded
Cache-Control: no-transform
Content-Encoding: $CONTENT_ENCODING

// if the asset is cacheable (the request does not have an `Authorization` or `Range` header)
Cache-Control: public, max-age=0, must-revalidate

// if requesting the asset over a preview URL
X-Robots-Tag: noindex
```

To modify the headers added by Cloudflare Pages - perhaps to add [Early Hints](/pages/configuration/early-hints/) - update the [\_headers file](/pages/configuration/headers/) in your project.

---

# Blazor

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-blazor-site/

import { Render } from "~/components";

[Blazor](https://blazor.net) is an SPA framework that can use C# code, rather than JavaScript in the browser. In this guide, you will build a site using Blazor, and deploy it using Cloudflare Pages.

## Install .NET

Blazor uses C#. You will need the latest version of the [.NET SDK](https://dotnet.microsoft.com/download) to continue creating a Blazor project. If you don't have the SDK installed on your system please download and run the installer.

## Creating a new Blazor WASM project

There are two types of Blazor hosting models: [Blazor Server](https://learn.microsoft.com/en-us/aspnet/core/blazor/hosting-models?view=aspnetcore-8.0#blazor-server) which requires a server to serve the Blazor application to the end user, and [Blazor WebAssembly](https://learn.microsoft.com/en-us/aspnet/core/blazor/hosting-models?view=aspnetcore-8.0#blazor-webassembly) which runs in the browser. Blazor Server is incompatible with the Cloudflare edge network model, thus this guide only use Blazor WebAssembly.

Create a new Blazor WebAssembly (WASM) application by running the following command:

```sh
dotnet new blazorwasm -o my-blazor-project
```

## Create the build script

To deploy, Cloudflare Pages will need a way to build the Blazor project. In the project's directory root, create a `build.sh` file. Populate the file with this (updating the `.dotnet-install.sh` line appropriately if you're not using the latest .NET SDK):

```
#!/bin/sh
curl -sSL https://dot.net/v1/dotnet-install.sh > dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh -c 8.0 -InstallDir ./dotnet
./dotnet/dotnet --version
./dotnet/dotnet publish -c Release -o output
```

Your `build.sh` file needs to be executable for the build command to work. You can make it so by running `chmod +x build.sh`.

<Render file="tutorials-before-you-start" />

## Create a `.gitignore` file

Creating a `.gitignore` file ensures that only what is needed gets pushed onto your GitHub repository. Create a `.gitignore` file by running the following command:

```sh
dotnet new gitignore
```

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-no-preset" />

<div>

| Configuration option | Value            |
| -------------------- | ---------------- |
| Production branch    | `main`           |
| Build command        | `./build.sh`     |
| Build directory      | `output/wwwroot` |

</div>

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `dotnet`, your project dependencies, and building your site, before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your Blazor site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

## Troubleshooting

### A file is over the 25 MiB limit

If you receive the error message `Error: Asset "/opt/buildhome/repo/output/wwwroot/_framework/dotnet.wasm" is over the 25MiB limit`, resolve this by doing one of the following actions:

1. Reduce the size of your assets with the following [guide](https://docs.microsoft.com/en-us/aspnet/core/blazor/performance?view=aspnetcore-6.0#minimize-app-download-size).

Or

2. Remove the `*.wasm` files from the output (`rm output/wwwroot/_framework/*.wasm`) and modify your Blazor application to [load the Brotli compressed files](https://docs.microsoft.com/en-us/aspnet/core/blazor/host-and-deploy/webassembly?view=aspnetcore-6.0#compression) instead.

<Render file="framework-guides/learn-more" params={{ one: "Blazor" }} />

---

# Docusaurus

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-docusaurus-site/

import { PagesBuildPreset, Render, PackageManagers } from "~/components";

[Docusaurus](https://docusaurus.io) is a static site generator. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site such as a personal website, a product site, a blog, or marketing landing pages.

## Set up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up your project. C3 will create a new project directory, initiate Docusaurus' official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Docusaurus project, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-docusaurus-app --framework=docusaurus --platform=pages"
/>

`create-cloudflare` will install additional dependencies, including the [Wrangler](/workers/wrangler/install-and-update/#check-your-wrangler-version) CLI and any necessary adapters, and ask you setup questions.

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render file="deploy-via-c3" params={{ name: "Docusaurus" }} />

### Deploy via the Cloudflare dashboard

<Render
	file="deploy-to-pages-steps-with-preset"
	params={{ name: "Docusarus" }}
/>

<PagesBuildPreset framework="docusaurus" />

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.

Every time you commit new code to your Docusaurus site and push those changes to GitHub, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests and be able to preview how changes look to your site before deploying them to production.

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

<Render file="framework-guides/learn-more" params={{ one: "Docusaurus" }} />

---

# Brunch

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-brunch-site/

import { PagesBuildPreset, Render } from "~/components";

[Brunch](https://brunch.io/) is a fast front-end web application build tool with simple declarative configuration and seamless incremental compilation for rapid development.

## Install Brunch

To begin, install Brunch:

```sh
npm install -g brunch
```

## Create a Brunch project

Brunch maintains a library of community-provided [skeletons](https://brunch.io/skeletons) to offer you a boilerplate for your project. Run Brunch's recommended `es6` skeleton with the `brunch new` command:

```sh
brunch new proj -s es6
```

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Brunch" }} />

<PagesBuildPreset framework="brunch" />

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.

Every time you commit new code to your Brunch site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests and be able to preview how changes look to your site before deploying them to production.

<Render file="framework-guides/learn-more" params={{ one: "Brunch" }} />

---

# Gatsby

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-gatsby-site/

import { PagesBuildPreset, Render } from "~/components";

[Gatsby](https://www.gatsbyjs.com/) is an open-source React framework for creating websites and apps. In this guide, you will create a new Gatsby application and deploy it using Cloudflare Pages. You will be using the `gatsby` CLI to create a new Gatsby site.

## Install Gatsby

Install the `gatsby` CLI by running the following command in your terminal:

```sh
npm install -g gatsby-cli
```

## Create a new project

With Gatsby installed, you can create a new project using `gatsby new`. The `new` command accepts a GitHub URL for using an existing template. As an example, use the `gatsby-starter-lumen` template by running the following command in your terminal. You can find more in [Gatsby's Starters section](https://www.gatsbyjs.com/starters/?v=2):

```sh
npx gatsby new my-gatsby-site https://github.com/alxshelepenok/gatsby-starter-lumen
```

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository_no_init" />

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Gatsby" }} />

<PagesBuildPreset framework="gatsby" />

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `gatsby`, your project dependencies, and building your site, before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your Gatsby site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

## Dynamic routes

If you are using [dynamic routes](https://www.gatsbyjs.com/docs/reference/functions/routing/#dynamic-routing) in your Gatsby project, set up a [proxy redirect](/pages/configuration/redirects/#proxying) for these routes to take effect.

If you have a dynamic route, such as `/users/[id]`, create your proxy redirect by referring to the following example:

```
/users/* /users/:id 200
```

<Render file="framework-guides/learn-more" params={{ one: "Gatsby" }} />

---

# Gridsome

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-gridsome-site/

import { PagesBuildPreset, Render } from "~/components";

[Gridsome](https://gridsome.org) is a Vue.js powered Jamstack framework for building static generated websites and applications that are fast by default. In this guide, you will create a new Gridsome project and deploy it using Cloudflare Pages. You will use the [`@gridsome/cli`](https://github.com/gridsome/gridsome/tree/master/packages/cli), a command line tool for creating new Gridsome projects.

## Install Gridsome

Install the `@gridsome/cli` by running the following command in your terminal:

```sh
npm install --global @gridsome/cli
```

## Set up a new project

With Gridsome installed, set up a new project by running `gridsome create`. The `create` command accepts a name that defines the directory of the project created and an optional starter kit name. You can review more starters in the [Gridsome starters section](https://gridsome.org/docs/starters/).

```sh
npx gridsome create my-gridsome-website
```

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

To deploy your site to Pages:

<Render
	file="deploy-to-pages-steps-with-preset"
	params={{ name: "Gridsome" }}
/>

<PagesBuildPreset framework="gridsome" />

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `vuepress`, your project dependencies, and building your site, before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`. Every time you commit new code to your Gridsome project, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes to your site look before deploying them to production.

<Render file="framework-guides/learn-more" params={{ one: "Gridsome" }} />

---

# Hexo

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-hexo-site/

import { Render } from "~/components";

[Hexo](https://hexo.io/) is a tool for generating static websites, powered by Node.js. Hexo's benefits include speed, simplicity, and flexibility, allowing it to render Markdown files into static web pages via Node.js.

In this guide, you will create a new Hexo application and deploy it using Cloudflare Pages. You will use the `hexo` CLI to create a new Hexo site.

## Installing Hexo

First, install the Hexo CLI with `npm` or `yarn` by running either of the following commands in your terminal:

```sh
npm install hexo-cli -g
# or
yarn global add hexo-cli
```

On macOS and Linux, you can install with [brew](https://brew.sh/):

```sh
brew install hexo
```

<Render file="tutorials-before-you-start" />

## Creating a new project

With Hexo CLI installed, create a new project by running the `hexo init` command in your terminal:

```sh
hexo init my-hexo-site
cd my-hexo-site
```

Hexo sites use themes to customize the appearance of statically built HTML sites. Hexo has a default theme automatically installed, which you can find on [Hexo's Themes page](https://hexo.io/themes/).

## Creating a post

Create a new post to give your Hexo site some initial content. Run the `hexo new` command in your terminal to generate a new post:

```sh
hexo new "hello hexo"
```

Inside of `hello-hexo.md`, use Markdown to write the content of the article. You can customize the tags, categories or other variables in the article. Refer to the [Front Matter section](https://hexo.io/docs/front-matter) of the [Hexo documentation](https://hexo.io/docs/) for more information.

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-no-preset" />

<div>

| Configuration option | Value           |
| -------------------- | --------------- |
| Production branch    | `main`          |
| Build command        | `npm run build` |
| Build directory      | `public`        |

</div>

After completing configuration, click the **Save and Deploy** button. You should see Cloudflare Pages installing `hexo` and your project dependencies, and building your site, before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your Hexo site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

## Using a specific Node.js version

Some Hexo themes or plugins have additional requirements for different Node.js versions. To use a specific Node.js version for Hexo:

1. Go to your Pages project.
2. Go to **Settings** > **Environment variables**.
3. Set the environment variable `NODE_VERSION` and a value of your required Node.js version (for example, `14.3`).

![Follow the instructions above to set up an environment variable in the Pages dashboard](~/assets/images/pages/framework-guides/node-version-pages.png)

<Render file="framework-guides/learn-more" params={{ one: "Hexo" }} />

---

# Hono

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-hono-site/

import {
	ResourcesBySelector,
	ExternalResources,
	Render,
	TabItem,
	Tabs,
	PackageManagers,
	Stream,
} from "~/components";

[Hono](https://honojs.dev/) is a small, simple, and ultrafast web framework for Cloudflare Pages and Workers, Deno, and Bun. Learn more about the creation of Hono by [watching an interview](#creator-interview) with its creator, [Yusuke Wada](https://yusu.ke/).

In this guide, you will create a new Hono application and deploy it using Cloudflare Pages.

## Create a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to create a new project. C3 will create a new project directory, initiate Hono's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Hono project, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-hono-app --framework=hono --platform=pages"
/>

In your new Hono project, you will find a `public/static` directory for your static files, and a `src/index.ts` file which is the entrypoint for your server-side code.

## Run in local dev

Develop your app locally by running:

<PackageManagers type="run" args={"dev"} />

You should be able to review your generated web application at `http://localhost:8788`.

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render file="deploy-via-c3" params={{ name: "Hono" }} />

### Deploy via the Cloudflare dashboard

<Render file="deploy-to-pages-steps-no-preset" />

<div>

| Configuration option | Value           |
| -------------------- | --------------- |
| Production branch    | `main`          |
| Build command        | `npm run build` |
| Build directory      | `dist`          |

</div>

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `my-hono-app`, your project dependencies, and building your site before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your Hono site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

## Related resources

### Tutorials

For more tutorials involving Hono and Cloudflare Pages, refer to the following resources:

<ResourcesBySelector
	tags={["Hono"]}
	types={["tutorial"]}
	products={["Pages"]}
/>

### Demo apps

For demo applications using Hono and Cloudflare Pages, refer to the following resources:

<ExternalResources tags={["Hono"]} type="apps" products={["Pages"]} />

### Creator Interview

<Stream
	id="db240ef1d351915849151242ec0c5f1c"
	title="DevTalk Episode 01 Hono"
	thumbnail="5s"
/>

---

# Hugo

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/

import { PagesBuildPreset, Render, TabItem, Tabs } from "~/components";

[Hugo](https://gohugo.io/) is a tool for generating static sites, written in Go. It is incredibly fast and has great high-level, flexible primitives for managing your content using different [content formats](https://gohugo.io/content-management/formats/).

In this guide, you will create a new Hugo application and deploy it using Cloudflare Pages. You will use the `hugo` CLI to create a new Hugo site.

<Render file="tutorials-before-you-start" />

Go to [Deploy with Cloudflare Pages](#deploy-with-cloudflare-pages) if you already have a Hugo site hosted with your [Git provider](/pages/get-started/git-integration/).

## Install Hugo

Install the Hugo CLI, using the specific instructions for your operating system.

<Tabs> <TabItem label="macos">

If you use the package manager [Homebrew](https://brew.sh), run the `brew install` command in your terminal to install Hugo:

```sh
brew install hugo
```

</TabItem>
<TabItem label="windows">

If you use the package manager [Chocolatey](https://chocolatey.org/), run the `choco install` command in your terminal to install Hugo:

```sh
choco install hugo --confirm
```

If you use the package manager [Scoop](https://scoop.sh/), run the `scoop install` command in your terminal to install Hugo:

```sh
scoop install hugo
```

</TabItem>
<TabItem label="linux">

The package manager for your Linux distribution may include Hugo. If this is the case, install Hugo directly using the distribution's package manager — for instance, in Ubuntu, run the following command:

```sh
sudo apt-get install hugo
```

If your package manager does not include Hugo or you would like to download a release directly, refer to the [**Manual**](/pages/framework-guides/deploy-a-hugo-site/#manual-installation) section.

</TabItem>
</Tabs>

### Manual installation

The Hugo GitHub repository contains pre-built versions of the Hugo command-line tool for various operating systems, which can be found on [the Releases page](https://github.com/gohugoio/hugo/releases).

For more instruction on installing these releases, refer to [Hugo's documentation](https://gohugo.io/getting-started/installing/).

## Create a new project

With Hugo installed, refer to [Hugo's Quick Start](https://gohugo.io/getting-started/quick-start/) to create your project or create a new project by running the `hugo new` command in your terminal:

```sh
hugo new site my-hugo-site
```

Hugo sites use themes to customize the look and feel of the statically built HTML site. There are a number of themes available at [themes.gohugo.io](https://themes.gohugo.io) — for now, use the [Ananke theme](https://themes.gohugo.io/themes/gohugo-theme-ananke/) by running the following commands in your terminal:

```sh
cd my-hugo-site
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo "theme = 'ananke'" >> hugo.toml
```

## Create a post

Create a new post to give your Hugo site some initial content. Run the `hugo new` command in your terminal to generate a new post:

```sh
hugo new content posts/hello-world.md
```

Inside of `hello-world.md`, add some initial content to create your post. Remove the `draft` line in your post's frontmatter when you are ready to publish the post. Any posts with `draft: true` set will be skipped by Hugo's build process.

<Render file="framework-guides/create-github-repository_no_init" />

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Hugo" }} />

<PagesBuildPreset framework="hugo" />

:::note[Base URL configuration]

Hugo allows you to configure the `baseURL` of your application. This allows you to utilize the `absURL` helper to construct full canonical URLs. In order to do this with Pages, you must provide the `-b` or `--baseURL` flags with the `CF_PAGES_URL` environment variable to your `hugo` build command.

Your final build command may look like this:

```sh
hugo -b $CF_PAGES_URL
```

:::

After completing deployment configuration, select the **Save and Deploy**. You should see Cloudflare Pages installing `hugo` and your project dependencies, and building your site, before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your Hugo site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

## Use a specific or newer Hugo version

To use a [specific or newer version of Hugo](https://github.com/gohugoio/hugo/releases), create the `HUGO_VERSION` environment variable in your Pages project > **Settings** > **Environment variables**. Set the value as the Hugo version you want to specify (v0.112.0 or later is recommended for newer versions).

For example, `HUGO_VERSION`: `0.115.4`.

:::note

If you plan to use [preview deployments](/pages/configuration/preview-deployments/), make sure you also add environment variables to your **Preview** environment.

:::

<Render file="framework-guides/learn-more" params={{ one: "Hugo" }} />

---

# Jekyll

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-jekyll-site/

import { PagesBuildPreset, Render } from "~/components";

[Jekyll](https://jekyllrb.com/) is an open-source framework for creating websites, based around Markdown with Liquid templates. In this guide, you will create a new Jekyll application and deploy it using Cloudflare Pages. You use the `jekyll` CLI to create a new Jekyll site.

:::note

If you have an existing Jekyll site on GitHub Pages, refer to [the Jekyll migration guide](/pages/migrations/migrating-jekyll-from-github-pages/).

:::

## Installing Jekyll

Jekyll is written in Ruby, meaning that you will need a functioning Ruby installation, like `rbenv`, to install Jekyll.

To install Ruby on your computer, follow the [`rbenv` installation instructions](https://github.com/rbenv/rbenv#installation) and select a recent version of Ruby by running the `rbenv` command in your terminal. The Ruby version you install will also be used to configure the Pages deployment for your application.

```sh
rbenv install <RUBY_VERSION> # For example, 3.1.3
```

With Ruby installed, you can install the `jekyll` Ruby gem:

```sh
gem install jekyll
```

## Creating a new project

With Jekyll installed, you can create a new project running the `jekyll new` in your terminal:

```sh
jekyll new my-jekyll-site
```

Create a base `index.html` in your newly created folder to give your site content:

```html
<!doctype html>
<html>
	<head>
		<meta charset="utf-8" />
		<title>Hello from Cloudflare Pages</title>
	</head>
	<body>
		<h1>Hello from Cloudflare Pages</h1>
	</body>
</html>
```

Optionally, you may use a theme with your new Jekyll site if you would like to start with great styling defaults. For example, the [`minimal-mistakes`](https://github.com/mmistakes/minimal-mistakes) theme has a ["Starting from `jekyll new`"](https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/#starting-from-jekyll-new) section to help you add the theme to your new site.

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository_no_init" />

If you are migrating an existing Jekyll project to Pages, confirm that your `Gemfile` is committed as part of your codebase. Pages will look at your Gemfile and run `bundle install` to install the required dependencies for your project, including the `jekyll` gem.

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Jekyll" }} />

<PagesBuildPreset framework="jekyll" />

Add an [environment variable](/pages/configuration/build-image/) that matches the Ruby version that you are using locally. Set this as `RUBY_VERSION` on both your preview and production deployments. Below, `3.1.3` is used as an example:

| Environment variable | Value   |
| -------------------- | ------- |
| `RUBY_VERSION`       | `3.1.3` |

After configuring your site, you can begin your first deployment. You should see Cloudflare Pages installing `jekyll`, your project dependencies, and building your site before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to [the Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your Jekyll site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

<Render file="framework-guides/learn-more" params={{ one: "Jekyll" }} />

---

# Nuxt

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-nuxt-site/

import {
	PagesBuildPreset,
	Render,
	TabItem,
	Tabs,
	ResourcesBySelector,
	ExternalResources,
	PackageManagers,
	Stream,
} from "~/components";

[Nuxt](https://nuxt.com) is a web framework making Vue.js-based development simple and powerful.

In this guide, you will create a new Nuxt application and deploy it using Cloudflare Pages.

### Video Tutorial

<Stream
	id="fd106a56e13af42eb39b35c499432e4b"
	title="Deploy a Nuxt Application to Cloudflare"
	thumbnail="2.5s"
/>

## Create a new project using the `create-cloudflare` CLI (C3)

The [`create-cloudflare` CLI (C3)](/pages/get-started/c3/) will configure your Nuxt site for Cloudflare Pages. Run the following command in your terminal to create a new Nuxt site:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-nuxt-app --framework=nuxt --platform=pages"
/>

C3 will ask you a series of setup questions and create a new project with [`nuxi` (the official Nuxt CLI)](https://github.com/nuxt/cli). C3 will also install the necessary adapters along with the [Wrangler CLI](/workers/wrangler/install-and-update/#check-your-wrangler-version).

After creating your project, C3 will generate a new `my-nuxt-app` directory using the default Nuxt template, updated to be fully compatible with Cloudflare Pages.

When creating your new project, C3 will give you the option of deploying an initial version of your application via [Direct Upload](/pages/how-to/use-direct-upload-with-continuous-integration/). You can redeploy your application at any time by running following command inside your project directory:

```sh
npm run deploy
```

:::note[Git integration]

The initial deployment created via C3 is referred to as a [Direct Upload](/pages/get-started/direct-upload/). To set up a deployment via the Pages Git integration, refer to the [Git Integration](#git-integration) section below.

:::

## Configure and deploy a project without C3

To deploy a Nuxt project without C3, follow the [Nuxt Get Started guide](https://nuxt.com/docs/getting-started/installation). After you have set up your Nuxt project, choose either the [Git integration guide](/pages/get-started/git-integration/) or [Direct Upload guide](/pages/get-started/direct-upload/) to deploy your Nuxt project on Cloudflare Pages.

<Render file="framework-guides/git-integration" />

### Create a GitHub repository

<Render file="framework-guides/create-gh-repo" />

```sh
# Skip the following three commands if you have built your application
# using C3 or already committed your changes
git init
git add .
git commit -m "Initial commit"

git branch -M main
git remote add origin https://github.com/<YOUR_GH_USERNAME>/<REPOSITORY_NAME>
git push -u origin main
```

### Create a Pages project

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Nuxt.js" }} />

<PagesBuildPreset framework="nuxt-js" />

Optionally, you can customize the **Project name** field. It defaults to the GitHub repository's name, but it does not need to match. The **Project name** value is assigned as your `*.pages.dev` subdomain.

4. After completing configuration, select the **Save and Deploy**.

Review your first deploy pipeline in progress. Pages installs all dependencies and builds the project as specified. Cloudflare Pages will automatically rebuild your project and deploy it on every new pushed commit.

Additionally, you will have access to [preview deployments](/pages/configuration/preview-deployments/), which repeat the build-and-deploy process for pull requests. With these, you can preview changes to your project with a real URL before deploying your changes to production.

## Use bindings in your Nuxt application

A [binding](/pages/functions/bindings/) allows your application to interact with Cloudflare developer products, such as [KV](/kv/), [Durable Objects](/durable-objects/), [R2](/r2/), and [D1](/d1/).

If you intend to use bindings in your project, you must first set up your bindings for local and remote development.

### Set up bindings for local development

Projects created via C3 come with `nitro-cloudflare-dev`, a `nitro` module that simplifies the process of working with bindings during development:

```typescript
export default defineNuxtConfig({
	modules: ["nitro-cloudflare-dev"],
});
```

This module is powered by the [`getPlatformProxy` helper function](/workers/wrangler/api#getplatformproxy). `getPlatformProxy` will automatically detect any bindings defined in your project's Wrangler configuration file and emulate those bindings in local development. Review [Wrangler configuration information on bindings](/workers/wrangler/configuration/#bindings) for more information on how to configure bindings in the [Wrangler configuration file](/workers/wrangler/configuration/).

:::note

`wrangler.toml` is currently **only** used for local development. Bindings specified in it are not available remotely.

:::

### Set up bindings for a deployed application

In order to access bindings in a deployed application, you will need to [configure your bindings](/pages/functions/bindings/) in the Cloudflare dashboard.

### Add bindings to TypeScript projects

To get proper type support, you need to create a new `env.d.ts` file in the root of your project and declare a [binding](/pages/functions/bindings/). Make sure you have generated Cloudflare runtime types by running [`wrangler types`](/pages/functions/typescript/).

The following is an example of adding a `KVNamespace` binding:

```ts null {9}

declare module "h3" {
	interface H3EventContext {
		cf: CfProperties;
		cloudflare: {
			request: Request;
			env: {
				MY_KV: KVNamespace;
			};
			context: ExecutionContext;
		};
	}
}
```

### Access bindings in your Nuxt application

In Nuxt, add server-side code via [Server Routes and Middleware](https://nuxt.com/docs/guide/directory-structure/server#server-directory). The `defineEventHandler()` method is used to define your API endpoints in which you can access Cloudflare's context via the provided `context` field. The `context` field allows you to access any bindings set for your application.

The following code block shows an example of accessing a KV namespace in Nuxt.

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```javascript null {2}
export default defineEventHandler(({ context }) => {
	const MY_KV = context.cloudflare.env.MY_KV;

	return {
		// ...
	};
});
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```typescript null {2}
export default defineEventHandler(({ context }) => {
	const MY_KV = context.cloudflare.env.MY_KV;

	return {
		// ...
	};
});
```

</TabItem> </Tabs>

<Render file="framework-guides/learn-more" params={{ one: "Nuxt" }} />

## Related resources

### Tutorials

For more tutorials involving Nuxt, refer to the following resources:

<ResourcesBySelector tags={["Nuxt"]} types={["tutorial"]} />

### Demo apps

For demo applications using Nuxt, refer to the following resources:

<ExternalResources tags={["Nuxt"]} type="apps" />

---

# Pelican

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-pelican-site/

import { PagesBuildPreset, Render } from "~/components";

[Pelican](https://docs.getpelican.com) is a static site generator, written in Python. With Pelican, you can write your content directly with your editor of choice in reStructuredText or Markdown formats.

## Create a Pelican project

To begin, create a Pelican project directory. `cd` into your new directory and run:

```sh
python3 -m pip install pelican
```

Then run:

```sh
pip freeze > requirements.txt
```

Create a directory in your project named `content`:

```sh
mkdir content
```

This is the directory name that you will set in the build command.

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Pelican" }} />

<PagesBuildPreset framework="pelican" />

4. Select **Environment variables (advanced)** and set the `PYTHON_VERSION` variable with the value of `3.7`.

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.

Every time you commit new code to your Pelican site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests and be able to preview how changes look to your site before deploying them to production.

<Render file="framework-guides/learn-more" params={{ one: "Pelican" }} />

---

# Preact

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-preact-site/

import { Render } from "~/components";

[Preact](https://preactjs.com) is a popular, open-source framework for building modern web applications. Preact can also be used as a lightweight alternative to React because the two share the same API and component model.

In this guide, you will create a new Preact application and deploy it using Cloudflare Pages.
You will use [`create-preact`](https://github.com/preactjs/create-preact), a lightweight project scaffolding tool to set up a new Preact app in seconds.

## Setting up a new project

Create a new project by running the [`npm init`](https://docs.npmjs.com/cli/v6/commands/npm-init) command in your terminal, giving it a title:

```sh
npm init preact
cd your-project-name
```

:::note

During initialization, you can accept the `Prerender app (SSG)?` option to have `create-preact` scaffold your app to produce static HTML pages, along with their assets, for production builds. This option is perfect for Pages.

:::

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-no-preset" />

<div>

| Configuration option | Value           |
| -------------------- | --------------- |
| Production branch    | `main`          |
| Build command        | `npm run build` |
| Build directory      | `dist`          |

</div>

Optionally, you can customize the **Project name** field. It defaults to the GitHub repository's name, but it does not need to match. The **Project name** value is assigned as your `*.pages.dev` subdomain.

After completing configuration, select **Save and Deploy**.

You will see your first deploy pipeline in progress. Pages installs all dependencies and builds the project as specified.

After you have deployed your site, you will receive a unique subdomain for your project on `*.pages.dev`.

Cloudflare Pages will automatically rebuild your project and deploy it on every new pushed commit.

Additionally, you will have access to [preview deployments](/pages/configuration/preview-deployments/), which repeat the build-and-deploy process for pull requests. With these, you can preview changes to your project with a real URL before deploying them to production.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

<Render file="framework-guides/learn-more" params={{ one: "Preact" }} />

---

# Qwik

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-qwik-site/

import { PagesBuildPreset, Render, PackageManagers } from "~/components";

[Qwik](https://github.com/builderio/qwik) is an open-source, DOM-centric, resumable web application framework designed for best possible time to interactive by focusing on [resumability](https://qwik.builder.io/docs/concepts/resumable/), server-side rendering of HTML and [fine-grained lazy-loading](https://qwik.builder.io/docs/concepts/progressive/#lazy-loading) of code.

In this guide, you will create a new Qwik application implemented via [Qwik City](https://qwik.builder.io/qwikcity/overview/) (Qwik's meta-framework) and deploy it using Cloudflare Pages.

## Creating a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to create a new project. C3 will create a new project directory, initiate Qwik's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Qwik project, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-qwik-app --framework=qwik --platform=pages"
/>

`create-cloudflare` will install additional dependencies, including the [Wrangler CLI](/workers/wrangler/install-and-update/#check-your-wrangler-version) and any necessary adapters, and ask you setup questions.

As part of the `cloudflare-pages` adapter installation, a `functions/[[path]].ts` file will be created. The `[[path]]` filename indicates that this file will handle requests to all incoming URLs. Refer to [Path segments](/pages/functions/routing/#dynamic-routes) to learn more.

After selecting your server option, change the directory to your project and render your project by running the following command:

```sh
npm start
```

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render file="deploy-via-c3" params={{ name: "Qwik" }} />

### Deploy via the Cloudflare dashboard

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Qwik" }} />

<PagesBuildPreset framework="qwik" />

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `npm`, your project dependencies, and building your site before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your Qwik site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, to preview how changes look to your site before deploying them to production.

## Use bindings in your Qwik application

A [binding](/pages/functions/bindings/) allows your application to interact with Cloudflare developer products, such as [KV](/kv/concepts/how-kv-works/), [Durable Object](/durable-objects/), [R2](/r2/), and [D1](https://blog.cloudflare.com/introducing-d1/).

In QwikCity, add server-side code via [routeLoaders](https://qwik.builder.io/qwikcity/route-loader/) and [actions](https://qwik.builder.io/qwikcity/action/). Then access bindings set for your application via the `platform` object provided by the framework.

The following code block shows an example of accessing a KV namespace in QwikCity.

```typescript null {4,5}
// ...

export const useGetServerTime = routeLoader$(({ platform }) => {
  // the type `KVNamespace` comes from runtime types generated by running `wrangler types`
  const { MY_KV } = (platform.env as { MY_KV: KVNamespace }));

  return {
    // ....
  }
});
```

<Render file="framework-guides/learn-more" params={{ one: "Qwik" }} />

---

# React

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-react-site/

import { PagesBuildPreset, Render, PackageManagers } from "~/components";

[React](https://reactjs.org/) is a popular framework for building reactive and powerful front-end applications, built by the open-source team at Facebook.

In this guide, you will create a new React application and deploy it using Cloudflare Pages.

## Setting up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate React's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new React project, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-react-app --framework=react --platform=pages"
/>

`create-cloudflare` will install dependencies, including the [Wrangler](/workers/wrangler/install-and-update/#check-your-wrangler-version) CLI and the Cloudflare Pages adapter, and ask you setup questions.

Go to the application's directory:

```sh
cd my-react-app
```

From here you can run your application with:

```sh
npm run dev
```

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository_no_init" />

## Deploy with Cloudflare Pages

<Render file="deploy-via-c3" params={{ name: "React" }} />

### Deploy via the Cloudflare dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**.
3. Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information:

<div>

<PagesBuildPreset framework="react" />

</div>

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `react`, your project dependencies, and building your site, before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your React application, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

:::note[SPA rendering]

By default, Cloudflare Pages assumes you are developing a single-page application. Refer to [Serving Pages](/pages/configuration/serving-pages/#single-page-application-spa-rendering) for more information.

:::

<Render file="framework-guides/learn-more" params={{ one: "React" }} />

---

# Remix

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-remix-site/

import {
	PagesBuildPreset,
	Render,
	PackageManagers,
	WranglerConfig,
} from "~/components";

[Remix](https://remix.run/) is a framework that is focused on fully utilizing the power of the web. Like Cloudflare Workers, it uses modern JavaScript APIs, and it places emphasis on web fundamentals such as meaningful HTTP status codes, caching and optimizing for both usability and performance.

In this guide, you will create a new Remix application and deploy to Cloudflare Pages.

## Setting up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Remix's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Remix project, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-remix-app --framework=remix --platform=pages"
/>

`create-cloudflare` will install additional dependencies, including the [Wrangler](/workers/wrangler/install-and-update/#check-your-wrangler-version) CLI and any necessary adapters, and ask you setup questions.

:::caution[Before you deploy]

Your Remix project will include a `functions/[[path]].ts` file. The `[[path]]` filename indicates that this file will handle requests to all incoming URLs. Refer to [Path segments](/pages/functions/routing/#dynamic-routes) to learn more.

The `functions/[[path]].ts` will not function as expected if you attempt to deploy your site before running `remix vite:build`.
:::

After setting up your project, change the directory and render your project by running the following command:

```sh
# choose Cloudflare Pages
cd my-remix-app
npm run dev
```

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository_no_init" />

## Deploy with Cloudflare Pages

<Render file="deploy-via-c3" params={{ name: "Remix" }} />

### Deploy via the Cloudflare dashboard

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Remix" }} />

<PagesBuildPreset framework="remix" />

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `npm`, your project dependencies, and building your site before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your Remix site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

### Deploy via the Wrangler CLI

If you use [`create-cloudflare`(C3)](https://www.npmjs.com/package/create-cloudflare) to create your new Remix project, C3 will automatically scaffold your project with [`wrangler`](/workers/wrangler/). To deploy your project, run the following command:

```sh
npm run deploy
```

## Create and add a binding to your Remix application

To add a binding to your Remix application, refer to [Bindings](/pages/functions/bindings/).
A [binding](/pages/functions/bindings/) allows your application to interact with Cloudflare developer products, such as [KV namespaces](/kv/concepts/how-kv-works/), [Durable Objects](/durable-objects/), [R2 storage buckets](/r2/), and [D1 databases](/d1/).

### Binding resources in local development

Remix uses Wrangler's [`getPlatformProxy`](/workers/wrangler/api/#getplatformproxy) to simulate the Cloudflare environment locally. You configure `getPlatformProxy` in your project's `vite.config.ts` file via [`cloudflareDevProxyVitePlugin`](https://remix.run/docs/en/main/future/vite#cloudflare-proxy).

To bind resources in local development, you need to configure the bindings in the Wrangler file. Refer to [Bindings](/workers/wrangler/configuration/#bindings) to learn more.

Once you have configured the bindings in the Wrangler file, the proxies are then available within `context.cloudflare` in your `loader` or `action` functions:

```typescript
export const loader = ({ context }: LoaderFunctionArgs) => {
	const { env, cf, ctx } = context.cloudflare;
	env.MY_BINDING; // Access bound resources here
	// ... more loader code here...
};
```

:::note[Correcting the env type]

You may have noticed that `context.cloudflare.env` is not typed correctly when you add additional bindings in the [Wrangler configuration file](/workers/wrangler/configuration/).

To fix this, run `npm run typegen` to generate the missing types. This will update the `Env` interface defined in `worker-configuration.d.ts`.
After running the command, you can access the bindings in your `loader` or `action` using `context.cloudflare.env` as shown above.
:::

### Binding resources in production

To bind resources in production, you need to configure the bindings in the Cloudflare dashboard. Refer to the [Bindings](/pages/functions/bindings/) documentation to learn more.

Once you have configured the bindings in the Cloudflare dashboard, the proxies are then available within `context.cloudflare.env` in your `loader` or `action` functions as shown [above](#binding-resources-in-local-development).

## Example: Access your D1 database in a Remix application

As an example, you will bind and query a D1 database in a Remix application.

1. Create a D1 database. Refer to the [D1 documentation](/d1/) to learn more.
2. Configure bindings for your D1 database in the Wrangler file:

<WranglerConfig>

```toml
[[ d1_databases ]]
binding = "DB"
database_name = "<YOUR_DATABASE_NAME>"
database_id = "<YOUR_DATABASE_ID>"
```

</WranglerConfig>

3. Run `npm run typegen` to generate TypeScript types for your bindings.

```sh
npm run typegen
```

```sh output
> typegen
> wrangler types

 ⛅️ wrangler 3.48.0
-------------------
interface Env {
	DB: D1Database;
}
```

4. Access the D1 database in your `loader` function:

```typescript
import type { LoaderFunction } from "@remix-run/cloudflare";
import { json } from "@remix-run/cloudflare";
import { useLoaderData } from "@remix-run/react";

export const loader: LoaderFunction = async ({ context, params }) => {
  const { env, cf, ctx } = context.cloudflare;
  let { results } = await env.DB.prepare(
    "SELECT * FROM products where id = ?1"
  ).bind(params.productId).all();
  return json(results);
};

export default function Index() {
  const results = useLoaderData<typeof loader>();
  return (
    <div>
      <h1>Welcome to Remix</h1>
      <div>
        A value from D1:
        <pre>{JSON.stringify(results)}</pre>
      </div>
    </div>
  );
}
```

<Render file="framework-guides/learn-more" params={{ one: "Remix" }} />

---

# SolidStart

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-solid-start-site/

import { Render, PackageManagers } from "~/components";

[Solid](https://www.solidjs.com/) is an open-source web application framework focused on generating performant applications with a modern developer experience based on JSX.

In this guide, you will create a new Solid application implemented via [SolidStart](https://start.solidjs.com/getting-started/what-is-solidstart) (Solid's meta-framework) and deploy it using Cloudflare Pages.

## Create a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Solid's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Solid project, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-solid-app --framework=solid"
/>

You will be prompted to select a starter. Choose any of the available options. You will then be asked if you want to enable Server Side Rendering. Reply `yes`. Finally, you will be asked if you want to use TypeScript, choose either `yes` or `no`.

`create-cloudflare` will then install dependencies, including the [Wrangler](/workers/wrangler/install-and-update/#check-your-wrangler-version) CLI and the SolidStart Cloudflare Pages adapter, and ask you setup questions.

After you have installed your project dependencies, start your application:

```sh
npm run dev
```

## SolidStart Cloudflare configuration

<Render file="c3-adapter" />

In order to configure SolidStart so that it can be deployed to Cloudflare pages, update its config file like so:

```diff
import { defineConfig } from "@solidjs/start/config";

export default defineConfig({
+  server: {
+    preset: "cloudflare-pages",

+    rollupConfig: {
+      external: ["node:async_hooks"]
+    }
+  }
});
```

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render file="deploy-via-c3" params={{ name: "Solid" }} />

### Deploy via the Cloudflare dashboard

<Render file="deploy-to-pages-steps-no-preset" />

<div>

| Configuration option | Value           |
| -------------------- | --------------- |
| Production branch    | `main`          |
| Build command        | `npm run build` |
| Build directory      | `dist`          |

</div>

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `npm`, your project dependencies, and building your site before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your Solid repository, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, to preview how changes look to your site before deploying them to production.

<Render file="framework-guides/learn-more" params={{ one: "Solid" }} />

---

# Sphinx

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-sphinx-site/

import { Render } from "~/components";

[Sphinx](https://www.sphinx-doc.org/) is a tool that makes it easy to create documentation and was originally made for the publication of Python documentation. It is well known for its simplicity and ease of use.

In this guide, you will create a new Sphinx project and deploy it using Cloudflare Pages.

## Prerequisites

- Python 3 - Sphinx is based on Python, therefore you must have Python installed

- [pip](https://pypi.org/project/pip/) - The PyPA recommended tool for installing Python packages

- [pipenv](https://pipenv.pypa.io/en/latest/) - automatically creates and manages a virtualenv for your projects

:::note

If you are already running a version of Python 3.7, ensure that Python version 3.7 is also installed on your computer before you begin this guide. Python 3.7 is the latest version supported by Cloudflare Pages.

:::

The latest version of Python 3.7 is 3.7.11:

[Python 3.7.11](https://www.python.org/downloads/release/python-3711/)

### Installing Python

Refer to the official Python documentation for installation guidance:

- [Windows](https://www.python.org/downloads/windows/)
- [Linux/UNIX](https://www.python.org/downloads/source/)
- [macOS](https://www.python.org/downloads/macos/)
- [Other](https://www.python.org/download/other/)

### Installing Pipenv

If you already had an earlier version of Python installed before installing version 3.7, other global packages you may have installed could interfere with the following steps to install Pipenv, or your other Python projects which depend on global packages.

[Pipenv](https://pipenv.pypa.io/en/latest/) is a Python-based package manager that makes managing virtual environments simple. This guide will not require you to have prior experience with or knowledge of Pipenv to complete your Sphinx site deployment. Cloudflare Pages natively supports the use of Pipenv and, by default, has the latest version installed.

The quickest way to install Pipenv is by running the command:

```sh
pip install --user pipenv
```

This command will install Pipenv to your user level directory and will make it accessible via your terminal. You can confirm this by running the following command and reviewing the expected output:

```sh
pipenv --version
```

```sh output
pipenv, version 2021.5.29
```

### Creating a Sphinx project directory

From your terminal, run the following commands to create a new directory and navigate to it:

```sh
mkdir my-wonderful-new-sphinx-project
cd my-wonderful-new-sphinx-project
```

### Pipenv with Python 3.7

Pipenv allows you to specify which version of Python to associate with a virtual environment. For the purpose of this guide, the virtual environment for your Sphinx project must use Python 3.7.

Use the following command:

```sh
pipenv --python 3.7
```

You should see the following output:

```bash
Creating a virtualenv for this project...
Pipfile: /home/ubuntu/my-wonderful-new-sphinx-project/Pipfile
Using /usr/bin/python3.7m (3.7.11) to create virtualenv...
⠸ Creating virtual environment...created virtual environment CPython3.7.11.final.0-64 in 1598ms
  creator CPython3Posix(dest=/home/ubuntu/.local/share/virtualenvs/my-wonderful-new-sphinx-project-Y2HfWoOr, clear=False, no_vcs_ignore=False, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/home/ubuntu/.local/share/virtualenv)
    added seed packages: pip==21.1.3, setuptools==57.1.0, wheel==0.36.2
  activators BashActivator,CShellActivator,FishActivator,PowerShellActivator,PythonActivator,XonshActivator

✔ Successfully created virtual environment!
Virtualenv location: /home/ubuntu/.local/share/virtualenvs/my-wonderful-new-sphinx-project-Y2HfWoOr
Creating a Pipfile for this project...
```

List the contents of the directory:

```sh
ls
```

```sh output
Pipfile
```

### Installing Sphinx

Before installing Sphinx, create the directory you want your project to live in.

From your terminal, run the following command to install Sphinx:

```sh
pipenv install sphinx
```

You should see output similar to the following:

```bash
Installing sphinx...
Adding sphinx to Pipfile's [packages]...
✔ Installation Succeeded
Pipfile.lock not found, creating...
Locking [dev-packages] dependencies...
Locking [packages] dependencies...
Building requirements...
Resolving dependencies...
✔ Success!
Updated Pipfile.lock (763aa3)!
Installing dependencies from Pipfile.lock (763aa3)...
  🐍   ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ 0/0 — 00:00:00
To activate this project's virtualenv, run pipenv shell.
Alternatively, run a command inside the virtualenv with pipenv run.
```

This will install Sphinx into a new virtual environment managed by Pipenv. You should see a directory structure like this:

```bash
my-wonderful-new-sphinx-project
|--Pipfile
|--Pipfile.lock
```

## Creating a new project

With Sphinx installed, you can now run the quickstart command to create a template project for you. This command will only work within the Pipenv environment you created in the previous step. To enter that environment, run the following command from your terminal:

```sh
pipenv shell
```

```sh output
Launching subshell in virtual environment...
ubuntu@sphinx-demo:~/my-wonderful-new-sphinx-project$  . /home/ubuntu/.local/share/virtualenvs/my-wonderful-new-sphinx-project-Y2HfWoOr/bin/activate
```

Now run the following command:

```sh
sphinx-quickstart
```

You will be presented with a number of questions, please answer them in the following:

```sh output
Separate source and build directories (y/n) [n]: Y
Project name: <Your project name>
Author name(s): <You Author Name>
Project release []: <You can accept default here or provide a version>
Project language [en]: <You can accept en here or provide a regional language code>
```

This will create four new files in your active directory, `source/conf.py`, `index.rst`, `Makefile` and `make.bat`:

```bash
my-wonderful-new-sphinx-project
|--Pipfile
|--Pipfile.lock
|--source
|----_static
|----_templates
|----conf.py
|----index.rst
|--Makefile
|--make.bat
```

You now have everything you need to start deploying your site to Cloudflare Pages. For learning how to create documentation with Sphinx, refer to the official [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/quickstart.html).

<Render file="tutorials-before-you-start" />

## Creating a GitHub repository

In a separate terminal window that is not within the pipenv shell session, verify that SSH key-based authentication is working:

```sh
eval "$(ssh-agent)"
ssh-add -T ~/.ssh/id_rsa.pub
ssh -T git@github.com
```

```sh output

The authenticity of host 'github.com (140.82.113.4)' can't be established.
RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'github.com,140.82.113.4' (RSA) to the list of known hosts.
Hi yourgithubusername! You've successfully authenticated, but GitHub does not provide shell access.
```

Create a new GitHub repository by visiting [repo.new](https://repo.new). After your repository is set up, push your application to GitHub by running the following commands in your terminal:

```sh
git init
git config user.name "Your Name"
git config user.email "username@domain.com"
git remote add origin git@github.com:yourgithubusername/githubrepo.git
git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main
```

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-no-preset" />

<div>

| Configuration option | Value        |
| -------------------- | ------------ |
| Production branch    | `main`       |
| Build command        | `make html`  |
| Build directory      | `build/html` |

</div>

Below the configuration, make sure to set the environment variable for specifying the `PYTHON_VERSION`.

For example:

<div>

| Variable name  | Value |
| -------------- | ----- |
| PYTHON_VERSION | 3.7   |

</div>

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `Pipenv`, your project dependencies, and building your site, before deployment.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`. Every time you commit new code to your Sphinx site, Cloudflare Pages will automatically rebuild your project and deploy it.

You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

<Render file="framework-guides/learn-more" params={{ one: "Sphinx" }} />

---

# SvelteKit

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-svelte-kit-site/

import { PagesBuildPreset, Render, PackageManagers } from "~/components";

SvelteKit is the official framework for building modern web applications with [Svelte](https://svelte.dev), an increasingly popular open-source tool for creating user interfaces. Unlike most frameworks, SvelteKit uses Svelte, a compiler that transforms your component code into efficient JavaScript, enabling SvelteKit to deliver fast, reactive applications that update the DOM surgically as the application state changes.

In this guide, you will create a new SvelteKit application and deploy it using Cloudflare Pages.
You will use [`SvelteKit`](https://kit.svelte.dev/), the official Svelte framework for building web applications of all sizes.

## Setting up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate SvelteKit's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new SvelteKit project, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-svelte-app --framework=svelte --platform=pages"
/>

SvelteKit will prompt you for customization choices. For the template option, choose one of the application/project options. The remaining answers will not affect the rest of this guide. Choose the options that suit your project.

`create-cloudflare` will then install dependencies, including the [Wrangler](/workers/wrangler/install-and-update/#check-your-wrangler-version) CLI and the SvelteKit `@sveltejs/adapter-cloudflare` adapter, and ask you setup questions.

After you have installed your project dependencies, start your application:

```sh
npm run dev
```

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## SvelteKit Cloudflare configuration

To use SvelteKit with Cloudflare Pages, you need to add the [Cloudflare adapter](https://kit.svelte.dev/docs/adapter-cloudflare) to your application.

<Render file="c3-adapter" />

1. Install the Cloudflare Adapter by running `npm i --save-dev @sveltejs/adapter-cloudflare` in your terminal.
2. Include the adapter in `svelte.config.js`:

```diff
- import adapter from '@sveltejs/adapter-auto';
+ import adapter from '@sveltejs/adapter-cloudflare';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    adapter: adapter(),
    // ... truncated ...
  }
};

export default config;
```

3. (Needed if you are using TypeScript) Include support for environment variables. The `env` object, containing KV namespaces and other storage objects, is passed to SvelteKit via the platform property along with context and caches, meaning you can access it in hooks and endpoints. For example:

```diff
declare namespace App {
    interface Locals {}

+   interface Platform {
+       env: {
+           COUNTER: DurableObjectNamespace;
+       };
+       context: {
+           waitUntil(promise: Promise<any>): void;
+       };
+       caches: CacheStorage & { default: Cache }
+   }

    interface Session {}

    interface Stuff {}
}

```

4. Access the added KV or Durable objects (or generally any [binding](/pages/functions/bindings/)) in your endpoint with `env`:

```js
export async function post(context) {
	const counter = context.platform.env.COUNTER.idFromName("A");
}
```

:::note

In addition to the Cloudflare adapter, review other adapters you can use in your project:

- [`@sveltejs/adapter-auto`](https://www.npmjs.com/package/@sveltejs/adapter-auto)

  SvelteKit's default adapter automatically chooses the adapter for your current environment. If you use this adapter, [no configuration is needed](https://kit.svelte.dev/docs/adapter-auto). However, the default adapter introduces a few disadvantages for local development because it has no way of knowing what platform the application is going to be deployed to.

To solve this issue, provide a `CF_PAGES` variable to SvelteKit so that the adapter can detect the Pages platform. For example, when locally building the application: `CF_PAGES=1 vite build`.

- [`@sveltejs/adapter-static`](https://www.npmjs.com/package/@sveltejs/adapter-static)
  Only produces client-side static assets (no server-side rendering) and is compatible with Cloudflare Pages.
  Review the [official SvelteKit documentation](https://kit.svelte.dev/docs/adapter-static) for instructions on how to set up the adapter. Keep in mind that if you decide to use this adapter, the build directory, instead of `.svelte-kit/cloudflare`, becomes `build`. You must also configure your Cloudflare Pages application's build directory accordingly.

:::

:::caution

If you are using any adapter different from the default SvelteKit adapter, remember to commit and push your adapter setting changes to your GitHub repository before attempting the deployment.

:::

## Deploy with Cloudflare Pages

<Render file="deploy-via-c3" params={{ name: "Svelte" }} />

### Deploy via the Cloudflare dashboard

<Render
	file="deploy-to-pages-steps-with-preset"
	params={{ name: "SvelteKit" }}
/>

<div>

<PagesBuildPreset framework="sveltekit" />

</div>

Optionally, you can customize the **Project name** field. It defaults to the GitHub repository's name, but it does not need to match. The **Project name** value is assigned as your `*.pages.dev` subdomain.

After completing configuration, click the **Save and Deploy** button.

You will see your first deploy pipeline in progress. Pages installs all dependencies and builds the project as specified.

Cloudflare Pages will automatically rebuild your SvelteKit project and deploy it on every new pushed commit.

Additionally, you will have access to [preview deployments](/pages/configuration/preview-deployments/), which repeat the build-and-deploy process for pull requests. With these, you can preview changes to your project with a real URL before deploying them to production.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

## Functions setup

In SvelteKit, functions are written as endpoints. Functions contained in the `/functions` directory at the project's root will not be included in the deployment, which compiles to a single `_worker.js` file.

To have the functionality equivalent to Pages Functions [`onRequests`](/pages/functions/api-reference/#onrequests), you need to write standard request handlers in SvelteKit. For example, the following TypeScript file behaves like an `onRequestGet`:

```ts
import type { RequestHandler } from "./$types";

export const GET = (({ url }) => {
	return new Response(String(Math.random()));
}) satisfies RequestHandler;
```

:::note[SvelteKit API Routes]

For more information about SvelteKit API Routes, refer to the [SvelteKit documentation](https://kit.svelte.dev/docs/routing#server).
:::

<Render file="framework-guides/learn-more" params={{ one: "Svelte" }} />

---

# Vite 3

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-vite3-project/

import { Render, PackageManagers } from "~/components";

[Vite](https://vitejs.dev) is a next-generation build tool for front-end developers. With [the release of Vite 3](https://vitejs.dev/blog/announcing-vite3.html), developers can make use of new command line (CLI) improvements, starter templates, and [more](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md#300-2022-07-13) to help build their front-end applications.

Cloudflare Pages has native support for Vite 3 projects. Refer to the blog post on [improvements to the Pages build process](https://blog.cloudflare.com/cloudflare-pages-build-improvements/), including sub-second build initialization, for more information on using Vite 3 and Cloudflare Pages to optimize your application's build tooling.

In this guide, you will learn how to start a new project using Vite 3, and deploy it to Cloudflare Pages.

<PackageManagers type="create" pkg="vite@latest" />

```sh output
✔ Project name: … vite-on-pages
✔ Select a framework: › vue
✔ Select a variant: › vue

Scaffolding project in ~/src/vite-on-pages...

Done. Now run:

  cd vite-on-pages
  npm install
  npm run dev
```

You will now create a new GitHub repository, and push your code using [GitHub's `gh` command line (CLI)](https://cli.github.com):

```sh
git init
```

```sh output
Initialized empty Git repository in ~/vite-vue3-on-pages/.git/
```

```sh
git add .
git commit -m "Initial commit"                                           vite-vue3-on-pages/git/main +
```

```sh output
[main (root-commit) dad4177] Initial commit
 14 files changed, 1452 insertions(+)
```

```sh
gh repo create
```

```sh output
✓ Created repository kristianfreeman/vite-vue3-on-pages on GitHub
✓ Added remote git@github.com:kristianfreeman/vite-vue3-on-pages.git
```

```sh
git push
```

To deploy your site to Pages:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**.
3. Select your new GitHub repository.
4. In the **Set up builds and deployments**, set `npm run build` as the **Build command**, and `dist` as the **Build output directory**.

After completing configuration, select **Save and Deploy**.

You will see your first deploy pipeline in progress. Pages installs all dependencies and builds the project as specified. After you have deployed your project, it will be available at the `<YOUR_PROJECT_NAME>.pages.dev` subdomain. Find your project's subdomain in **Workers & Pages** > select your Pages project > **Deployments**.

Cloudflare Pages will automatically rebuild your project and deploy it on every new pushed commit.

Additionally, you will have access to [preview deployments](/pages/configuration/preview-deployments/), which repeat the build-and-deploy process for pull requests. With these, you can preview changes to your project with a real URL before deploying them to production.

<Render file="framework-guides/learn-more" params={{ one: "Vite 3" }} />

---

# VitePress

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-vitepress-site/

import {
	PagesBuildPreset,
	Render,
	TabItem,
	Tabs,
	PackageManagers,
} from "~/components";

[VitePress](https://vitepress.dev/) is a [static site generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) designed for building fast, content-centric websites. VitePress takes your source content written in [Markdown](https://en.wikipedia.org/wiki/Markdown), applies a theme to it, and generates static HTML pages that can be easily deployed anywhere.

In this guide, you will create a new VitePress project and deploy it using Cloudflare Pages.

## Set up a new project

VitePress ships with a command line setup wizard that will help you scaffold a basic project.

Run the following command in your terminal to create a new VitePress project:

<PackageManagers type="dlx" pkg="vitepress@latest" args="init" />

Amongst other questions, the setup wizard will ask you in which directory to save your new project, make sure
to be in the project's directory and then install the `vitepress` dependency with the following command:

<PackageManagers pkg="vitepress@latest" dev />

:::note

If you encounter errors, make sure your local machine meets the [Prerequisites for VitePress](https://vitepress.dev/guide/getting-started#prerequisites).

:::

Finally create a `.gitignore` file with the following content:

```
node_modules
.vitepress/cache
.vitepress/dist
```

This step makes sure that unnecessary files are not going to be included in the project's git repository (which we will set up next).

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render
	file="deploy-to-pages-steps-with-preset"
	params={{ name: "VitePress" }}
/>

<PagesBuildPreset framework="vitepress" />

After configuring your site, you can begin your first deploy. Cloudflare Pages will install `vitepress`, your project dependencies, and build your site, before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`. Every time you commit and push new code to your VitePress project, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes to your site look before deploying them to production.

<Render file="framework-guides/learn-more" params={{ one: "VitePress" }} />

---

# Vue

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-vue-site/

import { PagesBuildPreset, Render, PackageManagers } from "~/components";

[Vue](https://vuejs.org/) is a progressive JavaScript framework for building user interfaces. A core principle of Vue is incremental adoption: this makes it easy to build Vue applications that live side-by-side with your existing code.

In this guide, you will create a new Vue application and deploy it using Cloudflare Pages. You will use `vue-cli`, a batteries-included tool for generating new Vue applications.

## Setting up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Vue's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Vue project, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-vue-app --framework=vue --platform=pages"
/>

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository_no_init" />

## Deploy with Cloudflare Pages

<Render file="deploy-via-c3" params={{ name: "Vue" }} />

### Deploy via the Cloudflare dashboard

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Vue" }} />

<div>

<PagesBuildPreset framework="vue" />

</div>

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `vue`, your project dependencies, and building your site, before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your Vue application, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

<Render file="framework-guides/learn-more" params={{ one: "Vue" }} />

---

# Zola

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-a-zola-site/

import { PagesBuildPreset, Render } from "~/components";

[Zola](https://www.getzola.org/) is a fast static site generator in a single binary with everything built-in. In this guide, you will create a new Zola application and deploy it using Cloudflare Pages. You will use the `zola` CLI to create a new Zola site.

## Installing Zola

First, [install](https://www.getzola.org/documentation/getting-started/installation/) the `zola` CLI, using the specific instructions for your operating system below:

### macOS (Homebrew)

If you use the package manager [Homebrew](https://brew.sh), run the `brew install` command in your terminal to install Zola:

```sh
brew install zola
```

### Windows (Chocolatey)

If you use the package manager [Chocolatey](https://chocolatey.org/), run the `choco install` command in your terminal to install Zola:

```sh
choco install zola
```

### Windows (Scoop)

If you use the package manager [Scoop](https://scoop.sh/), run the `scoop install` command in your terminal to install Zola:

```sh
scoop install zola
```

### Linux (pkg)

Your Linux distro's package manager may include Zola. If this is the case, you can install it directly using your distro's package manager -- for example, using `pkg`, run the following command in your terminal:

```sh
pkg install zola
```

If your package manager does not include Zola or you would like to download a release directly, refer to the [**Manual**](/pages/framework-guides/deploy-a-zola-site/#manual-installation) section below.

### Manual installation

The Zola GitHub repository contains pre-built versions of the Zola command-line tool for various operating systems, which can be found on [the Releases page](https://github.com/getzola/zola/releases).

For more instruction on installing these releases, refer to [Zola's install guide](https://www.getzola.org/documentation/getting-started/installation/).

## Creating a new project

With Zola installed, create a new project by running the `zola init` command in your terminal using the default template:

```sh
zola init my-zola-project
```

Upon running `zola init`, you will prompted with three questions:

1. What is the URL of your site? ([https://example.com](https://example.com)):
   You can leave this one blank for now.

2. Do you want to enable Sass compilation? \[Y/n]: Y

3. Do you want to enable syntax highlighting? \[y/N]: y

4. Do you want to build a search index of the content? \[y/N]: y

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository_no_init" />

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Zola" }} />

<PagesBuildPreset framework="zola" />

Below the configuration, make sure to set the **Environment Variables (advanced)** for specifying the `ZOLA_VERSION`.

For example, `ZOLA_VERSION`: `0.17.2`.

After configuring your site, you can begin your first deploy. You should see Cloudflare Pages installing `zola`, your project dependencies, and building your site, before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.

You can now add that subdomain as the `base_url` in your `config.toml` file.

For example:

```yaml
# The URL the site will be built for
base_url = "https://my-zola-project.pages.dev"
```

Every time you commit new code to your Zola site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

<Render file="framework-guides/learn-more" params={{ one: "Zola" }} />

---

# Elder.js

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-an-elderjs-site/

import { PagesBuildPreset, Render } from "~/components";

[Elder.js](https://elderguide.com/tech/elderjs/) is an SEO-focused framework for building static sites with [SvelteKit](/pages/framework-guides/deploy-a-svelte-kit-site/).

In this guide, you will create a new Elder.js application and deploy it using Cloudflare Pages.

## Setting up a new project

Create a new project using [`npx degit Elderjs/template`](https://docs.npmjs.com/cli/v6/commands/npm-init), giving it a project name:

```sh
npx degit Elderjs/template elderjs-app
cd elderjs-app
```

The Elder.js template includes a number of pages and examples showing how to build your static site, but by simply generating the project, it is already ready to be deployed to Cloudflare Pages.

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render
	file="deploy-to-pages-steps-with-preset"
	params={{ name: "Elder.js" }}
/>

<PagesBuildPreset framework="elder-js" />

Optionally, you can customize the **Project name** field. It defaults to the GitHub repository's name, but it does not need to match. The **Project name** value is assigned as your `*.pages.dev` subdomain.

### Finalize Setup

After completing configuration, click the **Save and Deploy** button.

You will see your first deploy pipeline in progress. Pages installs all dependencies and builds the project as specified.

Cloudflare Pages will automatically rebuild your project and deploy it on every new pushed commit.

Additionally, you will have access to [preview deployments](/pages/configuration/preview-deployments/), which repeat the build-and-deploy process for pull requests. With these, you can preview changes to your project with a real URL before deploying them to production.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

<Render file="framework-guides/learn-more" params={{ one: "Elder.js" }} />

---

# Astro

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-an-astro-site/

import {
	PagesBuildPreset,
	Render,
	PackageManagers,
	Stream,
} from "~/components";

[Astro](https://astro.build) is an all-in-one web framework for building fast, content-focused websites. By default, Astro builds websites that have zero JavaScript runtime code.

Refer to the [Astro Docs](https://docs.astro.build/) to learn more about Astro or for assistance with an Astro project.

In this guide, you will create a new Astro application and deploy it using Cloudflare Pages.

### Video Tutorial

<Stream
	id="d308a0e06bfaefd12115b34076ba99a4"
	title="Build a Full-Stack Application using Astro and Cloudflare Workers"
	thumbnail="3s"
/>

## Set up a new project

To use `create-cloudflare` to create a new Astro project, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-astro-app --framework=astro --platform=pages"
/>

Astro will ask:

1. Which project type you would like to set up. Your answers will not affect the rest of this tutorial. Select an answer ideal for your project.

2. If you want to initialize a Git repository. We recommend you to select `No` and follow this guide's [Git instructions](/pages/framework-guides/deploy-an-astro-site/#create-a-github-repository) below. If you select `Yes`, do not follow the below Git instructions precisely but adjust them to your needs.

`create-cloudflare` will then install dependencies, including the [Wrangler](/workers/wrangler/install-and-update/#check-your-wrangler-version) CLI and the `@astrojs/cloudflare` adapter, and ask you setup questions.

### Astro configuration

You can deploy an Astro Server-side Rendered (SSR) site to Cloudflare Pages using the [`@astrojs/cloudflare` adapter](https://github.com/withastro/adapters/tree/main/packages/cloudflare#readme). SSR sites render on Pages Functions and allow for dynamic functionality and customizations.

<Render file="c3-adapter" />

Add the [`@astrojs/cloudflare` adapter](https://github.com/withastro/adapters/tree/main/packages/cloudflare#readme) to your project's `package.json` by running:

```sh
npm run astro add cloudflare
```

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render file="deploy-via-c3" params={{ name: "Astro" }} />

### Deploy via the Cloudflare dashboard

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Astro" }} />

<div>

<PagesBuildPreset framework="astro" />

</div>

Optionally, you can customize the **Project name** field. It defaults to the GitHub repository's name, but it does not need to match. The **Project name** value is assigned as your `*.pages.dev` subdomain.

After completing configuration, select **Save and Deploy**.

You will see your first deployment in progress. Pages installs all dependencies and builds the project as specified.

Cloudflare Pages will automatically rebuild your project and deploy it on every new pushed commit.

Additionally, you will have access to [preview deployments](/pages/configuration/preview-deployments/), which repeat the build-and-deploy process for pull requests. With these, you can preview changes to your project with a real URL before deploying them to production.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

### Local runtime

Local runtime support is configured via the `platformProxy` option:

```js null {6}
import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";

export default defineConfig({
	adapter: cloudflare({
		platformProxy: {
			enabled: true,
		},
	}),
});
```

## Use bindings in your Astro application

A [binding](/pages/functions/bindings/) allows your application to interact with Cloudflare developer products, such as [KV](/kv/concepts/how-kv-works/), [Durable Object](/durable-objects/), [R2](/r2/), and [D1](https://blog.cloudflare.com/introducing-d1/).

Use bindings in Astro components and API routes by using `context.locals` from [Astro Middleware](https://docs.astro.build/en/guides/middleware/) to access the Cloudflare runtime which amongst other fields contains the Cloudflare's environment and consecutively any bindings set for your application.

Refer to the following example of how to access a KV namespace with TypeScript.

First, you need to define Cloudflare runtime and KV type by updating the `env.d.ts`. Make sure you have generated Cloudflare runtime types by running [`wrangler types`](/pages/functions/typescript/). 

```typescript
/// <reference types="astro/client" />

type ENV = {
	// replace `MY_KV` with your KV namespace
	MY_KV: KVNamespace;
};

// use a default runtime configuration (advanced mode).
type Runtime = import("@astrojs/cloudflare").Runtime<ENV>;
declare namespace App {
	interface Locals extends Runtime {}
}
```

You can then access your KV from an API endpoint in the following way:

```typescript null {3,4,5}
import type { APIContext } from "astro";

export async function get({ locals }: APIContext) {
	const { MY_KV } = locals.runtime.env;

	return {
		// ...
	};
}
```

Besides endpoints, you can also use bindings directly from your Astro components:

```typescript null {2,3}
---
const myKV = Astro.locals.runtime.env.MY_KV;
const value = await myKV.get("key");
---
<div>{value}</div>
```

To learn more about the Astro Cloudflare runtime, refer to the [Access to the Cloudflare runtime](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#access-to-the-cloudflare-runtime) in the Astro documentation.

<Render file="framework-guides/learn-more" params={{ one: "Astro" }} />

---

# Angular

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-an-angular-site/

import { PagesBuildPreset, Render, PackageManagers } from "~/components";

[Angular](https://angular.io/) is an incredibly popular framework for building reactive and powerful front-end applications.

In this guide, you will create a new Angular application and deploy it using Cloudflare Pages.

## Create a new project using the `create-cloudflare` CLI (C3)

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Angular's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Angular project, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-angular-app --framework=angular --platform=pages"
/>

`create-cloudflare` will install dependencies, including the [Wrangler](/workers/wrangler/install-and-update/#check-your-wrangler-version) CLI and the Cloudflare Pages adapter, and ask you setup questions.

:::note[Git integration]

The initial deployment created via C3 is referred to as a [Direct Upload](/pages/get-started/direct-upload/). To set up a deployment via the Pages Git integration, refer to the [Git Integration](#git-integration) section below.

:::

<Render file="framework-guides/git-integration" />

### Create a GitHub repository

<Render file="framework-guides/create-gh-repo" /> <br />

```sh
# Skip the following three commands if you have built your application
# using C3 or already committed your changes
git init
git add .
git commit -m "Initial commit"

git branch -M main
git remote add origin https://github.com/<YOUR_GH_USERNAME>/<REPOSITORY_NAME>
git push -u origin main
```

### Create a Pages project

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Angular" }} />

<PagesBuildPreset framework="angular" />


:::caution[On some versions of Angular, you may need to:]
Change the `Build command` to `npx ng build --output-path dist/cloudflare`\
Change the `Build directory` to `dist/cloudflare/browser`
:::

Optionally, you can customize the **Project name** field. It defaults to the GitHub repository's name, but it does not need to match. The **Project name** value is assigned as your `*.pages.dev` subdomain.

4. After completing configuration, select the **Save and Deploy**.

Review your first deploy pipeline in progress. Pages installs all dependencies and builds the project as specified. Cloudflare Pages will automatically rebuild your project and deploy it on every new pushed commit.

Additionally, you will have access to [preview deployments](/pages/configuration/preview-deployments/), which repeat the build-and-deploy process for pull requests. With these, you can preview changes to your project with a real URL before deploying your changes to production.

<Render file="framework-guides/learn-more" params={{ one: "Angular" }} />

---

# Analog

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-an-analog-site/

import {
	PagesBuildPreset,
	Render,
	TabItem,
	Tabs,
	PackageManagers,
} from "~/components";

[Analog](https://analogjs.org/) is a fullstack meta-framework for Angular, powered by [Vite](https://vitejs.dev/) and [Nitro](https://nitro.unjs.io/).

In this guide, you will create a new Analog application and deploy it using Cloudflare Pages.

## Create a new project with `create-cloudflare`

The easiest way to create a new Analog project and deploy to Cloudflare Pages is to use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (also known as C3). To get started, open a terminal and run:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-analog-app --framework=analog --platform=pages"
/>

C3 will walk you through the setup process and create a new project using `create-analog`, the official Analog creation tool. It will also install the necessary adapters along with the [Wrangler CLI](/workers/wrangler/install-and-update/#check-your-wrangler-version).

:::note[Deployment]

The final step of the C3 workflow will offer to deploy your application to Cloudflare. For more information on deployment options, see the [Deployment](#deployment) section below.

:::

## Bindings

A [binding](/pages/functions/bindings/) allows your application to interact with Cloudflare developer products, such as [KV](/kv/), [Durable Objects](/durable-objects/), [R2](/r2/), and [D1](/d1/).

If you intend to use bindings in your project, you must first set up your bindings for local and remote development.

In Analog, server-side code can be added via [API Routes](https://analogjs.org/docs/features/api/overview). The `defineEventHandler()` method is used to define your API endpoints in which you can access Cloudflare's context via the provided `context` field. The `context` field allows you to access any bindings set for your application.

The following code block shows an example of accessing a KV namespace in Analog.

```typescript null {2}
export default defineEventHandler(async ({ context }) => {
	const { MY_KV } = context.cloudflare.env;
	const greeting = (await MY_KV.get("greeting")) ?? "hello";

	return {
		greeting,
	};
});
```

### Setup bindings in development

Projects created via C3 come installed with a Nitro module that simplifies the process of working with bindings during development:

```typescript
const devBindingsModule = async (nitro: Nitro) => {
  if (nitro.options.dev) {
    nitro.options.plugins.push('./src/dev-bindings.ts');
  }
};

export default defineConfig({
  ...
  plugins: [analog({
    nitro: {
      preset: "cloudflare-pages",
      modules: [devBindingsModule]
    }
  })],
  ...
});
```

This module in turn loads a plugin which adds bindings to the request context in dev:

```typescript
import { NitroApp } from "nitropack";
import { defineNitroPlugin } from "nitropack/dist/runtime/plugin";

export default defineNitroPlugin((nitroApp: NitroApp) => {
	nitroApp.hooks.hook("request", async (event) => {
		const _pkg = "wrangler"; // Bypass bundling!
		const { getPlatformProxy } = (await import(
			_pkg
		)) as typeof import("wrangler");
		const platform = await getPlatformProxy();

		event.context.cf = platform["cf"];
		event.context.cloudflare = {
			env: platform["env"] as unknown as Env,
			context: platform["ctx"],
		};
	});
});
```

In the code above, the `getPlatformProxy` helper function will automatically detect any bindings defined in your project's Wrangler file and emulate those bindings in local development. You may wish to refer to [Wrangler configuration information on bindings](/workers/wrangler/configuration/#bindings).

A new type definition for the `Env` type (used by `context.cloudflare.env`) can be generated from the [Wrangler configuration file](/workers/wrangler/configuration/) with the following command:

```sh
npm run cf-typegen
```

This should be done any time you add new bindings to your Wrangler configuration.

### Setup bindings in deployed applications

In order to access bindings in a deployed application, you will need to [configure your bindings](/pages/functions/bindings/) in the Cloudflare dashboard.

## Deployment

When creating your new project, C3 will give you the option of deploying an initial version of your application via [Direct Upload](/pages/how-to/use-direct-upload-with-continuous-integration/). You can redeploy your application at any time by running following command inside your project directory:

```sh
npm run deploy
```

<Render file="framework-guides/git-integration" />

### Create a GitHub repository

<Render file="framework-guides/create-gh-repo" />

```sh
# Skip the following three commands if you have built your application
# using C3 or already committed your changes
git init
git add .
git commit -m "Initial commit"

git branch -M main
git remote add origin https://github.com/<YOUR_GH_USERNAME>/<REPOSITORY_NAME>
git push -u origin main
```

### Create a Pages project

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "Analog" }} />

<PagesBuildPreset framework="analog" />

Optionally, you can customize the **Project name** field. It defaults to the GitHub repository's name, but it does not need to match. The **Project name** value is assigned as your `*.pages.dev` subdomain.

4. After completing configuration, select the **Save and Deploy**.

Review your first deploy pipeline in progress. Pages installs all dependencies and builds the project as specified. Cloudflare Pages will automatically rebuild your project and deploy it on every new pushed commit.

Additionally, you will have access to [preview deployments](/pages/configuration/preview-deployments/), which repeat the build-and-deploy process for pull requests. With these, you can preview changes to your project with a real URL before deploying your changes to production.

---

# Eleventy

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-an-eleventy-site/

import { PagesBuildPreset, Render } from "~/components";

[Eleventy](https://www.11ty.dev/) is a simple static site generator. In this guide, you will create a new Eleventy site and deploy it using Cloudflare Pages. You will be using the `eleventy` CLI to create a new Eleventy site.

## Installing Eleventy

Install the `eleventy` CLI by running the following command in your terminal:

```sh
npm install -g @11ty/eleventy
```

## Creating a new project

There are a lot of [starter projects](https://www.11ty.dev/docs/starter/) available on the Eleventy website. As an example, use the `eleventy-base-blog` project by running the following commands in your terminal:

```sh
git clone https://github.com/11ty/eleventy-base-blog.git my-blog-name
cd my-blog-name
npm install
```

<Render file="tutorials-before-you-start" />

## Creating a GitHub repository

Create a new GitHub repository by visiting [repo.new](https://repo.new). After creating a new repository, prepare and push your local application to GitHub by running the following command in your terminal:

```sh
git remote set-url origin https://github.com/yourgithubusername/githubrepo
git branch -M main
git push -u origin main
```

## Deploy with Cloudflare Pages

<Render
	file="deploy-to-pages-steps-with-preset"
	params={{ name: "Eleventy" }}
/>

<PagesBuildPreset framework="eleventy" />

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.
Every time you commit new code to your Eleventy site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

<Render file="framework-guides/learn-more" params={{ one: "Eleventy" }} />

---

# Ember

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-an-emberjs-site/

import { PagesBuildPreset, Render } from "~/components";

[Ember.js](https://emberjs.com) is a productive, battle-tested JavaScript framework for building modern web applications. It includes everything you need to build rich UIs that work on any device.

## Install Ember

To begin, install Ember:

```sh
npm install -g ember-cli
```

## Create an Ember project

Use the `ember new` command to create a new application:

```sh
npx ember new ember-quickstart --lang en
```

After the application is generated, change the directory to your project and run your project by running the following commands:

```sh
cd ember-quickstart
npm start
```

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository_no_init" />

## Deploy with Cloudflare Pages

<Render
	file="deploy-to-pages-steps-with-preset"
	params={{ name: "Ember.js" }}
/>

<PagesBuildPreset framework="ember-js" />

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.

Every time you commit new code to your Ember site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests and be able to preview how changes to your site look before deploying them to production.

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

<Render file="framework-guides/learn-more" params={{ one: "Ember" }} />

---

# Static HTML

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-anything/

import { Details, Render } from "~/components";

Cloudflare supports deploying any static HTML website to Cloudflare Pages. If you manage your website without using a framework or static site generator, or if your framework is not listed in [Framework guides](/pages/framework-guides/), you can still deploy it using this guide.

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-no-preset" />

<div>

| Configuration option     | Value              |
| ------------------------ | ------------------ |
| Production branch        | `main`             |
| Build command (optional) | `exit 0`           |
| Build output directory   | `<YOUR_BUILD_DIR>` |

</div>

Unlike many of the framework guides, the build command and build output directory for your site are going to be completely custom. If you are not using a preset and do not need to build your site, use `exit 0` as your **Build command**. Cloudflare recommends using `exit 0` as your **Build command** to access features such as Pages Functions. The **Build output directory** is where your application's content lives.

After configuring your site, you can begin your first deploy. Your custom build command (if provided) will run, and Pages will deploy your static site.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After you have deployed your site, you will receive a unique subdomain for your project on `*.pages.dev`. Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

<Details header="Getting 404 errors on *.pages.dev?">

If you are getting `404` errors when visiting your `*.pages.dev` domain, make sure your website has a top-level file for `index.html`. This `index.html` is what Pages will serve on your apex with no page specified.

</Details>

<Render file="framework-guides/learn-more" params={{ one: " " }} />

---

# MkDocs

URL: https://developers.cloudflare.com/pages/framework-guides/deploy-an-mkdocs-site/

import { PagesBuildPreset, Render } from "~/components";

[MkDocs](https://www.mkdocs.org/) is a modern documentation platform where teams can document products, internal knowledge bases and APIs.

## Install MkDocs

MkDocs requires a recent version of Python and the Python package manager, pip, to be installed on your system. To install pip, refer to the [MkDocs Installation guide](https://www.mkdocs.org/user-guide/installation/). With pip installed, run:

```sh
pip install mkdocs
```

## Create an MkDocs project

Use the `mkdocs new` command to create a new application:

```sh
mkdocs new <PROJECT_NAME>
```

Then `cd` into your project, take MkDocs and its dependencies and put them into a `requirements.txt` file:

```sh
pip freeze > requirements.txt
```

<Render file="tutorials-before-you-start" />

<Render file="framework-guides/create-github-repository" />

You have successfully created a GitHub repository and pushed your MkDocs project to that repository.

## Deploy with Cloudflare Pages

<Render file="deploy-to-pages-steps-with-preset" params={{ name: "MkDocs" }} />

<PagesBuildPreset framework="mkdocs" />

4. Go to **Environment variables (advanced)** > **Add variable** > and add the variable `PYTHON_VERSION` with a value of `3.7`.

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.

Every time you commit new code to your MkDocs site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests and be able to preview how changes to your site look before deploying them to production.

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

<Render file="framework-guides/learn-more" params={{ one: "MkDocs" }} />

---

# Framework guides

URL: https://developers.cloudflare.com/pages/framework-guides/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Direct Upload

URL: https://developers.cloudflare.com/pages/get-started/direct-upload/

import { Render } from "~/components";

Direct Upload enables you to upload your prebuilt assets to Pages and deploy them to the Cloudflare global network. You should choose Direct Upload over Git integration if you want to [integrate your own build platform](/pages/how-to/use-direct-upload-with-continuous-integration/) or upload from your local computer.

This guide will instruct you how to upload your assets using Wrangler or the drag and drop method.

:::caution[You cannot switch to Git integration later]
If you choose Direct Upload, you cannot switch to [Git integration](/pages/get-started/git-integration/) later. You will have to create a new project with Git integration to use automatic deployments.
:::

## Prerequisites

Before you deploy your project with Direct Upload, run the appropriate [build command](/pages/configuration/build-configuration/#framework-presets) to build your project.

## Upload methods

After you have your prebuilt assets ready, there are two ways to begin uploading:

- [Wrangler](/pages/get-started/direct-upload/#wrangler-cli).
- [Drag and drop](/pages/get-started/direct-upload/#drag-and-drop).

:::note

Within a Direct Upload project, you can switch between creating deployments with either Wrangler or drag and drop. For existing Git-integrated projects, you can manually create deployments using [`wrangler deploy`](/workers/wrangler/commands/#deploy). However, you cannot use drag and drop on the dashboard with existing Git-integrated projects.

:::

## Supported file types

Below is the supported file types for each Direct Upload options:

- Wrangler: A single folder of assets. (Zip files are not supported.)
- Drag and drop: A zip file or single folder of assets.

## Wrangler CLI

### Set up Wrangler

To begin, install [`npm`](https://docs.npmjs.com/getting-started). Then [install Wrangler, the Developer Platform CLI](/workers/wrangler/install-and-update/).

#### Create your project

Log in to Wrangler with the [`wrangler login` command](/workers/wrangler/commands/#login). Then run the [`pages project create` command](/workers/wrangler/commands/#project-create):

```sh
npx wrangler pages project create
```

You will then be prompted to specify the project name. Your project will be served at `<PROJECT_NAME>.pages.dev` (or your project name plus a few random characters if your project name is already taken). You will also be prompted to specify your production branch.

Subsequent deployments will reuse both of these values (saved in your `node_modules/.cache/wrangler` folder).

#### Deploy your assets

From here, you have created an empty project and can now deploy your assets for your first deployment and for all subsequent deployments in your production environment. To do this, run the [`wrangler pages deploy`](/workers/wrangler/commands/#deploy-1) command:

```sh
npx wrangler pages deploy <BUILD_OUTPUT_DIRECTORY>
```

Find the appropriate build output directory for your project in [Build directory under Framework presets](/pages/configuration/build-configuration/#framework-presets).

Your production deployment will be available at `<PROJECT_NAME>.pages.dev`.

:::note

Before using the `wrangler pages deploy` command, you will need to make sure you are inside the project. If not, you can also pass in the project path.

:::

To deploy assets to a preview environment, run:

```sh
npx wrangler pages deploy <OUTPUT_DIRECTORY> --branch=<BRANCH_NAME>
```

For every branch you create, a branch alias will be available to you at `<BRANCH_NAME>.<PROJECT_NAME>.pages.dev`.

:::note

If you are in a Git workspace, Wrangler will automatically pull the branch information for you. Otherwise, you will need to specify your branch in this command.

:::

If you would like to streamline the project creation and asset deployment steps, you can also use the deploy command to both create and deploy assets at the same time. If you execute this command first, you will still be prompted to specify your project name and production branch. These values will still be cached for subsequent deployments as stated above. If the cache already exists and you would like to create a new project, you will need to run the [`create` command](#create-your-project).

#### Other useful commands

If you would like to use Wrangler to obtain a list of all available projects for Direct Upload, use [`pages project list`](/workers/wrangler/commands/#project-list):

```sh
npx wrangler pages project list
```

If you would like to use Wrangler to obtain a list of all unique preview URLs for a particular project, use [`pages deployment list`](/workers/wrangler/commands/#deployment-list):

```sh
npx wrangler pages deployment list
```

For step-by-step directions on how to use Wrangler and continuous integration tools like GitHub Actions, Circle CI, and Travis CI together for continuous deployment, refer to [Use Direct Upload with continuous integration](/pages/how-to/use-direct-upload-with-continuous-integration/).

## Drag and drop

#### Deploy your project with drag and drop

To deploy with drag and drop:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login).
2. In **Account Home**, select your account > **Workers & Pages**.
3. Select **Create application** > **Pages** > **Upload assets**.
4. Enter your project name in the provided field and drag and drop your assets.
5. Select **Deploy**.

Your project will be served from `<PROJECT_NAME>.pages.dev`. Next drag and drop your build output directory into the uploading frame. Once your files have been successfully uploaded, select **Save and Deploy** and continue to your newly deployed project.

#### Create a new deployment

After you have your project created, select **Create a new deployment** to begin a new version of your site. Next, choose whether your new deployment will be made to your production or preview environment. If choosing preview, you can create a new deployment branch or enter an existing one.

## Troubleshoot

### Limits

| Upload method | File limit   | File size |
| ------------- | ------------ | --------- |
| Wrangler      | 20,000 files | 25 MiB    |
| Drag and drop | 1,000 files  | 25 MiB    |

If using the drag and drop method, a red warning symbol will appear next to an asset if too large and thus unsuccessfully uploaded. In this case, you may choose to delete that asset but you cannot replace it. In order to do so, you must reupload the entire project.

### Production branch configuration

<Render file="prod-branch-update" />

### Functions

Drag and drop deployments made from the Cloudflare dashboard do not currently support compiling a `functions` folder of [Pages Functions](/pages/functions/). To deploy a `functions` folder, you must use Wrangler. When deploying a project using Wrangler, if a `functions` folder exists where the command is run, that `functions` folder will be uploaded with the project.

However, note that a `_worker.js` file is supported by both Wrangler and drag and drop deployments made from the dashboard.

---

# Git integration

URL: https://developers.cloudflare.com/pages/get-started/git-integration/

import { Details, Render } from "~/components";

In this guide, you will get started with Cloudflare Pages and deploy your first website to the Pages platform through Git integration. The Git integration enables automatic builds and deployments every time you push a change to your connected [GitHub](/pages/configuration/git-integration/github-integration/) or [GitLab](/pages/configuration/git-integration/gitlab-integration/) repository.

:::caution[You cannot switch to Direct Upload later]
If you deploy using the Git integration, you cannot switch to [Direct Upload](/pages/get-started/direct-upload/) later. However, if you already use a Git-integrated project and do not want to trigger deployments every time you push a commit, you can [disable automatic deployments](/pages/configuration/git-integration/#disable-automatic-deployments) on all branches. Then, you can use Wrangler to deploy directly to your Pages projects and make changes to your Git repository without automatically triggering a build.

:::

## Connect your Git provider to Pages

<Render file="get-started-git-connect-pages" product="pages" />

## Configure your deployment

<Render file="get-started-git-configure-deployment" product="pages" />

## Manage site

<Render file="get-started-git-manage-site" product="pages" />

---

# C3 CLI

URL: https://developers.cloudflare.com/pages/get-started/c3/

import {
	Render,
	TabItem,
	Tabs,
	Type,
	MetaInfo,
	PackageManagers,
} from "~/components";

Cloudflare provides a CLI command for creating new Workers and Pages projects — `npm create cloudflare`, powered by the [`create-cloudflare` package](https://www.npmjs.com/package/create-cloudflare).

## Create a new application

Open a terminal window and run:

<Render file="c3-run-command-no-directory" product="pages" />

Running this command will prompt you to install the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) package, and then ask you questions about the type of application you wish to create.

:::note
To create a Pages project you must now specify the `--platform=pages` arg, otherwise C3 will always create a Workers project.
:::

## Web frameworks

If you choose the "Framework Starter" option, you will be prompted to choose a framework to use. The following frameworks are currently supported:

- [Analog](/pages/framework-guides/deploy-an-analog-site/)
- [Angular](/pages/framework-guides/deploy-an-angular-site/)
- [Astro](/pages/framework-guides/deploy-an-astro-site/)
- [Docusaurus](/pages/framework-guides/deploy-a-docusaurus-site/)
- [Gatsby](/pages/framework-guides/deploy-a-gatsby-site/)
- [Hono](/pages/framework-guides/deploy-a-hono-site/)
- [Next.js](/pages/framework-guides/nextjs/)
- [Nuxt](/pages/framework-guides/deploy-a-nuxt-site/)
- [Qwik](/pages/framework-guides/deploy-a-qwik-site/)
- [React](/pages/framework-guides/deploy-a-react-site/)
- [Remix](/pages/framework-guides/deploy-a-remix-site/)
- [SolidStart](/pages/framework-guides/deploy-a-solid-start-site/)
- [SvelteKit](/pages/framework-guides/deploy-a-svelte-kit-site/)
- [Vue](/pages/framework-guides/deploy-a-vue-site/)

When you use a framework, `npm create cloudflare` directly uses the framework's own command for generating a new projects, which may prompt additional questions. This ensures that the project you create is up-to-date with the latest version of the framework, and you have all the same options when creating you project via `npm create cloudflare` that you would if you created your project using the framework's tooling directly.

## Deploy

Once your project has been configured, you will be asked if you would like to deploy the project to Cloudflare. This is optional.

If you choose to deploy, you will be asked to sign into your Cloudflare account (if you aren't already), and your project will be deployed.

## Creating a new Pages project that is connected to a git repository

To create a new project using `npm create cloudflare`, and then connect it to a Git repository on your Github or Gitlab account, take the following steps:

1. Run `npm create cloudflare@latest`, and choose your desired options
2. Select `no` to the prompt, "Do you want to deploy your application?". This is important — if you select `yes` and deploy your application from your terminal ([Direct Upload](/pages/get-started/direct-upload/)), then it will not be possible to connect this Pages project to a git repository later on. You will have to create a new Cloudflare Pages project.
3. Create a new git repository, using the application that `npm create cloudflare@latest` just created for you.
4. Follow the steps outlined in the [Git integration guide](/pages/get-started/git-integration/)

## CLI Arguments

C3 collects any required input through a series of interactive prompts. You may also specify your choices via command line arguments, which will skip these prompts. To use C3 in a non-interactive context such as CI, you must specify all required arguments via the command line.

This is the full format of a C3 invocation alongside the possible CLI arguments:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="--platform=pages [<DIRECTORY>] [OPTIONS] [-- <NESTED ARGS...>]"
/>

- `DIRECTORY` <Type text="string" /> <MetaInfo text="optional" />

  - The directory where the application should be created. The name of the application is taken from the directory name.

- `NESTED ARGS..` <Type text="string[]" /> <MetaInfo text="optional" />

  - CLI arguments to pass to eventual third party CLIs C3 might invoke (in the case of full-stack applications).

- `--category` <Type text="string" /> <MetaInfo text="optional" />

  - The kind of templates that should be created.

  - The possible values for this option are:

    - `hello-world`: Hello World example
    - `web-framework`: Framework Starter
    - `demo`: Application Starter
    - `remote-template`: Template from a GitHub repo

- `--type` <Type text="string" /> <MetaInfo text="optional" />

  - The type of application that should be created.

  - The possible values for this option are:

    - `hello-world`: A basic "Hello World" Cloudflare Worker.
    - `hello-world-durable-object`: A [Durable Object](/durable-objects/) and a Worker to communicate with it.
    - `common`: A Cloudflare Worker which implements a common example of routing/proxying functionalities.
    - `scheduled`: A scheduled Cloudflare Worker (triggered via [Cron Triggers](/workers/configuration/cron-triggers/)).
    - `queues`: A Cloudflare Worker which is both a consumer and produced of [Queues](/queues/).
    - `openapi`: A Worker implementing an OpenAPI REST endpoint.
    - `pre-existing`: Fetch a Worker initialized from the Cloudflare dashboard.

- `--framework` <Type text="string" /> <MetaInfo text="optional" />

  - The type of framework to use to create a web application (when using this option, `--type` is ignored).

  - The possible values for this option are:

    - `angular`
    - `astro`
    - `docusaurus`
    - `gatsby`
    - `hono`
    - `next`
    - `nuxt`
    - `qwik`
    - `react`
    - `remix`
    - `solid`
    - `svelte`
    - `vue`

- `--template` <Type text="string" /> <MetaInfo text="optional" />

  - Create a new project via an external template hosted in a git repository

  - The value for this option may be specified as any of the following:

    - `user/repo`
    - `git@github.com:user/repo`
    - `https://github.com/user/repo`
    - `user/repo/some-template` (subdirectories)
    - `user/repo#canary` (branches)
    - `user/repo#1234abcd` (commit hash)
    - `bitbucket:user/repo` (BitBucket)
    - `gitlab:user/repo` (GitLab)

    See the `degit` [docs](https://github.com/Rich-Harris/degit) for more details.

    At a minimum, templates must contain the following:

    - `package.json`
    - [Wrangler configuration file](/pages/functions/wrangler-configuration/)
    - `src/` containing a worker script referenced from the Wrangler configuration file

    See the [templates folder](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare/templates) of this repo for more examples.

- `--deploy` <Type text="boolean" /> <MetaInfo text="(default: true) optional" />

  - Deploy your application after it has been created.

- `--lang` <Type text="string" /> <MetaInfo text="(default: ts) optional" />

  - The programming language of the template.

  - The possible values for this option are:

    - `ts`
    - `js`
    - `python`

- `--ts` <Type text="boolean" /> <MetaInfo text="(default: true) optional" />

  - Use TypeScript in your application. Deprecated. Use `--lang=ts` instead.

- `--git` <Type text="boolean" /> <MetaInfo text="(default: true) optional" />

  - Initialize a local git repository for your application.

- `--open` <Type text="boolean" /> <MetaInfo text="(default: true) optional" />

  - Open with your browser the deployed application (this option is ignored if the application is not deployed).

- `--existing-script` <Type text="string" /> <MetaInfo text="optional" />

  - The name of an existing Cloudflare Workers script to clone locally. When using this option, `--type` is coerced to `pre-existing`.

  - When `--existing-script` is specified, `deploy` will be ignored.

- `-y`, `--accept-defaults` <Type text="boolean" /> <MetaInfo text="optional" />

  - Use all the default C3 options each can also be overridden by specifying it.

- `--auto-update` <Type text="boolean" /> <MetaInfo text="(default: true) optional" />

  - Automatically uses the latest version of C3.

- `-v`, `--version` <Type text="boolean" /> <MetaInfo text="optional" />

  - Show version number.

- `-h`, `--help` <Type text="boolean" /> <MetaInfo text="optional" />

  - Show a help message.

:::note

All the boolean options above can be specified with or without a value, for example `--open` and `--open true` have the same effect, prefixing `no-` to the option's name negates it, so for example `--no-open` and `--open false` have the same effect.

:::

## Telemetry

Cloudflare collects anonymous usage data to improve `create-cloudflare` over time. Read more about this in our [data policy](https://github.com/cloudflare/workers-sdk/blob/main/packages/create-cloudflare/telemetry.md).

You can opt-out if you do not wish to share any information.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="telemetry disable"
/>

Alternatively, you can set an environment variable:

```sh
export CREATE_CLOUDFLARE_TELEMETRY_DISABLED=1
```

You can check the status of telemetry collection at any time.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="telemetry status"
/>

You can always re-enable telemetry collection.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="telemetry enable"
/>

---

# Getting started

URL: https://developers.cloudflare.com/pages/get-started/

import { DirectoryListing } from "~/components";

Choose a setup method for your Pages project:

<DirectoryListing />

---

# Add custom HTTP headers

URL: https://developers.cloudflare.com/pages/how-to/add-custom-http-headers/

import { WranglerConfig } from "~/components";

:::note

Cloudflare provides HTTP header customization for Pages projects by adding a `_headers` file to your project. Refer to the [documentation](/pages/configuration/headers/) for more information.

:::

More advanced customization of HTTP headers is available through Cloudflare Workers [serverless functions](https://www.cloudflare.com/learning/serverless/what-is-serverless/).

If you have not deployed a Worker before, get started with our [tutorial](/workers/get-started/guide/). For the purpose of this tutorial, accomplish steps one (Sign up for a Workers account) through four (Generate a new project) before returning to this page.

Before continuing, ensure that your Cloudflare Pages project is connected to a [custom domain](/pages/configuration/custom-domains/#add-a-custom-domain).

## Writing a Workers function

Workers functions are written in [JavaScript](https://www.cloudflare.com/learning/serverless/serverless-javascript/). When a Worker makes a request to a Cloudflare Pages application, it will receive a response. The response a Worker receives is immutable, meaning it cannot be changed. In order to add, delete, or alter headers, clone the response and modify the headers on a new `Response` instance. Return the new response to the browser with your desired header changes. An example of this is shown below:

```js title="Setting custom headers with a Workers function"
export default {
	async fetch(request) {
		// This proxies your Pages application under the condition that your Worker script is deployed on the same custom domain as your Pages project
		const response = await fetch(request);

		// Clone the response so that it is no longer immutable
		const newResponse = new Response(response.body, response);

		// Add a custom header with a value
		newResponse.headers.append(
			"x-workers-hello",
			"Hello from Cloudflare Workers",
		);

		// Delete headers
		newResponse.headers.delete("x-header-to-delete");
		newResponse.headers.delete("x-header2-to-delete");

		// Adjust the value for an existing header
		newResponse.headers.set("x-header-to-change", "NewValue");

		return newResponse;
	},
};
```

## Deploying a Workers function in the dashboard

The easiest way to start deploying your Workers function is by typing [workers.new](https://workers.new/) in the browser. Log in to your account to be automatically directed to the Workers & Pages dashboard. From the Workers & Pages dashboard, write your function or use one of the [examples from the Workers documentation](/workers/examples/).

Select **Save and Deploy** when your script is ready and set a [route](/workers/configuration/routing/routes/) in your domain's zone settings.

For example, [here is a Workers script](/workers/examples/security-headers/) you can copy and paste into the Workers dashboard that sets common security headers whenever a request hits your Pages URL, such as X-XSS-Protection, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security, Content-Security-Policy (CSP), and more.

## Deploying a Workers function using the CLI

If you would like to skip writing this file yourself, you can use our `custom-headers-example` [template](https://github.com/kristianfreeman/custom-headers-example) to generate a new Workers function with [wrangler](/workers/wrangler/install-and-update/), the Workers CLI tool.

```sh title="Generating a serverless function with wrangler"
git clone https://github.com/cloudflare/custom-headers-example
cd custom-headers-example
npm install
```

To operate your Workers function alongside your Pages application, deploy it to the same custom domain as your Pages application. To do this, update the Wrangler file in your project with your account and zone details:

<WranglerConfig>

```toml null {4,6,7}
name = "custom-headers-example"

account_id = "FILL-IN-YOUR-ACCOUNT-ID"
workers_dev = false
route = "FILL-IN-YOUR-WEBSITE.com/*"
zone_id = "FILL-IN-YOUR-ZONE-ID"
```

</WranglerConfig>

If you do not know how to find your Account ID and Zone ID, refer to [our guide](/fundamentals/account/find-account-and-zone-ids/).

Once you have configured your [Wrangler configuration file](/pages/functions/wrangler-configuration/) , run `npx wrangler deploy` in your terminal to deploy your Worker:

```sh
npx wrangler deploy
```

After you have deployed your Worker, your desired HTTP header adjustments will take effect. While the Worker is deployed, you should continue to see the content from your Pages application as normal.

---

# Set build commands per branch

URL: https://developers.cloudflare.com/pages/how-to/build-commands-branches/

This guide will instruct you how to set build commands on specific branches. You will use the `CF_PAGES_BRANCH` environment variable to run a script on a specified branch as opposed to your Production branch. This guide assumes that you have a Cloudflare account and a Pages project.

## Set up

Create a `.sh` file in your project directory. You can choose your file's name, but we recommend you name the file `build.sh`.

In the following script, you will use the `CF_PAGES_BRANCH` environment variable to check which branch is currently being built. Populate your `.sh` file with the following:

```bash
# !/bin/bash

if [ "$CF_PAGES_BRANCH" == "production" ]; then
  # Run the "production" script in `package.json` on the "production" branch
  # "production" should be replaced with the name of your Production branch

  npm run production

elif [ "$CF_PAGES_BRANCH" == "staging" ]; then
  # Run the "staging" script in `package.json` on the "staging" branch
  # "staging" should be replaced with the name of your specific branch

  npm run staging

else
  # Else run the dev script
  npm run dev
fi
```

## Publish your changes

To put your changes into effect:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In Account Home, select **Workers & Pages** > in **Overview**, select your Pages project.
3. Go to **Settings** > **Build & deployments** > **Build configurations** > **Edit configurations**.
4. Update the **Build command** field value to `bash build.sh` and select **Save**.

To test that your build is successful, deploy your project.

---

# Add a custom domain to a branch

URL: https://developers.cloudflare.com/pages/how-to/custom-branch-aliases/

In this guide, you will learn how to add a custom domain (`staging.example.com`) that will point to a specific branch (`staging`) on your Pages project.

This will allow you to have a custom domain that will always show the latest build for a specific branch on your Pages project.

:::note

Currently, this setup is only supported when using Cloudflare DNS.

If you attempt to follow this guide using an external DNS provider, your custom alias will be sent to the production branch of your Pages project.

:::

First, make sure that you have a successful deployment on the branch you would like to set up a custom domain for.

Next, add a custom domain under your Pages project for your desired custom domain, for example, `staging.example.com`.

![Follow the instructions below to access the custom domains overview in the Pages dashboard.](~/assets/images/pages/how-to//pages_custom_domain-1.png)

To do this:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login).
2. In Account Home, go to **Workers & Pages**.
3. Select your Pages project.
4. Select **Custom domains** > **Setup a custom domain**.
5. Input the domain you would like to use, such as `staging.example.com`
6. Select **Continue** > **Activate domain**

![After selecting your custom domain, you will be asked to activate it.](~/assets/images/pages/how-to//pages_custom_domain-2.png)

After activating your custom domain, go to [DNS](https://dash.cloudflare.com/?to=/:account/:zone/dns) for the `example.com` zone and find the `CNAME` record with the name `staging` and change the target to include your branch alias.

In this instance, change `your-project.pages.dev` to `staging.your-project.pages.dev`.

![After activating your custom domain, change the CNAME target to include your branch name.](~/assets/images/pages/how-to//pages_custom_domain-3.png)

Now the `staging` branch of your Pages project will be available on `staging.example.com`.

---

# Deploy a static WordPress site

URL: https://developers.cloudflare.com/pages/how-to/deploy-a-wordpress-site/

## Overview

In this guide, you will use a WordPress plugin, [Simply Static](https://wordpress.org/plugins/simply-static/), to convert your existing WordPress site to a static website deployed with Cloudflare Pages.

## Prerequisites

This guide assumes that you are:

- The Administrator account on your WordPress site.
- Able to install WordPress plugins on the site.

## Setup

To start, install the [Simply Static](https://wordpress.org/plugins/simply-static/) plugin to export your WordPress site. In your WordPress dashboard, go to **Plugins** > **Add New**.

Search for `Simply Static` and confirm that the resulting plugin that you will be installing matches the plugin below.

![Simply Static plugin](~/assets/images/pages/how-to/simply-static.png)

Select **Install** on the plugin. After it has finished installing, select **Activate**.

### Export your WordPress site

After you have installed the plugin, go to your WordPress dashboard > **Simply Static** > **GENERATE STATIC FILES**.

In the **Activity Log**, find the **ZIP archive created** message and select **Click here to download** to download your ZIP file.

### Deploy your WordPress site with Pages

With your ZIP file downloaded, deploy your site to Pages:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Upload assets**.
3. Name your project > **Create project**.
4. Drag and drop your ZIP file (or unzipped folder of assets) or select it from your computer.
5. After your files have been uploaded, select **Deploy site**.

Your WordPress site will now be live on Pages.

Every time you make a change to your WordPress site, you will need to download a new ZIP file from the WordPress dashboard and redeploy to Cloudflare Pages. Automatic updates are not available with the free version of Simply Static.

## Limitations

There are some features available in WordPress sites that will not be supported in a static site environment:

- WordPress Forms.
- WordPress Comments.
- Any links to `/wp-admin` or similar internal WordPress routes.

## Conclusion

By following this guide, you have successfully deployed a static version of your WordPress site to Cloudflare Pages.

With a static version of your site being served, you can:

- Move your WordPress site to a custom domain or subdomain. Refer to [Custom domains](/pages/configuration/custom-domains/) to learn more.
- Run your WordPress instance locally, or put your WordPress site behind [Cloudflare Access](/pages/configuration/preview-deployments/#customize-preview-deployments-access) to only give access to your contributors. This has a significant effect on the number of attack vectors for your WordPress site and its content.
- Downgrade your WordPress hosting plan to a cheaper plan. Because the memory and bandwidth requirements for your WordPress instance are now smaller, you can often host it on a cheaper plan, or moving to shared hosting.

Connect with the [Cloudflare Developer community on Discord](https://discord.cloudflare.com) to ask questions and discuss the platform with other developers.

---

# Enable Zaraz

URL: https://developers.cloudflare.com/pages/how-to/enable-zaraz/

import { Render } from "~/components";

<Render file="zaraz-definition" product="zaraz" />

## Enable

To enable Zaraz on Cloudflare Pages, you need a [custom domain](/pages/configuration/custom-domains/) associated with your project.

After that, [set up Zaraz](/zaraz/get-started/) on the custom domain.

---

# How to

URL: https://developers.cloudflare.com/pages/how-to/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Install private packages

URL: https://developers.cloudflare.com/pages/how-to/npm-private-registry/

Cloudflare Pages supports custom package registries, allowing you to include private dependencies in your application. While this walkthrough focuses specifically on [npm](https://www.npmjs.com/), the Node package manager and registry, the same approach can be applied to other registry tools.

You will be be adjusting the [environment variables](/pages/configuration/build-configuration/#environment-variables) in your Pages project's **Settings**. An existing website can be modified at any time, but new projects can be initialized with these settings, too. Either way, altering the project settings will not be reflected until its next deployment.

:::caution

Be sure to trigger a new deployment after changing any settings.

:::

## Registry Access Token

Every package registry should have a means of issuing new access tokens. Ideally, you should create a new token specifically for Pages, as you would with any other CI/CD platform.

With npm, you can [create and view tokens through its website](https://docs.npmjs.com/creating-and-viewing-access-tokens) or you can use the `npm` CLI. If you have the CLI set up locally and are authenticated, run the following commands in your terminal:

```sh
# Verify the current npm user is correct
npm whoami

# Create a readonly token
npm token create --read-only
#-> Enter password, if prompted
#-> Enter 2FA code, if configured
```

This will produce a read-only token that looks like a UUID string. Save this value for a later step.

## Private modules on the npm registry

The following section applies to users with applications that are only using private modules from the npm registry.

In your Pages project's **Settings** > **Environment variables**, add a new [environment variable](/pages/configuration/build-configuration/#environment-variables) named `NPM_TOKEN` to the **Production** and **Preview** environments and paste the [read-only token you created](#registry-access-token) as its value.

:::caution

Add the `NPM_TOKEN` variable to both the **Production** and **Preview** environments.

:::

By default, `npm` looks for an environment variable named `NPM_TOKEN` and because you did not define a [custom registry endpoint](#custom-registry-endpoints), the npm registry is assumed. Local development should continue to work as expected, provided that you and your teammates are authenticated with npm accounts (see `npm whoami` and `npm login`) that have been granted access to the private package(s).

## Custom registry endpoints

When multiple registries are in use, a project will need to define its own root-level [`.npmrc`](https://docs.npmjs.com/cli/v7/configuring-npm/npmrc) configuration file. An example `.npmrc` file may look like this:

```ini
@foobar:registry=https://npm.pkg.github.com
//registry.npmjs.org/:_authToken=${TOKEN_FOR_NPM}
//npm.pkg.github.com/:_authToken=${TOKEN_FOR_GITHUB}
```

Here, all packages under the `@foobar` scope are directed towards the GitHub Packages registry. Then the registries are assigned their own access tokens via their respective environment variable names.

:::note

You only need to define an Access Token for the npm registry (refer to `TOKEN_FOR_NPM` in the example) if it is hosting private packages that your application requires.

:::

Your Pages project must then have the matching [environment variables](/pages/configuration/build-configuration/#environment-variables) defined for all environments. In our example, that means `TOKEN_FOR_NPM` must contain [the read-only npm token](#registry-access-token) value and `TOKEN_FOR_GITHUB` must contain its own [personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token#creating-a-token).

### Managing multiple environments

In the event that your local development no longer works with your new `.npmrc` file, you will need to add some additional changes:

1. Rename the Pages-compliant `.npmrc` file to `.npmrc.pages`. This should be referencing environment variables.

2. Restore your previous `.npmrc` file – the version that was previously working for you and your teammates.

3. Go to your Pages project > **Settings** > **Environment variables**, add a new [environment variable](/pages/configuration/build-configuration/#environment-variables) named [`NPM_CONFIG_USERCONFIG`](https://docs.npmjs.com/cli/v6/using-npm/config#npmrc-files) and set its value to `/opt/buildhome/repo/.npmrc.pages`. If your `.npmrc.pages` file is not in your project's root directory, adjust this path accordingly.

---

# Preview Local Projects with Cloudflare Tunnel

URL: https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/

[Cloudflare Tunnel](/cloudflare-one/connections/connect-networks/) runs a lightweight daemon (`cloudflared`) in your infrastructure that establishes outbound connections (Tunnels) between your origin web server and the Cloudflare global network. In practical terms, you can use Cloudflare Tunnel to allow remote access to services running on your local machine. It is an alternative to popular tools like [Ngrok](https://ngrok.com), and provides free, long-running tunnels via the [TryCloudflare](/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) service.

While Cloudflare Pages provides unique [deploy preview URLs](/pages/configuration/preview-deployments/) for new branches and commits on your projects, Cloudflare Tunnel can be used to provide access to locally running applications and servers during the development process. In this guide, you will install Cloudflare Tunnel, and create a new tunnel to provide access to a locally running application. You will need a Cloudflare account to begin using Cloudflare Tunnel.

## Installing Cloudflare Tunnel

Cloudflare Tunnel can be installed on Windows, Linux, and macOS. To learn about installing Cloudflare Tunnel, refer to the [Install cloudflared](/cloudflare-one/connections/connect-networks/downloads/) page in the Cloudflare for Teams documentation.

Confirm that `cloudflared` is installed correctly by running `cloudflared --version` in your command line:

```sh
cloudflared --version
```

```sh output
cloudflared version 2021.5.9 (built 2021-05-21-1541 UTC)
```

## Run a local service

The easiest way to get up and running with Cloudflare Tunnel is to have an application running locally, such as a [React](/pages/framework-guides/deploy-a-react-site/) or [SvelteKit](/pages/framework-guides/deploy-a-svelte-kit-site/) site. When you are developing an application with these frameworks, they will often make use of a `npm run develop` script, or something similar, which mounts the application and runs it on a `localhost` port. For example, the popular `vite` tool runs your in-development React application on port `5173`, making it accessible at the `http://localhost:5173` address.

## Start a Cloudflare Tunnel

With a local development server running, a new Cloudflare Tunnel can be instantiated by running `cloudflared tunnel` in a new command line window, passing in the `--url` flag with your `localhost` URL and port. `cloudflared` will output logs to your command line, including a banner with a tunnel URL:

```sh
cloudflared tunnel --url http://localhost:5173
```

```sh output
2021-07-15T20:11:29Z INF Cannot determine default configuration path. No file [config.yml config.yaml] in [~/.cloudflared ~/.cloudflare-warp ~/cloudflare-warp /etc/cloudflared /usr/local/etc/cloudflared]
2021-07-15T20:11:29Z INF Version 2021.5.9
2021-07-15T20:11:29Z INF GOOS: linux, GOVersion: devel +11087322f8 Fri Nov 13 03:04:52 2020 +0100, GoArch: amd64
2021-07-15T20:11:29Z INF Settings: map[url:http://localhost:5173]
2021-07-15T20:11:29Z INF cloudflared will not automatically update when run from the shell. To enable auto-updates, run cloudflared as a service: https://developers.cloudflare.com/argo-tunnel/reference/service/
2021-07-15T20:11:29Z INF Initial protocol h2mux
2021-07-15T20:11:29Z INF Starting metrics server on 127.0.0.1:42527/metrics
2021-07-15T20:11:29Z WRN Your version 2021.5.9 is outdated. We recommend upgrading it to 2021.7.0
2021-07-15T20:11:29Z INF Connection established connIndex=0 location=ATL
2021-07-15T20:11:32Z INF Each HA connection's tunnel IDs: map[0:cx0nsiqs81fhrfb82pcq075kgs6cybr86v9vdv8vbcgu91y2nthg]
2021-07-15T20:11:32Z INF +-------------------------------------------------------------+
2021-07-15T20:11:32Z INF |  Your free tunnel has started! Visit it:                    |
2021-07-15T20:11:32Z INF |    https://seasonal-deck-organisms-sf.trycloudflare.com     |
2021-07-15T20:11:32Z INF +-------------------------------------------------------------+
```

In this example, the randomly-generated URL `https://seasonal-deck-organisms-sf.trycloudflare.com` has been created and assigned to your tunnel instance. Visiting this URL in a browser will show the application running, with requests being securely forwarded through Cloudflare's global network, through the tunnel running on your machine, to `localhost:5173`:

![Cloudflare Tunnel example rendering a randomly-generated URL](~/assets/images/pages/how-to/tunnel.png)

## Next Steps

Cloudflare Tunnel can be configured in a variety of ways and can be used beyond providing access to your in-development applications. For example, you can provide `cloudflared` with a [configuration file](/cloudflare-one/connections/connect-networks/do-more-with-tunnels/local-management/configuration-file/) to add more complex routing and tunnel setups that go beyond a simple `--url` flag. You can also [attach a Cloudflare DNS record](/cloudflare-one/connections/connect-networks/routing-to-tunnel/dns/) to a domain or subdomain for an easily accessible, long-lived tunnel to your local machine.

Finally, by incorporating Cloudflare Access, you can provide [secure access to your tunnels](/cloudflare-one/applications/configure-apps/self-hosted-public-app/) without exposing your entire server, or compromising on security. Refer to the [Cloudflare for Teams documentation](/cloudflare-one/) to learn more about what you can do with Cloudflare's entire suite of Zero Trust tools.

---

# Redirecting *.pages.dev to a Custom Domain

URL: https://developers.cloudflare.com/pages/how-to/redirect-to-custom-domain/

import { Example } from "~/components";

Learn how to use [Bulk Redirects](/rules/url-forwarding/bulk-redirects/) to redirect your `*.pages.dev` subdomain to your [custom domain](/pages/configuration/custom-domains/).

You may want to do this to ensure that your site's content is served only on the custom domain, and not the `<project>.pages.dev` site automatically generated on your first Pages deployment.

## Setup

To redirect a `<project>.pages.dev` subdomain to your custom domain:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/pages/view/:pages-project/domains), and select your account.
2. Select **Workers & Pages** and select your Pages application.
3. Go to **Custom domains** and make sure that your custom domain is listed. If it is not, add it by clicking **Set up a custom domain**.
4. Go **Bulk Redirects**.
5. [Create a bulk redirect list](/rules/url-forwarding/bulk-redirects/create-dashboard/#1-create-a-bulk-redirect-list) modeled after the following (but replacing the values as appropriate):

<Example>

| Source URL            | Target URL            | Status | Parameters                                                                                                               |
| --------------------- | --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| `<project>.pages.dev` | `https://example.com` | `301`  | <ul><li>Preserve query string</li><li>Subpath matching</li><li>Preserve path suffix</li><li>Include subdomains</li></ul> |

</Example>

6. [Create a bulk redirect rule](/rules/url-forwarding/bulk-redirects/create-dashboard/#2-create-a-bulk-redirect-rule) using the list you just created.

To test that your redirect worked, go to your `<project>.pages.dev` domain. If the URL is now set to your custom domain, then the rule has propagated.

## Related resources

- [Redirect www to domain apex](/pages/how-to/www-redirect/)
- [Handle redirects with Bulk Redirects](/rules/url-forwarding/bulk-redirects/)

---

# Refactor a Worker to a Pages Function

URL: https://developers.cloudflare.com/pages/how-to/refactor-a-worker-to-pages-functions/

import { Render } from "~/components";

In this guide, you will learn how to refactor a Worker made to intake form submissions to a Pages Function that can be hosted on your Cloudflare Pages application. [Pages Functions](/pages/functions/) is a serverless function that lives within the same project directory as your application and is deployed with Cloudflare Pages. It enables you to run server-side code that adds dynamic functionality without running a dedicated server. You may want to refactor a Worker to a Pages Function for one of these reasons:

1. If you manage a serverless function that your Pages application depends on and wish to ship the logic without managing a Worker as a separate service.
2. If you are migrating your Worker to Pages Functions and want to use the routing and middleware capabilities of Pages Functions.

:::note

You can import your Worker to a Pages project without using Functions by creating a `_worker.js` file in the output directory of your Pages project. This [Advanced mode](/pages/functions/advanced-mode/) requires writing your Worker with [Module syntax](/workers/reference/migrate-to-module-workers/).

However, when using the `_worker.js` file in Pages, the entire `/functions` directory is ignored – including its routing and middleware characteristics.

:::

## General refactoring steps

1. Remove the fetch handler and replace it with the appropriate `OnRequest` method. Refer to [Functions](/pages/functions/get-started/) to select the appropriate method for your Function.
2. Pass the `context` object as an argument to your new `OnRequest` method to access the properties of the context parameter: `request`,`env`,`params` and `next`.
3. Use middleware to handle logic that must be executed before or after route handlers. Learn more about [using Middleware](/pages/functions/middleware/) in the Functions documentation.

## Background

To explain the process of refactoring, this guide uses a simple form submission example.

Form submissions can be handled by Workers but can also be a good use case for Pages Functions, since forms are most times specific to a particular application.

Assuming you are already using a Worker to handle your form, you would have deployed this Worker and then added the URL to your form action attribute in your HTML form. This means that when you change how the Worker handles your submissions, you must make changes to the Worker script. If the logic in your Worker is used by more than one application, Pages Functions would not be a good use case.

However, it can be beneficial to use a [Pages Function](/pages/functions/) when you would like to organize your function logic in the same project directory as your application.

Building your application using Pages Functions can help you manage your client and serverless logic from the same place and make it easier to write and debug your code.

## Handle form entries with Airtable and Workers

An [Airtable](https://airtable.com/) is a low-code platform for building collaborative applications. It helps customize your workflow, collaborate, and handle form submissions. For this example, you will utilize Airtable's form submission feature.

[Airtable](https://airtable.com/) can be used to store entries of information in different tables for the same account. When creating a Worker for handling the submission logic, the first step is to use [Wrangler](/workers/wrangler/install-and-update/) to initialize a new Worker within a specific folder or at the root of your application.

This step creates the boilerplate to write your Airtable submission Worker. After writing your Worker, you can deploy it to Cloudflare's global network after you [configure your project for deployment](/workers/wrangler/configuration/). Refer to the Workers documentation for a full tutorial on how to [handle form submission with Workers](/workers/tutorials/handle-form-submissions-with-airtable/).

The following code block shows an example of a Worker that handles Airtable form submission.

The `submitHandler` async function is called if the pathname of the work is `/submit`. This function checks that the request method is a `POST` request and then proceeds to parse and post the form entries to Airtable using your credentials, which you can store using [Wrangler `secret`](/workers/wrangler/commands/#secret).

```js
export default {
	async fetch(request, env, ctx) {
		const url = new URL(request.url);

		if (url.pathname === "/submit") {
			return submitHandler(request, env);
		}

		return fetch(request.url);
	},
};

async function submitHandler(request, env) {
	if (request.method !== "POST") {
		return new Response("Method not allowed", {
			status: 405,
		});
	}
	const body = await request.formData();

	const { first_name, last_name, email, phone, subject, message } =
		Object.fromEntries(body);

	const reqBody = {
		fields: {
			"First Name": first_name,
			"Last Name": last_name,
			Email: email,
			"Phone number": phone,
			Subject: subject,
			Message: message,
		},
	};

	return HandleAirtableData(reqBody, env);
}

const HandleAirtableData = (body, env) => {
	return fetch(
		`https://api.airtable.com/v0/${env.AIRTABLE_BASE_ID}/${encodeURIComponent(
			env.AIRTABLE_TABLE_NAME,
		)}`,
		{
			method: "POST",
			body: JSON.stringify(body),
			headers: {
				Authorization: `Bearer ${env.AIRTABLE_API_KEY}`,
				"Content-type": `application/json`,
			},
		},
	);
};
```

### Refactor your Worker

To refactor the above Worker, go to your Pages project directory and create a `/functions` folder. In `/functions`, create a `form.js` file. This file will handle form submissions.

Then, in the `form.js` file, export a single `onRequestPost`:

```js
export async function onRequestPost(context) {
	return await submitHandler(context);
}
```

Every Worker has an `addEventListener` to listen for `fetch` events, but you will not need this in a Pages Function. Instead, you will `export` a single `onRequest` function, and depending on the HTTPS request it handles, you will name it accordingly. Refer to [Function documentation](/pages/functions/get-started/) to select the appropriate method for your function.

The above code takes a `request` and `env` as arguments which pass these properties down to the `submitHandler` function, which remains unchanged from the [original Worker](#handle-form-entries-with-airtable-and-workers). However, because Functions allow you to specify the HTTPS request type, you can remove the `request.method` check in your Worker. This is now handled by Pages Functions by naming the `onRequest` handler.

Now, you will introduce the `submitHandler` function and pass the `env` parameter as a property. This will allow you to access `env` in the `HandleAirtableData` function below. This function does a `POST` request to Airtable using your Airtable credentials:

```js null {4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22}
export async function onRequestPost(context) {
	return await submitHandler(context);
}

async function submitHandler(context) {
	const body = await context.request.formData();

	const { first_name, last_name, email, phone, subject, message } =
		Object.fromEntries(body);

	const reqBody = {
		fields: {
			"First Name": first_name,
			"Last Name": last_name,
			Email: email,
			"Phone number": phone,
			Subject: subject,
			Message: message,
		},
	};

	return HandleAirtableData({ body: reqBody, env: env });
}
```

Finally, create a `HandleAirtableData` function. This function will send a `fetch` request to Airtable with your Airtable credentials and the body of your request:

```js
// ..
const HandleAirtableData = async function onRequest({ body, env }) {
	return fetch(
		`https://api.airtable.com/v0/${env.AIRTABLE_BASE_ID}/${encodeURIComponent(
			env.AIRTABLE_TABLE_NAME,
		)}`,
		{
			method: "POST",
			body: JSON.stringify(body),
			headers: {
				Authorization: `Bearer ${env.AIRTABLE_API_KEY}`,
				"Content-type": `application/json`,
			},
		},
	);
};
```

You can test your Function [locally using Wrangler](/pages/functions/local-development/). By completing this guide, you have successfully refactored your form submission Worker to a form submission Pages Function.

## Related resources

- [HTML forms](/pages/tutorials/forms/)
- [Plugins documentation](/pages/functions/plugins/)
- [Functions documentation](/pages/functions/)

---

# Use Direct Upload with continuous integration

URL: https://developers.cloudflare.com/pages/how-to/use-direct-upload-with-continuous-integration/

Cloudflare Pages supports directly uploading prebuilt assets, allowing you to use custom build steps for your applications and deploy to Pages with [Wrangler](/workers/wrangler/install-and-update/). This guide will teach you how to deploy your application to Pages, using continuous integration.

## Deploy with Wrangler

In your project directory, install [Wrangler](/workers/wrangler/install-and-update/) so you can deploy a folder of prebuilt assets by running the following command:

```sh
# Publish created project
$ CLOUDFLARE_ACCOUNT_ID=<ACCOUNT_ID> npx wrangler pages deploy <DIRECTORY> --project-name=<PROJECT_NAME>
```

## Get credentials from Cloudflare

### Generate an API Token

To generate an API token:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/profile/api-tokens).
2. Select **My Profile** from the dropdown menu of your user icon on the top right of your dashboard.
3. Select **API Tokens** > **Create Token**.
4. Under **Custom Token**, select **Get started**.
5. Name your API Token in the **Token name** field.
6. Under **Permissions**, select _Account_, _Cloudflare Pages_ and _Edit_:
7. Select **Continue to summary** > **Create Token**.

![Follow the instructions above to create an API token for Cloudflare Pages](~/assets/images/pages/how-to/select-api-token-for-pages.png)

Now that you have created your API token, you can use it to push your project from continuous integration platforms.

### Get project account ID

To find your account ID, log in to the Cloudflare dashboard > select your zone in **Account Home** > find your account ID in **Overview** under **API** on the right-side menu. If you have not added a zone, add one by selecting **Add site**. You can purchase a domain from [Cloudflare's registrar](/registrar/).

## Use GitHub Actions

[GitHub Actions](https://docs.github.com/en/actions) is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline when using GitHub. You can create workflows that build and test every pull request to your repository or deploy merged pull requests to production.

After setting up your project, you can set up a GitHub Action to automate your subsequent deployments with Wrangler.

### Add Cloudflare credentials to GitHub secrets

In the GitHub Action you have set up, environment variables are needed to push your project up to Cloudflare Pages. To add the values of these environment variables in your project's GitHub repository:

1. Go to your project's repository in GitHub.
2. Under your repository's name, select **Settings**.
3. Select **Secrets** > **Actions** > **New repository secret**.
4. Create one secret and put **CLOUDFLARE_ACCOUNT_ID** as the name with the value being your Cloudflare account ID.
5. Create another secret and put **CLOUDFLARE_API_TOKEN** as the name with the value being your Cloudflare API token.

Add the value of your Cloudflare account ID and Cloudflare API token as `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`, respectively. This will ensure that these secrets are secure, and each time your Action runs, it will access these secrets.

### Set up a workflow

Create a `.github/workflows/pages-deployment.yaml` file at the root of your project. The `.github/workflows/pages-deployment.yaml` file will contain the jobs you specify on the request, that is: `on: [push]` in this case. It can also be on a pull request. For a detailed explanation of GitHub Actions syntax, refer to the [official documentation](https://docs.github.com/en/actions).

In your `pages-deployment.yaml` file, copy the following content:

```yaml
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    name: Deploy to Cloudflare Pages
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      # Run your project's build step
      # - name: Build
      #   run: npm install && npm run build
      - name: Deploy
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy YOUR_DIRECTORY_OF_STATIC_ASSETS --project-name=YOUR_PROJECT_NAME
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
```

In the above code block, you have set up an Action that runs when you push code to the repository. Replace `YOUR_PROJECT_NAME` with your Cloudflare Pages project name and `YOUR_DIRECTORY_OF_STATIC_ASSETS` with your project's output directory, respectively.

The `${{ secrets.GITHUB_TOKEN }}` will be automatically provided by GitHub Actions with the `contents: read` and `deployments: write` permission. This will enable our Cloudflare Pages action to create a Deployment on your behalf.

:::note

This workflow automatically triggers on the current git branch, unless you add a `branch` option to the `with` section.

:::

## Using CircleCI for CI/CD

[CircleCI](https://circleci.com/) is another continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. It can be configured to efficiently run complex pipelines with caching, docker layer caching, and resource classes.

Similar to GitHub Actions, CircleCI can use Wrangler to continuously deploy your projects each time to push to your code.

### Add Cloudflare credentials to CircleCI

After you have generated your Cloudflare API token and found your account ID in the dashboard, you will need to add them to your CircleCI dashboard to use your environment variables in your project.

To add environment variables, in the CircleCI web application:

1. Go to your Pages project > **Settings**.
2. Select **Projects** in the side menu.
3. Select the ellipsis (...) button in the project's row. You will see the option to add environment variables.
4. Select **Environment Variables** > **Add Environment Variable**.
5. Enter the name and value of the new environment variable, which is your Cloudflare credentials (`CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`).

![Follow the instructions above to add environment variables to your CircleCI settings](~/assets/images/pages/how-to/project-settings-env-var-v2.png)

### Set up a workflow

Create a `.circleci/config.yml` file at the root of your project. This file contains the jobs that will be executed based on the order of your workflow. In your `config.yml` file, copy the following content:

```yaml
version: 2.1
jobs:
  Publish-to-Pages:
    docker:
      - image: cimg/node:18.7.0

    steps:
      - checkout
      # Run your project's build step
      - run: npm install && npm run build
      # Publish with wrangler
      - run: npx wrangler pages deploy dist --project-name=<PROJECT NAME> # Replace dist with the name of your build folder and input your project name

workflows:
  Publish-to-Pages-workflow:
    jobs:
      - Publish-to-Pages
```

Your continuous integration workflow is broken down into jobs when using CircleCI. From the code block above, you can see that you first define a list of jobs that run on each commit. For example, your repository will run on a prebuilt docker image `cimg/node:18.7.0`. It first checks out the repository with the Node version specified in the image.

:::note[Note]

Wrangler requires a Node version of at least `16.17.0`. You must upgrade your Node.js version if your version is lower than `16.17.0`.

:::

You can modify the Wrangler command with any [`wrangler pages deploy` options](/workers/wrangler/commands/#deploy-1).

After all the specified steps, define a `workflow` at the end of your file. You can learn more about creating a custom process with CircleCI from the [official documentation](https://circleci.com/docs/2.0/concepts/).

## Travis CI for CI/CD

Travis CI is an open-source continuous integration tool that handles specific tasks, such as pull requests and code pushes for your project workflow. Travis CI can be integrated into your GitHub projects, databases, and other preinstalled services enabled in your build configuration. To use Travis CI, you should have A GitHub, Bitbucket, GitLab or Assembla account.

### Add Cloudflare credentials to TravisCI

In your Travis project, add the Cloudflare credentials you have generated from the Cloudflare dashboard to access them in your `travis.yml` file. Go to your Travis CI dashboard and select your current project > **More options** > **Settings** > **Environment Variables**.

Set the environment variable's name and value and the branch you want it to be attached to. You can also set the privacy of the value.

### Setup

Go to [Travis-ci.com](https://Travis-ci.com) and enable your repository by login in with your preferred provider. This guide uses GitHub. Next, create a `.travis.yml` file and copy the following into the file:

```yaml
language: node_js
node_js:
  - "18.0.0" # You can specify more versions of Node you want your CI process to support
branches:
  only:
    - travis-ci-test # Specify what branch you want your CI process to run on
install:
  - npm install

script:
  - npm run build # Switch this out with your build command or remove it if you don't have a build step
  - npx wrangler pages deploy dist --project-name=<PROJECT NAME>

env:
  - CLOUDFLARE_ACCOUNT_ID: { $CLOUDFLARE_ACCOUNT_ID }
  - CLOUDFLARE_API_TOKEN: { $CLOUDFLARE_API_TOKEN }
```

This will set the Node.js version to 18. You have also set branches you want your continuous integration to run on. Finally, input your `PROJECT NAME` in the script section and your CI process should work as expected.

You can also modify the Wrangler command with any [`wrangler pages deploy` options](/workers/wrangler/commands/#deploy-1).

---

# Use Pages Functions for A/B testing

URL: https://developers.cloudflare.com/pages/how-to/use-worker-for-ab-testing-in-pages/

In this guide, you will learn how to use [Pages Functions](/pages/functions/) for A/B testing in your Pages projects. A/B testing is a user experience research methodology applied when comparing two or more versions of a web page or application. With A/B testing, you can serve two or more versions of a webpage to users and divide traffic to your site.

## Overview

Configuring different versions of your application for A/B testing will be unique to your specific use case. For all developers, A/B testing setup can be simplified into a few helpful principles.

Depending on the number of application versions you have (this guide uses two), you can assign your users into experimental groups. The experimental groups in this guide are the base route `/` and the test route `/test`.

To ensure that a user remains in the group you have given, you will set and store a cookie in the browser and depending on the cookie value you have set, the corresponding route will be served.

## Set up your Pages Function

In your project, you can handle the logic for A/B testing using [Pages Functions](/pages/functions/). Pages Functions allows you to handle server logic from within your Pages project.

To begin:

1. Go to your Pages project directory on your local machine.
2. Create a `/functions` directory. Your application server logic will live in the `/functions` directory.

## Add middleware logic

Pages Functions have utility functions that can reuse chunks of logic which are executed before and/or after route handlers. These are called [middleware](/pages/functions/middleware/). Following this guide, middleware will allow you to intercept requests to your Pages project before they reach your site.

In your `/functions` directory, create a `_middleware.js` file.

:::note

When you create your `_middleware.js` file at the base of your `/functions` folder, the middleware will run for all routes on your project. Learn more about [middleware routing](/pages/functions/middleware/).

:::

Following the Functions naming convention, the `_middleware.js` file exports a single async `onRequest` function that accepts a `request`, `env` and `next` as an argument.

```js
const abTest = async ({ request, next, env }) => {
	/*
  Todo:
  1. Conditional statements to check for the cookie
  2. Assign cookies based on percentage, then serve
  */
};

export const onRequest = [abTest];
```

To set the cookie, create the `cookieName` variable and assign any value. Then create the `newHomepagePathName` variable and assign it `/test`:

```js null {1,2}
const cookieName = "ab-test-cookie";
const newHomepagePathName = "/test";

const abTest = async ({ request, next, env }) => {
	/*
  Todo:
  1. Conditional statements to check for the cookie
  2. Assign cookie based on percentage then serve
  */
};

export const onRequest = [abTest];
```

## Set up conditional logic

Based on the URL pathname, check that the cookie value is equal to `new`. If the value is `new`, then `newHomepagePathName` will be served.

```js null {7,8,9,10,11,12,13,14,15,16,17,18,19}
const cookieName = "ab-test-cookie";
const newHomepagePathName = "/test";

const abTest = async ({ request, next, env }) => {
	/*
  Todo:
  1. Assign cookies based on randomly generated percentage, then serve
  */

	const url = new URL(request.url);
	if (url.pathname === "/") {
		// if cookie ab-test-cookie=new then change the request to go to /test
		// if no cookie set, pass x% of traffic and set a cookie value to "current" or "new"

		let cookie = request.headers.get("cookie");
		// is cookie set?
		if (cookie && cookie.includes(`${cookieName}=new`)) {
			// Change the request to go to /test (as set in the newHomepagePathName variable)
			url.pathname = newHomepagePathName;
			return env.ASSETS.fetch(url);
		}
	}
};

export const onRequest = [abTest];
```

If the cookie value is not present, you will have to assign one. Generate a percentage (from 0-99) by using: `Math.floor(Math.random() * 100)`. Your default cookie version is given a value of `current`.

If the percentage of the number generated is lower than `50`, you will assign the cookie version to `new`. Based on the percentage randomly generated, you will set the cookie and serve the assets. After the conditional block, pass the request to `next()`. This will pass the request to Pages. This will result in 50% of users getting the `/test` homepage.

The `env.ASSETS.fetch()` function will allow you to send the user to a modified path which is defined through the `url` parameter. `env` is the object that contains your environment variables and bindings. `ASSETS` is a default Function binding that allows communication between your Function and Pages' asset serving resource. `fetch()` calls to the Pages asset-serving resource and returns the asset (`/test` homepage) to your website's visitor.

:::note[Binding]

A Function is a Worker that executes on your Pages project to add dynamic functionality. A binding is how your Function (Worker) interacts with external resources. A binding is a runtime variable that the Workers runtime provides to your code.

:::

```js null {20-36}
const cookieName = "ab-test-cookie";
const newHomepagePathName = "/test";

const abTest = async (context) => {
	const url = new URL(context.request.url);
	// if homepage
	if (url.pathname === "/") {
		// if cookie ab-test-cookie=new then change the request to go to /test
		// if no cookie set, pass x% of traffic and set a cookie value to "current" or "new"

		let cookie = request.headers.get("cookie");
		// is cookie set?
		if (cookie && cookie.includes(`${cookieName}=new`)) {
			// pass the request to /test
			url.pathname = newHomepagePathName;
			return context.env.ASSETS.fetch(url);
		} else {
			const percentage = Math.floor(Math.random() * 100);
			let version = "current"; // default version
			// change pathname and version name for 50% of traffic
			if (percentage < 50) {
				url.pathname = newHomepagePathName;
				version = "new";
			}
			// get the static file from ASSETS, and attach a cookie
			const asset = await context.env.ASSETS.fetch(url);
			let response = new Response(asset.body, asset);
			response.headers.append("Set-Cookie", `${cookieName}=${version}; path=/`);
			return response;
		}
	}
	return context.next();
};

export const onRequest = [abTest];
```

## Deploy to Cloudflare Pages

After you have set up your `functions/_middleware.js` file in your project you are ready to deploy with Pages. Push your project changes to GitHub/GitLab.

After you have deployed your application, review your middleware Function:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In Account Home, select **Workers & Pages**.
3. In **Overview**, select your Pages project > **Settings** > **Functions** > **Configuration**.

---

# Enable Web Analytics

URL: https://developers.cloudflare.com/pages/how-to/web-analytics/

import { Render } from "~/components";

<Render file="web-analytics-definition" product="web-analytics" />

## Enable on Pages project

Cloudflare Pages offers a one-click setup for Web Analytics:

<Render file="web-analytics-setup" />

## View metrics

To view the metrics associated with your Pages project:

1. Log in to [Cloudflare dashboard](https://dash.cloudflare.com/login).
2. From Account Home, select **Analytics & Logs** > **Web Analytics**.
3. Select the analytics associated with your Pages project.

For more details about how to use Web Analytics, refer to the [Web Analytics documentation](/web-analytics/data-metrics/).

## Troubleshooting

<Render file="web-analytics-troubleshooting" product="web-analytics" />

---

# Redirecting www to domain apex

URL: https://developers.cloudflare.com/pages/how-to/www-redirect/

import { Example } from "~/components";

Learn how to redirect a `www` subdomain to your apex domain (`example.com`).

This setup assumes that you already have a [custom domain](/pages/configuration/custom-domains/) attached to your Pages project.

## Setup

To redirect your `www` subdomain to your domain apex:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Bulk Redirects**.
3. [Create a bulk redirect list](/rules/url-forwarding/bulk-redirects/create-dashboard/#1-create-a-bulk-redirect-list) modeled after the following (but replacing the values as appropriate):

<Example>

| Source URL        | Target URL            | Status | Parameters                                                                                                               |
| ----------------- | --------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| `www.example.com` | `https://example.com` | `301`  | <ul><li>Preserve query string</li><li>Subpath matching</li><li>Preserve path suffix</li><li>Include subdomains</li></ul> |

</Example>

4. [Create a bulk redirect rule](/rules/url-forwarding/bulk-redirects/create-dashboard/#2-create-a-bulk-redirect-rule) using the list you just created.
5. Go to **DNS**.
6. [Create a DNS record](/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records) for the `www` subdomain using the following values:

<Example>

| Type | Name  | IPv4 address | Proxy status |
| ---- | ----- | ------------ | ------------ |
| `A`  | `www` | `192.0.2.1`  | Proxied      |

</Example>

It may take a moment for this DNS change to propagate, but once complete, you can run the following command in your terminal.

```sh
curl --head -i https://www.example.com/
```

Then, inspect the output to verify that the `location` header and status code are being set as configured.

## Related resources

- [Redirect `*.pages.dev` to a custom domain](/pages/how-to/redirect-to-custom-domain/)
- [Handle redirects with Bulk Redirects](/rules/url-forwarding/bulk-redirects/)

---

# Migration guides

URL: https://developers.cloudflare.com/pages/migrations/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Migrating from Firebase

URL: https://developers.cloudflare.com/pages/migrations/migrating-from-firebase/

In this tutorial, you will learn how to migrate an existing Firebase application to Cloudflare Pages. You should already have an existing project deployed on Firebase that you would like to host on Cloudflare Pages.

## Finding your build command and build directory

To move your application to Cloudflare Pages, you will need to find your build command and build directory.

You will use these to tell Cloudflare Pages how to deploy your project. If you have been deploying manually from your local machine using the `firebase` command-line tool, the `firebase.json` configuration file should include a `public` key that will be your build directory:

```json title="firebase.json"
{
	"public": "public"
}
```

Firebase Hosting does not ask for your build command, so if you are running a standard JavaScript set up, you will probably be using `npm build` or a command specific to the framework or tool you are using (for example, `ng build`).

After you have found your build directory and build command, you can move your project to Cloudflare Pages.

## Creating a new Pages project

If you have not pushed your static site to GitHub before, you should do so before continuing. This will also give you access to features like automatic deployments, and [deployment previews](/pages/configuration/preview-deployments/).

You can create a new repository by visiting [repo.new](https://repo.new) and following the instructions to push your project up to GitHub.

Use the [Get started guide](/pages/get-started/) to add your project to Cloudflare Pages, using the **build command** and **build directory** that you saved earlier.

## Cleaning up your old application and assigning the domain

Once you have deployed your application, go to the Firebase dashboard and remove your old Firebase project. In your Cloudflare DNS settings for your domain, make sure to update the CNAME record for your domain from Firebase to Cloudflare Pages.

By completing this guide, you have successfully migrated your Firebase project to Cloudflare Pages.

---

# Migrating a Jekyll-based site from GitHub Pages

URL: https://developers.cloudflare.com/pages/migrations/migrating-jekyll-from-github-pages/

In this tutorial, you will learn how to migrate an existing [GitHub Pages site using Jekyll](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll) to Cloudflare Pages. Jekyll is one of the most popular static site generators used with GitHub Pages, and migrating your GitHub Pages site to Cloudflare Pages will take a few short steps.

This tutorial will guide you through:

1. Adding the necessary dependencies used by GitHub Pages to your project configuration.
2. Creating a new Cloudflare Pages site, connected to your existing GitHub repository.
3. Building and deploying your site on Cloudflare Pages.
4. (Optional) Migrating your custom domain.

Including build times, this tutorial should take you less than 15 minutes to complete.

:::note

If you have a Jekyll-based site not deployed on GitHub Pages, refer to [the Jekyll framework guide](/pages/framework-guides/deploy-a-jekyll-site/).

:::

## Before you begin

This tutorial assumes:

1. You have an existing GitHub Pages site using [Jekyll](https://jekyllrb.com/)
2. You have some familiarity with running Ruby's command-line tools, and have both `gem` and `bundle` installed.
3. You know how to use a few basic Git operations, including `add`, `commit`, `push`, and `pull`.
4. You have read the [Get Started](/pages/get-started/) guide for Cloudflare Pages.

If you do not have Rubygems (`gem`) or Bundler (`bundle`) installed on your machine, refer to the installation guides for [Rubygems](https://rubygems.org/pages/download) and [Bundler](https://bundler.io/).

## Preparing your GitHub Pages repository

:::note

If your GitHub Pages repository already has a `Gemfile` and `Gemfile.lock` present, you can skip this step entirely. The GitHub Pages environment assumes a default set of Jekyll plugins that are not explicitly specified in a `Gemfile`.

:::

Your existing Jekyll-based repository must specify a `Gemfile` (Ruby's dependency configuration file) to allow Cloudflare Pages to fetch and install those dependencies during the [build step](/pages/configuration/build-configuration/).

Specifically, you will need to create a `Gemfile` and install the `github-pages` gem, which includes all of the dependencies that the GitHub Pages environment assumes.

[Version 2 of the Pages build environment](/pages/configuration/build-image/#languages-and-runtime) will use Ruby 3.2.2 for the default Jekyll build. Please make sure your local development environment is compatible.

```sh title="Set Ruby Version"
brew install ruby@3.2
export PATH="/usr/local/opt/ruby@3.2/bin:$PATH"
```

```sh title="Create a Gemfile"
cd my-github-pages-repo
bundle init
```

Open the `Gemfile` that was created for you, and add the following line to the bottom of the file:

```ruby title="Specifying the github-pages version"
gem "github-pages", group: :jekyll_plugins
```

Your `Gemfile` should resemble the below:

```ruby
# frozen_string_literal: true

source "https://rubygems.org"

git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }

# gem "rails"
gem "github-pages", group: :jekyll_plugins
```

Run `bundle update`, which will install the `github-pages` gem for you, and create a `Gemfile.lock` file with the resolved dependency versions.

```sh title="Running bundle update"
bundle update
# Bundler will show a lot of output as it fetches the dependencies
```

This should complete successfully. If not, verify that you have copied the `github-pages` line above exactly, and have not commented it out with a leading `#`.

You will now need to commit these files to your repository so that Cloudflare Pages can reference them in the following steps:

```sh title="Commit Gemfile and Gemfile.lock"
git add Gemfile Gemfile.lock
git commit -m "deps: added Gemfiles"
git push origin main
```

## Configuring your Pages project

With your GitHub Pages project now explicitly specifying its dependencies, you can start configuring Cloudflare Pages. The process is almost identical to [deploying a Jekyll site](/pages/framework-guides/deploy-a-jekyll-site/).

:::note

If you are configuring your Cloudflare Pages site for the first time, refer to the [Git integration guide](/pages/get-started/git-integration/), which explains how to connect your existing Git repository to Cloudflare Pages.

:::

To deploy your site to Pages:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**.
3. Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information:

<div>

| Configuration option | Value          |
| -------------------- | -------------- |
| Production branch    | `main`         |
| Build command        | `jekyll build` |
| Build directory      | `_site`        |

</div>

After you have configured your site, you can begin your first deploy. You should see Cloudflare Pages installing `jekyll`, your project dependencies, and building your site, before deploying it.

:::note

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

:::

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`. Every time you commit new code to your Jekyll site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

## Migrating your custom domain

If you are using a [custom domain with GitHub Pages](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site), you must update your DNS record(s) to point at your new Cloudflare Pages deployment. This will require you to update the `CNAME` record at the DNS provider for your domain to point to `<your-pages-site>.pages.dev`, replacing `<your-username>.github.io`.

Note that it may take some time for DNS caches to expire and for this change to be reflected, depending on the DNS TTL (time-to-live) value you set when you originally created the record.

Refer to the [adding a custom domain](/pages/configuration/custom-domains/#add-a-custom-domain) section of the Get started guide for a list of detailed steps.

## What's next?

- Learn how to [customize HTTP response headers](/pages/how-to/add-custom-http-headers/) for your Pages site using Cloudflare Workers.
- Understand how to [rollback a potentially broken deployment](/pages/configuration/rollbacks/) to a previously working version.
- [Configure redirects](/pages/configuration/redirects/) so that visitors are always directed to your 'canonical' custom domain.

---

# Advanced mode

URL: https://developers.cloudflare.com/pages/functions/advanced-mode/

import { TabItem, Tabs } from "~/components";

Advanced mode allows you to develop your Pages Functions with a `_worker.js` file rather than the `/functions` directory.

In some cases, Pages Functions' built-in file path based routing and middleware system is not desirable for existing applications. You may have a Worker that is complex and difficult to splice up into Pages' file-based routing system. For these cases, Pages offers the ability to define a `_worker.js` file in the output directory of your Pages project.

When using a `_worker.js` file, the entire `/functions` directory is ignored, including its routing and middleware characteristics. Instead, the `_worker.js` file is deployed and must be written using the [Module Worker syntax](/workers/runtime-apis/handlers/fetch/). If you have never used Module syntax, refer to the [JavaScript modules blog post](https://blog.cloudflare.com/workers-javascript-modules/) to learn more. Using Module syntax enables JavaScript frameworks to generate a Worker as part of the Pages output directory contents.

## Set up a Function

In advanced mode, your Function will assume full control of all incoming HTTP requests to your domain. Your Function is required to make or forward requests to your project's static assets. Failure to do so will result in broken or unwanted behavior. Your Function must be written in Module syntax.

After making a `_worker.js` file in your output directory, add the following code snippet:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		if (url.pathname.startsWith("/api/")) {
			// TODO: Add your custom /api/* logic here.
			return new Response("Ok");
		}
		// Otherwise, serve the static assets.
		// Without this, the Worker will error and no assets will be served.
		return env.ASSETS.fetch(request);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
// Note: You would need to compile your TS into JS and output it as a `_worker.js` file. We do not read `_worker.ts`

interface Env {
	ASSETS: Fetcher;
}

export default {
	async fetch(request, env): Promise<Response> {
		const url = new URL(request.url);
		if (url.pathname.startsWith("/api/")) {
			// TODO: Add your custom /api/* logic here.
			return new Response("Ok");
		}
		// Otherwise, serve the static assets.
		// Without this, the Worker will error and no assets will be served.
		return env.ASSETS.fetch(request);
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

In the above code, you have configured your Function to return a response under all requests headed for `/api/`. Otherwise, your Function will fallback to returning static assets.

- The `env.ASSETS.fetch()` function will allow you to return assets on a given request.
- `env` is the object that contains your environment variables and bindings.
- `ASSETS` is a default Function binding that allows communication between your Function and Pages' asset serving resource.
- `fetch()` calls to Pages' asset-serving resource and serves the requested asset.

## Migrate from Workers

To migrate an existing Worker to your Pages project, copy your Worker code and paste it into your new `_worker.js` file. Then handle static assets by adding the following code snippet to `_worker.js`:

```ts
return env.ASSETS.fetch(request);
```

## Deploy your Function

After you have set up a new Function or migrated your Worker to `_worker.js`, make sure your `_worker.js` file is placed in your Pages' project output directory. Deploy your project through your Git integration for advanced mode to take effect.

---

# API reference

URL: https://developers.cloudflare.com/pages/functions/api-reference/

The following methods can be used to configure your Pages Function.

## Methods

### `onRequests`

The `onRequest` method will be called unless a more specific `onRequestVerb` method is exported. For example, if both `onRequest` and `onRequestGet` are exported, only `onRequestGet` will be called for `GET` requests.

- <code>onRequest(context[EventContext](#eventcontext))</code> Response | Promise\<Response>

  - This function will be invoked on all requests no matter what the request method is, as long as no specific request verb (like one of the methods below) is exported.

- <code>onRequestGet(context[EventContext](#eventcontext))</code> Response | Promise\<Response>

  - This function will be invoked on all `GET` requests.

- <code>onRequestPost(context[EventContext](#eventcontext))</code> Response | Promise\<Response>

  - This function will be invoked on all `POST` requests.

- <code>onRequestPatch(context[EventContext](#eventcontext))</code> Response | Promise\<Response>

  - This function will be invoked on all `PATCH` requests.

- <code>onRequestPut(context[EventContext](#eventcontext))</code> Response | Promise\<Response>

  - This function will be invoked on all `PUT` requests.

- <code>onRequestDelete(context[EventContext](#eventcontext))</code> Response | Promise\<Response>

  - This function will be invoked on all `DELETE` requests.

- <code>onRequestHead(context[EventContext](#eventcontext))</code> Response | Promise\<Response>

  - This function will be invoked on all `HEAD` requests.

- <code>onRequestOptions(context[EventContext](#eventcontext))</code> Response | Promise\<Response>

  - This function will be invoked on all `OPTIONS` requests.

### `env.ASSETS.fetch()`

The `env.ASSETS.fetch()` function allows you to fetch a static asset from your Pages project.

You can pass a [Request object](/workers/runtime-apis/request/), URL string, or URL object to `env.ASSETS.fetch()` function. The URL must be to the pretty path, not directly to the asset. For example, if you had the path `/users/index.html`, you will request `/users/` instead of `/users/index.html`. This method call will run the header and redirect rules, modifying the response that is returned.

## Types

### `EventContext`

The following are the properties on the `context` object which are passed through on the `onRequest` methods:

- `request` [Request](/workers/runtime-apis/request/)

  This is the incoming [Request](/workers/runtime-apis/request/).

- `functionPath` string

  This is the path of the request.

- <code>waitUntil(promisePromise\<any>)</code> void

  Refer to [`waitUntil` documentation](/workers/runtime-apis/context/#waituntil) for more information.

- <code>passThroughOnException()</code> void

  Refer to [`passThroughOnException` documentation](/workers/runtime-apis/context/#passthroughonexception) for more information. Note that this will not work on an [advanced mode project](/pages/functions/advanced-mode/).

- <code>next(input?Request | string, init?RequestInit)</code> Promise\<Response>

  Passes the request through to the next Function or to the asset server if no other Function is available.

- `env` [EnvWithFetch](#envwithfetch)

- `params` Params\<P>

  Holds the values from [dynamic routing](/pages/functions/routing/#dynamic-routes).

  In the following example, you have a dynamic path that is `/users/[user].js`. When you visit the site on `/users/nevi` the `params` object would look like:

  ```js
  {
  	user: "nevi";
  }
  ```

  This allows you fetch the dynamic value from the path:

  ```js
  export function onRequest(context) {
  	return new Response(`Hello ${context.params.user}`);
  }
  ```

  Which would return `"Hello nevi"`.

- `data` Data

### `EnvWithFetch`

Holds the environment variables, secrets, and bindings for a Function. This also holds the `ASSETS` binding which is how you can fallback to the asset-serving behavior.

---

# Bindings

URL: https://developers.cloudflare.com/pages/functions/bindings/

import { Render, TabItem, Tabs, WranglerConfig } from "~/components";

A [binding](/workers/runtime-apis/bindings/) 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](/kv/concepts/how-kv-works/), [Durable Objects](/durable-objects/), [R2](/r2/), and [D1](/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.

:::note

Pages Functions only support a subset of all [bindings](/workers/runtime-apis/bindings/), which are listed on this page.

:::

## KV namespaces

[Workers KV](/kv/concepts/kv-namespaces/) is Cloudflare's key-value storage solution.

To bind your KV namespace to your Pages Function, you can configure a KV namespace binding in the [Wrangler configuration file](/pages/functions/wrangler-configuration/#kv-namespaces) or the Cloudflare dashboard.

To configure a KV namespace binding via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project > **Settings**.
4. Select your Pages environment > **Bindings** > **Add** > **KV namespace**.
5. Give your binding a name under **Variable name**.
6. Under **KV namespace**, select your desired namespace.
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`:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

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

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
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);
};
```

</TabItem> </Tabs>

### 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 file and run [`npx wrangler pages dev`](/workers/wrangler/commands/#dev-1).
- 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:

```sh
npx wrangler pages dev <OUTPUT_DIR> --kv=TODO_LIST
```

<Render file="cli-precedence-over-file" />

## Durable Objects

[Durable Objects](/durable-objects/) (DO) are Cloudflare's strongly consistent data store that power capabilities such as connecting WebSockets and handling state.

<Render file="do-note" product="pages" />

To bind your Durable Object to your Pages Function, you can configure a Durable Object binding in the [Wrangler configuration file](/pages/functions/wrangler-configuration/#kv-namespaces) or the Cloudflare dashboard.

To configure a Durable Object binding via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project > **Settings**.
4. Select your Pages environment > **Bindings** > **Add** > **Durable Object**.
5. Give your binding a name under **Variable name**.
6. Under **Durable Object namespace**, select your desired namespace.
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`:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
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);
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
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);
};
```

</TabItem> </Tabs>

### 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 file and run [`npx wrangler pages dev`](/workers/wrangler/commands/#dev-1).
- 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`).

<Render file="cli-precedence-over-file" />

## R2 buckets

[R2](/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 the [Wrangler configuration file](/pages/functions/wrangler-configuration/#r2-buckets) or the Cloudflare dashboard.

To configure a R2 bucket binding via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project > **Settings**.
4. Select your Pages environment > **Bindings** > **Add** > **R2 bucket**.
5. Give your binding a name under **Variable name**.
6. Under **R2 bucket**, select your desired R2 bucket.
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`:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
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);
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
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);
};
```

</TabItem> </Tabs>

### 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 file and run [`npx wrangler pages dev`](/workers/wrangler/commands/#dev-1).
- Pass arguments to `wrangler pages dev` directly.

:::note

By default, Wrangler automatically persists data to local storage. For more information, refer to [Local development](/workers/development-testing/).

:::

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:

```sh
npx wrangler pages dev <OUTPUT_DIR> --r2=BUCKET
```

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

<Render file="cli-precedence-over-file" />

## D1 databases

[D1](/d1/) is Cloudflare’s native serverless database.

To bind your D1 database to your Pages Function, you can configure a D1 database binding in the [Wrangler configuration file](/pages/functions/wrangler-configuration/#d1-databases) or the Cloudflare dashboard.

To configure a D1 database binding via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project > **Settings**.
4. Select your Pages environment > **Bindings** > **Add**> **D1 database bindings**.
5. Give your binding a name under **Variable name**.
6. Under **D1 database**, select your desired D1 database.
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`:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
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);
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
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);
};
```

</TabItem> </Tabs>

### 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 file and run [`npx wrangler pages dev`](/workers/wrangler/commands/#dev-1).
- Pass arguments to `wrangler pages dev` directly.

To interact with a D1 database via the Wrangler CLI while [developing locally](/d1/best-practices/local-development/#develop-locally-with-pages), 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 file is `xxxx-xxxx-xxxx-xxxx-xxxx`, access this database in local development by running:

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

:::note

By default, Wrangler automatically persists data to local storage. For more information, refer to [Local development](/workers/development-testing/).

:::

Refer to the [D1 Workers Binding API documentation](/d1/worker-api/) for the API methods available on your D1 binding.

<Render file="cli-precedence-over-file" />

## Vectorize indexes

[Vectorize](/vectorize/) is Cloudflare’s native vector database.

To bind your Vectorize index to your Pages Function, you can configure a Vectorize index binding in the [Wrangler configuration file](/pages/functions/wrangler-configuration/#vectorize-indexes) or the Cloudflare dashboard.

To configure a Vectorize index binding via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) 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**.
5. Select your Pages environment > **Bindings** > **Add** > **Vectorize index**.
6. Give your binding a name under **Variable name**.
7. Under **Vectorize index**, select your desired Vectorize index.
8. 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`.

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
// 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);
	}
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
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);
	}
};
```

</TabItem> </Tabs>

## Workers AI

[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 the [Wrangler configuration file](/pages/functions/wrangler-configuration/#workers-ai) 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`](/workers/wrangler/commands/#dev) to expose the `context.env.AI` binding.

To configure a Workers AI binding via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project > **Settings**.
4. Select your Pages environment > **Bindings** > **Add** > **Workers AI**.
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`.

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
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-3.1-8b-instruct",
		input,
	);

	return Response.json(answer);
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Env {
	AI: Ai;
}

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-3.1-8b-instruct",
		input,
	);

	return Response.json(answer);
};
```

</TabItem> </Tabs>

### Interact with your Workers AI binding locally

<Render file="ai-local-usage-charges" product="workers" />

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

- Configure your Pages project's Wrangler file and run [`npx wrangler pages dev`](/workers/wrangler/commands/#dev-1).
- Pass arguments to `wrangler pages dev` directly.

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

```sh
npx wrangler pages dev --ai=<BINDING_NAME>
```

<Render file="cli-precedence-over-file" />

## Service bindings

[Service bindings](/workers/runtime-apis/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 the [Wrangler configuration file](/pages/functions/wrangler-configuration/#service-bindings) or the Cloudflare dashboard.

To configure a Service binding via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project > **Settings**.
4. Select your Pages environment > **Bindings** > **Add** > **Service binding**.
5. Give your binding a name under **Variable name**.
6. Under **Service**, select your desired Worker.
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`:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

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

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Env {
	SERVICE: Fetcher;
}

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

</TabItem> </Tabs>

### 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 file and run [`npx wrangler pages dev`](/workers/wrangler/commands/#dev-1).
- Pass arguments to `wrangler pages dev` directly.

To interact with a [Service binding](/workers/runtime-apis/bindings/service-bindings/) 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`).

Wrangler also supports running your Pages project and bound Workers in the same dev session with one command. To try it out, pass multiple -c flags to Wrangler, like this: `wrangler pages dev -c wrangler.toml -c ../other-worker/wrangler.toml`. The first argument must point to your Pages configuration file, and the subsequent configurations will be accessible via a Service binding from your Pages project.

:::caution

Support for running multiple Workers in the same dev session with one Wrangler command is experimental, and subject to change as we work on the experience. If you run into bugs or have any feedback, [open an issue on the workers-sdk repository](https://github.com/cloudflare/workers-sdk/issues/new)

:::

<Render file="cli-precedence-over-file" />

## Queue Producers

[Queue Producers](/queues/configuration/javascript-apis/#producer) 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 the [Wrangler configuration file](/pages/functions/wrangler-configuration/#queues-producers) or the Cloudflare dashboard:

To configure a queue producer binding via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project > **Settings**.
4. Select your Pages environment > **Functions** > **Add** > **Queue**.
5. Give your binding a name under **Variable name**.
6. Under **Queue**, select your desired queue.
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`:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
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!");
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
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!");
};
```

</TabItem> </Tabs>

### 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](/queues/get-started/#5-create-your-consumer-worker) with a [queue consumer handler](/queues/configuration/javascript-apis/#consumer) to consume events from the queue. Wrangler does not yet support running separate producer Functions and consumer Workers bound to the same queue locally.

## Hyperdrive configs

:::note

PostgreSQL drivers like [`Postgres.js`](https://github.com/porsager/postgres) depend on Node.js APIs. Pages Functions with Hyperdrive bindings must be [deployed with Node.js compatibility](/workers/runtime-apis/nodejs).

<WranglerConfig>

```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_compat" ]
compatibility_date = "2024-09-23"
```

</WranglerConfig>

:::

[Hyperdrive](/hyperdrive/) is a service for connecting to your existing databases from Cloudflare Workers and Pages Functions.

To bind your Hyperdrive config to your Pages Function, you can configure a Hyperdrive binding in the [Wrangler configuration file](/pages/functions/wrangler-configuration/#hyperdrive) or the Cloudflare dashboard.

To configure a Hyperdrive binding via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project > **Settings**.
4. Select your Pages environment > **Bindings** > **Add** > **Hyperdrive**.
5. Give your binding a name under **Variable name**.
6. Under **Hyperdrive configuration**, select your desired configuration.
7. Redeploy your project for the binding to take effect.

Below is an example of how to use Hyperdrive in your Function. In the following example, your Hyperdrive config is named `HYPERDRIVE` and you can access the binding in your Function code on `context.env`:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import postgres from "postgres";

export async function onRequest(context) {
	// create connection to postgres database
	const sql = postgres(context.env.HYPERDRIVE.connectionString);

	try {
		const result = await sql`SELECT id, name, value FROM records`;

		return Response.json({result: result})
	} catch (e) {
		return Response.json({error: e.message, {status: 500}});
	}
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import postgres from "postgres";

interface Env {
	HYPERDRIVE: Hyperdrive;
}

type MyRecord = {
	id: number;
	name: string;
	value: string;
};

export const onRequest: PagesFunction<Env> = async (context) => {
	// create connection to postgres database
	const sql = postgres(context.env.HYPERDRIVE.connectionString);

	try {
		const result = await sql<MyRecord[]>`SELECT id, name, value FROM records`;

		return Response.json({result: result})
	} catch (e) {
		return Response.json({error: e.message, {status: 500}});
	}
};
```

</TabItem> </Tabs>

### Interact with your Hyperdrive binding locally

To interact with your Hyperdrive binding locally, you must provide a local connection string to your database that your Pages project will connect to directly. You can set an environment variable `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` with the connection string of the database, or use the Wrangler file to configure your Hyperdrive binding with a `localConnectionString` as specified in [Hyperdrive documentation for local development](/hyperdrive/configuration/local-development/). Then, run [`npx wrangler pages dev <OUTPUT_DIR>`](/workers/wrangler/commands/#dev-1).

## Analytics Engine

The [Analytics Engine](/analytics/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 the [Wrangler configuration file](/pages/functions/wrangler-configuration/#analytics-engine-datasets) or the Cloudflare dashboard:

To configure an Analytics Engine binding via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project > **Settings**.
4. Select your Pages environment > **Bindings** > **Add** > **Analytics engine**.
5. Give your binding a name under **Variable name**.
6. Under **Dataset**, input your desired dataset.
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`:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
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");
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
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");
};
```

</TabItem> </Tabs>

### Interact with your Analytics Engine binding locally

You cannot use an Analytics Engine binding locally.

## Environment variables

An [environment variable](/workers/configuration/environment-variables/) 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 the [Wrangler configuration file](/pages/functions/wrangler-configuration/#environment-variables) or the Cloudflare dashboard.

To configure an environment variable via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project > **Settings**.
4. Select your Pages environment > **Variables and Secrets** > **Add** .
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`:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
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");
	}
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
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");
	}
};
```

</TabItem> </Tabs>

### 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 file and running `npx wrangler pages dev`.
- Pass arguments to [`wrangler pages dev`](/workers/wrangler/commands/#dev-1) 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:

```sh
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](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project > select **Settings**.
4. Select your Pages environment > **Variables and Secrets** > **Add**.
5. Set a variable name and value.
6. Select **Encrypt** to create your secret.
7. 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](#environment-variables).

### Local development with secrets

<Render file="secrets-in-dev" product="workers" />

---

# Debugging and logging

URL: https://developers.cloudflare.com/pages/functions/debugging-and-logging/

Access your Functions logs by using the Cloudflare dashboard or the [Wrangler CLI](/workers/wrangler/commands/#deployment-tail).

Logs are a powerful debugging tool that can help you test and monitor the behavior of your Pages Functions once they have been deployed. Logs are available for every deployment of your Pages project.

Logs provide detailed information about events and can give insight into:

- Successful or failed requests to your Functions.
- Uncaught exceptions thrown by your Functions.
- Custom `console.log`s declared within your Functions.
- Production issues that cannot be easily reproduced.
- Real-time view of incoming requests to your application.

There are two ways to start a logging session:

1. Run `wrangler pages deployment tail` [in your terminal](/pages/functions/debugging-and-logging/#view-logs-with-wrangler).
2. Use the [Cloudflare dashboard](/pages/functions/debugging-and-logging/#view-logs-in-the-cloudflare-dashboard).

## Add custom logs

Custom logs are `console.log()` statements that you can add yourself inside your Functions. When streaming logs for deployments that contain these Functions, the statements will appear in both `wrangler pages deployment tail` and dashboard outputs.

Below is an example of a custom `console.log` statement inside a Pages Function:

```js
export async function onRequest(context) {
	console.log(
		`[LOGGING FROM /hello]: Request came from ${context.request.url}`,
	);

	return new Response("Hello, world!");
}
```

After you deploy the code above, run `wrangler pages deployment tail` in your terminal. Then access the route at which your Function lives. Your terminal will display:

![Run wrangler pages deployment tail](~/assets/images/pages/platform/functions/wrangler-custom-logs.png)

Your dashboard will display:

![Follow the above steps to access custom logs in the dashboard](~/assets/images/pages/platform/functions/dash-custom-logs.png)

## View logs with Wrangler

`wrangler pages deployment tail` enables developers to livestream logs for a specific project and deployment.

To get started, run `wrangler pages deployment tail` in your Pages project directory. This will log any incoming requests to your application in your local terminal.

The output of each `wrangler pages deployment tail` log is a structured JSON object:

```js
{
  "outcome": "ok",
  "scriptName": null,
  "exceptions": [
    {
      "stack": "    at src/routes/index.tsx17:4\n    at new Promise (<anonymous>)\n",
      "name": "Error",
      "message": "An error has occurred",
      "timestamp": 1668542036110
    }
  ],
  "logs": [],
  "eventTimestamp": 1668542036104,
  "event": {
    "request": {
      "url": "https://pages-fns.pages.dev",
      "method": "GET",
      "headers": {},
      "cf": {}
    },
    "response": {
      "status": 200
    }
  },
  "id": 0
}
```

`wrangler pages deployment tail` allows you to customize a logging session to better suit your needs. Refer to the [`wrangler pages deployment tail` documentation](/workers/wrangler/commands/#deployment-tail) for available configuration options.

## View logs in the Cloudflare Dashboard

To view logs for your `production` or `preview` environments associated with any deployment:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. Select your Pages project, go to the deployment you want to view logs for and select **View details** > **Functions**.

Logging is available for all customers (Free, Paid, Enterprise).

## Limits

The following limits apply to Functions logs:

- Logs are not stored. You can start and stop the stream at any time to view them, but they do not persist.
- Logs will not display if the Function’s requests per second are over 100 for the last five minutes.
- Logs from any [Durable Objects](/pages/functions/bindings/#durable-objects) your Functions bind to will show up in the Cloudflare dashboard.
- A maximum of 10 clients can view a deployment’s logs at one time. This can be a combination of either dashboard sessions or `wrangler pages deployment tail` calls.

## Sourcemaps

If you're debugging an uncaught exception, you might find that the [stack traces](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack) in your logs contain line numbers to generated JavaScript files. Using Pages' support for [source maps](https://web.dev/articles/source-maps) you can get stack traces that match with the line numbers and symbols of your original source code.

:::note

When developing fullstack applications, many build tools (including wrangler for Pages Functions and most fullstack frameworks) will generate source maps for both the client and server, ensure your build step is configured to only emit server sourcemaps or use an additional build step to remove the client source maps. Public source maps might expose the source code of your application to the user.

:::

Refer to [Source maps and stack traces](/pages/functions/source-maps/) for an in-depth explanation.

---

# Get started

URL: https://developers.cloudflare.com/pages/functions/get-started/

This guide will instruct you on creating and deploying a Pages Function.

## Prerequisites

You must have a Pages project set up on your local machine or deployed on the Cloudflare dashboard. To create a Pages project, refer to [Get started](/pages/get-started/).

## Create a Function

To get started with generating a Pages Function, create a `/functions` directory. Make sure that the `/functions` directory is at the root of your Pages project (and not in the static root, such as `/dist`).

:::note[Advanced mode]

For existing applications where Pages Functions’ built-in file path based routing and middleware system is not desirable, use [Advanced mode](/pages/functions/advanced-mode/). Advanced mode allows you to develop your Pages Functions with a `_worker.js` file rather than the `/functions` directory.

:::

Writing your Functions files in the `/functions` directory will automatically generate a Worker with custom functionality at predesignated routes.

Copy and paste the following code into a `helloworld.js` file that you create in your `/functions` folder:

```js
export function onRequest(context) {
	return new Response("Hello, world!");
}
```

In the above example code, the `onRequest` handler takes a request [`context`](/pages/functions/api-reference/#eventcontext) object. The handler must return a `Response` or a `Promise` of a `Response`.

This Function will run on the `/helloworld` route and returns `"Hello, world!"`. The reason this Function is available on this route is because the file is named `helloworld.js`. Similarly, if this file was called `howdyworld.js`, this function would run on `/howdyworld`.

Refer to [Routing](/pages/functions/routing/) for more information on route customization.

### Runtime features

[Workers runtime features](/workers/runtime-apis/) are configurable on Pages Functions, including [compatibility with a subset of Node.js APIs](/workers/runtime-apis/nodejs) and the ability to set a [compatibility date or compatibility flag](/workers/configuration/compatibility-dates/).

Set these configurations by passing an argument to your [Wrangler](/workers/wrangler/commands/#dev-1) command or by setting them in the dashboard. To set Pages compatibility flags in the Cloudflare dashboard:

1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages** and select your Pages project.
3. Select **Settings** > **Functions** > **Compatibility Flags**.
4. Configure your Production and Preview compatibility flags as needed.

Additionally, use other Cloudflare products such as [D1](/d1/) (serverless DB) and [R2](/r2/) from within your Pages project by configuring [bindings](/pages/functions/bindings/).

## Deploy your Function

After you have set up your Function, deploy your Pages project. Deploy your project by:

- Connecting your [Git provider](/pages/get-started/git-integration/).
- Using [Wrangler](/workers/wrangler/commands/#pages) from the command line.

:::caution

[Direct Upload](/pages/get-started/direct-upload/) from the Cloudflare dashboard is currently not supported with Functions.
:::

## Related resources

- Customize your [Function's routing](/pages/functions/routing/)
- Review the [API reference](/pages/functions/api-reference/)
- Learn how to [debug your Function](/pages/functions/debugging-and-logging/)

---

# Functions

URL: https://developers.cloudflare.com/pages/functions/

import { DirectoryListing } from "~/components";

Pages Functions allows you to build full-stack applications by executing code on the Cloudflare network with [Cloudflare Workers](/workers/). With Functions, you can introduce application aspects such as authenticating, handling form submissions, or working with middleware. [Workers runtime features](/workers/runtime-apis/) are configurable on Pages Functions, including [compatibility with a subset of Node.js APIs](/workers/runtime-apis/nodejs) and the ability to set a [compatibility date or compatibility flag](/workers/configuration/compatibility-dates/). Use Functions to deploy server-side code to enable dynamic functionality without running a dedicated server.

To provide feedback or ask questions on Functions, join the [Cloudflare Developers Discord](https://discord.com/invite/cloudflaredev) and connect with the Cloudflare team in the [#functions channel](https://discord.com/channels/595317990191398933/910978223968518144).

<DirectoryListing />

---

# Local development

URL: https://developers.cloudflare.com/pages/functions/local-development/

Run your Pages application locally with our Wrangler Command Line Interface (CLI).

## Install Wrangler

To get started with Wrangler, refer to the [Install/Update Wrangler](/workers/wrangler/install-and-update/).

## Run your Pages project locally

The main command for local development on Pages is `wrangler pages dev`. This will let you run your Pages application locally, which includes serving static assets and running your Functions.

With your folder of static assets set up, run the following command to start local development:

```sh
npx wrangler pages dev <DIRECTORY-OF-ASSETS>
```

This will then start serving your Pages project. You can press `b` to open the browser on your local site, (available, by default, on [http://localhost:8788](http://localhost:8788)).

:::note

If you have a [Wrangler configuration file](/pages/functions/wrangler-configuration/) file configured for your Pages project, you can run [`wrangler pages dev`](/workers/wrangler/commands/#dev-1) without specifying a directory.

:::

### HTTPS support

To serve your local development server over HTTPS with a self-signed certificate, you can [set `local_protocol` via the [Wrangler configuration file](/pages/functions/wrangler-configuration/#local-development-settings) or you can pass the `--local-protocol=https` argument to [`wrangler pages dev`](/workers/wrangler/commands/#dev-1):

```sh
npx wrangler pages dev --local-protocol=https <DIRECTORY-OF-ASSETS>
```

## Attach bindings to local development

To attach a binding to local development, refer to [Bindings](/pages/functions/bindings/) and find the Cloudflare Developer Platform resource you would like to work with.

## Additional Wrangler configuration

If you are using a Wrangler configuration file in your project, you can set up dev server values like: `port`, `local protocol`, `ip`, and `port`. For more information, read about [configuring local development settings](/pages/functions/wrangler-configuration/#local-development-settings).

---

# Metrics

URL: https://developers.cloudflare.com/pages/functions/metrics/

Functions metrics can help you diagnose issues and understand your workloads by showing performance and usage data for your Functions.

## Functions metrics

Functions metrics aggregate request data for an individual Pages project. To view your Functions metrics:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages** > in **Overview**, select your Pages project.
3. In your Pages project, select **Functions Metrics**.

There are three metrics that can help you understand the health of your Function:

1. Requests success.
2. Requests errors.
3. Invocation Statuses.

### Requests

In **Functions metrics**, you can see historical request counts broken down into total requests, successful requests and errored requests. Information on subrequests is available by selecting **Subrequests**.

- **Total**: All incoming requests registered by a Function. Requests blocked by [Web Application Firewall (WAF)](https://www.cloudflare.com/waf/) or other security features will not count.
- **Success**: Requests that returned a `Success` or `Client Disconnected` [invocation status](#invocation-statuses).
- **Errors**: Requests that returned a `Script Threw Exception`, `Exceeded Resources`, or `Internal Error` [invocation status](#invocation-statuses)
- **Subrequests**: Requests triggered by calling `fetch` from within a Function. When your Function fetches a static asset, it will count as a subrequest. A subrequest that throws an uncaught error will not be counted.

Request traffic data may display a drop off near the last few minutes displayed in the graph for time ranges less than six hours. This does not reflect a drop in traffic, but a slight delay in aggregation and metrics delivery.

### Invocation statuses

Function invocation statuses indicate whether a Function executed successfully or failed to generate a response in the Workers runtime. Invocation statuses differ from HTTP status codes. In some cases, a Function invocation succeeds but does not generate a successful HTTP status because of another error encountered outside of the Workers runtime. Some invocation statuses result in a Workers error code being returned to the client.

| Invocation status      | Definition                                            | Workers error code | Graph QL field       |
| ---------------------- | ----------------------------------------------------- | ------------------ | -------------------- |
| Success                | Worker script executed successfully                   |                    | success              |
| Client disconnected    | HTTP client disconnected before the request completed |                    | clientDisconnected   |
| Script threw exception | Worker script threw an unhandled JavaScript exception | 1101               | scriptThrewException |
| Exceeded resources^1   | Worker script exceeded runtime limits                 | 1102, 1027         | exceededResources    |
| Internal error^2       | Workers runtime encountered an error                  |                    | internalError        |

1. The Exceeded Resources status may appear when the Worker exceeds a [runtime limit](/workers/platform/limits/#request-limits). The most common cause is excessive CPU time, but is also caused by a script exceeding startup time or free tier limits.
2. The Internal Error status may appear when the Workers runtime fails to process a request due to an internal failure in our system. These errors are not caused by any issue with the Function code nor any resource limit. While requests with Internal Error status are rare, some may appear during normal operation. These requests are not counted towards usage for billing purposes. If you notice an elevated rate of requests with Internal Error status, review [www.cloudflarestatus.com](http://www.cloudflarestatus.com).

To further investigate exceptions, refer to [Debugging and Logging](/pages/functions/debugging-and-logging)

### CPU time per execution

The CPU Time per execution chart shows historical CPU time data broken down into relevant quantiles using [reservoir sampling](https://en.wikipedia.org/wiki/Reservoir_sampling). Learn more about [interpreting quantiles](https://www.statisticshowto.com/quantile-definition-find-easy-steps/).

In some cases, higher quantiles may appear to exceed [CPU time limits](/workers/platform/limits/#cpu-time) without generating invocation errors because of a mechanism in the Workers runtime that allows rollover CPU time for requests below the CPU limit.

### Duration per execution

The **Duration** chart underneath **Median CPU time** in the **Functions metrics** dashboard shows historical [duration](/workers/platform/limits/#duration) per Function execution. The data is broken down into relevant quantiles, similar to the CPU time chart.

Understanding duration on your Function is useful when you are intending to do a significant amount of computation on the Function itself. This is because you may have to use the Standard or Unbound usage model which allows up to 30 seconds of CPU time.

Workers on the [Bundled Usage Model](/workers/platform/pricing/#workers) may have high durations, even with a 50 ms CPU time limit, if they are running many network-bound operations like fetch requests and waiting on responses.

### Metrics retention

Functions metrics can be inspected for up to three months in the past in maximum increments of one week. The **Functions metrics** dashboard in your Pages project includes the charts and information described above.

---

# Module support

URL: https://developers.cloudflare.com/pages/functions/module-support/

Pages Functions provide support for several module types, much like [Workers](https://blog.cloudflare.com/workers-javascript-modules/). This means that you can import and use external modules such as WebAssembly (Wasm), `text` and `binary` files inside your Functions code.

This guide will instruct you on how to use these different module types inside your Pages Functions.

## ECMAScript Modules

ECMAScript modules (or in short ES Modules) is the official, [standardized](https://tc39.es/ecma262/#sec-modules) module system for JavaScript. It is the recommended mechanism for writing modular and reusable JavaScript code.

[ES Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) are defined by the use of `import` and `export` statements. Below is an example of a script written in ES Modules format, and a Pages Function that imports that module:

```js
export function greeting(name: string): string {
  return `Hello ${name}!`;
}
```

```js
import { greeting } from "../src/greeting.ts";

export async function onRequest(context) {
	return new Response(`${greeting("Pages Functions")}`);
}
```

## WebAssembly Modules

[WebAssembly](/workers/runtime-apis/webassembly/) (abbreviated Wasm) allows you to compile languages like Rust, Go, or C to a binary format that can run in a wide variety of environments, including web browsers, Cloudflare Workers, Cloudflare Pages Functions, and other WebAssembly runtimes.

The distributable, loadable, and executable unit of code in WebAssembly is called a [module](https://webassembly.github.io/spec/core/syntax/modules.html).

Below is a basic example of how you can import Wasm Modules inside your Pages Functions code:

```js
import addModule from "add.wasm";

export async function onRequest() {
	const addInstance = await WebAssembly.instantiate(addModule);
	return new Response(
		`The meaning of life is ${addInstance.exports.add(20, 1)}`,
	);
}
```

## Text Modules

Text Modules are a non-standardized means of importing resources such as HTML files as a `String`.

To import the below HTML file into your Pages Functions code:

```html
<!DOCTYPE html>
<html>
	<body>
		<h1>Hello Pages Functions!</h1>
	</body>
</html>
```

Use the following script:

```js
import html from "../index.html";

export async function onRequest() {
	return new Response(html, {
		headers: { "Content-Type": "text/html" },
	});
}
```

## Binary Modules

Binary Modules are a non-standardized way of importing binary data such as images as an `ArrayBuffer`.

Below is a basic example of how you can import the data from a binary file inside your Pages Functions code:

```js
import data from "../my-data.bin";

export async function onRequest() {
	return new Response(data, {
		headers: { "Content-Type": "application/octet-stream" },
	});
}
```

---

# Middleware

URL: https://developers.cloudflare.com/pages/functions/middleware/

Middleware is reusable logic that can be run before your [`onRequest`](/pages/functions/api-reference/#onrequests) function. Middlewares are typically utility functions. Error handling, user authentication, and logging are typical candidates for middleware within an application.

## Add middleware

Middleware is similar to standard Pages Functions but middleware is always defined in a `_middleware.js` file in your project's `/functions` directory. A `_middleware.js` file exports an [`onRequest`](/pages/functions/api-reference/#onrequests) function. The middleware will run on requests that match any Pages Functions in the same `/functions` directory, including subdirectories. For example, `functions/users/_middleware.js` file will match requests for `/functions/users/nevi`, `/functions/users/nevi/123` and `functions/users`.

If you want to run a middleware on your entire application, including in front of static files, create a `functions/_middleware.js` file.

In `_middleware.js` files, you may export an `onRequest` handler or any of its method-specific variants. The following is an example middleware which handles any errors thrown in your project's Pages Functions. This example uses the `next()` method available in the request handler's context object:

```js
export async function onRequest(context) {
	try {
		return await context.next();
	} catch (err) {
		return new Response(`${err.message}\n${err.stack}`, { status: 500 });
	}
}
```

## Chain middleware

You can export an array of Pages Functions as your middleware handler. This allows you to chain together multiple middlewares that you want to run. In the following example, you can handle any errors generated from your project's Functions, and check if the user is authenticated:

```js
async function errorHandling(context) {
	try {
		return await context.next();
	} catch (err) {
		return new Response(`${err.message}\n${err.stack}`, { status: 500 });
	}
}

function authentication(context) {
	if (context.request.headers.get("x-email") != "admin@example.com") {
		return new Response("Unauthorized", { status: 403 });
	}

	return context.next();
}

export const onRequest = [errorHandling, authentication];
```

In the above example, the `errorHandling` function will run first. It will capture any errors in the `authentication` function and any errors in any other subsequent Pages Functions.

---

# Pricing

URL: https://developers.cloudflare.com/pages/functions/pricing/

Requests to your Functions are billed as Cloudflare Workers requests. Workers plans and pricing can be found [in the Workers documentation](/workers/platform/pricing/).

## Paid Plans

Requests to your Pages functions count towards your quota for Workers Paid plans, including requests from your Function to KV or Durable Object bindings.

Pages supports the [Standard usage model](/workers/platform/pricing/#example-pricing-standard-usage-model).

:::note

Workers Enterprise accounts are billed based on the usage model specified in their contract. To switch to the Standard usage model, reach out to your Customer Success Manager (CSM). Some Workers Enterprise customers maintain the ability to [change usage models](/workers/platform/pricing/#how-to-switch-usage-models).

:::

### Static asset requests

On both free and paid plans, requests to static assets are free and unlimited. A request is considered static when it does not invoke Functions. Refer to [Functions invocation routes](/pages/functions/routing/#functions-invocation-routes) to learn more about when Functions are invoked.

## Free Plan

Requests to your Pages Functions count towards your quota for the Workers Free plan. For example, you could use 50,000 Functions requests and 50,000 Workers requests to use your full 100,000 daily request usage. The free plan daily request limit resets at midnight UTC.

---

# Routing

URL: https://developers.cloudflare.com/pages/functions/routing/

import { FileTree } from "~/components";

Functions utilize file-based routing. Your `/functions` directory structure determines the designated routes that your Functions will run on. You can create a `/functions` directory with as many levels as needed for your project's use case. Review the following directory:

<FileTree>

- ...
- functions
  - index.js
  - helloworld.js
  - howdyworld.js
  - fruits
    - index.js
    - apple.js
    - banana.js

</FileTree>

The following routes will be generated based on the above file structure. These routes map the URL pattern to the `/functions` file that will be invoked when a visitor goes to the URL:

| File path                   | Route                     |
| --------------------------- | ------------------------- |
| /functions/index.js         | example.com               |
| /functions/helloworld.js    | example.com/helloworld    |
| /functions/howdyworld.js    | example.com/howdyworld    |
| /functions/fruits/index.js  | example.com/fruits        |
| /functions/fruits/apple.js  | example.com/fruits/apple  |
| /functions/fruits/banana.js | example.com/fruits/banana |

:::note[Trailing slash]

Trailing slash is optional. Both `/foo` and `/foo/` will be routed to `/functions/foo.js` or `/functions/foo/index.js`. If your project has both a `/functions/foo.js` and `/functions/foo/index.js` file, `/foo` and `/foo/` would route to `/functions/foo/index.js`.

:::

If no Function is matched, it will fall back to a static asset if there is one. Otherwise, the Function will fall back to the [default routing behavior](/pages/configuration/serving-pages/) for Pages' static assets.

## Dynamic routes

Dynamic routes allow you to match URLs with parameterized segments. This can be useful if you are building dynamic applications. You can accept dynamic values which map to a single path by changing your filename.

### Single path segments

To create a dynamic route, place one set of brackets around your filename – for example, `/users/[user].js`. By doing this, you are creating a placeholder for a single path segment:

| Path               | Matches? |
| ------------------ | -------- |
| /users/nevi        | Yes      |
| /users/daniel      | Yes      |
| /profile/nevi      | No       |
| /users/nevi/foobar | No       |
| /nevi              | No       |

### Multipath segments

By placing two sets of brackets around your filename – for example, `/users/[[user]].js` – you are matching any depth of route after `/users/`:

| Path                  | Matches? |
| --------------------- | -------- |
| /users/nevi           | Yes      |
| /users/daniel         | Yes      |
| /profile/nevi         | No       |
| /users/nevi/foobar    | Yes      |
| /users/daniel/xyz/123 | Yes      |
| /nevi                 | No       |

:::note[Route specificity]

More specific routes (routes with fewer wildcards) take precedence over less specific routes.

:::

#### Dynamic route examples

Review the following `/functions/` directory structure:

<FileTree>

- ...
- functions
  - date.js
  - users
    - special.js
    - [user].js
    - [[catchall]].js

</FileTree>

The following requests will match the following files:

| Request               | File                                              |
| --------------------- | ------------------------------------------------- |
| /foo                  | Will route to a static asset if one is available. |
| /date                 | /date.js                                          |
| /users/daniel         | /users/\[user].js                                 |
| /users/nevi           | /users/\[user].js                                 |
| /users/special        | /users/special.js                                 |
| /users/daniel/xyz/123 | /users/\[\[catchall]].js                          |

The URL segment(s) that match the placeholder (`[user]`) will be available in the request [`context`](/pages/functions/api-reference/#eventcontext) object. The [`context.params`](/pages/functions/api-reference/#eventcontext) object can be used to find the matched value for a given filename placeholder.

For files which match a single URL segment (use a single set of brackets), the values are returned as a string:

```js
export function onRequest(context) {
	return new Response(context.params.user);
}
```

The above logic will return `daniel` for requests to `/users/daniel`.

For files which match against multiple URL segments (use a double set of brackets), the values are returned as an array:

```js
export function onRequest(context) {
	return new Response(JSON.stringify(context.params.catchall));
}
```

The above logic will return `["daniel", "xyz", "123"]` for requests to `/users/daniel/xyz/123`.

## Functions invocation routes

On a purely static project, Pages offers unlimited free requests. However, once you add Functions on a Pages project, all requests by default will invoke your Function. To continue receiving unlimited free static requests, exclude your project's static routes by creating a `_routes.json` file. This file will be automatically generated if a `functions` directory is detected in your project when you publish your project with Pages CI or Wrangler.

:::note

Some frameworks (such as [Remix](/pages/framework-guides/deploy-a-remix-site/), [SvelteKit](/pages/framework-guides/deploy-a-svelte-kit-site/)) will also automatically generate a `_routes.json` file. However, if your preferred framework does not, create an issue on their framework repository with a link to this page or let us know on [Discord](https://discord.cloudflare.com). Refer to the [Framework guide](/pages/framework-guides/) for more information on full-stack frameworks.

:::

### Create a `_routes.json` file

Create a `_routes.json` file to control when your Function is invoked. It should be placed in the output directory of your project.

This file will include three different properties:

- **version**: Defines the version of the schema. Currently there is only one version of the schema (version 1), however, we may add more in the future and aim to be backwards compatible.
- **include**: Defines routes that will be invoked by Functions. Accepts wildcard behavior.
- **exclude**: Defines routes that will not be invoked by Functions. Accepts wildcard behavior. `exclude` always take priority over `include`.

:::note

Wildcards match any number of path segments (slashes). For example, `/users/*` will match everything after the`/users/` path.

:::

#### Example configuration

Below is an example of a `_routes.json`.

```json
{
	"version": 1,
	"include": ["/*"],
	"exclude": []
}
```

This `_routes.json` will invoke your Functions on all routes.

Below is another example of a `_routes.json` file. Any route inside the `/build` directory will not invoke the Function and will not incur a Functions invocation charge.

```json
{
	"version": 1,
	"include": ["/*"],
	"exclude": ["/build/*"]
}
```

## Fail open / closed

If on the Workers Free plan, you can configure how Pages behaves when your daily free tier allowance of Pages Functions requests is exhausted. If, for example, you are performing authentication checks or other critical functionality in your Pages Functions, you may wish to disable your Pages project when the allowance is exhausted.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. From **Account Home**, go to **Workers & Pages**.
3. In **Overview**, select your Pages project.
4. Go to **Settings** > **Runtime** > **Fail open / closed**.

"Fail open" means that static assets will continue to be served, even if Pages Functions would ordinarily have run first. "Fail closed" means an error page will be returned, rather than static assets.

The daily request limit for Pages Functions can be removed entirely by upgrading to [Workers Standard](/workers/platform/pricing/#workers).

### Limits

Functions invocation routes have the following limits:

- You must have at least one include rule.
- You may have no more than 100 include/exclude rules combined.
- Each rule may have no more than 100 characters.

---

# Smart Placement

URL: https://developers.cloudflare.com/pages/functions/smart-placement/

By default, [Workers](/workers/) and [Pages Functions](/pages/functions/) are invoked in a data center closest to where the request was received. If you are running back-end logic in a Pages Function, it may be more performant to run that Pages Function closer to your back-end infrastructure rather than the end user. Smart Placement (beta) automatically places your workloads in an optimal location that minimizes latency and speeds up your applications.

## Background

Smart Placement applies to Pages Functions and middleware. Normally, assets are always served globally and closest to your users.

Smart Placement on Pages currently has some caveats. While assets are always meant to be served from a location closest to the user, there are two exceptions to this behavior:

1. If using middleware for every request (`functions/_middleware.js`) when Smart Placement is enabled, all assets will be served from a location closest to your back-end infrastructure. This may result in an unexpected increase in latency as a result.

2. When using [`env.ASSETS.fetch`](https://developers.cloudflare.com/pages/functions/advanced-mode/), assets served via the `ASSETS` fetcher from your Pages Function are served from the same location as your Function. This could be the location closest to your back-end infrastructure and not the user.

:::note

To understand how Smart Placement works, refer to [Smart Placement](/workers/configuration/smart-placement/).

:::

## Enable Smart Placement (beta)

Smart Placement is available on all plans.

### Enable Smart Placement via the dashboard

To enable Smart Placement via the dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In Account Home, select **Workers & Pages**.
3. In **Overview**, select your Pages project.
4. Select **Settings** > **Functions**.
5. Under **Placement**, choose **Smart**.
6. Send some initial traffic (approximately 20-30 requests) to your Pages Functions. It takes a few minutes after you have sent traffic to your Pages Function for Smart Placement to take effect.
7. View your Pages Function's [request duration metrics](/workers/observability/metrics-and-analytics/) under Functions Metrics.

## Give feedback on Smart Placement

Smart Placement is in beta. To share your thoughts and experience with Smart Placement, join the [Cloudflare Developer Discord](https://discord.cloudflare.com).

---

# Source maps and stack traces

URL: https://developers.cloudflare.com/pages/functions/source-maps/

import { Render, WranglerConfig } from "~/components";

<Render file="source-maps" product="workers" />

:::caution

Support for uploading source maps for Pages is available now in open beta. Minimum required Wrangler version: 3.60.0.

:::

## Source Maps

To enable source maps, provide the `--upload-source-maps` flag to [`wrangler pages deploy`](/workers/wrangler/commands/#deploy-1) or add the following to your Pages application's [Wrangler configuration file](/pages/functions/wrangler-configuration/) if you are using the Pages build environment:

<WranglerConfig>

```toml
upload_source_maps = true
```

</WranglerConfig>

When uploading source maps is enabled, Wrangler will automatically generate and upload source map files when you run [`wrangler pages deploy`](/workers/wrangler/commands/#deploy-1).

## Stack traces

​​
When your application throws an uncaught exception, we fetch the source map and use it to map the stack trace of the exception back to lines of your application’s original source code.

You can then view the stack trace when streaming [real-time logs](/pages/functions/debugging-and-logging/).

:::note

The source map is retrieved after your Pages Function invocation completes — it's an asynchronous process that does not impact your applications's CPU utilization or performance. Source maps are not accessible inside the application at runtime, if you `console.log()` the [stack property](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack), you will not get a deobfuscated stack trace.

:::

## Limits

| Description             | Limit         |
| ----------------------- | ------------- |
| Maximum Source Map Size | 15 MB gzipped |

## Related resources

- [Real-time logs](/pages/functions/debugging-and-logging/) - Learn how to capture Pages logs in real-time.

---

# TypeScript

URL: https://developers.cloudflare.com/pages/functions/typescript/

import { PackageManagers, Render } from "~/components";

Pages Functions supports TypeScript. Author any files in your `/functions` directory with a `.ts` extension instead of a `.js` extension to start using TypeScript.

You can add runtime types and Env types by running:

<PackageManagers
	type="exec"
	pkg="wrangler"
	args={"types --path='./functions/types.d.ts'"}
/>

Then configure the types by creating a `functions/tsconfig.json` file:

```json
{
	"compilerOptions": {
		"target": "esnext",
		"module": "esnext",
		"lib": ["esnext"],
		"types": ["./types.d.ts"]
	}
}
```

See [the `wrangler types` command docs](/workers/wrangler/commands/#types) for more details.

If you already have a `tsconfig.json` at the root of your project, you may wish to explicitly exclude the `/functions` directory to avoid conflicts. To exclude the `/functions` directory:

```json
{
	"include": ["src/**/*"],
	"exclude": ["functions/**/*"],
	"compilerOptions": {}
}
```

Pages Functions can be typed using the `PagesFunction` type. This type accepts an `Env` parameter. The `Env` type should have been generated by `wrangler types` and can be found at the top of `types.d.ts`.

Alternatively, you can define the `Env` type manually. For example:

```ts
interface Env {
	KV: KVNamespace;
}

export const onRequest: PagesFunction<Env> = async (context) => {
	const value = await context.env.KV.get("example");
	return new Response(value);
};
```

If you are using `nodejs_compat`, make sure you have installed `@types/node` and updated your `tsconfig.json`.

```json
{
	"compilerOptions": {
		"target": "esnext",
		"module": "esnext",
		"lib": ["esnext"],
		"types": ["./types.d.ts", "node"]
	}
}
```

:::note

If you were previously using `@cloudflare/workers-types` instead of the runtime types generated by `wrangler types`, you can refer to this [migration guide](/workers/languages/typescript/#migrating).

:::

---

# Configuration

URL: https://developers.cloudflare.com/pages/functions/wrangler-configuration/

import {
	Render,
	TabItem,
	Tabs,
	Type,
	MetaInfo,
	WranglerConfig,
} from "~/components";

:::caution

If your project contains an existing Wrangler file that you [previously used for local development](/pages/functions/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](https://dash.cloudflare.com) or the Wrangler configuration file, a file used to customize the development and deployment setup for [Workers](/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](/pages/functions/wrangler-configuration/#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](/pages/functions/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

<WranglerConfig>

```toml
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"
```

</WranglerConfig>

## Requirements

### V2 build system

Pages Functions configuration via the Wrangler configuration file requires the [V2 build system](/pages/configuration/build-image/#v2-build-system) or later. To update from V1, refer to the [V2 build system migration instructions](/pages/configuration/build-image/#v1-to-v2-migration).

### 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](/workers/wrangler/install-and-update/).

## 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](/pages/functions/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:

<WranglerConfig>

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

</WranglerConfig>

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](/pages/configuration/build-configuration/#build-commands-and-directories) (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.

:::caution[Overwriting configuration]

Running [`wrangler pages download config`](/pages/functions/wrangler-configuration/#projects-without-existing-wranglertoml-file) 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.

<Tabs> <TabItem label="npm">

```sh
npx wrangler pages download config <PROJECT_NAME>
```

</TabItem> <TabItem label="yarn">

```sh
yarn wrangler pages download config <PROJECT_NAME>
```

</TabItem> <TabItem label="pnpm">

```sh
pnpm wrangler pages download config <PROJECT_NAME>
```

</TabItem> </Tabs>

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](/pages/get-started/git-integration/) or [Direct Upload](/pages/get-started/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](/workers/configuration/compatibility-dates/) 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](/workers), you may already be familiar with the [Wrangler configuration file](/workers/wrangler/configuration/). 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](/workers/wrangler/configuration/#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](/pages/functions/wrangler-configuration/#configure-environments) and configuration inheritance in this file **is not** the same as Workers.
- This file becomes the [source of truth](/pages/functions/wrangler-configuration/#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:

<WranglerConfig>

```toml
name = "my-pages-app"
pages_build_output_dir = "./dist"
compatibility_date = "2023-10-12"
compatibility_flags = ["nodejs_compat"]

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

</WranglerConfig>

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](#inheritable-keys) and [non-inheritable keys](#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](/pages/configuration/branch-build-controls/#production-branch-control) as well as your [preview branch settings](/pages/configuration/branch-build-controls/#preview-branch-control).

:::

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

```sh
npx wrangler pages deploy
```

or more specifically:

```sh
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](/pages/configuration/branch-build-controls/#preview-branch-control). 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](/workers/wrangler/configuration/#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:

<WranglerConfig>

```toml
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"
```

</WranglerConfig>

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:

<WranglerConfig>

```toml
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"
```

</WranglerConfig>

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

<WranglerConfig>

```toml
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"
```

</WranglerConfig>

## Inheritable keys

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

- `name` <Type text="string" /> <MetaInfo text="required" />

  - The name of your Pages project. Alphanumeric and dashes only.

- `pages_build_output_dir` <Type text="string" /> <MetaInfo text="required" />

  - The path to your project's build output folder. For example: `./dist`.

- `compatibility_date` <Type text="string" /> <MetaInfo text="required" />

  - A date in the form `yyyy-mm-dd`, which will be used to determine which version of the Workers runtime is used. Refer to [Compatibility dates](/workers/configuration/compatibility-dates/).

- `compatibility_flags` string\[] optional

  - A list of flags that enable features from upcoming features of the Workers runtime, usually used together with `compatibility_date`. Refer to [compatibility dates](/workers/configuration/compatibility-dates/).

- `send_metrics` <Type text="boolean" /> <MetaInfo text="optional" />

  - Whether Wrangler should send usage data to Cloudflare for this project. Defaults to `true`. You can learn more about this in our [data policy](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md).

- `limits` Limits optional

  - Configures limits to be imposed on execution at runtime. Refer to [Limits](#limits).

- `placement` Placement optional

  - Specify how Pages Functions should be located to minimize round-trip time. Refer to [Smart Placement](/workers/configuration/smart-placement/).

- `upload_source_maps` boolean

  - When `upload_source_maps` is set to `true`, Wrangler will upload any server-side source maps part of your Pages project to give corrected stack traces in logs.

## Non-inheritable keys

Non-inheritable keys are configurable at the top-level, but, if any one non-inheritable key is overridden for any environment (for example,`[[env.production.kv_namespaces]]`), all non-inheritable keys must also be specified in the environment configuration and overridden.

For example, this configuration will not work:

<WranglerConfig>

```toml
name = "my-pages-site"
pages_build_output_dir = "./dist"

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

[vars]
API_KEY = "1234567asdf"

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

</WranglerConfig>

`[[env.production.vars]]` is set to override `[vars]`. Because of this `[[kv_namespaces]]` must also be overridden by defining `[[env.production.kv_namespaces]]`.

This will work for local development, but will fail to validate when you try to deploy.

- `vars` <Type text="object" /> <MetaInfo text="optional" />

  - A map of environment variables to set when deploying your Function. Refer to [Environment variables](/pages/functions/bindings/#environment-variables).

- `d1_databases` <Type text="object" /> <MetaInfo text="optional" />

  - A list of D1 databases that your Function should be bound to. Refer to [D1 databases](/pages/functions/bindings/#d1-databases).

- `durable_objects` <Type text="object" /> <MetaInfo text="optional" />

  - A list of Durable Objects that your Function should be bound to. Refer to [Durable Objects](/pages/functions/bindings/#durable-objects).

- `hyperdrive` <Type text="object" /> <MetaInfo text="optional" />

  - Specifies Hyperdrive configs that your Function should be bound to. Refer to [Hyperdrive](/pages/functions/bindings/#r2-buckets).

- `kv_namespaces` <Type text="object" /> <MetaInfo text="optional" />

  - A list of KV namespaces that your Function should be bound to. Refer to [KV namespaces](/pages/functions/bindings/#kv-namespaces).

- `queues.producers` <Type text="object" /> <MetaInfo text="optional" />

  - Specifies Queues Producers that are bound to this Function. Refer to [Queues Producers](/queues/get-started/#4-set-up-your-producer-worker).

- `r2_buckets` <Type text="object" /> <MetaInfo text="optional" />

  - A list of R2 buckets that your Function should be bound to. Refer to [R2 buckets](/pages/functions/bindings/#r2-buckets).

- `vectorize` <Type text="object" /> <MetaInfo text="optional" />

  - A list of Vectorize indexes that your Function should be bound to. Refer to [Vectorize indexes](/vectorize/get-started/intro/#3-bind-your-worker-to-your-index).

- `services` <Type text="object" /> <MetaInfo text="optional" />

  - A list of service bindings that your Function should be bound to. Refer to [service bindings](/pages/functions/bindings/#service-bindings).

- `analytics_engine_datasets` <Type text="object" /> <MetaInfo text="optional" />

  - Specifies analytics engine datasets that are bound to this Function. Refer to [Workers Analytics Engine](/analytics/analytics-engine/get-started/).

- `ai` <Type text="object" /> <MetaInfo text="optional" />

  - Specifies an AI binding to this Function. Refer to [Workers AI](/pages/functions/bindings/#workers-ai).

## Limits

You can configure limits for your Pages project in the same way you can for Workers. Read [this guide](/workers/wrangler/configuration/#limits) for more details.

## Bindings

A [binding](/pages/functions/bindings/) 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](/kv/), [Durable Objects](/durable-objects/), [R2](/r2/), and [D1](/d1/). You can set bindings for both production and preview environments.

### D1 databases

[D1](/d1/) is Cloudflare's serverless SQL database. A Function can query a D1 database (or databases) by creating a [binding](/workers/runtime-apis/bindings/) to each database for [D1 Workers Binding API](/d1/worker-api/).

:::note

When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production database. Refer to [Local development](/workers/development-testing/) for more details.

:::

- Configure D1 database bindings via your [Wrangler file](/workers/wrangler/configuration/#d1-databases) the same way they are configured with Cloudflare Workers.
- Interact with your [D1 Database binding](/pages/functions/bindings/#d1-databases).

### Durable Objects

[Durable Objects](/durable-objects/) provide low-latency coordination and consistent storage for the Workers platform.

- Configure Durable Object namespace bindings via your [Wrangler file](/workers/wrangler/configuration/#durable-objects) the same way they are configured with Cloudflare Workers.

:::caution

<Render file="do-note" product="pages" /> Durable Object bindings configured in
a Pages project's Wrangler configuration file require the `script_name` key. For
Workers, the `script_name` key is optional.

:::

- Interact with your [Durable Object namespace binding](/pages/functions/bindings/#durable-objects).

### Environment variables

[Environment variables](/workers/configuration/environment-variables/) are a type of binding that allow you to attach text strings or JSON values to your Pages Function.

- Configure environment variables via your [Wrangler file](/workers/wrangler/configuration/#environment-variables) the same way they are configured with Cloudflare Workers.
- Interact with your [environment variables](/pages/functions/bindings/#environment-variables).

### Hyperdrive

[Hyperdrive](/hyperdrive/) bindings allow you to interact with and query any Postgres database from within a Pages Function.

- Configure Hyperdrive bindings via your [Wrangler file](/workers/wrangler/configuration/#hyperdrive) the same way they are configured with Cloudflare Workers.

### KV namespaces

[Workers KV](/kv/api/) is a global, low-latency, key-value data store. It stores data in a small number of centralized data centers, then caches that data in Cloudflare’s data centers after access.

:::note

When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production namespace. Refer to [Local development](/workers/development-testing/) for more details.

:::

- Configure KV namespace bindings via your [Wrangler file](/workers/wrangler/configuration/#kv-namespaces) the same way they are configured with Cloudflare Workers.
- Interact with your [KV namespace binding](/pages/functions/bindings/#kv-namespaces).

### Queues Producers

[Queues](/queues/) is Cloudflare's global message queueing service, providing [guaranteed delivery](/queues/reference/delivery-guarantees/) and [message batching](/queues/configuration/batching-retries/). [Queue Producers](/queues/configuration/javascript-apis/#producer) enable you to send messages into a queue within your Pages Function.

:::note

You cannot currently configure a [queues consumer](/queues/reference/how-queues-works/#consumers) with Pages Functions.

:::

- Configure Queues Producer bindings via your [Wrangler file](/workers/wrangler/configuration/#queues) the same way they are configured with Cloudflare Workers.
- Interact with your [Queues Producer binding](/pages/functions/bindings/#queue-producers).

### R2 buckets

[Cloudflare R2 Storage](/r2) allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.

:::note

When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production bucket. Refer to [Local development](/workers/development-testing/) for more details.

:::

- Configure R2 bucket bindings via your [Wrangler file](/workers/wrangler/configuration/#r2-buckets) the same way they are configured with Cloudflare Workers.
- Interact with your [R2 bucket bindings](/pages/functions/bindings/#r2-buckets).

### Vectorize indexes

A [Vectorize index](/vectorize/) allows you to insert and query vector embeddings for semantic search, classification and other vector search use-cases.

- Configure Vectorize bindings via your [Wrangler file](/workers/wrangler/configuration/#vectorize-indexes) the same way they are configured with Cloudflare Workers.

### Service bindings

A service binding allows you to call a Worker from within your Pages Function. Binding a Pages Function to a Worker allows you to send HTTP requests to the Worker without those requests going over the Internet. The request immediately invokes the downstream Worker, reducing latency as compared to a request to a third-party service. Refer to [About Service bindings](/workers/runtime-apis/bindings/service-bindings/).

- Configure service bindings via your [Wrangler file](/workers/wrangler/configuration/#service-bindings) the same way they are configured with Cloudflare Workers.
- Interact with your [service bindings](/pages/functions/bindings/#service-bindings).

### Analytics Engine Datasets

[Workers Analytics Engine](/analytics/analytics-engine/) provides analytics, observability and data logging from Pages Functions. Write data points within your Pages Function binding then query the data using the [SQL API](/analytics/analytics-engine/sql-api/).

- Configure Analytics Engine Dataset bindings via your [Wrangler file](/workers/wrangler/configuration/#analytics-engine-datasets) the same way they are configured with Cloudflare Workers.
- Interact with your [Analytics Engine Dataset](/pages/functions/bindings/#analytics-engine).

### Workers AI

[Workers AI](/workers-ai/) allows you to run machine learning models, on the Cloudflare network, from your own code – whether that be from Workers, Pages, or anywhere via REST API.

<Render file="ai-local-usage-charges" product="workers" />

Unlike other bindings, this binding is limited to one AI binding per Pages Function project.

- Configure Workers AI bindings via your [Wrangler file](/workers/wrangler/configuration/#workers-ai) the same way they are configured with Cloudflare Workers.
- Interact with your [Workers AI binding](/pages/functions/bindings/#workers-ai).

## Local development settings

The local development settings that you can configure are the same for Pages Functions and Cloudflare Workers. Read [this guide](/workers/wrangler/configuration/#local-development-settings) for more details.

## Source of truth

When used in your Pages Functions projects, your Wrangler file is the source of truth. You will be able to see, but not edit, the same fields when you log into the Cloudflare dashboard.

If you decide that you do not want to use a Wrangler configuration file for configuration, you can safely delete it and create a new deployment. Configuration values from your last deployment will still apply and you will be able to edit them from the dashboard.

---

# Changelog

URL: https://developers.cloudflare.com/pages/platform/changelog/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/pages.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Platform

URL: https://developers.cloudflare.com/pages/platform/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Known issues

URL: https://developers.cloudflare.com/pages/platform/known-issues/

Here are some known bugs and issues with Cloudflare Pages:

## Builds and deployment

- GitHub and GitLab are currently the only supported platforms for automatic CI/CD builds. [Direct Upload](/pages/get-started/direct-upload/) allows you to integrate your own build platform or upload from your local computer.

- Incremental builds are currently not supported in Cloudflare Pages.

- Uploading a `/functions` directory through the dashboard's Direct Upload option does not work (refer to [Using Functions in Direct Upload](/pages/get-started/direct-upload/#functions)).

- Commits/PRs from forked repositories will not create a preview. Support for this will come in the future.

## Git configuration

- If you deploy using the Git integration, you cannot switch to Direct Upload later. However, if you already use a Git-integrated project and do not want to trigger deployments every time you push a commit, you can [disable/pause automatic deployments](/pages/configuration/git-integration/#disable-automatic-deployments). Alternatively, you can delete your Pages project and create a new one pointing at a different repository if you need to update it.

## Build configuration

- `*.pages.dev` subdomains currently cannot be changed. If you need to change your `*.pages.dev` subdomain, delete your project and create a new one.

- Hugo builds automatically run an old version. To run the latest version of Hugo (for example, `0.101.0`), you will need to set an environment variable. Set `HUGO_VERSION` to `0.101.0` or the Hugo version of your choice.

- By default, Cloudflare uses Node `12.18.0` in the Pages build environment. If you need to use a newer Node version, refer to the [Build configuration page](/pages/configuration/build-configuration/) for configuration options.

- For users migrating from Netlify, Cloudflare does not support Netlify's Forms feature. [Pages Functions](/pages/functions/) are available as an equivalent to Netlify's Serverless Functions.

## Custom Domains

- It is currently not possible to add a custom domain with

  - a wildcard, for example, `*.domain.com`.
  - a Worker already routed on that domain.

- It is currently not possible to add a custom domain with a Cloudflare Access policy already enabled on that domain.

- Cloudflare's Load Balancer does not work with `*.pages.dev` projects; an `Error 1000: DNS points to prohibited IP` will appear.

- When adding a custom domain, the domain will not verify if Cloudflare cannot validate a request for an SSL certificate on that hostname. In order for the SSL to validate, ensure Cloudflare Access or a Cloudflare Worker is allowing requests to the validation path: `http://{domain_name}/.well-known/acme-challenge/*`.

- [Advanced Certificates](/ssl/edge-certificates/advanced-certificate-manager/) cannot be used with Cloudflare Pages due to Cloudflare for SaaS's [certificate prioritization](/ssl/reference/certificate-and-hostname-priority/).

## Pages Functions

- [Functions](/pages/functions/) does not currently support adding/removing polyfills, so your bundler (for example, webpack) may not run.

- `passThroughOnException()` is not currently available for Advanced Mode Pages Functions (Pages Functions which use an `_worker.js` file).

- `passThroughOnException()` is not currently as resilient as it is in Workers. We currently wrap Pages Functions code in a `try`/`catch` block and fallback to calling `env.ASSETS.fetch()`. This means that any critical failures (such as exceeding CPU time or exceeding memory) may still throw an error.

## Enable Access on your `*.pages.dev` domain

If you would like to enable [Cloudflare Access](https://www.cloudflare.com/teams-access/)] for your preview deployments and your `*.pages.dev` domain, you must:

1. Log in to [Cloudflare dashboard](https://dash.cloudflare.com/login).
2. From Account Home, select **Workers & Pages**.
3. In **Overview**, select your Pages project.
4. Go to **Settings** > **Enable access policy**.
5. Select **Edit** on the Access policy created for your preview deployments.
6. In Edit, go to **Overview**.
7. In the **Subdomain** field, delete the wildcard (`*`) and select **Save application**. You may need to change the **Application name** at this step to avoid an error.

At this step, your `*.pages.dev` domain has been secured behind Access. To resecure your preview deployments:

8. Go back to your Pages project > **Settings** > **General** > and reselect **Enable access policy**.
9. Review that two Access policies, one for your `*.pages.dev` domain and one for your preview deployments (`*.<YOUR_SITE>.pages.dev`), have been created.

If you have a custom domain and protected your `*.pages.dev` domain behind Access, you must:

10. Select **Add an application** > **Self hosted** in [Cloudflare Zero Trust](https://one.dash.cloudflare.com/).
11. Input an **Application name** and select your custom domain from the _Domain_ dropdown menu.
12. Select **Next** and configure your access rules to define who can reach the Access authentication page.
13. Select **Add application**.

:::caution

If you do not configure an Access policy for your custom domain, an Access authentication will render but not work for your custom domain visitors. If your Pages project has a custom domain, make sure to add an Access policy as described above in steps 10 through 13 to avoid any authentication issues.

:::

If you have an issue that you do not see listed, let the team know in the Cloudflare Workers Discord. Get your invite at [discord.cloudflare.com](https://discord.cloudflare.com), and share your bug report in the #pages-general channel.

## Delete a project with a high number of deployments

You may not be able to delete your Pages project if it has a high number (over 100) of deployments. The Cloudflare team is tracking this issue.

As a workaround, review the following steps to delete all deployments in your Pages project. After you delete your deployments, you will be able to delete your Pages project.

1. Download the `delete-all-deployments.zip` file by going to the following link: [https://pub-505c82ba1c844ba788b97b1ed9415e75.r2.dev/delete-all-deployments.zip](https://pub-505c82ba1c844ba788b97b1ed9415e75.r2.dev/delete-all-deployments.zip).
2. Extract the `delete-all-deployments.zip` file.
3. Open your terminal and `cd` into the `delete-all-deployments` directory.
4. In the `delete-all-deployments` directory, run `npm install` to install dependencies.
5. Review the following commands to decide which deletion you would like to proceed with:

- To delete all deployments except for the live production deployment (excluding [aliased deployments](https://developers.cloudflare.com/pages/configuration/preview-deployments/#preview-aliases)):

```sh
CF_API_TOKEN=<YOUR_CF_API_TOKEN> CF_ACCOUNT_ID=<ACCOUNT_ID> CF_PAGES_PROJECT_NAME=<PROJECT_NAME> npm start
```

- To delete all deployments except for the live production deployment (including [aliased deployments](https://developers.cloudflare.com/pages/configuration/preview-deployments/#preview-aliases), for example, `staging.example.pages.dev`):

```sh
CF_API_TOKEN=<YOUR_CF_API_TOKEN> CF_ACCOUNT_ID=<ACCOUNT_ID> CF_PAGES_PROJECT_NAME=<PROJECT_NAME> CF_DELETE_ALIASED_DEPLOYMENTS=true npm start
```

To find your Cloudflare API token, log in to the [Cloudflare dashboard](https://dash.cloudflare.com), select the user icon on the upper righthand side of your screen > go to **My Profile** > **API Tokens**.

To find your Account ID, refer to [Find your zone and account ID](/fundamentals/account/find-account-and-zone-ids/).

## Use Pages as Origin in Cloudflare Load Balancer

[Cloudflare Load Balancing](/load-balancing/) will not work without the host header set. To use a Pages project as target, make sure to select **Add host header** when [creating a pool](/load-balancing/pools/create-pool/#create-a-pool), and set both the host header value and the endpoint address to your `pages.dev` domain.

Refer to [Use Cloudflare Pages as origin](/load-balancing/pools/cloudflare-pages-origin/) for a complete tutorial.

---

# Limits

URL: https://developers.cloudflare.com/pages/platform/limits/

import { Render } from "~/components";

Below are limits observed by the Cloudflare Free plan. For more details on removing these limits, refer to the [Cloudflare plans](https://www.cloudflare.com/plans) page.

<Render file="limits_increase" product="workers" />

## Builds

Each time you push new code to your Git repository, Pages will build and deploy your site. You can build up to 500 times per month on the Free plan. Refer to the Pro and Business plans in [Pricing](https://pages.cloudflare.com/#pricing) if you need more builds.

Builds will timeout after 20 minutes. Concurrent builds are counted per account.

## Custom domains

Based on your Cloudflare plan type, a Pages project is limited to a specific number of custom domains. This limit is on a per-project basis.

| Free | Pro | Business | Enterprise |
| ---- | --- | -------- | ---------- |
| 100  | 250 | 500      | 500[^1]    |

[^1]: If you need more custom domains, contact your account team.

## Files

Pages uploads each file on your site to Cloudflare's globally distributed network to deliver a low latency experience to every user that visits your site. Cloudflare Pages sites can contain up to 20,000 files.

## File size

The maximum file size for a single Cloudflare Pages site asset is 25 MiB.

:::note[Larger Files]

To serve larger files, consider uploading them to [R2](/r2/) and utilizing the [public bucket](/r2/buckets/public-buckets/) feature. You can also use [custom domains](/r2/buckets/public-buckets/#connect-a-bucket-to-a-custom-domain), such as `static.example.com`, for serving these files.

:::

## Headers

A `_headers` file can have a maximum of 100 header rules.

An individual header in a `_headers` file can have a maximum of 2,000 characters. For managing larger headers, it is recommended to implement [Pages Functions](/pages/functions/).

## Preview deployments

You can have an unlimited number of [preview deployments](/pages/configuration/preview-deployments/) active on your project at a time.

## Redirects

A `_redirects` file can have a maximum of 2,000 static redirects and 100 dynamic redirects, for a combined total of 2,100 redirects. It is recommended to use [Bulk Redirects](/pages/configuration/redirects/#surpass-_redirects-limits) when you have a need for more than the `_redirects` file supports.

## Users

Your Pages site can be managed by an unlimited number of users via the Cloudflare dashboard. Note that this does not correlate with your Git project – you can manage both public and private repositories, open issues, and accept pull requests via without impacting your Pages site.

## Projects

Cloudflare Pages has a soft limit of 100 projects within your account in order to prevent abuse. If you need this limit raised, contact your Cloudflare account team or use the Limit Increase Request Form at the top of this page.

In order to protect against abuse of the service, Cloudflare may temporarily disable your ability to create new Pages projects, if you are deploying a large number of applications in a short amount of time. Contact support if you need this limit increased.

---

# Tutorials

URL: https://developers.cloudflare.com/pages/tutorials/

import { GlossaryTooltip, ListTutorials, YouTubeVideos } from "~/components";

View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Pages.

## Docs

<ListTutorials />

## Videos

<YouTubeVideos products={["Pages"]} />

---

# Configure output settings

URL: https://developers.cloudflare.com/pipelines/build-with-pipelines/output-settings/

import { Render, PackageManagers } from "~/components";

Pipelines convert a stream of records into output files and deliver the files to an R2 bucket in your account. This guide details how you can change the output destination and customize batch settings to generate query ready files.

## Configure an R2 bucket as a destination
To create or update a pipeline using Wrangler, run the following command in a terminal:

```sh
npx wrangler pipelines create [PIPELINE-NAME] --r2-bucket [R2-BUCKET-NAME]
```

After running this command, you will be prompted to authorize Cloudflare Workers Pipelines to create an R2 API token on your behalf. Your pipeline uses the R2 API token to load data into your bucket. You can approve the request through the browser link which will open automatically.

If you prefer not to authenticate this way, you can pass your [R2 API Token](/r2/api/tokens/) to Wrangler:
```sh
npx wrangler pipelines create [PIPELINE-NAME] --r2 [R2-BUCKET-NAME] --r2-access-key-id [ACCESS-KEY-ID] --r2-secret-access-key [SECRET-ACCESS-KEY]
```

## File format and compression
Output files are generated as Newline Delimited JSON files (`ndjson`). Each line in an output file maps to a single record.

By default, output files are compressed in the `gzip` format. Compression can be turned off using the `--compression`  flag:
```sh
npx wrangler pipelines update [PIPELINE-NAME] --compression none
```

Output files are named using a [ULID](https://github.com/ulid/spec) slug, followed by an extension.

## Customize batch behavior
When configuring your pipeline, you can define how records are batched before they are delivered to R2. Batches of records are written out to a single output file.

Batching can:
- Reduce the number of output files written to R2 and thus reduce the [cost of writing data to R2](/r2/pricing/#class-a-operations).
- Increase the size of output files making them more efficient to query.

There are three ways to define how ingested data is batched:

1. `batch-max-mb`: The maximum amount of data that will be batched in megabytes. Default, and maximum, is `100 MB`.
2. `batch-max-rows`: The maximum number of rows or events in a batch before data is written. Default, and maximum, is `10,000,000` rows.
3. `batch-max-seconds`: The maximum duration of a batch before data is written in seconds. Default, and maximum, is `300 seconds`.

Batch definitions are hints. A pipeline will follow these hints closely, but batches might not be exact.

All three batch definitions work together and whichever limit is reached first triggers the delivery of a batch.

For example, a `batch-max-mb` = 100 MB and a `batch-max-seconds` = 100 means that if 100 MB of events are posted to the pipeline, the batch will be delivered. However, if it takes longer than 100 seconds for 100 MB of events to be posted, a batch of all the messages that were posted during those 100 seconds will be created.

### Defining batch settings using Wrangler
You can use the following batch settings flags while creating or updating a pipeline:
* `--batch-max-mb`
* `--batch-max-rows`
* `--batch-max-seconds`

For example:
```sh
npx wrangler pipelines update [PIPELINE-NAME] --batch-max-mb 100 --batch-max-rows 10000 --batch-max-seconds 300
```

### Batch size limits

| Setting                                   | Default     		| Minimum   | Maximum     |
| ----------------------------------------- | ----------------| --------- | ----------- |
| Maximum Batch Size `batch-max-mb`         | 100 MB       		| 1 MB  		| 100 MB      |
| Maximum Batch Timeout `batch-max-seconds` | 300 seconds  		| 1 second 	| 300 seconds |
| Maximum Batch Rows `batch-max-rows`       | 10,000,000 rows | 1 row     | 10,000,000 rows |


## Deliver partitioned data
Partitioning organizes data into directories based on specific fields to improve query performance. Partitions reduce the amount of data scanned for queries, enabling faster reads.

:::note
By default, Pipelines partition data by event date and time. This will be customizable in the future.
:::

Output files are prefixed with event date and hour. For example, the output from a Pipeline in your R2 bucket might look like this:
```sh
- event_date=2025-04-01/hr=15/01JQWBZCZBAQZ7RJNZHN38JQ7V.json.gz
- event_date=2025-04-01/hr=15/01JQWC16FXGP845EFHMG1C0XNW.json.gz
```

## Deliver data to a prefix
You can specify an optional prefix for all the output files stored in your specified R2 bucket, using the flag `--r2-prefix`.

For example:
```sh
npx wrangler pipelines update [PIPELINE-NAME] --r2-prefix test
```

After running the above command, the output files generated by your pipeline will be stored under the prefix `test`. Files will remain partitioned. Your output will look like this:
```sh
- test/event_date=2025-04-01/hr=15/01JQWBZCZBAQZ7RJNZHN38JQ7V.json.gz
- test/event_date=2025-04-01/hr=15/01JQWC16FXGP845EFHMG1C0XNW.json.gz
```

---

# Increase pipeline throughput

URL: https://developers.cloudflare.com/pipelines/build-with-pipelines/shards/

import { Render, PackageManagers } from "~/components";

A pipeline's maximum throughput can be increased by increasing the shard count. A single shard can handle approximately 7,000 requests per second, or can ingest 7 MB/s of data.

By default, each pipeline is configured with two shards. To set the shard count, use the `--shard-count` flag while creating or updating a pipeline:
```sh
$ npx wrangler pipelines update [PIPELINE-NAME] --shard-count 10
```

:::note
The default shard count will be set to `auto` in the future, with support for automatic horizontal scaling.
:::

## How shards work
![Pipeline shards](~/assets/images/pipelines/shards.png)

Each pipeline is composed of stateless, independent shards. These shards are spun up when a pipeline is created. Each shard is composed of layers of [Durable Objects](/durable-objects). The Durable Objects buffer data, replicate for durability, handle compression, and delivery to R2.

When a record is sent to a pipeline:
1. The Pipelines [Worker](/workers) receives the record.
2. The record is routed to to one of the shards.
3. The record is handled by a set of Durable Objects, which commit the record to storage and replicate for durability.
4. Records accumulate until the [batch definitions](/pipelines/build-with-pipelines/output-settings/#customize-batch-behavior) are met.
5. The batch is written to an output file and optionally compressed.
6. The output file is delivered to the configured R2 bucket.

Increasing the number of shards will increase the maximum throughput of a pipeline, as well as the number of output files created.

### Example
Your workload might require making 5,000 requests per second to a pipeline. If you create a pipeline with a single shard, all 5,000 requests will be routed to the same shard. If your pipeline has been configured with a maximum batch duration of 1 second, every second, all 5,000 requests will be batched, and a single file will be delivered.

Increasing the shard count to 2 will double the number of output files. The 5,000 requests will be split into 2,500 requests to each shard. Every second, each shard will create a batch of data, and deliver to R2.

## Considerations while increasing the shard count
Increasing the shard count also increases the number of output files that your pipeline generates. This in turn increases the [cost of writing data to R2](/r2/pricing/#class-a-operations), as each file written to R2 counts as a single class A operation. Additionally, smaller files are slower, and more expensive, to query. Rather than setting the maximum, choose a shard count based on your workload needs.

## Determine the right number of shards
Choose a shard count based on these factors:
* The number of requests per second you will make to your pipeline
* The amount of data per second you will send to your pipeline

Each shard is capable of handling approximately 7,000 requests per second, or ingesting 7 MB/s of data. Either factor might act as the bottleneck, so choose the shard count based on the higher number.

For example, if you estimate that you will ingest 70 MB/s, making 70,000 requests per second, setup a pipeline with 10 shards. However, if you estimate that you will ingest 70 MB/s while making 100,000 requests per second, setup a pipeline with 15 shards.

## Limits
| Setting                                   | Default     | Minimum   | Maximum     |
| ----------------------------------------- | ----------- | --------- | ----------- |
| Shards per pipeline `shard-count`       	| 2       		| 1  				| 15 					|

---

# How Pipelines work

URL: https://developers.cloudflare.com/pipelines/concepts/how-pipelines-work/

Cloudflare Pipelines let you ingest data from a source and deliver to a sink. It is built for high volume, real time data streams. Each pipeline can ingest up to 100 MB/s of data, via HTTP or a Worker, and load the data as files in an R2 bucket.

![Pipelines Architecture](~/assets/images/pipelines/architecture.png)

## Supported sources, data formats, and sinks

### Sources
Pipelines supports the following sources:
* [HTTP Clients](/pipelines/build-with-pipelines/sources/http), with optional authentication and CORS settings
* [Cloudflare Workers](/workers/), using the [Pipelines Workers API](/pipelines/build-with-pipelines/sources/workers-apis)

Multiple sources can be active on a single pipeline simultaneously. For example, you can create a pipeline which accepts data from Workers and via HTTP. Multiple workers can be configured to send data to the same pipeline. There is no limit to the number of source clients.

### Data format
Pipelines can ingest JSON serializable records.

### Sinks
Pipelines supports delivering data into [R2 Object Storage](/r2/). Ingested data is delivered as newline delimited JSON files (`ndjson`) with optional compression. Multiple pipelines can be configured to deliver data to the same R2 bucket.

## Data durability
Pipelines are designed to be reliable. Any data which is successfully ingested will be delivered, at least once, to the configured R2 bucket, provided that the [R2 API credentials associated with a pipeline](/r2/api/tokens/) remain valid. Ordering of records is best effort.

Each pipeline maintains a storage buffer. Requests to send data to a pipeline receive a successful response only after the data is committed to this storage buffer.

Ingested data accumulates, until a sufficiently [large batch of data](/pipelines/build-with-pipelines/output-settings/#customize-batch-behavior) has been filled. Once the batch reaches its target size, the entire batch of data is converted to a file and delivered to R2.

Transient failures, such as network connectivity issues, are automatically retried.

However, if the [R2 API credentials associated with a pipeline](/r2/api/tokens/) expire or are revoked, data delivery will fail. In this scenario, some data might continue to accumulate in the buffers, but the pipeline will eventually start rejecting requests once the buffers are full.

## Updating a pipeline
Pipelines update without dropping records. Updating an existing pipeline creates a new instance of the pipeline. Requests are gracefully re-routed to the new instance. The old instance continues to write data into the configured sink. Once the old instance is fully drained, it is spun down.

This means that updates might take a few minutes to go into effect. For example, if you update a pipeline's sink, previously ingested data might continue to be delivered into the old sink.

## Backpressure behavior
If you send too much data, the pipeline will communicate backpressure by returning a 429 response to HTTP requests, or throwing an error if using the Workers API. Refer to the [limits](/pipelines/platform/limits) to learn how much volume a single pipeline can support. You might see 429 responses if you are sending too many requests or sending too much data.

If you are consistently seeing backpressure from your pipeline, consider the following strategies:
* Increase the [shard count](/pipelines/build-with-pipelines/shards) to increase the maximum throughput of your pipeline.
* Send data to a second pipeline if you receive an error. You can set up multiple pipelines to write to the same R2 bucket.

---

# Observability

URL: https://developers.cloudflare.com/pipelines/observability/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Metrics and analytics

URL: https://developers.cloudflare.com/pipelines/observability/metrics/

Pipelines expose metrics which allow you to measure data ingested, requests made, and data delivered.

The metrics displayed in the [Cloudflare dashboard](https://dash.cloudflare.com/) are queried from Cloudflare’s [GraphQL Analytics API](/analytics/graphql-api/). You can access the metrics [programmatically](#query-via-the-graphql-api) via GraphQL or HTTP client.

## Metrics

### Ingestion

Pipelines export the below metrics within the `pipelinesIngestionAdaptiveGroups` dataset.

| Metric           | GraphQL Field Name | Description                                                  |
| ---------------- | ------------------ | ------------------------------------------------------------ |
| Ingestion Events | `count`            | Number of ingestion events, or requests made, to a pipeline. |
| Ingested Bytes   | `ingestedBytes`    | Total number of bytes ingested                               |
| Ingested Records | `ingestedRecords`  | Total number of records ingested                             |

The `pipelinesIngestionAdaptiveGroups` dataset provides the following dimensions for filtering and grouping queries:

- `pipelineId` - ID of the pipeline
- `datetime` - Timestamp of the ingestion event
- `date` - Timestamp of the ingestion event, truncated to the start of a day
- `datetimeHour` - Timestamp of the ingestion event, truncated to the start of an hour
- `datetimeMinute` - Timestamp of the ingestion event, truncated to the start of a minute

### Delivery

Pipelines export the below metrics within the `pipelinesDeliveryAdaptiveGroups` dataset.

| Metric           | GraphQL Field Name | Description                               |
| ---------------- | ------------------ | ----------------------------------------- |
| Ingestion Events | `count`            | Number of delivery events to an R2 bucket |
| Delivered Bytes  | `deliveredBytes`   | Total number of bytes ingested            |

The `pipelinesDeliverynAdaptiveGroups` dataset provides the following dimensions for filtering and grouping queries:

- `pipelineId` - ID of the pipeline
- `datetime` - Timestamp of the delivery event
- `date` - Timestamp of the delivery event, truncated to the start of a day
- `datetimeHour` - Timestamp of the delivery event, truncated to the start of an hour
- `datetimeMinute` - Timestamp of the delivery event, truncated to the start of a minute

## Query via the GraphQL API

You can programmatically query analytics for your pipelines via the [GraphQL Analytics API](/analytics/graphql-api/). This API queries the same datasets as the Cloudflare dashboard and supports GraphQL [introspection](/analytics/graphql-api/features/discovery/introspection/).

Pipelines GraphQL datasets require an `accountTag` filter with your Cloudflare account ID.

### Measure total bytes & records ingested over time period

```graphql graphql-api-explorer
query PipelineIngestion(
	$accountTag: string!
	$pipelineId: string!
	$datetimeStart: Time!
	$datetimeEnd: Time!
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			pipelinesIngestionAdaptiveGroups(
				limit: 10000
				filter: {
					pipelineId: $pipelineId
					datetime_geq: $datetimeStart
					datetime_leq: $datetimeEnd
				}
			) {
				sum {
					ingestedBytes
					ingestedRecords
				}
			}
		}
	}
}
```

### Measure volume of data delivered

```graphql graphql-api-explorer
query PipelineDelivery(
	$accountTag: string!
	$pipelineId: string!
	$datetimeStart: Time!
	$datetimeEnd: Time!
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			pipelinesDeliveryAdaptiveGroups(
				limit: 10000
				filter: {
					pipelineId: $pipelineId
					datetime_geq: $datetimeStart
					datetime_leq: $datetimeEnd
				}
			) {
				sum {
					deliveredBytes
				}
			}
		}
	}
}
```

---

# Limits

URL: https://developers.cloudflare.com/pipelines/platform/limits/

import { Render } from "~/components"


| Feature                                       | Limit                                                         |
| --------------------------------------------- | ------------------------------------------------------------- |
| Maximum requests per second, per pipeline     | 14,000 default (configurable up to 100,000)                   |
| Maximum payload per request                   | 1 MB                                          								|
| Maximum data throughput per pipeline          | 14 MB/s default (configurable up to 100 MB/s)             |
| Shards per pipeline	                      		| 2 default (configurable up to 15) 	                          |
| Maximum batch size 	                        	| 100 MB                                          							|
| Maximum batch records	                				| 10,000,000                                          					|
| Maximum batch duration	                      | 300s 	                                          							|


## Exceeding requests per second or throughput limits
If you consistently exceed the requests per second or throughput limits, your pipeline might not be able to keep up with the load. The pipeline will communicate backpressure by returning a 429 response to HTTP requests or throwing an error if using the Workers API.

If you are consistently seeing backpressure from your pipeline, consider the following strategies:
* Increase the [shard count](/pipelines/build-with-pipelines/shards) to increase the maximum throughput of your pipeline.
* Send data to a second pipeline if you receive an error. You can setup multiple pipelines to write to the same R2 bucket.

---

# Platform

URL: https://developers.cloudflare.com/pipelines/platform/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Pricing

URL: https://developers.cloudflare.com/pipelines/platform/pricing/

:::note
Pipelines requires a [Workers paid](/workers/platform/pricing/#workers) plan to use.
:::

During the first phase of the Pipelines open beta, you will not be billed for Pipelines usage. You will be billed only for [R2 usage](/r2/pricing).

We plan to price based on the volume of data ingested into and delivered from Pipelines. We expect to begin charging by September 15, 2025, and will provide at least 30 days' notice beforehand.

|                                    | Workers Paid Users
| ---------------------------------- | ------------------------
| Ingestion                          | 50 GB / month included + $0.02 / additional GB
| Delivery to R2                     | 50 GB / month included + $0.02 / additional GB

---

# Wrangler commands

URL: https://developers.cloudflare.com/pipelines/platform/wrangler-commands/

import { Render, Type, MetaInfo } from "~/components"

<Render file="wrangler-commands/pipelines" product="workers" />

## Global commands
<Render file="wrangler-commands/global-flags" product="workers" />

---

# Reference

URL: https://developers.cloudflare.com/privacy-gateway/reference/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Tutorials

URL: https://developers.cloudflare.com/pipelines/tutorials/

import { GlossaryTooltip, ListTutorials } from "~/components";

View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Pipelines.

<ListTutorials />

---

# Legal

URL: https://developers.cloudflare.com/privacy-gateway/reference/legal/

Privacy Gateway is a managed gateway service deployed on Cloudflare’s global network that implements the Oblivious HTTP IETF standard to improve client privacy when connecting to an application backend.

OHTTP introduces a trusted third party (Cloudflare in this case), called a relay, between client and server. The relay’s purpose is to forward requests from client to server, and likewise to forward responses from server to client. These messages are encrypted between client and server such that the relay learns nothing of the application data, beyond the server the client is interacting with.

The Privacy Gateway service follows [Cloudflare’s privacy policy](https://www.cloudflare.com/privacypolicy/).

## What Cloudflare sees

While Cloudflare will never see the contents of the encrypted application HTTP request proxied through the Privacy Gateway service – because the client will first connect to the OHTTP relay server operated in Cloudflare’s global network– Cloudflare will see the following information: the connecting device’s IP address, the application service they are using, including its DNS name and IP address, and metadata associated with the request, including the type of browser, device operating system, hardware configuration, and timestamp of the request ("Privacy Gateway Logs").

## What Cloudflare stores

Cloudflare retains the Privacy Gateway Logs information for the most recent quarter plus one month (approximately 124 days).

## What Privacy Gateway customers see

* The application content of requests.
* The IP address and associated metadata of the Cloudflare Privacy Gateway server the request came from.

---

# Limitations

URL: https://developers.cloudflare.com/privacy-gateway/reference/limitations/

End users should be aware that Cloudflare cannot ensure that websites and services will not send identifying user data from requests forwarded through the Privacy Gateway. This includes information such as names, email addresses, and phone numbers.

---

# Privacy Gateway Metrics

URL: https://developers.cloudflare.com/privacy-gateway/reference/metrics/

Privacy Gateway now supports enhanced monitoring through our GraphQL API, providing detailed insights into your gateway traffic and performance. To access these metrics, ensure you have:

* A relay gateway proxy implementation where Cloudflare acts as the oblivious relay party.
* An API token with Analytics Read permissions.
  We offer two GraphQL nodes to retrieve metrics: `ohttpMetricsAdaptive` and `ohttpMetricsAdaptiveGroups`. The first node provides comprehensive request data, while the second facilitates grouped analytics.

## ohttpMetricsAdaptive

The `ohttpMetricsAdaptive` node is designed for detailed insights into individual OHTTP requests with adaptive sampling. This node can help in understanding the performance and load on your server and client setup.

### Key Arguments



* `filter` required
  * Apply filters to narrow down your data set. `accountTag` is a required filter.
* `limit`  optional
  * Specify the maximum number of records to return.
* `orderBy` optional
  * Choose how to sort your data, with options for various dimensions and metrics.


### Available Fields



* `bytesToClient` int optional
  * The number of bytes returned to the client.
* `bytesToGateway` int optional
  * Total bytes received from the client.
* `colo` string optional
  * Airport code of the Cloudflare data center that served the request.
* `datetime` Time optional
  * The date and time when the event was recorded.
* `gatewayStatusCode` int optional
  * Status code returned by the gateway.
* `relayStatusCode` int optional
  * Status code returned by the relay.


This node is useful for a granular view of traffic, helping you identify patterns, performance issues, or anomalies in your data flow.

## ohttpMetricsAdaptiveGroups

The `ohttpMetricsAdaptiveGroups` node allows for aggregated analysis of OHTTP request metrics with adaptive sampling. This node is particularly useful for identifying trends and patterns across different dimensions of your traffic and operations.

### Key Arguments



* `filter` required
  * Apply filters to narrow down your data set. `accountTag` is a required filter.
* `limit`  optional
  * Specify the maximum number of records to return.
* `orderBy` optional
  * Choose how to sort your data, with options for various dimensions and metrics.


### Available Fields



* `count` int optional
  * The number of records that meet the criteria.
* `dimensions` optional
  * Specifies the grouping dimensions for your data.
* `sum` optional
  * Aggregated totals for various metrics, per dimension.


**Dimensions**

You can group your metrics by various dimensions to get a more segmented view of your data:


* `colo` string optional
  * The airport code of the Cloudflare data center.
* `date` Date optional
  * The date of OHTTP request metrics.
* `datetimeFifteenMinutes` Time optional
  * Timestamp truncated to fifteen minutes.
* `datetimeFiveMinutes` Time optional
  * Timestamp truncated to five minutes.
* `datetimeHour` Time optional
  * Timestamp truncated to the hour.
* `datetimeMinute` Time optional
  * Timestamp truncated to the minute.
* `endpoint` string optional
  * The appId that generated traffic.
* `gatewayStatusCode` int optional
  * Status code returned by the gateway.
* `relayStatusCode` int optional
  * Status code returned by the relay.


**Sum Fields**

Sum fields offer a cumulative view of various metrics over your selected time period:


* `bytesToClient` int optional
  * Total bytes sent from the gateway to the client.
* `bytesToGateway` int optional
  * Total bytes from the client to the gateway.
* `clientRequestErrors` int optional
  * Total number of client request errors.
* `gatewayResponseErrors` int optional
  * Total number of gateway response errors.


Utilize the ohttpMetricsAdaptiveGroups node to gain comprehensive, aggregated insights into your traffic patterns, helping you optimize performance and user experience.

---

# Product compatibility

URL: https://developers.cloudflare.com/privacy-gateway/reference/product-compatibility/

When [using Privacy Gateway](/privacy-gateway/get-started/), the majority of Cloudflare products will be compatible with your application.

However, the following products are not compatible:

* [API Shield](/api-shield/): [Schema Validation](/api-shield/security/schema-validation/) and [API discovery](/api-shield/security/api-discovery/) are not possible since Cloudflare cannot see the request URLs.
* [Cache](/cache/): Caching of application content is no longer possible since each between client and gateway is end-to-end encrypted.
* [WAF](/waf/): Rules implemented based on request content are not supported since Cloudflare cannot see the request or response content.

---

# Connect with JavaScript (Node.js)

URL: https://developers.cloudflare.com/pub-sub/examples/connect-javascript/

import { PackageManagers } from "~/components";

Below is an example using [MQTT.js](https://github.com/mqttjs/MQTT.js#mqttclientstreambuilder-options) with the TOKEN authentication mode configured on a broker. The example assumes you have [Node.js](https://nodejs.org/en/) v16 or higher installed on your system.

Make sure to set the following environmental variables before running the example:

1. `BROKER_URI` (e.g. `mqtts://YOUR-BROKER.YOUR-NAMESPACE.cloudflarepubsub.com`)
2. `BROKER_TOKEN` with a [valid auth token](/pub-sub/platform/authentication-authorization/#generate-credentials)
3. `BROKER_TOPIC` to publish to - for example, `hello/world`

Before running the example, make sure to install the MQTT library:

<PackageManagers pkg="mqtt" />

Copy the following example as `example.js` and run it with `node example.js`.

```javascript
const mqtt = require("mqtt");

// Specify MQTT broker URI: mqtts://<broker name>.<namespace>.cloudflarepubsub.com
const uri = check_env(process.env.BROKER_URI);

// Any username and your token from the /brokers/YOUR_BROKER/credentials endpoint
// The token should be the base64-encoded JWT issued by the Pub/Sub API
const username = "anything";
const password = check_env(process.env.BROKER_TOKEN);

// Specify a topic name to subscribe to and publish on
let topic = check_env(process.env.BROKER_TOPIC);

// Configure and create the MQTT client
const client = mqtt.connect(uri, {
	protocolVersion: 5,
	port: 8883,
	clean: true,
	connectTimeout: 2000, // 2 seconds
	clientId: "",
	username,
	password,
});

// Emit errors and exit
client.on("error", function (err) {
	console.log(`⚠️  error: ${err}`);
	client.end();
	process.exit();
});

// Connect to your broker
client.on("connect", function () {
	console.log(`🌎 connected to ${process.env.BROKER_URI}!`);
	// Subscribe to a topic
	client.subscribe(topic, function (err) {
		if (!err) {
			console.log(`✅ subscribed to ${topic}`);
			// Publish a message!
			client.publish(topic, "My first MQTT message");
		}
	});
});

// Start waiting for messages
client.on("message", async function (topic, message) {
	console.log(`received a message: ${message.toString()}`);

	// Goodbye!
	client.end();
	process.exit();
});

// Return variable or throw error
function check_env(env) {
	if (!env) {
		throw "BROKER_URI, BROKER_TOKEN and BROKER_TOPIC must be set.";
	}

	return env;
}
```

---

# Connect with Python

URL: https://developers.cloudflare.com/pub-sub/examples/connect-python/

Below is an example using the [paho.mqtt.python](https://github.com/eclipse/paho.mqtt.python) package with the TOKEN authentication mode configured on a Broker.

The example below creates a simple subscriber, sends a message to the configured topic, and waits until the message is received before exiting.

Make sure to set environmental variables for the following before running the example:

- `BROKER_FQDN` - e.g. `YOUR-BROKER.YOUR-NAMESPACE.cloudflarepubsub.com` without the port or `mqtts://` scheme
- `BROKER_TOKEN` (a valid auth token)
- `BROKER_TOPIC` - e.g. `test/topic` or `hello/world`

The example below uses Python 3.8, but should run on Python 3.6 and above.

```sh
# Ensure you have paho-mqtt installed
pip3 install paho-mqtt
```

Create a file called `pubsub.py` with the following content, and use `python3 pubsub.py` to run the example:

```python
# Install the library via: pip install paho-mqtt

import os
import paho.mqtt.client as mqtt
import sys


# Making sure all environment variables are set
def check_env(env):
    if env is None:
        sys.exit("BROKER_FQDN, BROKER_TOKEN and BROKER_TOPIC must be set.")
    return env


# The callback for when the client receives a CONNACK response from the server.
def on_connect(ctx, userdata, flags, rc, properties):
    print("connected to {}".format(ctx._host))
    ctx.subscribe(topic)
    client.publish(topic, "Hello from Python and Pub/Sub!")


# The callback for when a PUBLISH message is received from the server.
def on_message(ctx, userdata, msg):
    print("{}: {}".format(msg.topic, msg.payload))
    # Good-Bye
    client.disconnect()


# Specify MQTT broker FQDN: <broker name>.<namespace>.cloudflarepubsub.com
fqdn = check_env(os.environ.get("BROKER_FQDN"))

# Any username and your token from the /brokers/YOUR_BROKER/credentials endpoint
# The token should be the base64-encoded JWT issued by the Pub/Sub API
username = "anything"
password = check_env(os.environ.get("BROKER_TOKEN")).strip("\"")

# Specify a topic name to subscribe to and publish on
topic = check_env(os.environ.get("BROKER_TOPIC"))

# Create the MQTT client
client = mqtt.Client(client_id="", protocol=mqtt.MQTTv5)

# Set username & password
client.username_pw_set(username, password)

# Enable TLS
client.tls_set()

# Connect to your broker and register callback functions
client.connect(fqdn, 8883)
client.on_connect = on_connect
client.on_message = on_message

# Wait until we have received our message
client.loop_forever()
```

---

# Connect with Rust

URL: https://developers.cloudflare.com/pub-sub/examples/connect-rust/

Below is an example using the [paho.mqtt.rust](https://github.com/eclipse/paho.mqtt.rust) crate with the TOKEN authentication mode configured on a Broker.

The example below creates a simple subscriber, sends a message to the configured topic, and waits until the message is received before exiting.

Make sure to set the `BROKER_URI` (e.g. `mqtts://YOUR-BROKER.YOUR-NAMESPACE.cloudflarepubsub.com`), `BROKER_TOKEN` (a valid auth token), and `BROKER_TOPIC` environmental variables before running the example program.

```toml
# in your Cargo.toml
paho-mqtt = "0.11.1"
```

Create a file called `example.rs` with the following content, and use `cargo run` to build and run the example:

```rust
use paho_mqtt::*;
use std::thread;

fn main() {
    // Specify MQTT broker hostname: <broker name>.<namespace>.cloudflarepubsub.com
    let uri = std::env::var("BROKER_URI").expect("URI must be set");

    // Your JWT token
    let jwt = std::env::var("BROKER_TOKEN").expect("JWT must be set");

    // Specify a topic name
    let topic = std::env::var("BROKER_TOPIC").expect("Topic must be set");

    // Configure the MQTT client
    let client_opts = CreateOptionsBuilder::new()
        .mqtt_version(MQTT_VERSION_5)
        .server_uri(uri)
        .finalize();

    // Connect options
    let options = ConnectOptionsBuilder::new()
        .ssl_options(SslOptions::default())
        .clean_start(true)
        .password(jwt)
        .finalize();

    // Create the MQTT client
    let cli = Client::new(client_opts).expect("Error creating client");

    // Connect to your broker
    cli.connect(options).expect("Error connecting to broker");

    // Message receiver
    let rx = cli.start_consuming();

    // Subscribe to a topic
    cli.subscribe(&topic, 0)
        .expect("Error subscribing to topic");

    // Start waiting for messages
    let reader = thread::spawn(move || match rx.recv().expect("Error receiving message") {
        Some(message) => {
            println!("{:?}", message);
        }
        None => {}
    });

    // Publish a message!
    cli.publish(Message::new(topic, "My first MQTT message", 0))
        .expect("Error publishing");

    // Wait until we have received our message
    let _ = reader.join();

    // Good-Bye
    cli.disconnect(DisconnectOptions::default())
        .expect("Error disconnecting");
}
```

---

# Examples

URL: https://developers.cloudflare.com/pub-sub/examples/

import { ListExamples } from "~/components";

<ListExamples directory="pub-sub/examples/" />

---

# Recommended client libraries

URL: https://developers.cloudflare.com/pub-sub/learning/client-libraries/

MQTT is a popular standard, and you can find open-source libraries for many popular programming languages.

The list of client libraries are not formally supported by Cloudflare but have been vetted by the team.

| Platform/Language                | Source                                                                                 |
| -------------------------------- | -------------------------------------------------------------------------------------- |
| macOS, Windows, Linux            | [https://mqttx.app/](https://mqttx.app/) (GUI tool)                                    |
| JavaScript (Node.js, TypeScript) | [https://github.com/mqttjs/MQTT.js](https://github.com/mqttjs/MQTT.js)                 |
| Go (MQTT v5.0 specific library)  | [https://github.com/eclipse/paho.golang](https://github.com/eclipse/paho.golang)       |
| Python                           | [https://pypi.org/project/paho-mqtt/](https://pypi.org/project/paho-mqtt/)             |
| Rust                             | [https://github.com/eclipse/paho.mqtt.rust](https://github.com/eclipse/paho.mqtt.rust) |

:::note


Pub/Sub implements version 5 of the MQTT specification ("MQTT v5.0"), which was published in March 2019. Most major client libraries support MQTT v5.0 today, but we recommend double-checking that the client library explicitly advertises MQTT v5.0 support.


:::

---

# Using Wrangler (Command Line Interface)

URL: https://developers.cloudflare.com/pub-sub/learning/command-line-wrangler/

Wrangler is a command-line tool for building and managing Cloudflare's Developer Platform, including [Cloudflare Workers](https://workers.cloudflare.com/), [R2 Storage](/r2/) and [Cloudflare Pub/Sub](/pub-sub/).

:::note

Pub/Sub support in Wrangler requires wrangler `2.0.16` or above. If you're using an older version of Wrangler, ensure you [update the installed version](/workers/wrangler/install-and-update/#update-wrangler).

:::

## Authenticating Wrangler

To use Wrangler with Pub/Sub, you'll need an API Token that has permissions to both read and write for Pub/Sub. The `wrangler login` flow does not issue you an API Token with valid Pub/Sub permissions.

:::note

This API token requirement will be lifted prior to Pub/Sub becoming Generally Available.

:::

To create an API Token that Wrangler can use:

1. From the [Cloudflare dashboard](https://dash.cloudflare.com), click on the profile icon and select **My Profile**.
2. Under **My Profile**, click **API Tokens**.
3. On the [**API Tokens**](https://dash.cloudflare.com/profile/api-tokens) page, click **Create Token**
4. Choose **Get Started** next to **Create Custom Token**
5. Name the token - e.g. "Pub/Sub Write Access"
6. Under the **Permissions** heading, choose **Account**, select **Pub/Sub** from the first drop-down, and **Edit** as the permission.
7. Click **Continue to Summary** at the bottom of the page, where you should see _All accounts - Pub/Sub:Edit_ as the permission
8. Click **Create Token**, and copy the token value.

In your terminal, configure a `CLOUDFLARE_API_TOKEN` environmental variable with your Pub/Sub token. When this variable is set, `wrangler` will use it to authenticate against the Cloudflare API.

```sh
export CLOUDFLARE_API_TOKEN="pasteyourtokenhere"
```

:::caution[Warning]

This token should be kept secret and not committed to source code or placed in any client-side code.

:::

## Pub/Sub Commands

Wrangler exposes two groups of commands for managing your Pub/Sub configurations:

1. `wrangler pubsub namespace`, which manages the [namespaces](/pub-sub/learning/how-pubsub-works/#brokers-and-namespaces) your brokers are grouped into.
2. `wrangler pubsub broker` for managing your individual brokers, issuing and revoking credentials, and updating your [Worker integrations](/pub-sub/learning/integrate-workers/).

The available `wrangler pubsub namespace` sub-commands include:

```sh
wrangler pubsub namespace --help
```

```sh output

Manage your Pub/Sub Namespaces

Commands:
  wrangler pubsub namespace create <name>    Create a new Pub/Sub Namespace
  wrangler pubsub namespace list             List your existing Pub/Sub Namespaces
  wrangler pubsub namespace delete <name>    Delete a Pub/Sub Namespace
  wrangler pubsub namespace describe <name>  Describe a Pub/Sub Namespace
```

The available `wrangler pubsub broker` sub-commands include:

```sh
wrangler pubsub broker --help
```

```sh output

Interact with your Pub/Sub Brokers

Commands:
  wrangler pubsub broker create <name>            Create a new Pub/Sub Broker
  wrangler pubsub broker update <name>            Update an existing Pub/Sub Broker's configuration.
  wrangler pubsub broker list                     List the Pub/Sub Brokers within a Namespace
  wrangler pubsub broker delete <name>            Delete an existing Pub/Sub Broker
  wrangler pubsub broker describe <name>          Describe an existing Pub/Sub Broker.
  wrangler pubsub broker issue <name>             Issue new client credentials for a specific Pub/Sub Broker.
  wrangler pubsub broker revoke <name>            Revoke a set of active client credentials associated with the given Broker
  wrangler pubsub broker unrevoke <name>          Restore access to a set of previously revoked client credentials.
  wrangler pubsub broker show-revocations <name>  Show all previously revoked client credentials.
  wrangler pubsub broker public-keys <name>       Show the public keys used for verifying on-publish hooks and credentials for a Broker.
```

### Create a Namespace

To create a [Namespace](/pub-sub/learning/how-pubsub-works/#brokers-and-namespaces):

```sh
wrangler pubsub namespace create NAMESPACE_NAME
```

### Create a Broker

To create a [Broker](/pub-sub/learning/how-pubsub-works/#brokers-and-namespaces) within a Namespace:

```sh
wrangler pubsub broker create BROKER_NAME --namespace=NAMESPACE_NAME
```

### Issue an Auth Token

You can issue client credentials for a Pub/Sub Broker directly via Wrangler. Note that:

- Tokens are scoped per Broker
- You can issue multiple tokens at once
- Tokens currently allow a client to publish and/or subscribe to _any_ topic on the Broker.

To issue a single token:

```sh
wrangler pubsub broker issue BROKER_NAME --namespace=NAMESPACE_NAME
```

You can use `--number=<NUM>` to issue multiple tokens at once, and `--expiration=<DURATION>` to set an expiry (e.g. `4h` or `30d`) on the issued tokens.

### Revoke a Token

To revoke one or more tokens—which will immediately prevent that token from being used to authenticate—use the `revoke` sub-command and pass the unique token ID (or `JTI`):

```sh
wrangler pubsub broker revoke BROKER_NAME --namespace=NAMESPACE_NAME --jti=JTI_ONE --jti=JTI_TWO
```

## Filing Bugs

If you've found a bug with one of the `wrangler pubsub [...]` commands, please [file a bug on GitHub](https://github.com/cloudflare/workers-sdk/issues/new/choose), and include the version of `wrangler` you're using with `wrangler --version`.

---

# How Pub/Sub works

URL: https://developers.cloudflare.com/pub-sub/learning/how-pubsub-works/

Cloudflare Pub/Sub is a powerful way to send (publish) messages to and from remote clients.

There are four major concepts to understand with Pub/Sub:

1. [Brokers and namespaces](#brokers-and-namespaces)
2. [Authentication](#authentication)
3. [Topics and subscriptions](#topics-and-subscriptions)
4. [Messages](#messages)

## Brokers and namespaces

Brokers and namespaces are fundamentally "containers" for organizing clients, topics, and their associated permissions.

* A **namespace** is a collection of brokers that can be organized by location, end-customer, environment (production vs. staging), or by teams within an organization. When starting out, one namespace is typically all you need. Namespaces are globally unique across all customers.

* A **broker** is a term commonly used in MQTT to refer to the "server," but because an MQTT "server" is effectively a relay or proxy that accepts messages from one set of clients and sends them to the next, the term broker is used to distinguish from a typical client-server architecture. Clients – and their credentials – are scoped to a broker, and a broker itself is an addressable endpoint that accepts MQTT connections from clients on a TCP port.

For example, you could create a namespace called `acme-telemetry` and a broker called `dev-broker`. Together, these define an endpoint of `dev-broker.acme-telemetry.cloudflarepubsub.com` that authenticated clients can connect, send (publish), and receive (subscribe) messages against.

## Authentication

All clients must authenticate – prove they are allowed to connect – to a broker, and credentials are scoped per broker. A client with credentials for `dev-broker.acme-telemetry.cloudflarepubsub.com` would need a separate set of credentials to connect to` prod-broker.acme-telemetry.cloudflarepubsub.com` even if both are in the same account.

* Authentication is based on the MQTT standard, which allows for **username and password** (often called **token auth**) authentication, as well as implementation specific Mutual TLS (often called **TLS Client Credentials**) based authentication.
* With Cloudflare Pub/Sub, the easiest way to get started is to issue per-client tokens. Tokens take the place of the **password** in the authentication flow. These tokens are signed [JSON Web Tokens](https://datatracker.ietf.org/doc/html/rfc7519), which can only be generated by Cloudflare. Because they are signed, the client ID, permissions, or other claims embedded in the token cannot be changed without invalidating the signature.

For more information about how authentication is handled, refer to [Authentication and authorization](/pub-sub/platform/authentication-authorization).

## Topics and subscriptions

The **topic** is the core concept of Pub/Sub and MQTT, and all messages are contained within the topic they are published on. In MQTT, topics are strings that are separated by a `/` (forward slash) character to denote different topic levels and define a hierarchy for subscribers. Importantly, and one of the benefits of the underlying MQTT protocol, topics do not have to be defined centrally. Clients can publish to arbitrary topics, provided the broker allows that client to do so, which allows you to flexibly group messages as needed.

A Pub/Sub client can be both a publisher and subscriber at once, and can publish and subscribe to multiple topics at once.

As a set of best practices when constructing and naming your topics:

* **Define topics as a consistent hierarchy such as location/data-type/data-format/**. For example, a client in the EU publishing HTTP metrics data would publish to `eu/metrics/request_count` so that subscribers can more easily identify the data.
* **Ensure that you are consistent with your casing (lower vs. upper case) for topic names**. Topics are case-sensitive in the MQTT protocol and a client subscribed to `eu/metrics/request_count` will never receive a message published to `EU/metrics/request_count` (note the upper-cased "EU").
* **Avoid overly long topic names (the MQTT specification supports up to 65K bytes)**. Long topic names will increase your payload size and the cost of message processing on both publishers and subscribers.
* **Avoid a leading forward slash when naming topics**. `/us/metrics/transactions_processed` is a different topic from `us/metrics/transactions_processed`. The leading slash is unnecessary.

## Messages

The MQTT standard that Cloudflare Pub/Sub is built on defines a message as the **payload** within a [`PUBLISH` packet](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901119). Payloads themselves can be UTF-8 strings, which is what most developers are used to dealing with, or a stream of bytes (a "byte array") for more complex use cases or for cases where you are using other serialized data formats, such as Protobuf or MessagePack.

In Pub/Sub, which is based on MQTT v5.0, you can also set additional fields to indicate whether the payload is a string or a stream of bytes. Both the `payloadFormatIndicator` (0 for bytes; 1 for strings) property and the `contentType` property, which accepts a [`MIME` type](https://www.iana.org/assignments/media-types/media-types.xhtml), can be used by the client to more clearly define the payload format.

As a set of best practices when sending Pub/Sub messages, you should consider:

* **Keep messages reasonably sized**. Buffering data on the client up to 1 KB (or every 2-3 seconds) is a good way to optimize for message size, throughput, and overall system latency.
* **Set the `payloadFormatIndicator` property when publishing a message**. This gives your subscribers or Workers a hint about how to parse the message.
* **Set the `contentType` property to the MIME type of the payload**. For example, `application/json ` or `application/x-msgpack`  as an additional hint, especially if clients are actively publishing messages in different formats.

---

# Delivery guarantees

URL: https://developers.cloudflare.com/pub-sub/learning/delivery-guarantees/

Delivery guarantees or "delivery modes" define how strongly a messaging system enforces the delivery of messages it processes. Each mode comes with a number of trade-offs. As you make stronger guarantees about message delivery, the system needs to perform more checks and acknowledgments to ensure that messages are delivered, or maintain state to ensure a message is only delivered the specified number of times. This increases the latency of the system and reduces the overall throughput of the system. Each "real" message may require an additional 2-4 messages, and an equivalent number of additional roundtrips, before it can be considered delivered.

Pub/Sub is based on the MQTT protocol, which allows per-message flexibility around delivery guarantees or [Quality of Service](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901234) in MQTT terms.

| Level                 | Default | Currently supported | Details                                                                                                                                                                                                                                                                                                                                                                                                                                      | Best for                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------- | ------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| At most once (QoS 0)  | Yes     | Yes                 | Often called "best-effort", where a message is published without any formal acknowledgement of receipt, and isn't replayed. <br/><br/> Has the least performance overhead as this mode does not generate additional acknowledgement packets for messages sent or delivered. <br/><br/> Depending on the reliability of the network or system (as a whole), some messages can be lost as subscribers are not required to acknowledge receipt. | Telemetry, metrics and event data, where data points are quickly superseded and/or where messages are sent at a high rate and you want to minimize resource utilization on the client. <br/><br/> QoS 0 offers the lowest latency (due to the lack of acknowledgement overhead) and thus highest per-client throughput.                                                                                                                           |
| At least once (QoS 1) | -       | No                  | Typically implemented through a handshake or "acknowledgement" protocol, a message will be re-sent until it is formally acknowledged by a recipient. <br/><br/> A message can, depending on the behavior and configuration of the system, be re-sent and thus delivered more than once. Incurs a small overhead due to additional acknowledgement packets. <br/>                                                                             | Transaction processing, most forms of chat messaging, and remote command processing such as to IoT devices). <br/><br/> Subscribers can often handle duplicates at the persistency layer by ensuring each message carries a unique identifier or "idempotency key." Even if the message is received more than once, the database layer will reject the duplicate key.                                                                             |
| Exactly once (QoS 2   | -       | No                  | The hardest to achieve and incurs significant per-message overhead on both the client, server and network. <br/><br/> It requires not only a way to acknowledge delivery, but additional state on the sender and receiver to ensure that a message is only accepted once, and that duplicates are discarded.                                                                                                                                 | Processing use-cases where subscribers must receive the message only once. Ideal when message rates are fairly low and where latency is not a primary concern. <br/><br/>This is typically very rare, and QoS 2 naturally increases latency and reduces throughput due to the additional acknowledgement packets. You should only use QoS 2 if your publishers, subscribers, or persistency layer cannot be changed to handle idempotent inserts. |

## Determine the right delivery mode

Each mode comes with a number of trade-offs. As you make stronger guarantees about message delivery, the system needs to perform more checks and acknowledgments to ensure that messages are delivered or maintain state to ensure a message is only delivered the specified number of times. This increases the latency of the system and reduces the overall throughput of the system. Each "real" message may require an additional 2-4 messages and an equivalent number of additional roundtrips, before it can be considered delivered.

MQTT specifies delivery guarantees at a per-message (PUBLISH) level, rather than at a per-broker or per-topic level as some other messaging systems do.

* This allows additional flexibility. General metrics and telemetry data that can afford a small percentage of "lost" messages can be sent with QoS level 0 (at most once), which is the default.
  * For example, the loss of 5-10 messages over 1000 sensor readings is unlikely to impact subsequent data analysis, especially if the payload is small and the data superseded quickly by a subsequent reading.
* In other cases, however, such as when delivering a chat message to another user, or publishing transaction data to a central system, the ability to set a higher QoS level — QoS level 1 corresponding to "at least once" and QoS level 2 to "exactly once" — means that only those messages incur the additional overhead.
  For most use cases, QoS level 0 is ideal for high-volume telemetry or sensor data, where concrete acknowledgement of delivery is not required. For other cases, such as publishing transaction data, chat messages or user-facing notifications, QoS level 1 ("at least once") is recommended.

---

# Learning

URL: https://developers.cloudflare.com/pub-sub/learning/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Integrate with Workers

URL: https://developers.cloudflare.com/pub-sub/learning/integrate-workers/

import { WranglerConfig, Render } from "~/components";

Once of the most powerful features of Pub/Sub is the ability to connect [Cloudflare Workers](/workers/) — powerful serverless functions that run on the edge — and filter, aggregate and mutate every message published to that broker. Workers can also mirror those messages to other sources, including writing to [Cloudflare R2 storage](/r2/), external databases, or other cloud services beyond Cloudflare, making it easy to persist or analyze incoming message payloads and data at scale.

There are three ways to integrate a Worker with Pub/Sub:

1. **As an “On Publish” hook that receives all messages published to a Broker**. This allows the Worker to modify, copy to other destinations (such as [R2](/r2/) or [KV](/kv/concepts/how-kv-works/)), filter and/or drop messages before they are delivered to subscribers.
2. (Not yet available in beta) **Publishing directly to a Pub/Sub topic from a Worker.** You can publish telemetry and events to Pub/Sub topics from your Worker code.
3. (Not yet available in beta) **Subscribing to a Pub/Sub topic (or topics) from within a Worker**. This allows the Worker to act as any other subscriber and consume messages published either from external clients (over MQTT) or from other Workers.

You can use one, many or all of these integrations as needed.

## On-Publish Hooks

"On-Publish" hooks are a powerful way to filter and modify messages as they are published to your Pub/Sub Broker.

- The Worker runs as a "post-publish" hook where messages are accepted by the broker, passed to the Worker, and messages are only sent to clients who subscribed to the topic after the Worker returns a valid HTTP response.
- If the Worker does not return a response (intentionally or not), or returns an HTTP status code other than HTTP 200, the message is dropped.
- All `PUBLISH` messages (packets) published to your Broker are sent to the Worker. Other MQTT packets, such as CONNECT or AUTH packets, are automatically handled for you by Pub/Sub.

### Connect a Worker to a Broker

:::note

You must validate the signature of every incoming message to ensure it comes from Cloudflare and not an untrusted third-party.

:::

To connect a Worker to a Pub/Sub Broker as an on-publish hook, you'll need to:

1. Create a Cloudflare Worker (or expand an existing Worker) to handle incoming POST requests from the broker. The public URL of your Worker will be the URL you configure your Broker to send messages to.
2. Configure the broker to send messages to the Worker by setting the `on_publish.url` field on your Broker.
3. **Important**: Verify the signature of the payload using the public keys associated with your Broker to confirm the request was from your Pub/Sub Broker, and **not** an untrusted third-party or another broker.
4. Inspect or mutate the message (the HTTP request payload) as you see fit!
5. Return an HTTP 200 OK with a well-formed response, which allows the broker to send the message on to any subscribers.

The following is an end-to-end example showing how to:

- Authenticate incoming requests from Pub/Sub (and reject those not from Pub/Sub)
- Replace the payload of a message on a specific topic
- Return the message to the Broker so that it can forward it to subscribers

:::note

You should be familiar with setting up a [Worker](/workers/get-started/guide/) before continuing with this example.

:::

To ensure your Worker can validate incoming requests, you must make the public keys available to your Worker via an [environmental variable](/workers/configuration/environment-variables/). To do so, we can fetch the public keys from our Broker:

```sh
wrangler pubsub broker public-keys YOUR_BROKER --namespace=NAMESPACE_NAME
```

You should receive a success response that resembles the example below, with the public key set from your Worker:

```json
"keys": [
  {
    "use": "sig",
    "kty": "OKP",
    "kid": "JDPuYJqHOvqzlakkNFQ9kfN7WsYs5uHndp_ziRdmOCU",
    "crv": "Ed25519",
    "alg": "EdDSA",
    "x": "Phf82R8tG1FdY475-AgtlaWIwH1lLFlfWu5LrsKhyjw"
  },
  {
    "use": "sig",
    "kty": "OKP",
    "kid": "qk7Z4hbN738v-m2CKdVaKTav9pU32MAaQXB2tDaQ-_o",
    "crv": "Ed25519",
    "alg": "EdDSA",
    "x": "Bt4kQWcK_XhZP1ZxEflsoYbqaBm9rEDk_jNWPdhxwTI"
  }
]
```

Copy the array of public keys into your [Wrangler configuration file](/workers/wrangler/configuration/) as an environmental variable:

:::note

Your public keys will be unique to your own Pub/Sub Broker: you should ensure you're copying the keys associated with your own Broker.

:::

<WranglerConfig>

```toml
name = "my-pubsub-worker"
type = "javascript"

account_id = "<YOUR ACCOUNT_ID>"
workers_dev = true

# Define top-level environment variables
# under the `[vars]` block using
# the `key = "value"` format
[vars]
# This will be accessible via env.BROKER_PUBLIC_KEYS in our Worker
# Note that we use three single quotes (') around our raw JSON
BROKER_PUBLIC_KEYS = '''{
  "keys": [
    {
      "use": "sig",
      "kty": "OKP",
      "kid": "JDPuYJqHOvqzlakkNFQ9kfN7WsYs5uHndp_ziRdmOCU",
      "crv": "Ed25519",
      "alg": "EdDSA",
      "x": "Phf82R8tG1FdY475-AgtlaWIwH1lLFlfWu5LrsKhyjw"
    },
    {
      "use": "sig",
      "kty": "OKP",
      "kid": "qk7Z4hbN738v-m2CKdVaKTav9pU32MAaQXB2tDaQ-_o",
      "crv": "Ed25519",
      "alg": "EdDSA",
      "x": "Bt4kQWcK_XhZP1ZxEflsoYbqaBm9rEDk_jNWPdhxwTI"
    }
  ]
}'''
```

</WranglerConfig>

<Render file="wrangler-typegen" product="workers" />

With the `BROKER_PUBLIC_KEYS` environmental variable set, we can now access these in our Worker code. The [`@cloudflare/pubsub`](https://www.npmjs.com/package/@cloudflare/pubsub) package allows you to authenticate the incoming request against your Broker's
public keys.

To install `@cloudflare/pubsub`, you can use `npm` or `yarn`:

```sh
npm i @cloudflare/pubsub
```

With `@cloudflare/pubsub` installed, we can now import both the `isValidBrokerRequest` function and our `PubSubMessage` types into
our Worker code directly:

```typescript
// An example that shows how to consume and transform Pub/Sub messages from a Cloudflare Worker.

import { isValidBrokerRequest, PubSubMessage } from "@cloudflare/pubsub";

async function pubsub(
	messages: Array<PubSubMessage>,
	env: any,
	ctx: ExecutionContext,
): Promise<Array<PubSubMessage>> {
	// Messages may be batched at higher throughputs, so we should loop over
	// the incoming messages and process them as needed.
	for (let msg of messages) {
		console.log(msg);
		// Replace the message contents in our topic - named "test/topic"
		// as a simple example
		if (msg.topic.startsWith("test/topic")) {
			msg.payload = `replaced text payload at ${Date.now()}`;
		}
	}

	return messages;
}

const worker = {
	async fetch(req, env, ctx): Promise<Response> {
		// Retrieve this from your Broker's "publicKey" field.
		//
		// Each Broker has a unique key to distinguish between your Broker vs. others
		// We store these keys in environmental variables (/workers/configuration/environment-variables/)
		// to avoid needing to fetch them on every request.
		let publicKeys = env.BROKER_PUBLIC_KEYS;

		// Critical: you must validate the incoming request is from your Broker.
		//
		// In the future, Workers will be able to do this on your behalf for Workers
		// in the same account as your Pub/Sub Broker.
		if (await isValidBrokerRequest(req, publicKeys)) {
			// Parse the PubSub message
			let incomingMessages: Array<PubSubMessage> = await req.json();

			// Pass the messages to our pubsub handler, and capture the returned
			// message.
			let outgoingMessages = await pubsub(incomingMessages, env, ctx);

			// Re-serialize the messages and return a HTTP 200.
			// The Content-Type is optional, but must either by
			// "application/octet-stream" or left empty.
			return new Response(JSON.stringify(outgoingMessages), { status: 200 });
		}

		return new Response("not a valid Broker request", { status: 403 });
	},
} satisfies ExportedHandler;

export default worker;
```

Once you have deployed your Worker using `npx wrangler deploy`, you will need to configure your Broker to invoke the Worker. This is done by setting the `--on-publish-url` value of your Broker to the _publicly accessible_ URL of your Worker:

```sh
wrangler pubsub broker update YOUR_BROKER --namespace=NAMESPACE_NAME --on-publish-url="https://your.worker.workers.dev"
```

```json {11} output
{
	"id": "4c63fa30ee13414ba95be5b56d896fea",
	"name": "example-broker",
	"authType": "TOKEN",
	"created_on": "2022-05-11T23:19:24.356324Z",
	"modified_on": "2022-05-11T23:19:24.356324Z",
	"expiration": null,
	"endpoint": "mqtts://example-broker.namespace.cloudflarepubsub.com:8883",
	"on_publish": {
		"url": "https://your-worker.your-account.workers.dev"
	}
}
```

Once you set this, _all_ MQTT `PUBLISH` messages sent to your Broker from clients will be delivered to your Worker for further processing. You can use our [web-based live demo](https://demo.mqtt.dev) to test that your Worker is correctly validating requests and intercepting messages.

Note that other HTTPS-enabled endpoints are valid destinations to forward messages to, but may incur latency and/or reduce message delivery success rates as messages will necessarily need to traverse the public Internet.

### Message Payload

Below is an example of a PubSub message sent over HTTP to a Worker:

```json
[
	{
		"mid": 0,
		"broker": "my-broker.my-namespace.cloudflarepubsub.com",
		"topic": "us/external/metrics/abc-456-def-123/request_count",
		"clientId": "broker01G24VP1T3B51JJ0WJQJWCSY61",
		"receivedAt": 1651578191,
		"contentType": null,
		"payloadFormatIndicator": 1,
		"payload": "<payload>"
	},
	{
		"mid": 1,
		"broker": "my-broker.my-namespace.cloudflarepubsub.com",
		"topic": "ap/external/metrics/abc-456-def-123/transactions_processed",
		"clientId": "broker01G24VS053KYGNBBX8RH3T7CY5",
		"receivedAt": 1651578193,
		"contentType": null,
		"payloadFormatIndicator": 1,
		"payload": "<payload>"
	}
]
```

### Per-Message Metadata and TypeScript Support

Messages delivered to a Worker, or sent from a Worker, are wrapped with additional metadata about the message so that you can more easily inspect the topic, message format, and other properties that can help you to route & filter messages.

This metadata includes:

- the `broker` the message was associated with, so that your code can distinguish between messages from multiple Brokers
- the `topic` the message was published to by the client. **Note that this is readonly: attempting to change the topic in the Worker is invalid and will result in that message being dropped**.
- a `receivedTimestamp`, set when Pub/Sub first parses and deserializes the message
- the `mid` ("message id") of the message. This is a unique ID allowing Pub/Sub to track messages sent to your Worker, including which messages were dropped (if any). The `mid` field is immutable and returning a modified or missing `mid` will likely cause messages to be dropped.

This metadata, including their JavaScript types and whether they are immutable ("`readonly`"), are expressed as the `PubSubMessage` interface in the [@cloudflare/pubsub](https://github.com/cloudflare/pubsub) library.

The `PubSubMessage` type may grow to include additional fields over time, and we recommend importing `@cloudflare/pubsub` (instead of copy+pasting) to ensure your code can benefit from any future changes.

### Batching

Messages sent to your on-publish Worker may be batched: each batch is an array of 1 or more `PubSubMessage`.

- Batching helps to reduce the number of invocations against your Worker, and can allow you to better aggregate messages when writing them to upstream services.
- Pub/Sub’s batching mechanism is designed to batch messages arriving simultaneously from publishers, and not wait several seconds.
- It does **not** measurably increase the latency of message delivery.

### On-Publish Best Practices

- Only inspect the topics you need to reduce the compute your Worker needs to do.
- Use `ctx.waitUntil` if you need to write to storage or communicate with remote services and avoid increasing message delivery latency while waiting on those operations to complete.
- Catch exceptions using [try-catch](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) - if your on-publish hook is able to “fail open”, you should use the `catch` block to return messages to the Broker in the event of an exception so that messages aren’t dropped.

## Troubleshoot Workers integrations

Some common failure modes can result in messages not being sent to subscribed clients when a Worker is processing messages, including:

- Failing to correctly validate incoming requests. This can happen if you are not using the correct public keys (keys are unique to each of your Brokers), if the keys are malformed, and/or if you have not populated the keys in the Worker via environmental variables.
- Not returning a HTTP 200 response. Any other HTTP status code is interpreted as an error and the message is dropped.
- Not returning a valid Content-Type. The Content-Type in the HTTP response header must be `application/octet-stream`
- Taking too long to return a response (more than 10 seconds). You can use [`ctx.waitUntil`](/workers/runtime-apis/context/#waituntil) if you need to write messages to other destinations after returning the message to the broker.
- Returning an invalid or unstructured body, a body or payload that exceeds size limits, or returning no body at all.

Because the Worker is acting as the "server" in the HTTP request-response lifecycle, invalid responses from your Worker can fail silently, as the Broker can no longer return an error response.

---

# WebSockets and Browser Clients

URL: https://developers.cloudflare.com/pub-sub/learning/websockets-browsers/

import { PackageManagers } from "~/components";

Pub/Sub allows you to both publish and subscribe from within a web browser or other WebSocket capable client. Every Pub/Sub Broker supports MQTT over WebSockets natively, without further configuration.

With Pub/Sub’s WebSocket support, you can:

- Subscribe to a topic in the browser and push near real-time updates (such as notifications or chat messages) to those clients from your backend services.
- Publish telemetry directly from WebSocket clients and then aggregate those messages in a centralized service or by using [Workers Analytics Engine](https://blog.cloudflare.com/workers-analytics-engine/) to consume them on your behalf.
- Publish and subscribe directly between a browser client and your MQTT-capable IoT devices in the field.

When clients are connecting from a browser, you should use [`token` authentication](/pub-sub/platform/authentication-authorization/) and ensure you are issuing clients unique credentials.

## MQTT over WebSockets

WebSocket support in Pub/Sub works by encapsulating MQTT packets (Pub/Sub’s underlying native protocol) within WebSocket [frames](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#exchanging_data_frames).

- In many MQTT libraries, you can replace the `mqtts://` scheme with `wss://`, and your code will use a WebSocket transport instead of the native “raw” TCP transport.
- The WebSocket listener is available on both TCP ports `443` and `8884` versus `8883` for native MQTT.
- WebSocket clients need to speak MQTT over WebSockets. Pub/Sub does not support other message serialization methods over WebSockets at present.
- **Clients should include a `sec-websocket-protocol: mqtt` request header in the initial HTTP GET request** to distinguish an "MQTT over WebSocket" request from future, non-MQTT protocol support over WebSockets.
- Authentication is performed within the WebSocket connection itself. An MQTT `CONNECT` packet inside the WebSocket tunnel includes the required username and password. The WebSocket connection itself does not need to be authenticated at the HTTP level.

We recommend using [MQTT.js](https://github.com/mqttjs/MQTT.js), one of the most popular JavaScript libraries, for client-side JavaScript support. It can be used in both the browser via Webpack or Browserify and in a Node.js environment.

## JavaScript Web Example

In this example, we use MQTT.js’s WebSocket support to subscribe to a topic and publish messages to it.

:::note

You can view a live demo available at [demo.mqtt.dev](http://demo.mqtt.dev) that allows you to use your own Pub/Sub Broker and a valid token to subscribe to a topic and publish messages to it.
:::

In a real-world deployment, our publisher could be another client, a native MQTT client, or a WebSocket client running on a remote server elsewhere.

<PackageManagers pkg="mqtt" />

```js
import * as mqtt from "mqtt"

// Where 'url' is "mqtts://BROKER.NAMESPACE.cloudflarepubsub.com:8884"
function example(url) {
  let client = mqtt.connect(url, {
    protocolVersion: 5,
    reconnectPeriod: 0,
    username: 'anything',
    password: jwt, // pass this from a form field in your app
    clientId: '',
  })

  client.on('connect', function () {
    client.subscribe(topic, function (err) {
      if (err) {
        client.end();
      } else {
        console.log(`subscribed to ${topic}`)
      }
  })

  client.on('message', function (topic, message) {
    let line = (new Date()).toLocaleString('en-US') + ": " + message.toString() + "\n";
    console.log(line)
  })
}
```

You can use a JavaScript bundler, such as Webpack, to include the library into a script you can include in your web application.

---

# Authentication and authorization

URL: https://developers.cloudflare.com/pub-sub/platform/authentication-authorization/

Pub/Sub supports two authentication modes. A broker may allow one or both, but never none as authentication is always required.

| Mode             | Details                                                                                                                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TOKEN`          | Accepts a Client ID and a password (represented by a signed JSON Web Token) in the CONNECT packet. The MQTT User Name field is optional. If provided, it must match the Client ID. |
| `MTLS`           | **Not yet supported.** Accepts an mTLS keypair (TLS client credentials) scoped to that broker. Keypairs are issued from a Cloudflare root CA unless otherwise configured.          |
| `MTLS_AND_TOKEN` | **Not yet supported.** Allows clients to use both MTLS and/or Token auth for a broker.                                                                                             |

To generate credentials scoped to a specific broker, you have two options:

- Allow Pub/Sub to generate Client IDs for you.
- Supply a list of Client IDs that Pub/Sub will use to generate tokens.

The recommended and simplest approach if you are starting from scratch is to have Pub/Sub generate Client IDs for you, which ensures they are sufficiently random and that there are not conflicting Client IDs. Duplicate Client IDs can cause issues with clients because only one instance of a Client ID is allowed to connect to a broker.

## Generate credentials

:::note

Ensure you do not commit your credentials to source control, such as GitHub. A valid token allows anyone to connect to your broker and publish or subscribe to messages. Treat credentials as secrets.

:::

To generate a single token for a broker named `example-broker` in `your-namespace`, issue a request to the Pub/Sub API.

- By default, the API returns one valid` <Client ID, Token>` pair but can return up to 100 per API call to simplify issuance for larger deployments.
- You must specify a Topic ACL (Access Control List) for the tokens. This defines what topics clients authenticating with these tokens can PUBLISH or SUBSCRIBE to. Currently, the Topic ACL must be `#` all topics — finer-grained ACLs are not yet supported.

For example, to generate five valid tokens with an automatically generated Client ID for each token:

```sh
wrangler pubsub broker issue example-broker --number=5 --expiration=48h
```

You should receive a scucess response that resembles the example below, which is a map of Client IDs and their associated tokens.

```json
{
  "01G3A5GBJE5P3GPXJZ72X4X8SA": "eyJhbGciOiJFZERTQSIsImtpZCI6IkpEUHVZSnFIT3Zxemxha2tORlE5a2ZON1dzWXM1dUhuZHBfemlSZG1PQ1UifQ.
  not-a-real-token.ZZL7PNittVwJOeMpFMn2CnVTgIz4AcaWXP9NqMQK0D_iavcRv_p2DVshg6FPe5xCdlhIzbatT6gMyjMrOA2wBg",
  "01G3A5GBJECX5DX47P9RV1C5TV": "eyJhbGciOiJFZERTQSIsImtpZCI6IkpEUHVZSnFIT3Zxemxha2tORlE5a2ZON1dzWXM1dUhuZHBfemlSZG1PQ1UifQ.also-not-a-real-token.WrhK-VTs_IzOEALB-T958OojHK5AjYBC5ZT9xiI_6ekdQrKz2kSPGnvZdUXUsTVFDf9Kce1Smh-mw1sF2rSQAQ",
}
```

## Configuring Clients

To configure an MQTT client to connect to Pub/Sub, you need:

- Your Broker hostname - e.g. `your-broker.your-namespace.cloudflarepubsub.com` and port (`8883` for MQTT)
- A Client ID - this must be either the Client ID associated with your token, or left empty. Some clients require a Client ID, and others generate a random Client ID. **You will not be able to connect if the Client ID is mismatched**.
- A username - Pub/Sub does not require you to specify a username. You can leave this empty, or for clients that require one to be set, the text `PubSub` is typically sufficient.
- A "password" - this is a valid JSON Web Token (JWT) received from the API, _specific to the Broker you are trying to connect to_.

The most common failure case is supplying a Client ID that does not match your token. Ensure you are setting this correctly in your client, or (recommended) leaving it empty if your client supports auto-assigning the Client ID when it connects to Pub/Sub.

## Token claims and metadata

An JSON Web Token (JWT) issued by Pub/Sub will include the following claims.

| Claims   | Details                                                                                                                                                                                                                                                                                                                                                         |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| iat      | A Unix timestamp representing the token's creation time.                                                                                                                                                                                                                                                                                                        |
| exp      | A Unix timestamp representing the token's expiry time. Only included when the JWT has an optional expiry timestamp.                                                                                                                                                                                                                                             |
| sub      | The "subject" - the MQTT Client Identifier associated with this token. This is the source of truth for the Client ID. If a Client ID is provided in the CONNECT packet, it must match this ID. Clients that do not specify a Client ID in the CONNECT packet will see this Client ID as the "Assigned Client Identifier" in the CONNACK packet when connecting. |
| jti      | JWT ID. An identifier that uniquely identifies this JWT. Used to distinguish multiple JWTs for the same (broker, clientId) apart, and allows revocation of specific tokens.                                                                                                                                                                                     |
| topicAcl | Must be `#` (matches all topics). In the future, ACLs will allow you to express what topics the client can PUBLISH to, SUBSCRIBE to, or both.                                                                                                                                                                                                                   |

## Revoking Credentials

To revoke a credential, which immediately invalidates it and prevents any clients from connecting with it, you can use `wrangler pubsub broker revoke [...]` or issue a POST request to the `/revocations` endpoint of the Pub/Sub API with the `jti` (unique token identifier).

This will add the token to a revocation list. When using JWTs, you can revoke the JWT based on its unique `jti` claim. To revoke multiple tokens at once, provide a list of token identifiers.

```sh
wrangler pubsub broker revoke example-broker --namespace=NAMESPACE_NAME --jti=JTI_ONE --jti=JTI_TWO
```

You can also list all currently revoked tokens by using `wrangler pubsub broker show-revocations [...]` or by making a GET request to the `/revocations` endpoint.

You can _unrevoke_ a token by using `wrangler pubsub broker unrevoke [...]` or by issuing a DELETE request to the `/revocations` endpoint with the `jti` as a query parameter.

## Credential Lifetime and Expiration

Credentials can be set to expire at a Broker-level that applies to all credentials, and/or at a per-credential level.

- By default, credentials do not expire, in order to simplify credential management.
- Credentials will inherit the shortest of the expirations set, if both the Broker and the issued credential have an expiration set.

To set an expiry for each set of credentials issued by setting the `expiration` value when requesting credentials: in this case, we specify 1 day (`1d`):

```sh
wrangler pubsub broker issue example-broker --namespace=NAMESPACE_NAME --expiration=1d
```

This will return a token that expires 1 day (24 hours) from issuance:

```json
{
  "01G3A5GBJE5P3GPXJZ72X4X8SA": "eyJhbGciOiJFZERTQSIsImtpZCI6IkpEUHVZSnFIT3Zxemxha2tORlE5a2ZON1dzWXM1dUhuZHBfemlSZG1PQ1UifQ.
  not-a-real-token.ZZL7PNittVwJOeMpFMn2CnVTgIz4AcaWXP9NqMQK0D_iavcRv_p2DVshg6FPe5xCdlhIzbatT6gMyjMrOA2wBg"
}
```

To set a Broker-level global expiration on an existing Pub/Sub Broker, set the `expiration` field on the Broker to the seconds any credentials issued should inherit:

```sh
wrangler pubsub broker update YOUR_BROKER --namespace=NAMESPACE_NAME --expiration=7d
```

This will cause any token issued by the Broker to have a default expiration of 7 days. You can make this _shorter_ by passing the `--expiration` flag to `wrangler pubsub broker issue [...]`. For example:

- If you set a longer `--expiration` than the Broker itself has, the Broker's expiration will be used instead (shortest wins).
- Using `wrangler pubsub broker issue [...] --expiration -1` will remove the `exp` claim from the token - essentially returning a non-expiring token - even if a Broker-level expiration has been set.

### Best Practices

- We strongly recommend setting a per-broker expiration configuration via the **expiration** (integer seconds) field, which will implicitly set an expiration timestamp for all credentials generated for that broker via the `exp` JWT claim.
- Using short-lived credentials – for example, 7 to 30 days – with an automatic rotation policy can reduce the risk of credential compromise and the need to actively revoke credentials after-the-fact.
- You can use Pub/Sub itself to issue fresh credentials to clients using [Cron Triggers](/workers/configuration/cron-triggers/) or a separate HTTP endpoint that clients can use to refresh their local token store.

## Authorization and Access Control

:::note

Pub/Sub currently supports `#` (all topics) as an ACL. Finer-grained ACL support is on the roadmap.

:::

In order to limit what topics a client can PUBLISH or SUBSCRIBE to, you can define an ACL (Access Control List). Topic ACLs are defined in the signed credentials issued to a client and determined when the client connects.

---

# Platform

URL: https://developers.cloudflare.com/pub-sub/platform/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Limits

URL: https://developers.cloudflare.com/pub-sub/platform/limits/

The table lists limits that apply to Pub/Sub brokers and clients during the beta release.

:::note


These limits are subject to change and many will increase over time.


:::

| Item                                             | Limit | Notes                                                                                                                                                                                                                                   |
| ------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Namespaces per Account                           | 3                      | The maximum number of namespaces allowed on an account.                                                                                                                                                                                 |
| Brokers per Namespace                            | 3                      | Can eventually be increased.                                                                                                                                                                                                            |
| Subscribers per topic                            | 1000                   | The maximum number of subscribers per MQTT topic.                                                                                                                                                                                       |
| Connections per Device                           | 1                      | The number of simultaneous connections from a single client ID (or token). **More than one connection from the same client ID will result in existing clients receiving a DISCONNECT** using Reason Code 0x8e (Session Taken Over).     |
| Maximum Packets per Second per Client            | 10                     | The number of MQTT packets per second a client can send to the broker. <br/> Clients that exceed this rate will receive a DISCONNECT with Reason Code 0x96 (Message rate too high).                                                     |
| Maximum Topic Length                             | 65k bytes              | The maximum length of a topic, in bytes, including all slashes, prefixes, or wildcard symbols.                                                                                                                                          |
| Maximum Topic Depth                              | 8                      | The maximum number of forward slashes (`/`) allowed in a topic.                                                                                                                                                                         |
| Maximum Message Size                             | 64KB                   | Includes metadata such as client ID, additional metadata fields, and optional MQTT fields.                                                                                                                                              |
| Maximum Client ID Length                         | 23 bytes               | The maximum length of an MQTT Client Identifier in bytes.<br/> Client IDs must also be at least 1 byte long per the MQTT standard. Shorter client IDs are rejected with a CONNACK using Reason Code 0x85 (Client Identifier not valid). |
| Maximum Username Length                          | 32 bytes               | The maximum length of the username in bytes. <br/> Usernames are optional, but if provided, must match the Client ID. <br/> Invalid usernames are rejected with CONNACK using Reason Code 0x86 (Bad Username or Password).              |
| Maximum Password Length                          | 4,096 bytes            | The maximum size of the UTF-8 encoded password, in bytes. <br/> Invalid passwords are rejected with CONNACK using Reason Code 0x86 (Bad Username or Password).                                                                          |
| Connect Interval                                 | 10 seconds             | Maximum interval that a client can wait between establishing TLS connection and send a CONNECT. <br/> Clients that take longer than this will be disconnected.                                                                          |
| Minimum Keep Alive Interval                      | 10 seconds             | Minimum time interval in which a client must send an MQTT control packet or a PINGREQ packet. <br/> Clients that take longer than this will be disconnected.                                                                            |
| Maximum Session Expiry Interval                  | 7 days                 | Maximum time interval to retain a client's session state. Currently includes Subscriptions and Will messages. <br/> Note that 7 days is best effort, and in some cases, the session state may be shorter.                               |
| Maximum Number of Revoked Credentials per Broker | 10,000                 | The maximum number of credentials that can be revoked for a single broker.                                                                                                                                                              |

Storage and network units are in [SI units](https://physics.nist.gov/cuu/Units/binary.html).

---

# MQTT compatibility

URL: https://developers.cloudflare.com/pub-sub/platform/mqtt-compatibility/

:::note


Pub/Sub will continue to expand support for MQTT protocol features during the beta period. The documentation will be updated to reflect the expanded features, so check these docs periodically.


:::

Pub/Sub supports the core parts of the [MQTT v5.0 specification](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html), and any MQTT v5.0 compatible client should be able to connect to a Pub/Sub Broker.

MQTT is one of the most pervasive “messaging protocols” deployed today. There are tens of millions (at least!) of devices that speak MQTT today, from connected payment terminals through to autonomous vehicles, cell phones, and even video games. Sensor readings, telemetry, financial transactions or mobile notifications and messages are all common use cases for MQTT, and the flexibility of the protocol allows developers to make trade-offs around reliability, topic hierarchy, and persistence specific to their use case.

:::note


In many cases, the MQTT specification mandates that a client is explicitly disconnected when attempting to use features not supported by a broker. Ensure that your client only uses supported features to avoid disconnection loops that prevent a client from sending messages to a broker.


:::

Pub/Sub supports the following MQTT protocol features.

| Protocol feature                      | Supported         | Details                                                                                                                                                                                                                                    |
| ------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| User Name & Password Authentication   | Yes               | Pub/Sub uses signed JSON Web Tokens in place of passwords for authenticating clients. <br/> For more information on how authentication works, refer to [Authentication and Authorization](/pub-sub/platform/authentication-authorization). |
| Mutual TLS (TLS Client Credentials)   | Not yet supported | None yet                                                                                                                                                                                                                                   |
| Enhanced Authentication               | Not supported     | Commonly used to support Kerberos.                                                                                                                                                                                                         |
| Delivery: At Most Once (QoS 0)        | Yes (default)     | This is the default QoS level in MQTT and relies on the underlying TCP connection and system for basic delivery guarantees and network-level re-transmissions.                                                                             |
| Delivery: At Least Once (QoS 1)       | Not yet supported | The broker will return a DISCONNECT with Reason Code 0x9B (QoS not supported) if a client attempts to send a message with an unsupported Quality of Service mode.                                                                          |
| Delivery: Exactly Once (QoS 2)        | Not yet supported | The broker will return a DISCONNECT with Reason Code 0x9B (QoS not supported) if a client attempts to send a message with an unsupported Quality of Service mode.                                                                          |
| Retain                                | Not yet supported | The Broker will return a DISCONNECT Reason Code of 0x9A (Retain not supported) if a client attempts to send a message with the Retain bit set to any value other than zero (0).                                                            |
| Will Messages                         | Not yet supported | Will messages (sometimes called "Last Will" messages) are not currently supported and will be ignored by a broker.                                                                                                                         |
| Receive Maximum                       | Not yet supported | Only applies to QoS 1 and QoS 2 messages, which are not currently supported.                                                                                                                                                               |
| Single-level Wildcard (`+` character) | Not yet supported | The broker will return a DISCONNECT Reason Code of 0x90 (Topic Name invalid) if a client attempts to subscribe to a Topic with a wildcard (`+` or `#` character).                                                                          |
| Multi-level Wildcard (`#` character)  | Not yet supported | The broker will return a DISCONNECT Reason Code of 0x90 (Topic Name invalid) if a client attempts to subscribe to a topic with a wildcard (`+` or `#` character).                                                                          |
| Shared Subscriptions                  | Not yet supported | Clients that attempt to SUBSCRIBE to a Shared Subscription, which are prefixed with a literal `$share/` string, the server will return a DISCONNECT with Reason Code 0x9E (Shared Subscriptions not supported).                            |
| Subscription Identifiers              | Not yet supported | Clients that send a SUBSCRIBE packet with a Subscription Identifier will receive a DISCONNECT with Reason Code of 0xA1 (Subscription Identifiers not supported).                                                                           |
| User Properties                       | Not yet supported | [User Properties](https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc464547991) included in a PUBLISH packet will not be forwarded to subscribers.                                                                        |

## Permissions and IAM

During the beta period, users need the **Super Administrator** or **Administrator** permission to create, modify, or delete namespaces or brokers associated with an account.

In the future, Pub/Sub will have brokers-specific IAM permissions for:

* **Admin** - Create, edit, and delete namespaces; create, edit, and delete brokers
* **User** - Create, edit, and delete brokers (only); view namespaces but cannot create or delete namespaces
* **Viewer** - View brokers. Can view config but cannot issue new credentials or modify config

Longer term, Pub/Sub will allow users to scope those permissions per namespace to better support isolated environments and distributed teams.

---

# Configure Queues

URL: https://developers.cloudflare.com/queues/configuration/configure-queues/

import { WranglerConfig, Type } from "~/components";

Cloudflare Queues can be configured using [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Cloudflare's Developer Platform, which includes [Workers](/workers/), [R2](/r2/), and other developer products.


Each Producer and Consumer Worker has a [Wrangler configuration file](/workers/wrangler/configuration/) that specifies environment variables, triggers, and resources, such as a queue. To enable Worker-to-resource communication, you must set up a [binding](/workers/runtime-apis/bindings/) in your Worker project's Wrangler file.

Use the options below to configure your queue.

:::note


Below are options for queues, refer to the Wrangler documentation for a full reference of the [Wrangler configuration file](/workers/wrangler/configuration/).


:::

## Queue configuration
The following queue level settings can be configured using Wrangler:

```sh
$ npx run wrangler queues update <QUEUE-NAME> --delivery-delay-secs 60 --message-retention-period-secs 3000
```

* `--delivery-delay-secs` <Type text="number" /> <Type text="optional" />
	* How long a published message is delayed for, before it is delivered to consumers.
	* Must be between 0 and 43200 (12 hours).
	* Defaults to 0.

* `--message-retention-period-secs`  <Type text="number" /> <Type text="optional" />
	* How long messages are retained on the Queue.
	* Defaults to 345600 (4 days).
	* Must be between 60 and 1209600 (14 days)

## Producer Worker configuration

A producer is a [Cloudflare Worker](/workers/) that writes to one or more queues. A producer can accept messages over HTTP, asynchronously write messages when handling requests, and/or write to a queue from within a [Durable Object](/durable-objects/). Any Worker can write to a queue.

To produce to a queue, set up a binding in your Wrangler file. These options should be used when a Worker wants to send messages to a queue.

<WranglerConfig>

```toml
[[queues.producers]]
  queue = "my-queue"
  binding = "MY_QUEUE"
```

</WranglerConfig>



* <code>queue</code> <Type text="string" />

  * The name of the queue.

* <code>binding</code> <Type text="string" />

  * The name of the binding, which is a JavaScript variable.



## Consumer Worker Configuration

To consume messages from one or more queues, set up a binding in your Wrangler file. These options should be used when a Worker wants to receive messages from a queue.



<WranglerConfig>

```toml
[[queues.consumers]]
  queue = "my-queue"
  max_batch_size = 10
  max_batch_timeout = 30
  max_retries = 10
  dead_letter_queue = "my-queue-dlq"
```

</WranglerConfig>

Refer to [Limits](/queues/platform/limits) to review the maximum values for each of these options.



* <code>queue</code> <Type text="string" />

  * The name of the queue.

* <code>max\_batch\_size</code> <Type text="number" /> <Type text="optional" />

  * The maximum number of messages allowed in each batch.
  * Defaults to `10` messages.

* <code>max\_batch\_timeout</code> <Type text="number" /> <Type text="optional" />

  * The maximum number of seconds to wait until a batch is full.
  * Defaults to `5` seconds.

* <code>max\_retries</code> <Type text="number" /> <Type text="optional" />

  * The maximum number of retries for a message, if it fails or [`retryAll()`](/queues/configuration/javascript-apis/#messagebatch) is invoked.
  * Defaults to `3` retries.

* <code>dead\_letter\_queue</code> <Type text="string" /> <Type text="optional" />

  * The name of another queue to send a message if it fails processing at least `max_retries` times.
  * If a `dead_letter_queue` is not defined, messages that repeatedly fail processing will eventually be discarded.
  * If there is no queue with the specified name, it will be created automatically.

* <code>max\_concurrency</code> <Type text="number" /> <Type text="optional" />

  * The maximum number of concurrent consumers allowed to run at once. Leaving this unset will mean that the number of invocations will scale to the [currently supported maximum](/queues/platform/limits/).
  * Refer to [Consumer concurrency](/queues/configuration/consumer-concurrency/) for more information on how consumers autoscale, particularly when messages are retried.



## Pull-based

A queue can have a HTTP-based consumer that pulls from the queue. This consumer can be any HTTP-speaking service that can communicate over the Internet. Review [Pull consumers](/queues/configuration/pull-consumers/) to learn how to configure a pull-based consumer.

---

# Batching, Retries and Delays

URL: https://developers.cloudflare.com/queues/configuration/batching-retries/

import { WranglerConfig } from "~/components";

## Batching

When configuring a [consumer Worker](/queues/reference/how-queues-works#consumers) for a queue, you can also define how messages are batched as they are delivered.

Batching can:

1. Reduce the total number of times your consumer Worker needs to be invoked (which can reduce costs).
2. Allow you to batch messages when writing to an external API or service (reducing writes).
3. Disperse load over time, especially if your producer Workers are associated with user-facing activity.

There are two ways to configure how messages are batched. You configure batching when connecting your consumer Worker to a queue.

- `max_batch_size` - The maximum size of a batch delivered to a consumer (defaults to 10 messages).
- `max_batch_timeout` - the _maximum_ amount of time the queue will wait before delivering a batch to a consumer (defaults to 5 seconds)

:::note[Batch size configuration]

Both `max_batch_size` and `max_batch_timeout` work together. Whichever limit is reached first will trigger the delivery of a batch.

:::

For example, a `max_batch_size = 30` and a `max_batch_timeout = 10` means that if 30 messages are written to the queue, the consumer will deliver a batch of 30 messages. However, if it takes longer than 10 seconds for those 30 messages to be written to the queue, then the consumer will get a batch of messages that contains however many messages were on the queue at the time (somewhere between 1 and 29, in this case).

:::note[Empty queues]

When a queue is empty, a push-based (Worker) consumer's `queue` handler will not be invoked until there are messages to deliver. A queue does not attempt to push empty batches to a consumer and thus does not invoke unnecessary reads.

[Pull-based consumers](/queues/configuration/pull-consumers/) that attempt to pull from a queue, even when empty, will incur a read operation.

:::

When determining what size and timeout settings to configure, you will want to consider latency (how long can you wait to receive messages?), overall batch size (when writing to external systems), and cost (fewer-but-larger batches).

### Batch settings

The following batch-level settings can be configured to adjust how Queues delivers batches to your configured consumer.

<table-wrap>

| Setting                                   | Default     | Minimum   | Maximum      |
| ----------------------------------------- | ----------- | --------- | ------------ |
| Maximum Batch Size `max_batch_size`       | 10 messages | 1 message | 100 messages |
| Maximum Batch Timeout `max_batch_timeout` | 5 seconds   | 0 seconds | 60 seconds   |

</table-wrap>

## Explicit acknowledgement and retries

You can acknowledge individual messages within a batch by explicitly acknowledging each message as it is processed. Messages that are explicitly acknowledged will not be re-delivered, even if your queue consumer fails on a subsequent message and/or fails to return successfully when processing a batch.

- Each message can be acknowledged as you process it within a batch, and avoids the entire batch from being re-delivered if your consumer throws an error during batch processing.
- Acknowledging individual messages is useful when you are calling external APIs, writing messages to a database, or otherwise performing non-idempotent (state changing) actions on individual messages.

To explicitly acknowledge a message as delivered, call the `ack()` method on the message.

```ts title="index.js"
export default {
	async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
		for (const msg of batch.messages) {
			// TODO: do something with the message
			// Explicitly acknowledge the message as delivered
			msg.ack();
		}
	},
};
```

You can also call `retry()` to explicitly force a message to be redelivered in a subsequent batch. This is referred to as "negative acknowledgement". This can be particularly useful when you want to process the rest of the messages in that batch without throwing an error that would force the entire batch to be redelivered.

```ts title="index.ts"
export default {
	async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
		for (const msg of batch.messages) {
			// TODO: do something with the message that fails
			msg.retry();
		}
	},
};
```

You can also acknowledge or negatively acknowledge messages at a batch level with `ackAll()` and `retryAll()`. Calling `ackAll()` on the batch of messages (`MessageBatch`) delivered to your consumer Worker has the same behaviour as a consumer Worker that successfully returns (does not throw an error).

Note that calls to `ack()`, `retry()` and their `ackAll()` / `retryAll()` equivalents follow the below precedence rules:

- If you call `ack()` on a message, subsequent calls to `ack()` or `retry()` are silently ignored.
- If you call `retry()` on a message and then call `ack()`: the `ack()` is ignored. The first method call wins in all cases.
- If you call either `ack()` or `retry()` on a single message, and then either/any of `ackAll()` or `retryAll()` on the batch, the call on the single message takes precedence. That is, the batch-level call does not apply to that message (or messages, if multiple calls were made).

## Delivery failure

When a message is failed to be delivered, the default behaviour is to retry delivery three times before marking the delivery as failed. You can set `max_retries` (defaults to 3) when configuring your consumer, but in most cases we recommend leaving this as the default.

Messages that reach the configured maximum retries will be deleted from the queue, or if a [dead-letter queue](/queues/configuration/dead-letter-queues/) (DLQ) is configured, written to the DLQ instead.

:::note

Each retry counts as an additional read operation per [Queues pricing](/queues/platform/pricing/).

:::

When a single message within a batch fails to be delivered, the entire batch is retried, unless you have [explicitly acknowledged](#explicit-acknowledgement-and-retries) a message (or messages) within that batch. For example, if a batch of 10 messages is delivered, but the 8th message fails to be delivered, all 10 messages will be retried and thus redelivered to your consumer in full.

:::caution[Retried messages and consumer concurrency]

Retrying messages with `retry()` or calling `retryAll()` on a batch will **not** cause the consumer to autoscale down if consumer concurrency is enabled. Refer to [Consumer concurrency](/queues/configuration/consumer-concurrency/) to learn more.

:::

## Delay messages

When publishing messages to a queue, or when [marking a message or batch for retry](#explicit-acknowledgement-and-retries), you can choose to delay messages from being processed for a period of time.

Delaying messages allows you to defer tasks until later, and/or respond to backpressure when consuming from a queue. For example, if an upstream API you are calling to returns a `HTTP 429: Too Many Requests`, you can delay messages to slow down how quickly you are consuming them before they are re-processed.

Messages can be delayed by up to 12 hours.

:::note

Configuring delivery and retry delays via the `wrangler` CLI or when [developing locally](/queues/configuration/local-development/) requires `wrangler` version `3.38.0` or greater. Use `npx wrangler@latest` to always use the latest version of `wrangler`.

:::

### Delay on send

To delay a message or batch of messages when sending to a queue, you can provide a `delaySeconds` parameter when sending a message.

```ts
// Delay a singular message by 600 seconds (10 minutes)
await env.YOUR_QUEUE.send(message, { delaySeconds: 600 });

// Delay a batch of messages by 300 seconds (5 minutes)
await env.YOUR_QUEUE.sendBatch(messages, { delaySeconds: 300 });

// Do not delay this message.
// If there is a global delay configured on the queue, ignore it.
await env.YOUR_QUEUE.sendBatch(messages, { delaySeconds: 0 });
```

You can also configure a default, global delay on a per-queue basis by passing `--delivery-delay-secs` when creating a queue via the `wrangler` CLI:

```sh
# Delay all messages by 5 minutes as a default
npx wrangler queues create $QUEUE-NAME --delivery-delay-secs=300
```

### Delay on retry

When [consuming messages from a queue](/queues/reference/how-queues-works/#consumers), you can choose to [explicitly mark messages to be retried](#explicit-acknowledgement-and-retries). Messages can be retried and delayed individually, or as an entire batch.

To delay an individual message within a batch:

```ts title="index.ts"
export default {
	async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
		for (const msg of batch.messages) {
			// Mark for retry and delay a singular message
			// by 3600 seconds (1 hour)
			msg.retry({ delaySeconds: 3600 });
		}
	},
};
```

To delay a batch of messages:

```ts title="index.ts"
export default {
	async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
		// Mark for retry and delay a batch of messages
		// by 600 seconds (10 minutes)
		batch.retryAll({ delaySeconds: 600 });
	},
};
```

You can also choose to set a default retry delay to any messages that are retried due to either implicit failure or when calling `retry()` explicitly. This is set at the consumer level, and is supported in both push-based (Worker) and pull-based (HTTP) consumers.

Delays can be configured via the `wrangler` CLI:

```sh
# Push-based consumers
# Delay any messages that are retried by 60 seconds (1 minute) by default.
npx wrangler@latest queues consumer worker add $QUEUE-NAME $WORKER_SCRIPT_NAME --retry-delay-secs=60

# Pull-based consumers
# Delay any messages that are retried by 60 seconds (1 minute) by default.
npx wrangler@latest queues consumer http add $QUEUE-NAME --retry-delay-secs=60
```

Delays can also be configured in the [Wrangler configuration file](/workers/wrangler/configuration/#queues) with the `delivery_delay` setting for producers (when sending) and/or the `retry_delay` (when retrying) per-consumer:

<WranglerConfig>

```toml title="wrangler.toml"
[[queues.producers]]
  binding = "<BINDING_NAME>"
  queue = "<QUEUE-NAME>"
  delivery_delay = 60 # delay every message delivery by 1 minute

[[queues.consumers]]
  queue = "my-queue"
  retry_delay = 300 # delay any retried message by 5 minutes before re-attempting delivery
```

</WranglerConfig>

If you use both the `wrangler` CLI and the [Wrangler configuration file](/workers/wrangler/configuration/) to change the settings associated with a queue or a queue consumer, the most recent configuration change will take effect.

Refer to the [Queues REST API documentation](/api/resources/queues/subresources/consumers/methods/get/) to learn how to configure message delays and retry delays programmatically.

### Message delay precedence

Messages can be delayed by default at the queue level, or per-message (or batch).

- Per-message/batch delay settings take precedence over queue-level settings.
- Setting `delaySeconds: 0` on a message when sending or retrying will ignore any queue-level delays and cause the message to be delivered in the next batch.
- A message sent or retried with `delaySeconds: <any positive integer>` to a queue with a shorter default delay will still respect the message-level setting.

### Apply a backoff algorithm

You can apply a backoff algorithm to increasingly delay messages based on the current number of attempts to deliver the message.

Each message delivered to a consumer includes an `attempts` property that tracks the number of delivery attempts made.

For example, to generate an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) for a message, you can create a helper function that calculates this for you:

```ts
const calculateExponentialBackoff = (
	attempts: number,
	baseDelaySeconds: number,
) => {
	return baseDelaySeconds ** attempts;
};
```

In your consumer, you then pass the value of `msg.attempts` and your desired delay factor as the argument to `delaySeconds` when calling `retry()` on an individual message:

```ts title="index.ts"
const BASE_DELAY_SECONDS = 30;

export default {
	async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
		for (const msg of batch.messages) {
			// Mark for retry and delay a singular message
			// by 3600 seconds (1 hour)
			msg.retry({
				delaySeconds: calculateExponentialBackoff(
					msg.attempts,
					BASE_DELAY_SECONDS,
				),
			});
		}
	},
};
```

## Related

- Review the [JavaScript API](/queues/configuration/javascript-apis/) documentation for Queues.
- Learn more about [How Queues Works](/queues/reference/how-queues-works/).
- Understand the [metrics available](/queues/observability/metrics/) for your queues, including backlog and delayed message counts.

---

# Consumer concurrency

URL: https://developers.cloudflare.com/queues/configuration/consumer-concurrency/

import { WranglerConfig } from "~/components";

Consumer concurrency allows a [consumer Worker](/queues/reference/how-queues-works/#consumers) processing messages from a queue to automatically scale out horizontally to keep up with the rate that messages are being written to a queue.

In many systems, the rate at which you write messages to a queue can easily exceed the rate at which a single consumer can read and process those same messages. This is often because your consumer might be parsing message contents, writing to storage or a database, or making third-party (upstream) API calls.

Note that queue producers are always scalable, up to the [maximum supported messages-per-second](/queues/platform/limits/) (per queue) limit.

## Enable concurrency

By default, all queues have concurrency enabled. Queue consumers will automatically scale up [to the maximum concurrent invocations](/queues/platform/limits/) as needed to manage a queue's backlog and/or error rates.

## How concurrency works

After processing a batch of messages, Queues will check to see if the number of concurrent consumers should be adjusted. The number of concurrent consumers invoked for a queue will autoscale based on several factors, including:

- The number of messages in the queue (backlog) and its rate of growth.
- The ratio of failed (versus successful) invocations. A failed invocation is when your `queue()` handler returns an uncaught exception instead of `void` (nothing).
- The value of `max_concurrency` set for that consumer.

Where possible, Queues will optimize for keeping your backlog from growing exponentially, in order to minimize scenarios where the backlog of messages in a queue grows to the point that they would reach the [message retention limit](/queues/platform/limits/) before being processed.

:::note[Consumer concurrency and retried messages]

[Retrying messages with `retry()`](/queues/configuration/batching-retries/#explicit-acknowledgement-and-retries) or calling `retryAll()` on a batch will **not** count as a failed invocation.

:::

### Example

If you are writing 100 messages/second to a queue with a single concurrent consumer that takes 5 seconds to process a batch of 100 messages, the number of messages in-flight will continue to grow at a rate faster than your consumer can keep up.

In this scenario, Queues will notice the growing backlog and will scale the number of concurrent consumer Workers invocations up to a steady-state of (approximately) five (5) until the rate of incoming messages decreases, the consumer processes messages faster, or the consumer begins to generate errors.

### Why are my consumers not autoscaling?

If your consumers are not autoscaling, there are a few likely causes:

- `max_concurrency` has been set to 1.
- Your consumer Worker is returning errors rather than processing messages. Inspect your consumer to make sure it is healthy.
- A batch of messages is being processed. Queues checks if it should autoscale consumers only after processing an entire batch of messages, so it will not autoscale while a batch is being processed. Consider reducing batch sizes or refactoring your consumer to process messages faster.

## Limit concurrency

:::caution[Recommended concurrency setting]

Cloudflare recommends leaving the maximum concurrency unset, which will allow your queue consumer to scale up as much as possible. Setting a fixed number means that your consumer will only ever scale up to that maximum, even as Queues increases the maximum supported invocations over time.

:::

If you have a workflow that is limited by an upstream API and/or system, you may prefer for your backlog to grow, trading off increased overall latency in order to avoid overwhelming an upstream system.

You can configure the concurrency of your consumer Worker in two ways:

1. Set concurrency settings in the Cloudflare dashboard
2. Set concurrency settings via the [Wrangler configuration file](/workers/wrangler/configuration/)

### Set concurrency settings in the Cloudflare dashboard

To configure the concurrency settings for your consumer Worker from the dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages** > **Queues**.
3. Select your queue > **Settings**.
4. Select **Edit Consumer** under Consumer details.
5. Set **Maximum consumer invocations** to a value between `1` and `250`. This value represents the maximum number of concurrent consumer invocations available to your queue.

To remove a fixed maximum value, select **auto (recommended)**.

Note that if you are writing messages to a queue faster than you can process them, messages may eventually reach the [maximum retention period](/queues/platform/limits/) set for that queue. Individual messages that reach that limit will expire from the queue and be deleted.

### Set concurrency settings in the [Wrangler configuration file](/workers/wrangler/configuration/)

:::note

Ensure you are using the latest version of [wrangler](/workers/wrangler/install-and-update/). Support for configuring the maximum concurrency of a queue consumer is only supported in wrangler [`2.13.0`](https://github.com/cloudflare/workers-sdk/releases/tag/wrangler%402.13.0) or greater.

:::

To set a fixed maximum number of concurrent consumer invocations for a given queue, configure a `max_concurrency` in your Wrangler file:

<WranglerConfig>

```toml
[[queues.consumers]]
  queue = "my-queue"
  max_concurrency = 1
```

</WranglerConfig>

To remove the limit, remove the `max_concurrency` setting from the `[[queues.consumers]]` configuration for a given queue and call `npx wrangler deploy` to push your configuration update.

    {/* Not yet available but will be very soon

    ### wrangler CLI

    ```sh
    # where `N` is a positive integer between 1 and 250
    wrangler queues consumer update <script-name> --max-concurrency=N
    ```

    To remove the limit and allow Queues to scale your consumer to the maximum number of invocations, call `consumer update` without any flags:

    ```sh
    # Call update without passing a flag to allow concurrency to scale to the maximum
    wrangler queues consumer update <script-name>
    ``` */}

## Billing

When multiple consumer Workers are invoked, each Worker invocation incurs [CPU time costs](/workers/platform/pricing/#workers).

- If you intend to process all messages written to a queue, _the effective overall cost is the same_, even with concurrency enabled.
- Enabling concurrency simply brings those costs forward, and can help prevent messages from reaching the [message retention limit](/queues/platform/limits/).

Billing for consumers follows the [Workers standard usage model](/workers/platform/pricing/#example-pricing) meaning a developer is billed for the request and for CPU time used in the request.

### Example

A consumer Worker that takes 2 seconds to process a batch of messages will incur the same overall costs to process 50 million (50,000,000) messages, whether it does so concurrently (faster) or individually (slower).

---

# Dead Letter Queues

URL: https://developers.cloudflare.com/queues/configuration/dead-letter-queues/

import { WranglerConfig } from "~/components";

A Dead Letter Queue (DLQ) is a common concept in a messaging system, and represents where messages are sent when a delivery failure occurs with a consumer after `max_retries` is reached. A Dead Letter Queue is like any other queue, and can be produced to and consumed from independently.

With Cloudflare Queues, a Dead Letter Queue is defined within your [consumer configuration](/queues/configuration/configure-queues/). Messages are delivered to the DLQ when they reach the configured retry limit for the consumer. Without a DLQ configured, messages that reach the retry limit are deleted permanently.

For example, the following consumer configuration would send messages to our DLQ named `"my-other-queue"` after retrying delivery (by default, 3 times):

<WranglerConfig>

```toml
[[queues.consumers]]
  queue = "my-queue"
  dead_letter_queue = "my-other-queue"
```

</WranglerConfig>

You can also configure a DLQ when creating a consumer from the command-line using `wrangler`:

```sh
wrangler queues consumer add $QUEUE_NAME $SCRIPT_NAME --dead-letter-queue=$NAME_OF_OTHER_QUEUE
```

To process messages placed on your DLQ, you need to [configure a consumer](/queues/configuration/configure-queues/) for that queue as you would with any other queue.

Messages delivered to a DLQ without an active consumer will persist for four (4) days before being deleted from the queue.

---

# Configuration

URL: https://developers.cloudflare.com/queues/configuration/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# JavaScript APIs

URL: https://developers.cloudflare.com/queues/configuration/javascript-apis/

import { Type } from "~/components";

Cloudflare Queues is integrated with [Cloudflare Workers](/workers). To send and receive messages, you must use a Worker.

A Worker that can send messages to a Queue is a producer Worker, while a Worker that can receive messages from a Queue is a consumer Worker. It is possible for the same Worker to be a producer and consumer, if desired.

In the future, we expect to support other APIs, such as HTTP endpoints to send or receive messages. To report bugs or request features, go to the [Cloudflare Community Forums](https://community.cloudflare.com/c/developers/workers/40). To give feedback, go to the [`#queues`](https://discord.cloudflare.com) Discord channel.

## Producer

These APIs allow a producer Worker to send messages to a Queue.

An example of writing a single message to a Queue:

```ts
type Environment = {
  readonly MY_QUEUE: Queue;
};

export default {
  async fetch(req: Request, env: Environment): Promise<Response> {
    await env.MY_QUEUE.send({
      url: req.url,
      method: req.method,
      headers: Object.fromEntries(req.headers),
    });
    return new Response('Sent!');
  },
};
```

The Queues API also supports writing multiple messages at once:

```ts
const sendResultsToQueue = async (results: Array<any>, env: Environment) => {
  const batch: MessageSendRequest[] = results.map((value) => ({
    body: JSON.stringify(value),
  }));
  await env.queue.sendBatch(batch);
};
```

### `Queue`

A binding that allows a producer to send messages to a Queue.

```ts
interface Queue<Body = unknown> {
  send(body: Body, options?: QueueSendOptions): Promise<void>;
  sendBatch(messages: Iterable<MessageSendRequest<Body>>, options?: QueueSendBatchOptions): Promise<void>;
}
```



* `send(bodyunknown, options?{ contentType?: QueuesContentType })` <Type text="Promise<void>" />

  * Sends a message to the Queue. The body can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types), as long as its size is less than 128 KB.
  * When the promise resolves, the message is confirmed to be written to disk.

* `sendBatch(bodyIterable<MessageSendRequest<unknown>>)` <Type text="Promise<void>" />

  * Sends a batch of messages to the Queue. Each item in the provided [Iterable](https://www.typescriptlang.org/docs/handbook/iterators-and-generators.html) must be supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types). A batch can contain up to 100 messages, though items are limited to 128 KB each, and the total size of the array cannot exceed 256 KB.
  * When the promise resolves, the messages are confirmed to be written to disk.



### `MessageSendRequest`

A wrapper type used for sending message batches.

```ts
type MessageSendRequest<Body = unknown> = {
  body: Body;
  options?: QueueSendOptions;
};
```



* <code>body</code> <Type text="unknown" />

  * The body of the message.
  * The body can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types), as long as its size is less than 128 KB.

* <code>options</code> <Type text="QueueSendOptions" />

  * Options to apply to the current message, including content type and message delay settings.



### `QueueSendOptions`

Optional configuration that applies when sending a message to a queue.

* <code>contentType</code> <Type text="QueuesContentType" />

  * The explicit content type of a message so it can be previewed correctly with the [List messages from the dashboard](/queues/examples/list-messages-from-dash/) feature. Optional argument.
  * As of now, this option is for internal use. In the future, `contentType` will be used by alternative consumer types to explicitly mark messages as serialized so they can be consumed in the desired type.
  * See [QueuesContentType](#queuescontenttype) for possible values.

* <code>delaySeconds</code> <Type text="number" />

  * The number of seconds to [delay a message](/queues/configuration/batching-retries/) for within the queue, before it can be delivered to a consumer.
  * Must be an integer between 0 and 43200 (12 hours). Setting this value to zero will explicitly prevent the message from being delayed, even if there is a global (default) delay at the queue level.

### `QueueSendBatchOptions`

Optional configuration that applies when sending a batch of messages to a queue.

* <code>delaySeconds</code> <Type text="number" />

  * The number of seconds to [delay messages](/queues/configuration/batching-retries/) for within the queue, before it can be delivered to a consumer.
  * Must be a positive integer.

### `QueuesContentType`

A union type containing valid message content types.

```ts
// Default: json
type QueuesContentType = "text" | "bytes" | "json" | "v8";
```

* Use `"json"` to send a JavaScript object that can be JSON-serialized. This content type can be previewed from the [Cloudflare dashboard](https://dash.cloudflare.com). The `json` content type is the default.
* Use `"text"` to send a `String`. This content type can be previewed with the [List messages from the dashboard](/queues/examples/list-messages-from-dash/) feature.
* Use `"bytes"` to send an `ArrayBuffer`. This content type cannot be previewed from the [Cloudflare dashboard](https://dash.cloudflare.com) and will display as Base64-encoded.
* Use `"v8"` to send a JavaScript object that cannot be JSON-serialized but is supported by [structured clone](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types) (for example `Date` and `Map`). This content type cannot be previewed from the [Cloudflare dashboard](https://dash.cloudflare.com) and will display as Base64-encoded.

:::note


The default content type for Queues changed to `json` (from `v8`) to improve compatibility with pull-based consumers for any Workers with a [compatibility date](/workers/configuration/compatibility-flags/#queues-send-messages-in-json-format) after `2024-03-18`.


:::

If you specify an invalid content type, or if your specified content type does not match the message content's type, the send operation will fail with an error.

## Consumer

These APIs allow a consumer Worker to consume messages from a Queue.

To define a consumer Worker, add a `queue()` function to the default export of the Worker. This will allow it to receive messages from the Queue.

By default, all messages in the batch will be acknowledged as soon as all of the following conditions are met:

1. The `queue()` function has returned.
2. If the `queue()` function returned a promise, the promise has resolved.
3. Any promises passed to `waitUntil()` have resolved.

If the `queue()` function throws, or the promise returned by it or any of the promises passed to `waitUntil()` were rejected, then the entire batch will be considered a failure and will be retried according to the consumer's retry settings.

:::note


`waitUntil()` is the only supported method to run tasks (such as logging or metrics calls) that resolve after a queue handler has completed. Promises that have not resolved by the time the queue handler returns may not complete and will not block completion of execution.


:::

```ts
export default {
  async queue(
    batch: MessageBatch,
    env: Environment,
    ctx: ExecutionContext
  ): Promise<void> {
    for (const message of batch.messages) {
      console.log('Received', message);
    }
  },
};
```

The `env` and `ctx` fields are as [documented in the Workers documentation](/workers/reference/migrate-to-module-workers/).

Or alternatively, a queue consumer can be written using the (deprecated) service worker syntax:

```js
addEventListener('queue', (event) => {
	event.waitUntil(handleMessages(event));
});
```

In service worker syntax, `event` provides the same fields and methods as `MessageBatch`, as defined below, in addition to [`waitUntil()`](https://developer.mozilla.org/en-US/docs/Web/API/ExtendableEvent/waitUntil).

:::note


When performing asynchronous tasks in your queue handler that iterates through messages, use an asynchronous version of iterating through your messages. For example, `for (const m of batch.messages)`or `await Promise.all(batch.messages.map(work))` allow for waiting for the results of asynchronous calls. `batch.messages.forEach()` does not.


:::

### `MessageBatch`

A batch of messages that are sent to a consumer Worker.

```ts
interface MessageBatch<Body = unknown> {
  readonly queue: string;
  readonly messages: Message<Body>[];
  ackAll(): void;
  retryAll(options?: QueueRetryOptions): void;
}
```



* <code>queue</code> <Type text="string" />

  * The name of the Queue that belongs to this batch.

* <code>messages</code> <Type text="Message[]" />

  * An array of messages in the batch. Ordering of messages is best effort -- not guaranteed to be exactly the same as the order in which they were published. If you are interested in guaranteed FIFO ordering, please [email the Queues team](mailto:queues@cloudflare.com).

* <code>ackAll()</code> <Type text="void" />


  * Marks every message as successfully delivered, regardless of whether your `queue()` consumer handler returns successfully or not.

* <code>retryAll(options?: QueueRetryOptions)</code> <Type text="void" />

  * Marks every message to be retried in the next batch.
  * Supports an optional `options` object.



### `Message`

A message that is sent to a consumer Worker.

```ts
interface Message<Body = unknown> {
  readonly id: string;
  readonly timestamp: Date;
  readonly body: Body;
	readonly attempts: number;
  ack(): void;
  retry(options?: QueueRetryOptions): void;
}
```



* <code>id</code> <Type text="string" />

  * A unique, system-generated ID for the message.

* <code>timestamp</code> <Type text="Date" />

  * A timestamp when the message was sent.

* <code>body</code> <Type text="unknown" />

  * The body of the message.
  * The body can be any type supported by the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types), as long as its size is less than 128 KB.

* <code>attempts</code> <Type text="number" />

	* The number of times the consumer has attempted to process this message. Starts at 1.

* <code>ack()</code> <Type text="void" />

  * Marks a message as successfully delivered, regardless of whether your `queue()` consumer handler returns successfully or not.

* <code>retry(options?: QueueRetryOptions)</code> <Type text="void" />

  * Marks a message to be retried in the next batch.
  * Supports an optional `options` object.



### `QueueRetryOptions`

Optional configuration when marking a message or a batch of messages for retry.

```ts
interface QueueRetryOptions {
  delaySeconds?: number;
}
```

* <code>delaySeconds</code> <Type text="number" />

  * The number of seconds to [delay a message](/queues/configuration/batching-retries/) for within the queue, before it can be delivered to a consumer.
  * Must be a positive integer.

---

# Local Development

URL: https://developers.cloudflare.com/queues/configuration/local-development/

Queues support local development workflows using [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Workers. Wrangler runs the same version of Queues as Cloudflare runs globally.

## Prerequisites

To develop locally with Queues, you will need:

- [Wrangler v3.1.0](https://blog.cloudflare.com/wrangler3/) or later.

- Node.js version of `18.0.0` or later. Consider using a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change Node versions.

- If you are new to Queues and/or Cloudflare Workers, refer to the [Queues tutorial](/queues/get-started/) to install `wrangler` and deploy their first Queue.

## Start a local development session

Open your terminal and run the following commands to start a local development session:
```sh
npx wrangler@latest dev
```

```sh output
------------------
Your Worker and resources are simulated locally via Miniflare. For more information, see: https://developers.cloudflare.com/workers/testing/local-development.

Your worker has access to the following bindings:
- Queues: <QUEUE-NAME>
```

Local development sessions create a standalone, local-only environment that mirrors the production environment Queues runs in so you can test your Workers _before_ you deploy to production.

Refer to the [`wrangler dev` documentation](/workers/wrangler/commands/#dev) to learn more about how to configure a local development session.

## Separating producer & consumer Workers
Wrangler supports running multiple Workers simultaneously with a single command. If your architecture separates the producer and consumer into distinct Workers, you can use this functionality to test the entire message flow locally.

:::caution
Support for running multiple Workers at once with one Wrangler command is experimental, and subject to change as we work on the experience. If you run into bugs or have any feedback, [open an issue on the workers-sdk repository](https://github.com/cloudflare/workers-sdk/issues/new)
:::

For example, if your project has the following directory structure: 
```
producer-worker/
├── wrangler.jsonc
├── index.ts
└── consumer-worker/
    ├── wrangler.jsonc
    └── index.ts
```

You can start development servers for both workers with the following command:
```sh
npx wrangler@latest dev -c wrangler.jsonc -c consumer-worker/wrangler.jsonc --persist-to .wrangler/state
```

When the producer Worker sends messages to the queue, the consumer Worker will automatically be invoked to handle them.
:::note
[Consumer concurrency](/queues/configuration/consumer-concurrency/) is not supported while running locally.
:::

## Known Issues
- Queues does not support Wrangler remote mode (`wrangler dev --remote`).

---

# Pause and Purge

URL: https://developers.cloudflare.com/queues/configuration/pause-purge/

import { WranglerConfig, Type, MetaInfo } from "~/components";

## Pause Delivery

You can pause delivery of messages from your queue to any connected consumers. Pausing a queue is useful when managing downtime (for example, if your consumer Worker is unhealthy) without losing any messages.

Queues continue to receive and store messages even while delivery is paused. Messages in a paused queue are still subject to expiry, if the messages become older than the queue message retention period.

Pausing affects both [push-based consumer Workers](/queues/reference/how-queues-works#consumers) and [pull based consumers](/queues/configuration/pull-consumers).

### Pause and resume delivery using Wrangler

The following command will pause message delivery from your queue:

```sh
$ npx run wrangler queues pause-delivery <QUEUE-NAME>
```

- `queue-name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the queue for which delivery should be paused.

The following command will resume message delivery:

```sh
$ npx run wrangler queues resume-delivery <QUEUE-NAME>
```

- `queue-name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the queue for which delivery should be resumed.

### What happens to HTTP Pull consumers with a paused queue?
When a queue is paused, messages cannot be pulled by an [HTTP pull based consumer](/queues/configuration/pull-consumers). Requests to pull messages will receive a `409` response, along with an error message stating `queue_delivery_paused`.

## Purge queue
Purging a queue permanently deletes any messages currently stored in the Queue. Purging is useful while developing a new application, especially to clear out any test data. It can also be useful in production to handle scenarios when a batch of bad messages have been sent to a Queue.

Note that any in flight messages, which are currently being processed by consumers, might still be processed. Messages sent to a queue during a purge operation might not be purged. Any delayed messages will also be deleted from the queue.

:::caution
Purging a queue is an irreversible operation. Make sure to use this operation carefully.
:::

### Purge queue using Wrangler
The following command will purge messages from your queue. You will be prompted to enter the queue name to confirm the operation.
```sh
$ npx run wrangler queues purge <QUEUE-NAME>

This operation will permanently delete all the messages in Queue <QUEUE-NAME>. Type <QUEUE-NAME> to proceed.
```

### Does purging a Queue affect my bill?
Purging a queue counts as a single billable operation, regardless of how many messages are deleted. For example, if you purge a queue which has 100 messages, all 100 messages will be permanently deleted, and you will be billed for 1 billable operation. Refer to the [pricing](/queues/platform/pricing) page for more information about how Queues is billed.

---

# Pull consumers

URL: https://developers.cloudflare.com/queues/configuration/pull-consumers/

import { WranglerConfig } from "~/components";

A pull-based consumer allows you to pull from a queue over HTTP from any environment and/or programming language outside of Cloudflare Workers. A pull-based consumer can be useful when your message consumption rate is limited by upstream infrastructure or long-running tasks.

## How to choose between push or pull consumer

Deciding whether to configure a push-based consumer or a pull-based consumer will depend on how you are using your queues, as well as the configuration of infrastructure upstream from your queue consumer.

- **Starting with a [push-based consumer](/queues/reference/how-queues-works/#consumers) is the easiest way to get started and consume from a queue**. A push-based consumer runs on Workers, and by default, will automatically scale up and consume messages as they are written to the queue.
- Use a pull-based consumer if you need to consume messages from existing infrastructure outside of Cloudflare Workers, and/or where you need to carefully control how fast messages are consumed. A pull-based consumer must explicitly make a call to pull (and then acknowledge) messages from the queue, only when it is ready to do so.

You can remove and attach a new consumer on a queue at any time, allowing you to change from a pull-based to a push-based consumer if your requirements change.

:::note[Retrieve an API bearer token]

To configure a pull-based consumer, create [an API token](/fundamentals/api/get-started/create-token/) with both the `queues#read` and `queues#write` permissions. A consumer must be able to write to a queue to acknowledge messages.

:::

To configure a pull-based consumer and receive messages from a queue, you need to:

1. Enable HTTP pull for the queue.
2. Create a valid authentication token for the HTTP client.
3. Pull message batches from the queue.
4. Acknowledge and/or retry messages within a batch.

## 1. Enable HTTP pull

You can enable HTTP pull or change a queue from push-based to pull-based via the [Wrangler configuration file](/workers/wrangler/configuration/), the `wrangler` CLI, or via the [Cloudflare dashboard](https://dash.cloudflare.com/).

### Wrangler configuration file

A HTTP consumer can be configured in the [Wrangler configuration file](/workers/wrangler/configuration/) by setting `type = "http_pull"` in the consumer configuration:

<WranglerConfig>

```toml
[[queues.consumers]]
# Required
queue = "QUEUE-NAME"
type = "http_pull"
# Optional
visibility_timeout_ms = 5000
max_retries = 5
dead_letter_queue = "SOME-OTHER-QUEUE"
```

</WranglerConfig>

Omitting the `type` property will default the queue to push-based.

### wrangler CLI

You can enable a pull-based consumer on any existing queue by using the `wrangler queues consumer http` sub-commands and providing a queue name.

```sh
npx wrangler queues consumer http add $QUEUE-NAME
```

If you have an existing push-based consumer, you will need to remove that first. `wrangler` will return an error if you attempt to call `consumer http add` on a queue with an existing consumer configuration:

```sh
wrangler queues consumer worker remove $QUEUE-NAME $SCRIPT_NAME
```

:::note

If you remove the Worker consumer with `wrangler` but do not delete the `[[queues.consumer]]` configuration from your [Wrangler configuration file](/workers/wrangler/configuration/), subsequent deployments of your Worker will fail when they attempt to add a conflicting consumer configuration.

Ensure you remove the consumer configuration first.

:::

## 2. Consumer authentication

HTTP Pull consumers require an [API token](/fundamentals/api/get-started/create-token/) with the `com.cloudflare.api.account.queues_read` and `com.cloudflare.api.account.queues_write` permissions.

Both read _and_ write are required as a pull-based consumer needs to write to the queue state to acknowledge the messages it receives. Consuming messages mutates the queue.

API tokens are presented as Bearer tokens in the `Authorization` header of a HTTP request in the format `Authorization: Bearer $YOUR_TOKEN_HERE`. The following example shows how to pass an API token using the `curl` HTTP client:

```bash
curl "https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/queues/${QUEUE_ID}/messages/pull" \
--header "Authorization: Bearer ${QUEUES_TOKEN}" \
--header "Content-Type: application/json" \
--data '{ "visibility_timeout": 10000, "batch_size": 2 }'
```

You may authenticate and run multiple concurrent pull-based consumers against a single queue.

### Create API tokens

To create an API token:

1. Go to the API tokens page of the [Cloudflare dashboard](https://dash.cloudflare.com/profile/api-tokens/).
2. Select **Create Token**.
3. Scroll to the bottom of the page and select **Create Custom Token**.
4. Give the token a name. For example, `queue-pull-token`.
5. Under the **Permissions** section, choose **Account** and then **Queues**. Ensure you have selected **Edit** (read+write).
6. (Optional) Select **All accounts** (default) or a specific account to scope the token to.
7. Select **Continue to summary** and then **Create token**.

You will need to note the token down: it will only be displayed once.

## 3. Pull messages

To pull a message, make a HTTP POST request to the [Queues REST API](/api/resources/queues/subresources/messages/methods/pull/) with a JSON-encoded body that optionally specifies a `visibility_timeout` and a `batch_size`, or an empty JSON object (`{}`):

```ts
// POST /accounts/${CF_ACCOUNT_ID}/queues/${QUEUE_ID}/messages/pull with the timeout & batch size
let resp = await fetch(
	`https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/queues/${QUEUE_ID}/messages/pull`,
	{
		method: "POST",
		headers: {
			"content-type": "application/json",
			authorization: `Bearer ${QUEUES_API_TOKEN}`,
		},
		// Optional - you can provide an empty object '{}' and the defaults will apply.
		body: JSON.stringify({ visibility_timeout_ms: 6000, batch_size: 50 }),
	},
);
```

This will return an array of messages (up to the specified `batch_size`) in the below format:

```json
{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"message_backlog_count": 10,
		"messages": [
			{
				"body": "hello",
				"id": "1ad27d24c83de78953da635dc2ea208f",
				"timestamp_ms": 1689615013586,
				"attempts": 2,
				"metadata":{
					"CF-sourceMessageSource":"dash",
					"CF-Content-Type":"json"
        },
				"lease_id": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIn0..NXmbr8h6tnKLsxJ_AuexHQ.cDt8oBb_XTSoKUkVKRD_Jshz3PFXGIyu7H1psTO5UwI.smxSvQ8Ue3-ymfkV6cHp5Va7cyUFPIHuxFJA07i17sc"
			},
			{
				"body": "world",
				"id": "95494c37bb89ba8987af80b5966b71a7",
				"timestamp_ms": 1689615013586,
				"attempts": 2,
				"metadata":{
					"CF-sourceMessageSource":"dash",
					"CF-Content-Type":"json"
        },
				"lease_id": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIn0..QXPgHfzETsxYQ1Vd-H0hNA.mFALS3lyouNtgJmGSkTzEo_imlur95EkSiH7fIRIn2U.PlwBk14CY_EWtzYB-_5CR1k30bGuPFPUx1Nk5WIipFU"
			}
		]
	}
}
```

Pull consumers follow a "short polling" approach: if there are messages available to be delivered, Queues will return a response immediately with messages up to the configured `batch_size`. If there are no messages to deliver, Queues will return an empty response. Queues does not hold an open connection (often referred to as "long polling") if there are no messages to deliver.

:::note

The [`pull`](/api/resources/queues/subresources/messages/methods/pull/) and [`ack`](/api/resources/queues/subresources/messages/methods/ack/) endpoints use the new `/queues/queue_id/messages/{action}` API format, as defined in the Queues API documentation.

The undocumented `/queues/queue_id/{action}` endpoints are not supported and will be deprecated as of June 30th, 2024.

:::

Each message object has five fields:

1. `body` - this may be base64 encoded based on the [content-type the message was published as](#content-types).
2. `id` - a unique, read-only ephemeral identifier for the message.
3. `timestamp_ms` - when the message was published to the queue in milliseconds since the [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). This allows you to determine how old a message is by subtracting it from the current timestamp.
4. `attempts` - how many times the message has been attempted to be delivered in full. When this reaches the value of `max_retries`, the message will not be re-delivered and will be deleted from the queue permanently.
5. `lease_id` - the encoded lease ID of the message. The `lease_id` is used to explicitly acknowledge or retry the message.

The `lease_id` allows your pull consumer to explicitly acknowledge some, none or all messages in the batch or mark them for retry. If messages are not acknowledged or marked for retry by the consumer, then they will be marked for re-delivery once the `visibility_timeout` is reached. A `lease_id` is no longer valid once this timeout has been reached.

You can configure both `batch_size` and `visibility_timeout` when pulling from a queue:

- `batch_size` (defaults to 5; max 100) - how many messages are returned to the consumer in each pull.
- `visibility_timeout` (defaults to 30 second; max 12 hours) - defines how long the consumer has to explicitly acknowledge messages delivered in the batch based on their `lease_id`. Once this timeout expires, messages are assumed unacknowledged and queued for re-delivery again.

### Concurrent consumers

You may have multiple HTTP clients pulling from the same queue concurrently: each client will receive a unique batch of messages and retain the "lease" on those messages up until the `visibility_timeout` expires, or until those messages are marked for retry.

Messages marked for retry will be put back into the queue and can be delivered to any consumer. Messages are _not_ tied to a specific consumer, as consumers do not have an identity and to avoid a slow or stuck consumer from holding up processing of messages in a queue.

Multiple consumers can be useful in cases where you have multiple upstream resources (for example, GPU infrastructure), where you want to autoscale based on the [backlog](/queues/observability/metrics/) of a queue, and/or cost.

## 4. Acknowledge messages

Messages pulled by a consumer need to be either acknowledged or marked for retry.

To acknowledge and/or mark messages to be retried, make a HTTP `POST` request to `/ack` endpoint of your queue per the [Queues REST API](/api/resources/queues/subresources/messages/methods/ack/) by providing an array of `lease_id` objects to acknowledge and/or retry:

```ts
// POST /accounts/${CF_ACCOUNT_ID}/queues/${QUEUE_ID}/messages/ack with the lease_ids
let resp = await fetch(
	`https://api.cloudflare.com/client/v4/accounts/${CF_ACCOUNT_ID}/queues/${QUEUE_ID}/messages/ack`,
	{
		method: "POST",
		headers: {
			"content-type": "application/json",
			authorization: `Bearer ${QUEUES_API_TOKEN}`,
		},
		// If you have no messages to retry, you can specify an empty array - retries: []
		body: JSON.stringify({
			acks: [
				{ lease_id: "lease_id1" },
				{ lease_id: "lease_id2" },
				{ lease_id: "etc" },
			],
			retries: [{ lease_id: "lease_id4" }],
		}),
	},
);
```

You may optionally specify the number of seconds to delay a message for when marking it for retry by providing a `{ lease_id: string, delay_seconds: number }` object in the `retries` array:

```json
{
	"acks": [
		{ "lease_id": "lease_id1" },
		{ "lease_id": "lease_id2" },
		{ "lease_id": "lease_id3" }
	],
	"retries": [{ "lease_id": "lease_id4", "delay_seconds": 600 }]
}
```

Additionally:

- You should provide every `lease_id` in the request to the `/ack` endpoint if you are processing those messages in your consumer. If you do not acknowledge a message, it will be marked for re-delivery (put back in the queue).
- You can optionally mark messages to be retried: for example, if there is an error processing the message or you have upstream resource pressure. Explicitly marking a message for retry will place it back into the queue immediately, instead of waiting for a (potentially long) `visibility_timeout` to be reached.
- You can make multiple calls to the `/ack` endpoint as you make progress through a batch of messages, but we recommend grouping acknowledgements to reduce the number of API calls required.

Queues aims to be permissive when it comes to lease IDs: if a consumer acknowledges a message by its lease ID _after_ the visibility timeout is reached, Queues will still accept that acknowledgment. If the message was delivered to another consumer during the intervening period, it will also be able to acknowledge the message without an error.

    {/* <!--

	## Examples

	### TypeScript (Node.js)

	The following example is a Node.js-based TypeScript application that pulls from a queue on startup, acknowledges messages after writing them to stdout, and polls the queue at a fixed interval.

	In a production application, you could replace writing to stdout with inserting into a database, making HTTP requests to an upstream service, or writing to object storage.

	```ts

	```

	### Go

	The following example is a Go application that pulls from a queue on startup, acknowledges messages after writing them to stdout, and polls the queue at a fixed interval.

	```go


	```

	--> */}

## Content types

:::caution

When attaching a pull-based consumer to a queue, you should ensure that messages are sent with only a `text`, `bytes` or `json` [content type](/queues/configuration/javascript-apis/#queuescontenttype).

The default content type is `json`.

Pull-based consumers cannot decode the `v8` content type as it is specific to the Workers runtime.

:::

When publishing to a queue that has an external consumer, you should be aware that certain content types may be encoded in a way that allows them to be safely serialized within a JSON object.

For both the `json` and `bytes` content types, this means that they will be base64-encoded ([RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648)). The `text` type will be sent as a plain UTF-8 encoded string.

Your consumer will need to decode the `json` and `bytes` types before operating on the data.

## Next steps

- Review the [REST API documentation](/api/resources/queues/subresources/consumers/methods/create/) and schema for Queues.
- Learn more about [how to make API calls](/fundamentals/api/how-to/make-api-calls/) to the Cloudflare API.
- Understand [what limit apply](/queues/platform/limits/) when consuming and writing to a queue.

---

# Examples

URL: https://developers.cloudflare.com/queues/examples/

import { ListExamples } from "~/components";

<ListExamples directory="queues/examples/" />

---

# List and acknowledge messages from the dashboard

URL: https://developers.cloudflare.com/queues/examples/list-messages-from-dash/

## List messages from the dashboard

Listing messages from the dashboard allows you to debug Queues or queue producers without a consumer Worker. Fetching a batch of messages to preview will not acknowledge or retry the message or affect its position in the queue. The queue can still be consumed normally by a consumer Worker.

To list messages in the dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages** > **Queues**.
3. Select the queue to preview messages from.
4. Select the **Messages** tab.
5. Select **Queued Messages**.
6. Select a maximum batch size of messages to fetch. The size can be a number from 1 to 100. If a consumer Worker is configured, this defaults to your consumer Worker's maximum batch size.

![A form to configure how many messages are listed at a time, with a number input showing '10'](~/assets/images/queues/examples/fetch-message-batch-size.png)

7. Select **List messages**.
8. When the list of messages loads, select the blue arrow to the right of each row to expand the message preview.

![A table showing two previewed messages, one text and one JSON, both with some placeholder text](~/assets/images/queues/examples/fetched-messages.png)

This will preview a batch of messages currently in the Queue.

## Acknowledge messages from the dashboard

Acknowledging messages from the [Cloudflare dashboard](https://dash.cloudflare.com) will permanently remove them from the queue, with equivalent behavior as `ack()` in a Worker.

1. Select the checkbox to the left of each row to select the message for acknowledgement, or select the checkbox in the table header to select all messages.
2. Select **Acknowledge messages**.
3. Confirm you want to acknowledge the messages, and select **Acknowledge messages**.

This will remove the selected messages from the queue and prevent consumers from processing them further.

Refer to the [Get Started guide](/queues/get-started/) to learn how to process and acknowledge messages from a queue in a Worker.

---

# Publish to a Queue via HTTP

URL: https://developers.cloudflare.com/queues/examples/publish-to-a-queue-over-http/

import { WranglerConfig } from "~/components";

The following example shows you how to publish messages to a queue from any HTTP client, using a shared secret to securely authenticate the client.

This allows you to write to a Queue from any service or programming language that support HTTP, including Go, Rust, Python or even a Bash script.

### Prerequisites

- A [queue created](/queues/get-started/#3-create-a-queue) via the [Cloudflare dashboard](https://dash.cloudflare.com) or the [wrangler CLI](/workers/wrangler/install-and-update/).
- A [configured **producer** binding](/queues/configuration/configure-queues/#producer-worker-configuration) in the Cloudflare dashboard or Wrangler file.

Configure your Wrangler file as follows:

<WranglerConfig>

```toml
name = "my-worker"

[[queues.producers]]
  queue = "my-queue"
  binding = "YOUR_QUEUE"

```

</WranglerConfig>

### 1. Create a shared secret

Before you deploy the Worker, you need to create a [secret](/workers/configuration/secrets/) that you can use as a shared secret. A shared secret is a secret that both the client uses to authenticate and the server (your Worker) matches against for authentication.

:::caution

Do not commit secrets to source control. You should use [`wrangler secret`](/workers/configuration/secrets/) to store API keys and authentication tokens securely.

:::

To generate a cryptographically secure secret, you can use the `openssl` command-line tool and `wrangler secret` to create a hex-encoded string that can be used as the shared secret:

```sh
openssl rand -hex 32
# This will output a 65 character long hex string
```

Copy this string and paste it into the prompt for `wrangler secret`:

```sh
npx wrangler secret put QUEUE_AUTH_SECRET
```

```sh output
✨ Success! Uploaded secret QUEUE_AUTH_SECRET
```

This secret will also need to be used by the client application writing to the queue: ensure you store it securely.

### 2. Create the Worker

The following Worker script:

1. Authenticates the client using a shared secret.
2. Validates that the payload uses JSON.
3. Publishes the payload to the queue.

```ts
interface Env {
	YOUR_QUEUE: Queue;
	QUEUE_AUTH_SECRET: string;
}

export default {
	async fetch(req, env): Promise<Response> {
		// Authenticate that the client has the correct auth key
		if (env.QUEUE_AUTH_SECRET == "") {
			return Response.json(
				{ err: "application not configured" },
				{ status: 500 },
			);
		}

		// Return a HTTP 403 (Forbidden) if the auth key is invalid/incorrect/misconfigured
		let authToken = req.headers.get("Authorization") || "";
		let encoder = new TextEncoder();
		// Securely compare our secret with the auth token provided by the client
		try {
			if (
				!crypto.subtle.timingSafeEqual(
					encoder.encode(env.QUEUE_AUTH_SECRET),
					encoder.encode(authToken),
				)
			) {
				return Response.json(
					{ err: "invalid auth token provided" },
					{ status: 403 },
				);
			}
		} catch (e) {
			return Response.json(
				{ err: "invalid auth token provided" },
				{ status: 403 },
			);
		}

		// Optional: Validate the payload is JSON
		// In a production application, we may more robustly validate the payload
		// against a schema using a library like 'zod'
		let messages;
		try {
			messages = await req.json();
		} catch (e) {
			// Return a HTTP 400 (Bad Request) if the payload isn't JSON
			return Response.json({ err: "payload not valid JSON" }, { status: 500 });
		}

		// Publish to the Queue
		try {
			await env.YOUR_QUEUE.send(messages);
		} catch (e: any) {
			console.log(`failed to send to the queue: ${e}`);
			// Return a HTTP 500 (Internal Error) if our publish operation fails
			return Response.json({ error: e.message }, { status: 500 });
		}

		// Return a HTTP 200 if the send succeeded!
		return Response.json({ success: true });
	},
} satisfies ExportedHandler<Env>;
```

To deploy this Worker:

```sh
npx wrangler deploy
```

### 3. Send a test message

To make sure you successfully authenticate and write a message to your queue, use `curl` on the command line:

```sh
# Make sure to replace the placeholder with your shared secret
curl -H "Authorization: pasteyourkeyhere" "https://YOUR_WORKER.YOUR_ACCOUNT.workers.dev" --data '{"messages": [{"msg":"hello world"}]}'
```

```sh output
{"success":true}
```

This will issue a HTTP POST request, and if successful, return a HTTP 200 with a `success: true` response body.

- If you receive a HTTP 403, this is because the `Authorization` header is invalid, or you did not configure a secret.
- If you receive a HTTP 500, this is either because you did not correctly create a shared secret to your Worker, or you attempted to send an invalid message to your queue.

You can use [`wrangler tail`](/workers/observability/logs/real-time-logs/) to debug the output of `console.log`.

---

# Use Queues to store data in R2

URL: https://developers.cloudflare.com/queues/examples/send-errors-to-r2/

import { WranglerConfig } from "~/components";

The following Worker will catch JavaScript errors and send them to a queue. The same Worker will receive those errors in batches and store them to a log file in an R2 bucket.

<WranglerConfig>

```toml
name = "my-worker"

[[queues.producers]]
  queue = "my-queue"
  binding = "ERROR_QUEUE"

[[queues.consumers]]
  queue = "my-queue"
  max_batch_size = 100
  max_batch_timeout = 30

[[r2_buckets]]
  bucket_name = "my-bucket"
  binding = "ERROR_BUCKET"
```

</WranglerConfig>

```ts
type Environment = {
	readonly ERROR_QUEUE: Queue<Error>;
	readonly ERROR_BUCKET: R2Bucket;
};

export default {
  async fetch(req, env): Promise<Response> {
    try {
      return doRequest(req);
    } catch (error) {
      await env.ERROR_QUEUE.send(error);
      return new Response(error.message, { status: 500 });
    }
  },
  async queue(batch, env): Promise<void> {
    let file = '';
    for (const message of batch.messages) {
      const error = message.body;
      file += error.stack || error.message || String(error);
      file += '\r\n';
    }
    await env.ERROR_BUCKET.put(`errors/${Date.now()}.log`, file);
  },
} satisfies ExportedHandler<Environment, Error>;

function doRequest(request: Request): Promise<Response> {
  if (Math.random() > 0.5) {
    return new Response('Success!');
  }
  throw new Error('Failed!');
}
```

---

# Send messages from the dashboard

URL: https://developers.cloudflare.com/queues/examples/send-messages-from-dash/

Sending messages from the dashboard allows you to debug Queues or queue consumers without a producer Worker.

To send messages from the dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages** > **Queues**.
3. Select the queue to send a message to.
4. Select the **Messages** tab.
5. Select **Send message**.
6. Enter your message. You can choose your message content type by selecting the **Text** or **JSON** tabs. Alternatively, select the **Upload a file** button or drag a file over the textbox to upload a file as a message.
7. Select **Send message**.

Your message will be sent to the queue.

Refer to the [Get Started guide](/queues/get-started/) to learn how to send messages to a queue from a Worker.

---

# Use Queues from Durable Objects

URL: https://developers.cloudflare.com/queues/examples/use-queues-with-durable-objects/

import { WranglerConfig } from "~/components";

The following example shows you how to write a Worker script to publish to [Cloudflare Queues](/queues/) from within a [Durable Object](/durable-objects/).

Prerequisites:

- A [queue created](/queues/get-started/#3-create-a-queue) via the Cloudflare dashboard or the [wrangler CLI](/workers/wrangler/install-and-update/).
- A [configured **producer** binding](/queues/configuration/configure-queues/#producer-worker-configuration) in the Cloudflare dashboard or Wrangler file.
- A [Durable Object namespace binding](/workers/wrangler/configuration/#durable-objects).

Configure your Wrangler file as follows:

<WranglerConfig>

```toml
name = "my-worker"

[[queues.producers]]
  queue = "my-queue"
  binding = "YOUR_QUEUE"

[durable_objects]
bindings = [
  { name = "YOUR_DO_CLASS", class_name = "YourDurableObject" }
]

[[migrations]]
tag = "v1"
new_sqlite_classes = ["YourDurableObject"]
```

</WranglerConfig>

The following Worker script:

1. Creates a Durable Object stub, or retrieves an existing one based on a userId.
2. Passes request data to the Durable Object.
3. Publishes to a queue from within the Durable Object.

The `constructor()` in the Durable Object makes your `Environment` available (in scope) on `this.env` to the [`fetch()` handler](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/) in the Durable Object.

```ts
interface Env {
  YOUR_QUEUE: Queue;
  YOUR_DO_CLASS: DurableObjectNamespace;
}

export default {
  async fetch(req, env): Promise<Response> {
    // Assume each Durable Object is mapped to a userId in a query parameter
    // In a production application, this will be a userId defined by your application
    // that you validate (and/or authenticate) first.
    let url = new URL(req.url)
    let userIdParam = url.searchParams.get("userId")

    if (userIdParam) {
      // Create (or get) a Durable Object based on that userId.
      let durableObjectId = env.YOUR_DO_CLASS.idFromName(userIdParam);
      // Get a "stub" that allows you to call that Durable Object
      let durableObjectStub = env.YOUR_DO_CLASS.get(durableObjectId);

      // Pass the request to that Durable Object and await the response
      // This invokes the constructor once on your Durable Object class (defined further down)
      // on the first initialization, and the fetch method on each request.
      // We pass the original Request to the Durable Object's fetch method
      let response = await durableObjectStub.fetch(req);

      // This would return "wrote to queue", but you could return any response.
      return response;
    }
    return new Response("userId must be provided", { status: 400 });
  },
} satisfies ExportedHandler<Env>;

export class YourDurableObject implements DurableObject {
  constructor(private state: DurableObjectState, private env: Env) {}

  async fetch(req: Request): Promise<Response> {
    // Error handling elided for brevity.
    // Publish to your queue
    await this.env.YOUR_QUEUE.send({
      id: this.state.id.toString() // Write the ID of the Durable Object to your queue
      // Write any other properties to your queue
    });

    return new Response("wrote to queue")
  }
```

---

# Observability

URL: https://developers.cloudflare.com/queues/observability/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Metrics

URL: https://developers.cloudflare.com/queues/observability/metrics/

Queues expose metrics which allow you to measure the queue backlog, consumer concurrency, and message operations.

The metrics displayed in the [Cloudflare dashboard](https://dash.cloudflare.com/) are queried from Cloudflare’s [GraphQL Analytics API](/analytics/graphql-api/). You can access the metrics [programmatically](#query-via-the-graphql-api) via GraphQL or HTTP client.

## Metrics

### Backlog

Queues export the below metrics within the `queuesBacklogAdaptiveGroups` dataset.

| Metric           | GraphQL Field Name | Description                                        |
| ---------------- | ------------------ | -------------------------------------------------- |
| Backlog bytes    | `bytes`            | Average size of the backlog, in bytes              |
| Backlog messages | `messages`         | Average size of the backlog, in number of messages |

The `queuesBacklogAdaptiveGroups` dataset provides the following dimensions for filtering and grouping queries:

- `queueID` - ID of the queue
- `datetime` - Timestamp for when the message was sent
- `date` - Timestamp for when the message was sent, truncated to the start of a day
- `datetimeHour` - Timestamp for when the message was sent, truncated to the start of an hour
- `datetimeMinute` - Timestamp for when the message was sent, truncated to the start of a minute

### Consumer concurrency

Queues export the below metrics within the `queueConsumerMetricsAdaptiveGroups` dataset.

| Metric                    | GraphQL Field Name | Description                                            |
| ------------------------- | ------------------ | ------------------------------------------------------ |
| Avg. Consumer Concurrency | `concurrency`      | Average number of concurrent consumers over the period |

The `queueConsumerMetricsAdaptiveGroups` dataset provides the following dimensions for filtering and grouping queries:

- `queueID` - ID of the queue
- `datetime` - Timestamp for the consumer metrics
- `date` - Timestamp for the consumer metrics, truncated to the start of a day
- `datetimeHour` - Timestamp for the consumer metrics, truncated to the start of an hour
- `datetimeMinute` - Timestamp for the consumer metrics, truncated to the start of a minute

### Message operations

Queues export the below metrics within the `queueMessageOperationsAdaptiveGroups` dataset.

| Metric                    | GraphQL Field Name   | Description                                                                                                     |
| ------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------- |
| Total billable operations | `billableOperations` | Sum of billable operations (writes, reads, and deletes) over the time period                                    |
| Total Bytes               | `bytes`              | Sum of bytes read, written, and deleted from the queue                                                          |
| Lag                       | `lagTime`            | Average lag time in milliseconds between when the message was written and the operation to consume the message. |
| Retries                   | `retryCount`         | Average number of retries per message                                                                           |
| Message Size              | `messageSize`        | Maximum message size over the specified period                                                                  |

The `queueMessageOperationsAdaptiveGroups` dataset provides the following dimensions for filtering and grouping queries:

- `queueID` - ID of the queue
- `actionType` - The type of message operation. Can be `WriteMessage`, `ReadMessage` or `DeleteMessage`
- `consumerType` - The queue consumer type. Can be `worker` or `http`. Only applicable for `ReadMessage` and `DeleteMessage` action types
- `outcome` - The outcome of the mesage operation. Only applicable for `DeleteMessage` action types. Can be `success`, `dlq` or `fail`.
- `datetime` - Timestamp for the message operation
- `date` - Timestamp for the message operation, truncated to the start of a day
- `datetimeHour` - Timestamp for the message operation, truncated to the start of an hour
- `datetimeMinute` - Timestamp for the message operation, truncated to the start of a minute

## Example GraphQL Queries

### Get average queue backlog over time period

```graphql graphql-api-explorer
query QueueBacklog(
	$accountTag: string!
	$queueId: string!
	$datetimeStart: Time!
	$datetimeEnd: Time!
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			queueBacklogAdaptiveGroups(
				limit: 10000
				filter: {
					queueId: $queueId
					datetime_geq: $datetimeStart
					datetime_leq: $datetimeEnd
				}
			) {
				avg {
					messages
					bytes
				}
			}
		}
	}
}
```

### Get average consumer concurrency by hour

```graphql graphql-api-explorer
query QueueConcurrencyByHour(
	$accountTag: string!
	$queueId: string!
	$datetimeStart: Time!
	$datetimeEnd: Time!
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			queueConsumerMetricsAdaptiveGroups(
				limit: 10000
				filter: {
					queueId: $queueId
					datetime_geq: $datetimeStart
					datetime_leq: $datetimeEnd
				}
				orderBy: [datetimeHour_DESC]
			) {
				avg {
					concurrency
				}
				dimensions {
					datetimeHour
				}
			}
		}
	}
}
```

### Get message operations by minute

```graphql graphql-api-explorer
query QueueMessageOperationsByMinute(
	$accountTag: string!
	$queueId: string!
	$datetimeStart: Date!
	$datetimeEnd: Date!
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			queueMessageOperationsAdaptiveGroups(
				limit: 10000
				filter: {
					queueId: $queueId
					datetime_geq: $datetimeStart
					datetime_leq: $datetimeEnd
				}
				orderBy: [datetimeMinute_DESC]
			) {
				count
				sum {
					bytes
				}
				dimensions {
					datetimeMinute
				}
			}
		}
	}
}
```

---

# Audit Logs

URL: https://developers.cloudflare.com/queues/platform/audit-logs/

[Audit logs](/fundamentals/account/account-security/review-audit-logs/) provide a comprehensive summary of changes made within your Cloudflare account, including those made to Queues. This functionality is always enabled.

## Viewing audit logs

To view audit logs for your Queue:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?account=audit-log) and select your account.
2. Go to **Manage Account** > **Audit Log**.

For more information on how to access and use audit logs, refer to [Review audit logs](/fundamentals/account/account-security/review-audit-logs/).

## Logged operations

The following configuration actions are logged:

<table>
  <tbody>
    <th colspan="5" rowspan="1" style="width:220px">
      Operation
    </th>
    <th colspan="5" rowspan="1">
      Description
    </th>
    <tr>
      <td colspan="5" rowspan="1">
        CreateQueue
      </td>
      <td colspan="5" rowspan="1">
        Creation of a new queue.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        DeleteQueue
      </td>
      <td colspan="5" rowspan="1">
        Deletion of an existing queue.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        UpdateQueue
      </td>
      <td colspan="5" rowspan="1">
        Updating the configuration of a queue.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        AttachConsumer
      </td>
      <td colspan="5" rowspan="1">
        Attaching a consumer, including HTTP pull consumers, to the Queue.
      </td>
    </tr>
     <tr>
      <td colspan="5" rowspan="1">
        RemoveConsumer
      </td>
      <td colspan="5" rowspan="1">
        Removing a consumer, including HTTP pull consumers, from the Queue.
      </td>
    </tr>
     <tr>
      <td colspan="5" rowspan="1">
        UpdateConsumerSettings
      </td>
      <td colspan="5" rowspan="1">
        Changing Queues consumer settings.
      </td>
    </tr>

  </tbody>
</table>

---

# Platform

URL: https://developers.cloudflare.com/queues/platform/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Changelog

URL: https://developers.cloudflare.com/queues/platform/changelog/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/queues.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Limits

URL: https://developers.cloudflare.com/queues/platform/limits/

import { Render, WranglerConfig } from "~/components"


| Feature                                       									| Limit                                                         |
| ----------------------------------------------------------------| ------------------------------------------------------------- |
| Queues                                        									| 10,000 per account								                            |
| Message size                                  									| 128 KB <sup>1</sup>                                           |
| Message retries                               									| 100                                                           |
| Maximum consumer batch size                   									| 100 messages 								                                  |
| Maximum messages per `sendBatch` call         									| 100 (or 256KB in total)                                       |
| Maximum Batch wait time                       									| 60 seconds                                                    |
| Per-queue message throughput    																| 5,000 messages per second <sup>2</sup>                        |
| Message retention period <sup>3</sup>         									| 4 days (default). [Configurable to 14 days](/queues/configuration/configure-queues/#queue-configuration)                                                       |
| Per-queue backlog size <sup>4</sup>           									| 25GB                                                          |
| Concurrent consumer invocations               									| 250 <sup>push-based only</sup>                                |
| Consumer duration (wall clock time) 														| 15 minutes <sup>5</sup>                                       |
| [Consumer CPU time](/workers/platform/limits/#cpu-time)| 30 seconds (default). [Configurable to 5 minutes](/queues/platform/limits/#increasing-queue-consumer-worker-cpu-limits) 							|
| `visibilityTimeout` (pull-based queues)       									| 12 hours                                                      |
| `delaySeconds` (when sending or retrying)     									| 12 hours                                                      |
| Requests to the Queues API (excluding pull consumer operations)<sup>6</sup>     | [1200 requests / 5 mins](/fundamentals/api/reference/limits/) |


<sup>1</sup> 1 KB is measured as 1000 bytes. Messages can include up to \~100 bytes of internal metadata that counts towards total message limits.

<sup>2</sup> Exceeding the maximum message throughput will cause the `send()` and `sendBatch()` methods to throw an exception with a `Too Many Requests` error until your producer falls below the limit.

<sup>3</sup> Messages in a queue that reach the maximum message retention are deleted from the queue. Queues does not delete messages in the same queue that have not reached this limit.

<sup>4</sup> Individual queues that reach this limit will receive a `Storage Limit Exceeded` error when calling `send()` or `sendBatch()` on the queue.

<sup>5</sup> Refer to [Workers limits](/workers/platform/limits/#cpu-time).

<sup>6</sup> [Pull Consumers](/queues/configuration/pull-consumers) allow you to consume messages from a queue over HTTP. Pulls, acknowledgements, and retries over HTTP are not subject to the API rate limit.

<Render file="limits_increase" product="workers" />

### Increasing Queue Consumer Worker CPU Limits
[Queue consumer Workers](/queues/reference/how-queues-works/#consumers) are Worker scripts, and share the same [per invocation CPU limits](/workers/platform/limits/#worker-limits) as any Workers do. Note that CPU time is active processing time: not time spent waiting on network requests, storage calls, or other general I/O.

By default, the maximum CPU time per consumer Worker invocation is set to 30 seconds, but can be increased by setting `limits.cpu_ms` in your Wrangler configuration:

<WranglerConfig>

```jsonc
{
  // ...rest of your configuration...
  "limits": {
    "cpu_ms": 300000, // 300,000 milliseconds = 5 minutes
  },
  // ...rest of your configuration...
}
```

</WranglerConfig>

To learn more about CPU time and limits, [review the Workers documentation](/workers/platform/limits/#cpu-time).

---

# Pricing

URL: https://developers.cloudflare.com/queues/platform/pricing/

import { Render } from "~/components"

<Render file="queues_pricing" product="workers" />

## Examples

If an application writes, reads and deletes (consumes) one million messages a day (in a 30 day month), and each message is less than 64 KB in size, the estimated bill for the month would be:



|                     | Total Usage           | Free Usage | Billed Usage | Price      |
| ------------------- | --------------------- | ---------- | ------------ | ---------- |
| Standard operations | 3 \* 30 \* 1,000,000  | 1,000,000  | 89,000,000   | $35.60     |
|                     | (write, read, delete) |            |              |            |
| **TOTAL**           |                       |            |              | **$35.60** |



An application that writes, reads and deletes (consumes) 100 million \~127 KB messages (each message counts as two 64 KB chunks) per month would have an estimated bill resembling the following:



|                     | Total Usage                  | Free Usage | Billed Usage | Price       |
| ------------------- | ---------------------------- | ---------- | ------------ | ----------- |
| Standard operations | 2 \* 3 \* 100 \* 1,000,000   | 1,000,000  | 599,000,000  | $239.60     |
|                     | (2x ops for > 64KB messages) |            |              |             |
| **TOTAL**           |                              |            |              | **$239.60** |

---

# Delivery guarantees

URL: https://developers.cloudflare.com/queues/reference/delivery-guarantees/

Delivery guarantees define how strongly a messaging system enforces the delivery of messages it processes.

As you make stronger guarantees about message delivery, the system needs to perform more checks and acknowledgments to ensure that messages are delivered, or maintain state to ensure a message is only delivered the specified number of times. This increases the latency of the system and reduces the overall throughput of the system. Each message may require an additional internal acknowledgements, and an equivalent number of additional roundtrips, before it can be considered delivered.

* **Queues provides *at least once* delivery by default** in order to optimize for reliability.
* This means that messages are guaranteed to be delivered at least once, and in rare occasions, may be delivered more than once.
* For the majority of applications, this is the right balance between not losing any messages and minimizing end-to-end latency, as exactly once delivery incurs additional overheads in any messaging system.

In cases where processing the same message more than once would introduce unintended behaviour, generating a unique ID when writing the message to the queue and using that as the primary key on database inserts and/or as an idempotency key to de-duplicate the message after processing. For example, using this idempotency key as the ID in an upstream email API or payment API will allow those services to reject the duplicate on your behalf, without you having to carry additional state in your application.

---

# Reference

URL: https://developers.cloudflare.com/queues/reference/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# How Queues Works

URL: https://developers.cloudflare.com/queues/reference/how-queues-works/

import { WranglerConfig } from "~/components";

Cloudflare Queues is a flexible messaging queue that allows you to queue messages for asynchronous processing. Message queues are great at decoupling components of applications, like the checkout and order fulfillment services for an e-commerce site. Decoupled services are easier to reason about, deploy, and implement, allowing you to ship features that delight your customers without worrying about synchronizing complex deployments. Queues also allow you to batch and buffer calls to downstream services and APIs.

There are four major concepts to understand with Queues:

1. [Queues](#what-is-a-queue)
2. [Producers](#producers)
3. [Consumers](#consumers)
4. [Messages](#messages)

## What is a queue

A queue is a buffer or list that automatically scales as messages are written to it, and allows a consumer Worker to pull messages from that same queue.

Queues are designed to be reliable, and messages written to a queue should never be lost once the write succeeds. Similarly, messages are not deleted from a queue until the [consumer](#consumers) has successfully consumed the message.

Queues does not guarantee that messages will be delivered to a consumer in the same order in which they are published.

Developers can create multiple queues. Creating multiple queues can be useful to:

* Separate different use-cases and processing requirements: for example, a logging queue vs. a password reset queue.
* Horizontally scale your overall throughput (messages per second) by using multiple queues to scale out.
* Configure different batching strategies for each consumer connected to a queue.

For most applications, a single producer Worker per queue, with a single consumer Worker consuming messages from that queue allows you to logically separate the processing for each of your queues.

## Producers

A producer is the term for a client that is publishing or producing messages on to a queue. A producer is configured by [binding](/workers/runtime-apis/bindings/) a queue to a Worker and writing messages to the queue by calling that binding.

For example, if we bound a queue named `my-first-queue` to a binding of `MY_FIRST_QUEUE`, messages can be written to the queue by calling `send()` on the binding:

```ts
type Environment = {
  readonly MY_FIRST_QUEUE: Queue;
};

export default {
  async fetch(req, env, context): Promise<Response> {
    let message = {
      url: req.url,
      method: req.method,
      headers: Object.fromEntries(req.headers),
    };

    await env.MY_FIRST_QUEUE.send(message); // This will throw an exception if the send fails for any reason
  },
} satisfies ExportedHandler<Environment>;
```

:::note


You can also use [`context.waitUntil()`](/workers/runtime-apis/context/#waituntil) to send the message without blocking the response.

Note that because `waitUntil()` is non-blocking, any errors raised from the `send()` or `sendBatch()` methods on a queue will be implicitly ignored.


:::

A queue can have multiple producer Workers. For example, you may have multiple producer Workers writing events or logs to a shared queue based on incoming HTTP requests from users. There is no limit to the total number of producer Workers that can write to a single queue.

Additionally, multiple queues can be bound to a single Worker. That single Worker can decide which queue to write to (or write to multiple) based on any logic you define in your code.

### Content types

Messages published to a queue can be published in different formats, depending on what interoperability is needed with your consumer. The default content type is `json`, which means that any object that can be passed to `JSON.stringify()` will be accepted.

To explicitly set the content type or specify an alternative content type, pass the `contentType` option to the `send()` method of your queue:

```ts
type Environment = {
  readonly MY_FIRST_QUEUE: Queue;
};

export default {
  async fetch(req, env): Promise<Response> {
    let message = {
      url: req.url,
      method: req.method,
      headers: Object.fromEntries(req.headers),
    };
    try {
      await env.MY_FIRST_QUEUE.send(message, { contentType: "json" }); // "json" is the default
    } catch (e) {
      // Catch cases where send fails, including due to a mismatched content type
      console.log(e)
      return Response.json({"msg": e}, { status: 500 })
    }
  },
} satisfies ExportedHandler<Environment>;
```

To only accept simple strings when writing to a queue, set `{ contentType: "text" }` instead:

```ts
    try {
      // This will throw an exception (error) if you write to pass a non-string to the queue, such as a
      // native JavaScript object or ArrayBuffer.
      await env.MY_FIRST_QUEUE.send("hello there", { contentType: "text" }); // explicitly set 'text'
    } catch (e) {
      console.log(e)
      return Response.json({"msg": e}, { status: 500 })
```

The [`QueuesContentType`](/queues/configuration/javascript-apis/#queuescontenttype) API documentation describes how each format is serialized to a queue.

## Consumers

Queues supports two types of consumer:

1. A [consumer Worker](/queues/configuration/configure-queues/), which is push-based: the Worker is invoked when the queue has messages to deliver.
2. A [HTTP pull consumer](/queues/configuration/pull-consumers/), which is pull-based: the consumer calls the queue endpoint over HTTP to receive and then acknowledge messages.

A queue can only have one type of consumer configured.

### Create a consumer Worker

A consumer is the term for a client that is subscribing to or *consuming* messages from a queue. In its most basic form, a consumer is defined by creating a `queue` handler in a Worker:

```ts
export default {
  async queue(batch: MessageBatch<Error>, env: Environment): Promise<void> {
    // Do something with messages in the batch
    // i.e. write to R2 storage, D1 database, or POST to an external API
    // You can also iterate over each message in the batch by looping over batch.messages
  },
};
```

You then connect that consumer to a queue with `wrangler queues consumer <queue-name> <worker-script-name>` or by defining a `[[queues.consumers]]` configuration in your [Wrangler configuration file](/workers/wrangler/configuration/) manually:

<WranglerConfig>

```toml
[[queues.consumers]]
  queue = "<your-queue-name>"
  max_batch_size = 100 # optional
  max_batch_timeout = 30 # optional
```

</WranglerConfig>

Importantly, each queue can only have one active consumer. This allows Cloudflare Queues to achieve at least once delivery and minimize the risk of duplicate messages beyond that.

:::note[Best practice]


Configure a single consumer per queue. This both logically separates your queues, and ensures that errors (failures) in processing messages from one queue do not impact your other queues.


:::

Notably, you can use the same consumer with multiple queues. The queue handler that defines your consumer Worker will be invoked by the queues it is connected to.

* The `MessageBatch` that is passed to your `queue` handler includes a `queue` property with the name of the queue the batch was read from.
* This can reduce the amount of code you need to write, and allow you to process messages based on the name of your queues.

For example, a consumer configured to consume messages from multiple queues would resemble the following:

```ts
export default {
  async queue(batch: MessageBatch<Error>, env: Environment): Promise<void> {
    // MessageBatch has a `queue` property we can switch on
    switch (batch.queue) {
      case 'log-queue':
        // Write the batch to R2
        break;
      case 'debug-queue':
        // Write the message to the console or to another queue
        break;
      case 'email-reset':
        // Trigger a password reset email via an external API
        break;
      default:
      // Handle messages we haven't mentioned explicitly (write a log, push to a DLQ)
    }
  },
};
```

### Remove a consumer

To remove a queue from your project, run `wrangler queues consumer remove <queue-name> <script-name>` and then remove the desired queue below the `[[queues.consumers]]` in Wrangler file.

### Pull consumers

A queue can have a HTTP-based consumer that pulls from the queue, instead of messages being pushed to a Worker.

This consumer can be any HTTP-speaking service that can communicate over the Internet. Review the [pull consumer guide](/queues/configuration/pull-consumers/) to learn how to configure a pull-based consumer for a queue.

## Messages

A message is the object you are producing to and consuming from a queue.

Any JSON serializable object can be published to a queue. For most developers, this means either simple strings or JSON objects. You can explicitly [set the content type](#content-types) when sending a message.

Messages themselves can be [batched when delivered to a consumer](/queues/configuration/batching-retries/). By default, messages within a batch are treated as all or nothing when determining retries. If the last message in a batch fails to be processed, the entire batch will be retried. You can also choose to [explicitly acknowledge](/queues/configuration/batching-retries/) messages as they are successfully processed, and/or mark individual messages to be retried.

---

# Tutorials

URL: https://developers.cloudflare.com/queues/tutorials/

import { ListTutorials, YouTubeVideos } from "~/components";

## Docs

<ListTutorials />

## Videos

<YouTubeVideos products={["Queues"]} />

---

# API

URL: https://developers.cloudflare.com/r2/api/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Authentication

URL: https://developers.cloudflare.com/r2/api/tokens/

You can generate an API token to serve as the Access Key for usage with existing S3-compatible SDKs or XML APIs.

You must purchase R2 before you can generate an API token.

To create an API token:

1. In **Account Home**, select **R2**.
2. Under the **API** dropdown, select [**Manage API tokens**](https://dash.cloudflare.com/?to=/:account/r2/api-tokens).
3. Choose to create either:
   - **Create Account API token** - These tokens are tied to the Cloudflare account itself and can be used by any authorized system or user. Only users with the Super Administrator role can view or create them. These tokens remain valid until manually revoked.
   - **Create User API token** - These tokens are tied to your individual Cloudflare user. They inherit your personal permissions and become inactive if your user is removed from the account.
4. Under **Permissions**, choose a permission types for your token. Refer to [Permissions](#permissions) for information about each option.
5. (Optional) If you select the **Object Read and Write** or **Object Read** permissions, you can scope your token to a set of buckets.
6. Select **Create Account API token** or **Create User API token**.

After your token has been successfully created, review your **Secret Access Key** and **Access Key ID** values. These may often be referred to as Client Secret and Client ID, respectively.

:::caution

You will not be able to access your **Secret Access Key** again after this step. Copy and record both values to avoid losing them.

:::

You will also need to configure the `endpoint` in your S3 client to `https://<ACCOUNT_ID>.r2.cloudflarestorage.com`.

Find your [account ID in the Cloudflare dashboard](/fundamentals/account/find-account-and-zone-ids/).

Buckets created with jurisdictions must be accessed via jurisdiction-specific endpoints:

- European Union (EU): `https://<ACCOUNT_ID>.eu.r2.cloudflarestorage.com`
- FedRAMP: `https://<ACCOUNT_ID>.fedramp.r2.cloudflarestorage.com`

:::caution

Jurisdictional buckets can only be accessed via the corresponding jurisdictional endpoint. Most S3 clients will not let you configure multiple `endpoints`, so you'll generally have to initialize one client per jurisdiction.

:::

## Permissions

| Permission          | Description                                                                                                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Admin Read & Write  | Allows the ability to create, list, and delete buckets, edit bucket configuration, read, write, and list objects, and read and write to data catalog tables and associated metadata. |
| Admin Read only     | Allows the ability to list buckets and view bucket configuration, read and list objects, and read from the data catalog tables and associated metadata.                              |
| Object Read & Write | Allows the ability to read, write, and list objects in specific buckets.                                                                                                             |
| Object Read only    | Allows the ability to read and list objects in specific buckets.                                                                                                                     |

:::note

Currently **Admin Read & Write** or **Admin Read only** permission is required to use [R2 Data Catalog](/r2/data-catalog/).

:::

## Create API tokens via API

You can create API tokens via the API and use them to generate corresponding Access Key ID and Secret Access Key values. To get started, refer to [Create API tokens via the API](/fundamentals/api/how-to/create-via-api/). Below are the specifics for R2.

### Access Policy

An Access Policy specifies what resources the token can access and the permissions it has.

#### Resources

There are two relevant resource types for R2: `Account` and `Bucket`. For more information on the Account resource type, refer to [Account](/fundamentals/api/how-to/create-via-api/#account).

##### Bucket

Include a set of R2 buckets or all buckets in an account.

A specific bucket is represented as:

```json
"com.cloudflare.edge.r2.bucket.<ACCOUNT_ID>_<JURISDICTION>_<BUCKET_NAME>": "*"
```

- `ACCOUNT_ID`: Refer to [Find zone and account IDs](/fundamentals/account/find-account-and-zone-ids/#find-account-id-workers-and-pages).
- `JURISDICTION`: The [jurisdiction](/r2/reference/data-location/#available-jurisdictions) where the R2 bucket lives. For buckets not created in a specific jurisdiction this value will be `default`.
- `BUCKET_NAME`: The name of the bucket your Access Policy applies to.

All buckets in an account are represented as:

```json
"com.cloudflare.api.account.<ACCOUNT_ID>": {
  "com.cloudflare.edge.r2.bucket.*": "*"
}
```

- `ACCOUNT_ID`: Refer to [Find zone and account IDs](/fundamentals/account/find-account-and-zone-ids/#find-account-id-workers-and-pages).

#### Permission groups

Determine what [permission groups](/fundamentals/api/how-to/create-via-api/#permission-groups) should be applied.

<table>
	<tbody>
		<th colspan="5" rowspan="1">
			Permission group
		</th>
		<th colspan="5" rowspan="1">
			Resource
		</th>
		<th colspan="5" rowspan="1">
			Description
		</th>
		<tr>
			<td colspan="5" rowspan="1">
				<code>Workers R2 Storage Write</code>
			</td>
			<td colspan="5" rowspan="1">
				Account
			</td>
			<td colspan="5" rowspan="1">
				Can create, delete, and list buckets, edit bucket configuration, and
				read, write, and list objects.
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				<code>Workers R2 Storage Read</code>
			</td>
			<td colspan="5" rowspan="1">
				Account
			</td>
			<td colspan="5" rowspan="1">
				Can list buckets and view bucket configuration, and read and list
				objects.
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				<code>Workers R2 Storage Bucket Item Write</code>
			</td>
			<td colspan="5" rowspan="1">
				Bucket
			</td>
			<td colspan="5" rowspan="1">
				Can read, write, and list objects in buckets.
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				<code>Workers R2 Storage Bucket Item Read</code>
			</td>
			<td colspan="5" rowspan="1">
				Bucket
			</td>
			<td colspan="5" rowspan="1">
				Can read and list objects in buckets.
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				<code>Workers R2 Data Catalog Write</code>
			</td>
			<td colspan="5" rowspan="1">
				Account
			</td>
			<td colspan="5" rowspan="1">
				Can read from and write to data catalogs. This permission allows
				access to the Iceberg REST catalog interface.
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				<code>Workers R2 Data Catalog Read</code>
			</td>
			<td colspan="5" rowspan="1">
				Account
			</td>
			<td colspan="5" rowspan="1">
				Can read from data catalogs. This permission allows read-only
				access to the Iceberg REST catalog interface.
			</td>
		</tr>
	</tbody>
</table>

#### Example Access Policy

```json
[
	{
		"id": "f267e341f3dd4697bd3b9f71dd96247f",
		"effect": "allow",
		"resources": {
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_default_my-bucket": "*",
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_eu_my-eu-bucket": "*"
		},
		"permission_groups": [
			{
				"id": "6a018a9f2fc74eb6b293b0c548f38b39",
				"name": "Workers R2 Storage Bucket Item Read"
			}
		]
	}
]
```

### Get S3 API credentials from an API token

You can get the Access Key ID and Secret Access Key values from the response of the [Create Token](/api/resources/user/subresources/tokens/methods/create/) API:

- Access Key ID: The `id` of the API token.
- Secret Access Key: The SHA-256 hash of the API token `value`.

Refer to [Authenticate against R2 API using auth tokens](/r2/examples/authenticate-r2-auth-tokens/) for a tutorial with JavaScript, Python, and Go examples.

## Temporary access credentials

If you need to create temporary credentials for a bucket or a prefix/object within a bucket, you can use the [temp-access-credentials endpoint](/api/resources/r2/subresources/temporary_credentials/methods/create/) in the API. You will need an existing R2 token to pass in as the parent access key id. You can use the credentials from the API result for an S3-compatible request by setting the credential variables like so:

```
AWS_ACCESS_KEY_ID = <accessKeyId>
AWS_SECRET_ACCESS_KEY = <secretAccessKey>
AWS_SESSION_TOKEN = <sessionToken>
```

:::note

The temporary access key cannot have a permission that is higher than the parent access key. e.g. if the parent key is set to `Object Read Write`, the temporary access key could only have `Object Read Write` or `Object Read Only` permissions.

:::

---

# Getting started

URL: https://developers.cloudflare.com/r2/data-catalog/get-started/

import {
	Render,
	PackageManagers,
	Steps,
	FileTree,
	Tabs,
	TabItem,
	TypeScriptExample,
	WranglerConfig,
	LinkCard,
} from "~/components";

## Overview

This guide will instruct you through:

- Creating your first [R2 bucket](/r2/buckets/) and enabling its [data catalog](/r2/data-catalog/).
- Creating an [API token](/r2/api/tokens/) needed for query engines to authenticate with your data catalog.
- Using [PyIceberg](https://py.iceberg.apache.org/) to create your first Iceberg table in a [marimo](https://marimo.io/) Python notebook.
- Using [PyIceberg](https://py.iceberg.apache.org/) to load sample data into your table and query it.

## Prerequisites

<Render file="prereqs" product="workers" />

## 1. Create an R2 bucket

<Tabs syncKey='CLIvDash'>
<TabItem label='Wrangler CLI'>

<Steps>
1. If not already logged in, run:

    	```
    	npx wrangler login
    	```

2.  Create an R2 bucket:

        ```
        npx wrangler r2 bucket create r2-data-catalog-tutorial
        ```

</Steps>

</TabItem>
<TabItem label='Dashboard'>

<Steps>
1. From the Cloudflare dashboard, select **R2 Object Storage** from the sidebar.
2. Select **Create bucket**.
3. Enter the bucket name: r2-data-catalog-tutorial
4. Select **Create bucket**.
</Steps>
</TabItem>
</Tabs>

## 2. Enable the data catalog for your bucket

<Tabs syncKey='CLIvDash'>
<TabItem label='Wrangler CLI'>

Then, enable the catalog on your chosen R2 bucket:

        ```
        npx wrangler r2 bucket catalog enable r2-data-catalog-tutorial
        ```

When you run this command, take note of the "Warehouse" and "Catalog URI". You will need these later. 

</TabItem>
<TabItem label='Dashboard'>

<Steps>
1. From the Cloudflare dashboard, select **R2 Object Storage** from the sidebar.
2. Select the bucket: r2-data-catalog-tutorial.
3. Switch to the **Settings** tab, scroll down to **R2 Data Catalog**, and select **Enable**.
4. Once enabled, note the **Catalog URI** and **Warehouse name**.
</Steps>
</TabItem>
</Tabs>

## 3. Create an API token

Iceberg clients (including [PyIceberg](https://py.iceberg.apache.org/)) must authenticate to the catalog with a [Cloudflare API token](/fundamentals/api/get-started/create-token/) that has both R2 and catalog permissions.

<Steps>
1. From the Cloudflare dashboard, select **R2 Object Storage** from the sidebar.

2. Expand the **API** dropdown and select **Manage API tokens**.

3. Select **Create API token**.

4. Select the **R2 Token** text to edit your API token name.

5. Under **Permissions**, choose the **Admin Read & Write** permission.

6. Select **Create API Token**.

7. Note the **Token value**.

</Steps>

## 4. Install uv

You need to install a Python package manager. In this guide, use [uv](https://docs.astral.sh/uv/). If you do not already have uv installed, follow the [installing uv guide](https://docs.astral.sh/uv/getting-started/installation/).

## 5. Install marimo and set up your project with uv

We will use [marimo](https://github.com/marimo-team/marimo) as a Python notebook.

<Steps>
1. Create a directory where our notebook will be stored:

    	```
    	mkdir r2-data-catalog-notebook
    	```

2. Change into our new directory:

      ```
      cd r2-data-catalog-notebook
      ```

3. Initialize a new uv project (this creates a `.venv` and a `pyproject.toml`):

      ```
      uv init
      ```

4. Add marimo and required dependencies:

      ```py
      uv add marimo pyiceberg pyarrow pandas
      ```

</Steps>

## 6. Create a Python notebook to interact with the data warehouse

<Steps>
1. Create a file called `r2-data-catalog-tutorial.py`.

2. Paste the following code snippet into your `r2-data-catalog-tutorial.py` file:

        ```py
        import marimo

        __generated_with = "0.11.31"
        app = marimo.App(width="medium")


        @app.cell
        def _():
        		import marimo as mo
        		return (mo,)


        @app.cell
        def _():
        		import pandas
        		import pyarrow as pa
        		import pyarrow.compute as pc
        		import pyarrow.parquet as pq

        		from pyiceberg.catalog.rest import RestCatalog

        		# Define catalog connection details (replace variables)
        		WAREHOUSE = "<WAREHOUSE>"
        		TOKEN = "<TOKEN>"
        		CATALOG_URI = "<CATALOG_URI>"

        		# Connect to R2 Data Catalog
        		catalog = RestCatalog(
        				name="my_catalog",
        				warehouse=WAREHOUSE,
        				uri=CATALOG_URI,
        				token=TOKEN,
        		)
        		return (
        				CATALOG_URI,
        				RestCatalog,
        				TOKEN,
        				WAREHOUSE,
        				catalog,
        				pa,
        				pandas,
        				pc,
        				pq,
        		)


        @app.cell
        def _(catalog):
        		# Create default namespace if needed
        		catalog.create_namespace_if_not_exists("default")
        		return


        @app.cell
        def _(pa):
        		# Create simple PyArrow table
        		df = pa.table({
        				"id": [1, 2, 3],
        				"name": ["Alice", "Bob", "Charlie"],
        				"score": [80.0, 92.5, 88.0],
        		})
        		return (df,)


        @app.cell
        def _(catalog, df):
        		# Create or load Iceberg table
        		test_table = ("default", "people")
        		if not catalog.table_exists(test_table):
        				print(f"Creating table: {test_table}")
        				table = catalog.create_table(
        						test_table,
        						schema=df.schema,
        				)
        		else:
        				table = catalog.load_table(test_table)
        		return table, test_table


        @app.cell
        def _(df, table):
        		# Append data
        		table.append(df)
        		return


        @app.cell
        def _(table):
        		print("Table contents:")
        		scanned = table.scan().to_arrow()
        		print(scanned.to_pandas())
        		return (scanned,)


        @app.cell
        def _():
        		# Optional cleanup. To run uncomment and run cell
        		# print(f"Deleting table: {test_table}")
        		# catalog.drop_table(test_table)
        		# print("Table dropped.")
        		return


        if __name__ == "__main__":
        		app.run()
        ```

3. Replace the `CATALOG_URI`, `WAREHOUSE`, and `TOKEN` variables with your values from sections **2** and **3** respectively.

4. Launch the notebook editor in your browser:

    	```
    	uv run marimo edit r2-data-catalog-tutorial.py
    	```

			Once your notebook connects to the catalog, you'll see the catalog along with its namespaces and tables appear in marimo's Datasources panel.

</Steps>
In the Python notebook above, you:

1. Connect to your catalog.
2. Create the `default` namespace.
3. Create a simple PyArrow table.
4. Create (or load) the `people` table in the `default` namespace.
5. Append sample data to the table.
6. Print the contents of the table.
7. (Optional) Drop the `people` table we created for this tutorial.

## Learn more

<LinkCard
	title="Managing catalogs"
	href="/r2/data-catalog/manage-catalogs/"
	description="Enable or disable R2 Data Catalog on your bucket, retrieve configuration details, and authenticate your Iceberg engine."
/>

<LinkCard
	title="Connect to Iceberg engines"
	href="/r2/data-catalog/config-examples/"
	description="Find detailed setup instructions for Apache Spark and other common query engines."
/>

---

# R2 Data Catalog

URL: https://developers.cloudflare.com/r2/data-catalog/

import { Render, LinkCard } from "~/components";

:::note
R2 Data Catalog is in **public beta**, and any developer with an [R2 subscription](/r2/pricing/) can start using it. Currently, outside of standard R2 storage and operations, you will not be billed for your use of R2 Data Catalog.
:::

R2 Data Catalog is a managed [Apache Iceberg](https://iceberg.apache.org/) data catalog built directly into your R2 bucket. It exposes a standard Iceberg REST catalog interface, so you can connect the engines you already use, like [Spark](/r2/data-catalog/config-examples/spark-scala/), [Snowflake](/r2/data-catalog/config-examples/snowflake/), and [PyIceberg](/r2/data-catalog/config-examples/pyiceberg/).

R2 Data Catalog makes it easy to turn an R2 bucket into a data warehouse or lakehouse for a variety of analytical workloads including log analytics, business intelligence, and data pipelines. R2's zero-egress fee model means that data users and consumers can access and analyze data from different clouds, data platforms, or regions without incurring transfer costs.

To get started with R2 Data Catalog, refer to the [R2 Data Catalog: Getting started](/r2/data-catalog/get-started/).

## What is Apache Iceberg?

[Apache Iceberg](https://iceberg.apache.org/) is an open table format designed to handle large-scale analytics datasets stored in object storage. Key features include:

- ACID transactions - Ensures reliable, concurrent reads and writes with full data integrity.
- Optimized metadata - Avoids costly full table scans by using indexed metadata for faster queries.
- Full schema evolution - Allows adding, renaming, and deleting columns without rewriting data.

Iceberg is already [widely supported](https://iceberg.apache.org/vendors/) by engines like Apache Spark, Trino, Snowflake, DuckDB, and ClickHouse, with a fast-growing community behind it.

## Why do you need a data catalog?

Although the Iceberg data and metadata files themselves live directly in object storage (like [R2](https://developers.cloudflare.com/r2/)), the list of tables and pointers to the current metadata need to be tracked centrally by a data catalog.

Think of a data catalog as a library's index system. While books (your data) are physically distributed across shelves (object storage), the index provides a single source of truth about what books exist, their locations, and their latest editions. Without this index, readers (query engines) would waste time searching for books, might access outdated versions, or could accidentally shelve new books in ways that make them unfindable.

Similarly, data catalogs ensure consistent, coordinated access, which allows multiple query engines to safely read from and write to the same tables without conflicts or data corruption.

## Learn more

<LinkCard
	title="Get started"
	href="/r2/data-catalog/get-started/"
	description="Learn how to enable the R2 Data Catalog on your bucket, load sample data, and run your first query."
/>

<LinkCard
	title="Managing catalogs"
	href="/r2/data-catalog/manage-catalogs/"
	description="Enable or disable R2 Data Catalog on your bucket, retrieve configuration details, and authenticate your Iceberg engine."
/>

<LinkCard
	title="Connect to Iceberg engines"
	href="/r2/data-catalog/config-examples/"
	description="Find detailed setup instructions for Apache Spark and other common query engines."
/>

---

# Manage catalogs

URL: https://developers.cloudflare.com/r2/data-catalog/manage-catalogs/

import {
	Render,
	PackageManagers,
	Steps,
	FileTree,
	Tabs,
	TabItem,
	TypeScriptExample,
	WranglerConfig,
	LinkCard,
} from "~/components";

Learn how to:

- Enable and disable [R2 Data Catalog](/r2/data-catalog/) on your buckets.
- Authenticate Iceberg engines using API tokens.

## Enable R2 Data Catalog on a bucket

Enabling the catalog on a bucket turns on the REST catalog interface and provides a **Catalog URI** and **Warehouse name** required by Iceberg clients. Once enabled, you can create and manage Iceberg tables in that bucket.

### Dashboard

<Steps>
1. From the Cloudflare dashboard, select **R2 Object Storage** from the sidebar.
2. Select the bucket you want to enable as a data catalog.
3. Switch to the **Settings** tab, scroll down to **R2 Data Catalog**, and select **Enable**.
4. Once enabled, note the **Catalog URI** and **Warehouse name**.
</Steps>

### Wrangler CLI

To enable the catalog on your bucket, run the [`r2 bucket catalog enable command`](/workers/wrangler/commands/#r2-bucket-catalog-enable):

```bash
npx wrangler r2 bucket catalog enable <BUCKET_NAME>
```

After enabling, Wrangler will return your catalog URI and warehouse name.

## Disable R2 Data Catalog on a bucket

When you disable the catalog on a bucket, it immediately stops serving requests from the catalog interface. Any Iceberg table references stored in that catalog become inaccessible until you re-enable it.

### Dashboard

<Steps>
1. From the Cloudflare dashboard, select **R2 Object Storage** from the sidebar.
2. Select the bucket where you want to disable the data catalog.
3. Switch to the **Settings** tab, scroll down to **R2 Data Catalog**, and select **Disable**.
</Steps>

### Wrangler CLI

To disable the catalog on your bucket, run the [`r2 bucket catalog disable command`](/workers/wrangler/commands/#r2-bucket-catalog-disable):

```bash
npx wrangler r2 bucket catalog disable <BUCKET_NAME>
```

## Authenticate your Iceberg engine

To connect your Iceberg engine to R2 Data Catalog, you must provide a Cloudflare API token with **both** R2 Data Catalog permissions and R2 storage permissions. Iceberg engines interact with R2 Data Catalog to perform table operations. The catalog also provides engines with SigV4 credentials, which are required to access the underlying data files stored in R2.

### Create API token in the dashboard

Create an [R2 API token](/r2/api/tokens/#permissions) with **Admin Read & Write** or **Admin Read only** permissions. These permissions include both:

- Access to R2 Data Catalog (read-only or read/write, depending on chosen permission)
- Access to R2 storage (read-only or read/write, depending on chosen permission)

Providing the resulting token value to your Iceberg engine gives it the ability to manage catalog metadata and handle data operations (reads or writes to R2).

### Create API token via API

To create an API token programmatically for use with R2 Data Catalog, you'll need to specify both R2 Data Catalog and R2 storage permission groups in your [Access Policy](/r2/api/tokens/#access-policy).

#### Example Access Policy

```json
[
	{
		"id": "f267e341f3dd4697bd3b9f71dd96247f",
		"effect": "allow",
		"resources": {
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_default_my-bucket": "*",
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_eu_my-eu-bucket": "*"
		},
		"permission_groups": [
			{
				"id": "d229766a2f7f4d299f20eaa8c9b1fde9",
				"name": "Workers R2 Data Catalog Write"
			},
			{
				"id": "2efd5506f9c8494dacb1fa10a3e7d5b6",
				"name": "Workers R2 Storage Bucket Item Write"
			}
		]
	}
]
```

To learn more about how to create API tokens for R2 Data Catalog using the API, including required permission groups and usage examples, refer to the [Create API tokens via API documentation](/r2/api/tokens/#create-api-tokens-via-api).

## Learn more

<LinkCard
	title="Get started"
	href="/r2/data-catalog/get-started/"
	description="Learn how to enable the R2 Data Catalog on your bucket, load sample data, and run your first query."
/>

<LinkCard
	title="Connect to Iceberg engines"
	href="/r2/data-catalog/config-examples/"
	description="Find detailed setup instructions for Apache Spark and other common query engines."
/>

---

# Bucket locks

URL: https://developers.cloudflare.com/r2/buckets/bucket-locks/

Bucket locks prevent the deletion and overwriting of objects in an R2 bucket for a specified period — or indefinitely. When enabled, bucket locks enforce retention policies on your objects, helping protect them from accidental or premature deletions.

## Get started with bucket locks

Before getting started, you will need:

- An existing R2 bucket. If you do not already have an existing R2 bucket, refer to [Create buckets](/r2/buckets/create-buckets/).
- (API only) An API token with [permissions](/r2/api/tokens/#permissions) to edit R2 bucket configuration.

### Enable bucket lock via dashboard

1. From the Cloudflare dashboard, select **R2** from the sidebar.
2. Select the bucket you would like to add bucket lock rule to.
3. Switch to the **Settings** tab, then scroll down to the **Bucket lock rules** card.
4. Select **Add rule** and enter the rule name, prefix, and retention period.
5. Select **Save changes**.

### Enable bucket lock via Wrangler

1. Install [`npm`](https://docs.npmjs.com/getting-started).
2. Install [Wrangler, the Developer Platform CLI](/workers/wrangler/install-and-update/).
3. Log in to Wrangler with the [`wrangler login` command](/workers/wrangler/commands/#login).
4. Add a bucket lock rule to your bucket by running the [`r2 bucket lock add` command](/workers/wrangler/commands/#r2-bucket-lock-add).

```sh
npx wrangler r2 bucket lock add <BUCKET_NAME> [OPTIONS]
```

Alternatively, you can set the entire bucket lock configuration for a bucket from a JSON file using the [`r2 bucket lock set` command](/workers/wrangler/commands/#r2-bucket-lock-set).

```sh
npx wrangler r2 bucket lock set <BUCKET_NAME> --file <FILE_PATH>
```

The JSON file should be in the format of the request body of the [put bucket lock configuration API](/api/resources/r2/subresources/buckets/subresources/locks/methods/update/).

### Enable bucket lock via API

For information about getting started with the Cloudflare API, refer to [Make API calls](/fundamentals/api/how-to/make-api-calls/). For information on required parameters and more examples of how to set bucket lock configuration, refer to the [API documentation](/api/resources/r2/subresources/buckets/subresources/locks/methods/update/).

Below is an example of setting a bucket lock configuration (a collection of rules):

```bash
curl -X PUT "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/r2/buckets/<BUCKET_NAME>/lock" \
    -H "Authorization: Bearer <API_TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{
        "rules": [
            {
                "id": "lock-logs-7d",
                "enabled": true,
                "prefix": "logs/",
                "condition": {
                    "type": "Age",
                    "maxAgeSeconds": 604800
                }
            },
            {
                "id": "lock-images-indefinite",
                "enabled": true,
                "prefix": "images/",
                "condition": {
                    "type": "Indefinite"
                }
            }
        ]
    }'
```

This request creates two rules:

- `lock-logs-7d`: Objects under the `logs/` prefix are retained for 7 days (604800 seconds).
- `lock-images-indefinite`: Objects under the `images/` prefix are locked indefinitely.

:::note

If your bucket is setup with [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions), you will need to pass a `cf-r2-jurisdiction` request header with that jurisdiction. For example, `cf-r2-jurisdiction: eu`.

:::

## Get bucket lock rules for your R2 bucket

### Dashboard

1. From the Cloudflare dashboard, select **R2** from the sidebar.
2. Select the bucket you would like to add bucket lock rule to.
3. Switch to the **Settings** tab, then scroll down to the **Bucket lock rules** card.

### Wrangler

To list bucket lock rules, run the [`r2 bucket lock list` command](/workers/wrangler/commands/#r2-bucket-lock-list):

```sh
npx wrangler r2 bucket lock list <BUCKET_NAME>
```

### API

For more information on required parameters and examples of how to get bucket lock rules, refer to the [API documentation](/api/resources/r2/subresources/buckets/subresources/locks/methods/get/).

## Remove bucket lock rules from your R2 bucket

### Dashboard

1. From the Cloudflare dashboard, select **R2** from the sidebar.
2. Select the bucket you would like to add bucket lock rule to.
3. Switch to the **Settings** tab, then scroll down to the **Bucket lock rules** card.
4. Locate the rule you want to remove, select the `...` icon next to it, and then select **Delete**.

### Wrangler

To remove a bucket lock rule, run the [`r2 bucket lock remove` command](/workers/wrangler/commands/#r2-bucket-lock-remove):

```sh
npx wrangler r2 bucket lock remove <BUCKET_NAME> --id <RULE_ID>
```

### API

To remove bucket lock rules via API, exclude them from your updated configuration and use the [put bucket lock configuration API](/api/resources/r2/subresources/buckets/subresources/locks/methods/update/).

## Bucket lock rules

A bucket lock configuration can include up to 1,000 rules. Each rule specifies which objects it covers (via prefix) and how long those objects must remain locked. You can:

- Lock objects for a specific duration. For example, 90 days.
- Retain objects until a certain date. For example, until January 1, 2026.
- Keep objects locked indefinitely.

If multiple rules apply to the same prefix or object key, the strictest (longest) retention requirement takes precedence.

## Notes

- Rules without prefix apply to all objects in the bucket.
- Rules apply to both new and existing objects in the bucket.
- Bucket lock rules take precedence over [lifecycle rules](/r2/buckets/object-lifecycles/). For example, if a lifecycle rule attempts to delete an object at 30 days but a bucket lock rule requires it be retained for 90 days, the object will not be deleted until the 90-day requirement is met.

---

# Configure CORS

URL: https://developers.cloudflare.com/r2/buckets/cors/

[Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) is a standardized method that prevents domain X from accessing the resources of domain Y. It does so by using special headers in HTTP responses from domain Y, that allow your browser to verify that domain Y permits domain X to access these resources.

While CORS can help protect your data from malicious websites, CORS is also used to interact with objects in your bucket and configure policies on your bucket.

CORS is used when you interact with a bucket from a web browser, and you have two options:

**[Set a bucket to public:](#use-cors-with-a-public-bucket)** This option makes your bucket accessible on the Internet as read-only, which means anyone can request and load objects from your bucket in their browser or anywhere else. This option is ideal if your bucket contains images used in a public blog.

**[Presigned URLs:](#use-cors-with-a-presigned-url)** Allows anyone with access to the unique URL to perform specific actions on your bucket.

## Prerequisites

Before you configure CORS, you must have:

- An R2 bucket with at least one object. If you need to create a bucket, refer to [Create a public bucket](/r2/buckets/public-buckets/).
- A domain you can use to access the object. This can also be a `localhost`.
- (Optional) Access keys. An access key is only required when creating a presigned URL.

## Use CORS with a public bucket

[To use CORS with a public bucket](/r2/buckets/public-buckets/), ensure your bucket is set to allow public access.

Next, [add a CORS policy](#add-cors-policies-from-the-dashboard) to your bucket to allow the file to be shared.

## Use CORS with a presigned URL

Presigned URLs are an S3 concept that contain a special signature that encodes details of an S3 action, such as `GetObject` or `PutObject`. Presigned URLs are only used for authentication, which means they are generally safe to distribute publicly without revealing any secrets.

### Create a presigned URL

You will need a pair of S3-compatible credentials to use when you generate the presigned URL.

The example below shows how to generate a presigned `PutObject` URL using the [`@aws-sdk/client-s3`](https://www.npmjs.com/package/@aws-sdk/client-s3) package for JavaScript.

```js
import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
const S3 = new S3Client({
	endpoint: "https://<account_id>.r2.cloudflarestorage.com",
	credentials: {
		accessKeyId: "<access_key_id>",
		secretAccessKey: "<access_key_secret>",
	},
	region: "auto",
});
const url = await getSignedUrl(
	S3,
	new PutObjectCommand({
		Bucket: bucket,
		Key: object,
	}),
	{
		expiresIn: 60 * 60 * 24 * 7, // 7d
	},
);
console.log(url);
```

### Test the presigned URL

Test the presigned URL by uploading an object using cURL. The example below would upload the `123` text to R2 with a `Content-Type` of `text/plain`.

```sh
curl --request PUT <URL> --header "Content-Type: text/plain" --data "123"
```

## Add CORS policies from the dashboard

1. From the Cloudflare dashboard, select **R2**.
2. Locate and select your bucket from the list.
3. From your bucket’s page, select **Settings**.
4. Under **CORS Policy**, select **Add CORS policy**.
5. From the **JSON** tab, manually enter or copy and paste your policy into the text box.
6. When you are done, select **Save**.

Your policy displays on the **Settings** page for your bucket.

## Response headers

The following fields in an R2 CORS policy map to HTTP response headers. These response headers are only returned when the incoming HTTP request is a valid CORS request.

| Field Name       | Description                                                                                                                                                                                                                                                                                                                                                           | Example                                                                                                                                                                                                                              |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AllowedOrigins` | Specifies the value for the `Access-Control-Allow-Origin` header R2 sets when requesting objects in a bucket from a browser.                                                                                                                                                                                                                                          | If a website at `www.test.com` needs to access resources (e.g. fonts, scripts) on a [custom domain](/r2/buckets/public-buckets/#custom-domains) of `static.example.com`, you would set `https://www.test.com` as an `AllowedOrigin`. |
| `AllowedMethods` | Specifies the value for the `Access-Control-Allow-Methods` header R2 sets when requesting objects in a bucket from a browser.                                                                                                                                                                                                                                         | `GET`, `POST`, `PUT`                                                                                                                                                                                                                 |
| `AllowedHeaders` | Specifies the value for the `Access-Control-Allow-Headers` header R2 sets when requesting objects in this bucket from a browser.Cross-origin requests that include custom headers (e.g. `x-user-id`) should specify these headers as `AllowedHeaders`.                                                                                                                | `x-requested-by`, `User-Agent`                                                                                                                                                                                                       |
| `ExposeHeaders`  | Specifies the headers that can be exposed back, and accessed by, the JavaScript making the cross-origin request. If you need to access headers beyond the [safelisted response headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Expose-Headers#examples), such as `Content-Encoding` or `cf-cache-status`, you must specify it here. | `Content-Encoding`, `cf-cache-status`, `Date`                                                                                                                                                                                        |
| `MaxAgeSeconds`  | Specifies the amount of time (in seconds) browsers are allowed to cache CORS preflight responses. Browsers may limit this to 2 hours or less, even if the maximum value (86400) is specified.                                                                                                                                                                         | `3600`                                                                                                                                                                                                                               |

## Example

This example shows a CORS policy added for a bucket that contains the `Roboto-Light.ttf` object, which is a font file.

The `AllowedOrigins` specify the web server being used, and `localhost:3000` is the hostname where the web server is running. The `AllowedMethods` specify that only `GET` requests are allowed and can read objects in your bucket.

```json
[
	{
		"AllowedOrigins": ["http://localhost:3000"],
		"AllowedMethods": ["GET"]
	}
]
```

In general, a good strategy for making sure you have set the correct CORS rules is to look at the network request that is being blocked by your browser.

- Make sure the rule's `AllowedOrigins` includes the origin where the request is being made from. (like `http://localhost:3000` or `https://yourdomain.com`)
- Make sure the rule's `AllowedMethods` includes the blocked request's method.
- Make sure the rule's `AllowedHeaders` includes the blocked request's headers.

Also note that CORS rule propagation can, in rare cases, take up to 30 seconds.

## Common Issues

- Only a cross-origin request will include CORS response headers.
  - A cross-origin request is identified by the presence of an `Origin` HTTP request header, with the value of the `Origin` representing a valid, allowed origin as defined by the `AllowedOrigins` field of your CORS policy.
  - A request without an `Origin` HTTP request header will _not_ return any CORS response headers. Origin values must match exactly.
- The value(s) for `AllowedOrigins` in your CORS policy must be a valid [HTTP Origin header value](https://fetch.spec.whatwg.org/#origin-header). A valid `Origin` header does _not_ include a path component and must only be comprised of a `scheme://host[:port]` (where port is optional).
  - Valid `AllowedOrigins` value: `https://static.example.com` - includes the scheme and host. A port is optional and implied by the scheme.
  - Invalid `AllowedOrigins` value: `https://static.example.com/` or `https://static.example.com/fonts/Calibri.woff2` - incorrectly includes the path component.
- If you need to access specific header values via JavaScript on the origin page, such as when using a video player, ensure you set `Access-Control-Expose-Headers` correctly and include the headers your JavaScript needs access to, such as `Content-Length`.

---

# Create new buckets

URL: https://developers.cloudflare.com/r2/buckets/create-buckets/

You can create a bucket from the Cloudflare dashboard or using Wrangler.

:::note

Wrangler is [a command-line tool](/workers/wrangler/install-and-update/) for building with Cloudflare's developer products, including R2.

The R2 support in Wrangler allows you to manage buckets and perform basic operations against objects in your buckets. For more advanced use-cases, including bulk uploads or mirroring files from legacy object storage providers, we recommend [rclone](/r2/examples/rclone/) or an [S3-compatible](/r2/api/s3/) tool of your choice.

:::

## Bucket-Level Operations

Create a bucket with the [`r2 bucket create`](/workers/wrangler/commands/#r2-bucket-create) command:

```sh
wrangler r2 bucket create your-bucket-name
```

:::note

- Bucket names can only contain lowercase letters (a-z), numbers (0-9), and hyphens (-).
- Bucket names cannot begin or end with a hyphen.
- Bucket names can only be between 3-63 characters in length.

The placeholder text is only for the example.

:::

List buckets in the current account with the [`r2 bucket list`](/workers/wrangler/commands/#r2-bucket-list) command:

```sh
wrangler r2 bucket list
```

Delete a bucket with the [`r2 bucket delete`](/workers/wrangler/commands/#r2-bucket-delete) command. Note that the bucket must be empty and all objects must be deleted.

```sh
wrangler r2 bucket delete BUCKET_TO_DELETE
```

## Notes

- Bucket names and buckets are not public by default. To allow public access to a bucket, refer to [Public buckets](/r2/buckets/public-buckets/).
- For information on controlling access to your R2 bucket with Cloudflare Access, refer to [Protect an R2 Bucket with Cloudflare Access](/r2/tutorials/cloudflare-access/).
- Invalid (unauthorized) access attempts to private buckets do not incur R2 operations charges against that bucket. Refer to the [R2 pricing FAQ](/r2/pricing/#frequently-asked-questions) to understand what operations are billed vs. not billed.

---

# Event notifications

URL: https://developers.cloudflare.com/r2/buckets/event-notifications/

Event notifications send messages to your [queue](/queues/) when data in your R2 bucket changes. You can consume these messages with a [consumer Worker](/queues/reference/how-queues-works/#create-a-consumer-worker) or [pull over HTTP](/queues/configuration/pull-consumers/) from outside of Cloudflare Workers.

## Get started with event notifications

### Prerequisites

Before getting started, you will need:

- An existing R2 bucket. If you do not already have an existing R2 bucket, refer to [Create buckets](/r2/buckets/create-buckets/).
- An existing queue. If you do not already have a queue, refer to [Create a queue](/queues/get-started/#2-create-a-queue).
- A [consumer Worker](/queues/reference/how-queues-works/#create-a-consumer-worker) or [HTTP pull](/queues/configuration/pull-consumers/) enabled on your Queue.

### Enable event notifications via Dashboard

1. From the Cloudflare dashboard, select **R2** from the sidebar.
2. Select the bucket you'd like to add an event notification rule to.
3. Switch to the **Settings** tab, then scroll down to the **Event notifications** card.
4. Select **Add notification** and choose the queue you'd like to receive notifications and the [type of events](/r2/buckets/event-notifications/#event-types) that will trigger them.
5. Select **Add notification**.

### Enable event notifications via Wrangler

#### Set up Wrangler

To begin, install [`npm`](https://docs.npmjs.com/getting-started). Then [install Wrangler, the Developer Platform CLI](/workers/wrangler/install-and-update/).

#### Enable event notifications on your R2 bucket

Log in to Wrangler with the [`wrangler login` command](/workers/wrangler/commands/#login). Then add an [event notification rule](/r2/buckets/event-notifications/#event-notification-rules) to your bucket by running the [`r2 bucket notification create` command](/workers/wrangler/commands/#r2-bucket-notification-create).

```sh
npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME>
```

To add filtering based on `prefix` or `suffix` use the `--prefix` or `--suffix` flag, respectively.

```sh
# Filter using prefix
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --prefix "<PREFIX_VALUE>"

# Filter using suffix
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --suffix "<SUFFIX_VALUE>"

# Filter using prefix and suffix. Both the conditions will be used for filtering
$ npx wrangler r2 bucket notification create <BUCKET_NAME> --event-type <EVENT_TYPE> --queue <QUEUE_NAME> --prefix "<PREFIX_VALUE>" --suffix "<SUFFIX_VALUE>"
```

For a more complete step-by-step example, refer to the [Log and store upload events in R2 with event notifications](/r2/tutorials/upload-logs-event-notifications/) example.

## Event notification rules

Event notification rules determine the [event types](/r2/buckets/event-notifications/#event-types) that trigger notifications and optionally enable filtering based on object `prefix` and `suffix`. You can have up to 100 event notification rules per R2 bucket.

## Event types

<table>
	<tbody>
		<th style="width:25%">Event type</th>
		<th style="width:50%">Description</th>
		<th style="width:25%">Trigger actions</th>
		<tr>
			<td>
				<code>object-create</code>
			</td>
			<td>
				Triggered when new objects are created or existing objects are
				overwritten.
			</td>
			<td>
				<ul>
					<li>
						<code>PutObject</code>
					</li>
					<li>
						<code>CopyObject</code>
					</li>
					<li>
						<code>CompleteMultipartUpload</code>
					</li>
				</ul>
			</td>
		</tr>
		<tr>
			<td>
				<code>object-delete</code>
			</td>
			<td>Triggered when an object is explicitly removed from the bucket.</td>
			<td>
				<ul>
					<li>
						<code>DeleteObject</code>
					</li>
					<li>
						<code>LifecycleDeletion</code>
					</li>
				</ul>
			</td>
		</tr>
	</tbody>
</table>

## Message format

Queue consumers receive notifications as [Messages](/queues/configuration/javascript-apis/#message). The following is an example of the body of a message that a consumer Worker will receive:

```json
{
	"account": "3f4b7e3dcab231cbfdaa90a6a28bd548",
	"action": "CopyObject",
	"bucket": "my-bucket",
	"object": {
		"key": "my-new-object",
		"size": 65536,
		"eTag": "c846ff7a18f28c2e262116d6e8719ef0"
	},
	"eventTime": "2024-05-24T19:36:44.379Z",
	"copySource": {
		"bucket": "my-bucket",
		"object": "my-original-object"
	}
}
```

### Properties

<table>
	<tbody>
		<th style="width:22%">Property</th>
		<th style="width:18%">Type</th>
		<th style="width:60%">Description</th>
		<tr>
			<td>
				<code>account</code>
			</td>
			<td>String</td>
			<td>The Cloudflare account ID that the event is associated with.</td>
		</tr>
		<tr>
			<td>
				<code>action</code>
			</td>
			<td>String</td>
			<td>
				The type of action that triggered the event notification. Example
				actions include: <code>PutObject</code>, <code>CopyObject</code>,{" "}
				<code>CompleteMultipartUpload</code>, <code>DeleteObject</code>.
			</td>
		</tr>
		<tr>
			<td>
				<code>bucket</code>
			</td>
			<td>String</td>
			<td>The name of the bucket where the event occurred.</td>
		</tr>
		<tr>
			<td>
				<code>object</code>
			</td>
			<td>Object</td>
			<td>
				A nested object containing details about the object involved in the
				event.
			</td>
		</tr>
		<tr>
			<td>
				<code>object.key</code>
			</td>
			<td>String</td>
			<td>The key (or name) of the object within the bucket.</td>
		</tr>
		<tr>
			<td>
				<code>object.size</code>
			</td>
			<td>Number</td>
			<td>
				The size of the object in bytes. Note: not present for object-delete
				events.
			</td>
		</tr>
		<tr>
			<td>
				<code>object.eTag</code>
			</td>
			<td>String</td>
			<td>
				The entity tag (eTag) of the object. Note: not present for object-delete
				events.
			</td>
		</tr>
		<tr>
			<td>
				<code>eventTime</code>
			</td>
			<td>String</td>
			<td>The time when the action that triggered the event occurred.</td>
		</tr>
		<tr>
			<td>
				<code>copySource</code>
			</td>
			<td>Object</td>
			<td>
				A nested object containing details about the source of a copied object.
				Note: only present for events triggered by <code>CopyObject</code>.
			</td>
		</tr>
		<tr>
			<td>
				<code>copySource.bucket</code>
			</td>
			<td>String</td>
			<td>The bucket that contained the source object.</td>
		</tr>
		<tr>
			<td>
				<code>copySource.object</code>
			</td>
			<td>String</td>
			<td>The name of the source object.</td>
		</tr>
	</tbody>
</table>

## Notes

- Queues [per-queue message throughput](/queues/platform/limits/) is currently 5,000 messages per second. If your workload produces more than 5,000 notifications per second, we recommend splitting notification rules across multiple queues.
- Rules without prefix/suffix apply to all objects in the bucket.
- Overlapping or conflicting rules that could trigger multiple notifications for the same event are not allowed. For example, if you have an `object-create` (or `PutObject` action) rule without a prefix and suffix, then adding another `object-create` (or `PutObject` action) rule with a prefix like `images/` could trigger more than one notification for a single upload, which is invalid.

---

# Buckets

URL: https://developers.cloudflare.com/r2/buckets/

import { DirectoryListing } from "~/components"

With object storage, all of your objects are stored in buckets. Buckets do not contain folders that group the individual files, but instead, buckets have a flat structure which simplifies the way you access and retrieve the objects in your bucket.

Learn more about bucket level operations from the items below.

<DirectoryListing />

---

# Object lifecycles

URL: https://developers.cloudflare.com/r2/buckets/object-lifecycles/

Object lifecycles determine the retention period of objects uploaded to your bucket and allow you to specify when objects should transition from Standard storage to Infrequent Access storage.

A lifecycle configuration is a collection of lifecycle rules that define actions to apply to objects during their lifetime.

For example, you can create an object lifecycle rule to delete objects after 90 days, or you can set a rule to transition objects to Infrequent Access storage after 30 days.

## Behavior

- Objects will typically be removed from a bucket within 24 hours of the `x-amz-expiration` value.
- When a lifecycle configuration is applied that deletes objects, newly uploaded objects' `x-amz-expiration` value immediately reflects the expiration based on the new rules, but existing objects may experience a delay. Most objects will be transitioned within 24 hours but may take longer depending on the number of objects in the bucket. While objects are being migrated, you may see old applied rules from the previous configuration.
- An object is no longer billable once it has been deleted.
- Buckets have a default lifecycle rule to expire multipart uploads seven days after initiation.
- When an object is transitioned from Standard storage to Infrequent Access storage, a [Class A operation](/r2/pricing/#class-a-operations) is incurred.
- When rules conflict and specify both a storage class transition and expire transition within a 24-hour period, the expire (or delete) lifecycle transition takes precedence over transitioning storage class.

## Configure lifecycle rules for your bucket

When you create an object lifecycle rule, you can specify which prefix you would like it to apply to.

- Note that object lifecycles currently has a 1000 rule maximum.
- Managing object lifecycles is a bucket-level action, and requires an API token with the [`Workers R2 Storage Write`](/r2/api/tokens/#permission-groups) permission group.

### Dashboard

1. From the Cloudflare dashboard, select **R2**.
2. Locate and select your bucket from the list.
3. From the bucket page, select **Settings**.
4. Under **Object lifecycle rules**, select **Add rule**.
5. Fill out the fields for the new rule.
6. When you are done, select **Add rule**.

### Wrangler

1. Install [`npm`](https://docs.npmjs.com/getting-started).
2. Install [Wrangler, the Developer Platform CLI](/workers/wrangler/install-and-update/).
3. Log in to Wrangler with the [`wrangler login` command](/workers/wrangler/commands/#login).
4. Add a lifecycle rule to your bucket by running the [`r2 bucket lifecycle add` command](/workers/wrangler/commands/#r2-bucket-lifecycle-add).

```sh
npx wrangler r2 bucket lifecycle add <BUCKET_NAME> [OPTIONS]
```

Alternatively you can set the entire lifecycle configuration for a bucket from a JSON file using the [`r2 bucket lifecycle set` command](/workers/wrangler/commands/#r2-bucket-lifecycle-set).

```sh
npx wrangler r2 bucket lifecycle set <BUCKET_NAME> --file <FILE_PATH>
```

The JSON file should be in the format of the request body of the [put object lifecycle configuration API](/api/resources/r2/subresources/buckets/subresources/lifecycle/methods/update/).

### S3 API

Below is an example of configuring a lifecycle configuration (a collection of lifecycle rules) with different sets of rules for different potential use cases.

```js title="Configure the S3 client to interact with R2"
const client = new S3({
	endpoint: "https://<account_id>.r2.cloudflarestorage.com",
	credentials: {
		accessKeyId: "<access_key_id>",
		secretAccessKey: "<access_key_secret>",
	},
	region: "auto",
});
```

```javascript title="Set the lifecycle configuration for a bucket"
await client
	.putBucketLifecycleConfiguration({
		Bucket: "testBucket",
		LifecycleConfiguration: {
			Rules: [
				// Example: deleting objects on a specific date
				// Delete 2019 documents in 2024
				{
					ID: "Delete 2019 Documents",
					Status: "Enabled",
					Filter: {
						Prefix: "2019/",
					},
					Expiration: {
						Date: new Date("2024-01-01"),
					},
				},
				// Example: transitioning objects to Infrequent Access storage by age
				// Transition objects older than 30 days to Infrequent Access storage
				{
					ID: "Transition Objects To Infrequent Access",
					Status: "Enabled",
					Transitions: [
						{
							Days: 30,
							StorageClass: "STANDARD_IA",
						},
					],
				},
				// Example: deleting objects by age
				// Delete logs older than 90 days
				{
					ID: "Delete Old Logs",
					Status: "Enabled",
					Filter: {
						Prefix: "logs/",
					},
					Expiration: {
						Days: 90,
					},
				},
				// Example: abort all incomplete multipart uploads after a week
				{
					ID: "Abort Incomplete Multipart Uploads",
					Status: "Enabled",
					AbortIncompleteMultipartUpload: {
						DaysAfterInitiation: 7,
					},
				},
				// Example: abort user multipart uploads after a day
				{
					ID: "Abort User Incomplete Multipart Uploads",
					Status: "Enabled",
					Filter: {
						Prefix: "useruploads/",
					},
					AbortIncompleteMultipartUpload: {
						// For uploads matching the prefix, this rule will take precedence
						// over the one above due to its earlier expiration.
						DaysAfterInitiation: 1,
					},
				},
			],
		},
	})
	.promise();
```

## Get lifecycle rules for your bucket

### Wrangler

To get the list of lifecycle rules associated with your bucket, run the [`r2 bucket lifecycle list` command](/workers/wrangler/commands/#r2-bucket-lifecycle-list).

```sh
npx wrangler r2 bucket lifecycle list <BUCKET_NAME>
```

### S3 API

```js
import S3 from "aws-sdk/clients/s3.js";

// Configure the S3 client to talk to R2.
const client = new S3({
	endpoint: "https://<account_id>.r2.cloudflarestorage.com",
	credentials: {
		accessKeyId: "<access_key_id>",
		secretAccessKey: "<access_key_secret>",
	},
	region: "auto",
});

// Get lifecycle configuration for bucket
console.log(
	await client
		.getBucketLifecycleConfiguration({
			Bucket: "bucketName",
		})
		.promise(),
);
```

## Delete lifecycle rules from your bucket

### Dashboard

1. From the Cloudflare dashboard, select **R2**.
2. Locate and select your bucket from the list.
3. From the bucket page, select **Settings**.
4. Under **Object lifecycle rules**, select the rules you would like to delete.
5. When you are done, select **Delete rule(s)**.

### Wrangler

To remove a specific lifecycle rule from your bucket, run the [`r2 bucket lifecycle remove` command](/workers/wrangler/commands/#r2-bucket-lifecycle-remove).

```sh
npx wrangler r2 bucket lifecycle remove <BUCKET_NAME> --id <RULE_ID>
```

### S3 API

```js
import S3 from "aws-sdk/clients/s3.js";

// Configure the S3 client to talk to R2.
const client = new S3({
	endpoint: "https://<account_id>.r2.cloudflarestorage.com",
	credentials: {
		accessKeyId: "<access_key_id>",
		secretAccessKey: "<access_key_secret>",
	},
	region: "auto",
});

// Delete lifecycle configuration for bucket
await client
	.deleteBucketLifecycle({
		Bucket: "bucketName",
	})
	.promise();
```

---

# Public buckets

URL: https://developers.cloudflare.com/r2/buckets/public-buckets/

import { Render } from "~/components";

Public Bucket is a feature that allows users to expose the contents of their R2 buckets directly to the Internet. By default, buckets are never publicly accessible and will always require explicit user permission to enable.

Public buckets can be set up in either one of two ways:

- Expose your bucket as a custom domain under your control.
- Expose your bucket using a Cloudflare-managed `https://r2.dev` subdomain for non-production use cases.

These options can be used independently. Enabling custom domains does not require enabling `r2.dev` access.

To use features like WAF custom rules, caching, access controls, or bot management, you must configure your bucket behind a custom domain. These capabilities are not available when using the `r2.dev` development url.

:::note

Currently, public buckets do not let you list the bucket contents at the root of your (sub) domain.

:::

## Custom domains

### Caching

Domain access through a custom domain allows you to use [Cloudflare Cache](/cache/) to accelerate access to your R2 bucket.

Configure your cache to use [Smart Tiered Cache](/cache/how-to/tiered-cache/#smart-tiered-cache) to have a single upper tier data center next to your R2 bucket.

:::note

By default, only certain file types are cached. To cache all files in your bucket, you must set a Cache Everything page rule.

For more information on default Cache behavior and how to customize it, refer to [Default Cache Behavior](/cache/concepts/default-cache-behavior/#default-cached-file-extensions)

:::

### Access control

To restrict access to your custom domain's bucket, use Cloudflare's existing security products.

- [Cloudflare Zero Trust Access](/cloudflare-one/applications/configure-apps): Protects buckets that should only be accessible by your teammates. Refer to [Protect an R2 Bucket with Cloudflare Access](/r2/tutorials/cloudflare-access/) tutorial for more information.
- [Cloudflare WAF Token Authentication](/waf/custom-rules/use-cases/configure-token-authentication/): Restricts access to documents, files, and media to selected users by providing them with an access token.

:::caution

Disable public access to your [`r2.dev` subdomain](#disable-public-development-url) when using products like WAF or Cloudflare Access. If you do not disable public access, your bucket will remain publicly available through your `r2.dev` subdomain.

:::

### Minimum TLS Version

To specify the minimum TLS version of a custom hostname of an R2 bucket, you can issue an API call to edit [R2 custom domain settings](/api/resources/r2/subresources/buckets/subresources/domains/subresources/custom/methods/update/).

## Add your domain to Cloudflare

The domain being used must have been added as a [zone](/fundamentals/concepts/accounts-and-zones/#zones) in the same account as the R2 bucket.

- If your domain is already managed by Cloudflare, you can proceed to [Connect a bucket to a custom domain](/r2/buckets/public-buckets/#connect-a-bucket-to-a-custom-domain).
- If your domain is not managed by Cloudflare, you need to set it up using a [partial (CNAME) setup](/dns/zone-setups/partial-setup/) to add it to your account.

Once the domain exists in your Cloudflare account (regardless of setup type), you can link it to your bucket.

## Connect a bucket to a custom domain

<Render file="custom-domain-steps" />

To view the added DNS record, select **...** next to the connected domain and select **Manage DNS**.

:::note

If the zone is on an Enterprise plan, make sure that you [release the zone hold](/fundamentals/account/account-security/zone-holds/#release-zone-holds) before adding the custom domain.

A zone hold would prevent the custom subdomain from activating.

:::

## Disable domain access

Disabling a domain will turn off public access to your bucket through that domain. Access through other domains or the managed `r2.dev` subdomain are unaffected.
The specified domain will also remain connected to R2 until you remove it or delete the bucket.

To disable a domain:

1. In **R2**, select the bucket you want to modify.
2. On the bucket page, Select **Settings**, go to **Custom Domains**.
3. Next to the domain you want to disable, select **...** and **Disable domain**.
4. The badge under **Access to Bucket** will update to **Not allowed**.

## Remove domain

Removing a custom domain will disconnect it from your bucket and delete its configuration from the dashboard. Your bucket will remain publicly accessible through any other enabled access method, but the domain will no longer appear in the connected domains list.

To remove a domain:

1. In **R2**, select the bucket you want to modify.
2. On the bucket page, Select **Settings**, go to **Custom Domains**.
3. Next to the domain you want to disable, select **...** and **Remove domain**.
4. Select ‘Remove domain’ in the confirmation window. This step also removes the CNAME record pointing to the domain. You can always add the domain again.

## Public development URL

Expose the contents of this R2 bucket to the internet through a Cloudflare-managed r2.dev subdomain. This endpoint is intended for non-production traffic.

:::note

Public access through `r2.dev` subdomains are rate limited and should only be used for development purposes.

To enable access management, Cache and bot management features, you must set up a custom domain when enabling public access to your bucket.

Avoid creating a CNAME record pointing to the `r2.dev` subdomain. This is an **unsupported access path**, and we cannot guarantee consistent reliability or performance. For production use, [add your domain to Cloudflare](#add-your-domain-to-cloudflare) instead.
:::

### Enable public development url

When you enable public development URL access for your bucket, its contents become available on the internet through a Cloudflare-managed `r2.dev` subdomain.

To enable access through `r2.dev` for your buckets:

1. In **R2**, select the bucket you want to modify.
2. On the bucket page, select **Settings**.
3. Under **Public Development URL**, select **Enable**.
4. In **Allow Public Access?**, confirm your choice by typing ‘allow’ to confirm and select **Allow**.
5. You can now access the bucket and its objects using the Public Bucket URL.

To verify that your bucket is publicly accessible, check that **Public URL Access** shows **Allowed** in you bucket settings.

### Disable public development url

Disabling public development URL access removes your bucket’s exposure through the `r2.dev` subdomain. The bucket and its objects will no longer be accessible via the Public Bucket URL.

If you have connected other domains, the bucket will remain accessible for those domains.

To disable public access for your bucket:

1. In **R2**, select the bucket you want to modify.
2. On the bucket page, select **Settings**.
3. Under **Public Development URL**, select **Disable**.
4. In **Disallow Public Access?**, type ‘disallow’ to confirm and select **Disallow**.

---

# Storage classes

URL: https://developers.cloudflare.com/r2/buckets/storage-classes/

import { Badge, Tabs, TabItem } from "~/components"

Storage classes allow you to trade off between the cost of storage and the cost of accessing data. Every object stored in R2 has an associated storage class.

All storage classes share the following characteristics:

* Compatible with Workers API, S3 API, and public buckets.
* 99.999999999% (eleven 9s) of annual durability.
* No minimum object size.

## Available storage classes

| Storage class                  | Minimum storage duration  | Data retrieval fees (processing) | Egress fees (data transfer to Internet)  |
|--------------------------------|---------------------------|----------------------------------|------------------------------------------|
| Standard                       | None                      | None                             | None                                     |
| Infrequent Access              | 30 days                   | Yes                              | None                                     |

For more information on how storage classes impact pricing, refer to [Pricing](/r2/pricing/).

### Standard storage

Standard storage is designed for data that is accessed frequently. This is the default storage class for new R2 buckets unless otherwise specified.

#### Example use cases

* Website and application data
* Media content (e.g., images, video)
* Storing large datasets for analysis and processing
* AI training data
* Other workloads involving frequently accessed data

### Infrequent Access storage <Badge text="Beta" variant="caution" size="small" />

:::note[Open Beta]


This feature is currently in beta. To report bugs or request features, go to the #r2 channel in the [Cloudflare Developer Discord](https://discord.cloudflare.com) or fill out the [feedback form](https://forms.gle/5FqffSHcsL8ifEG8A).


:::

Infrequent Access storage is ideal for data that is accessed less frequently. This storage class offers lower storage cost compared to Standard storage, but includes [retrieval fees](/r2/pricing/#data-retrieval) and a 30 day [minimum storage duration](/r2/pricing/#minimum-storage-duration) requirement.

:::note


For objects stored in Infrequent Access storage, you will be charged for the object for the minimum storage duration even if the object was deleted, moved, or replaced before the specified duration.


:::

#### Example use cases

* Long-term data archiving (for example, logs and historical records needed for compliance)
* Data backup and disaster recovery
* Long tail user-generated content

## Set default storage class for buckets

By setting the default storage class for a bucket, all objects uploaded into the bucket will automatically be assigned the selected storage class unless otherwise specified. Default storage class can be changed after bucket creation in the Dashboard.

To learn more about creating R2 buckets, refer to [Create new buckets](/r2/buckets/create-buckets/).

## Set storage class for objects

### Specify storage class during object upload

To learn more about how to specify the storage class for new objects, refer to the [Workers API](/r2/api/workers/) and [S3 API](/r2/api/s3/) documentation.

### Use object lifecycle rules to transition objects to Infrequent Access storage

:::note


Once an object is stored in Infrequent Access, it cannot be transitioned to Standard Access using lifecycle policies.


:::

To learn more about how to transition objects from Standard storage to Infrequent Access storage, refer to [Object lifecycles](/r2/buckets/object-lifecycles/).

## Change storage class for objects

You can change the storage class of an object which is already stored in R2 using the [`CopyObject` API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html).

Use the `x-amz-storage-class` header to change between `STANDARD` and `STANDARD_IA`.

An example of switching an object from `STANDARD` to `STANDARD_IA` using `aws cli` is shown below:

```sh
aws s3api copy-object \
  --endpoint-url https://<ACCONUT_ID>.r2.cloudflarestorage.com \
  --bucket bucket-name \
  --key path/to/object.txt \
  --copy-source /bucket-name/path/to/object.txt \
  --storage-class STANDARD_IA
```

- Refer to [aws CLI](/r2/examples/aws/aws-cli/) for more information on using `aws CLI`.
- Refer to [object-level operations](/r2/api/s3/api/#object-level-operations) for the full list of object-level API operations with R2-compatible S3 API.

---

# Data migration

URL: https://developers.cloudflare.com/r2/data-migration/

Quickly and easily migrate data from other cloud providers to R2. Explore each option further by navigating to their respective documentation page.

<table>
	<tbody>
		<th colspan="5" rowspan="1" style="width:160px">
			Name
		</th>
		<th colspan="5" rowspan="1">
			Description
		</th>
		<th colspan="5" rowspan="1">
			When to use
		</th>
		<tr>
			<td colspan="5" rowspan="1">
				<a href="/r2/data-migration/super-slurper/">Super Slurper</a>
			</td>
			<td colspan="5" rowspan="1">
				Quickly migrate large amounts of data from other cloud providers to R2.
			</td>
			<td colspan="5" rowspan="1">
				<ul>
					<li>For one-time, comprehensive transfers.</li>
				</ul>
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				<a href="/r2/data-migration/sippy/">Sippy</a>
			</td>
			<td colspan="5" rowspan="1">
				Incremental data migration, populating your R2 bucket as objects are
				requested.
			</td>
			<td colspan="5" rowspan="1">
				<ul>
					<li>For gradual migration that avoids upfront egress fees.</li>
					<li>
						To start serving frequently accessed objects from R2 without a full
						migration.
					</li>
				</ul>
			</td>
		</tr>
	</tbody>
</table>

For information on how to leverage these tools effectively, refer to [Migration Strategies](/r2/data-migration/migration-strategies/)

---

# Migration Strategies

URL: https://developers.cloudflare.com/r2/data-migration/migration-strategies/

import { Render } from "~/components";

You can use a combination of Super Slurper and Sippy to effectively migrate all objects with minimal downtime.

### When the source bucket is actively being read from / written to

1. Enable Sippy and start using the R2 bucket in your application.
   - This copies objects from your previous bucket into the R2 bucket on demand when they are requested by the application.
   - New uploads will go to the R2 bucket.
2. Use Super Slurper to trigger a one-off migration to copy the remaining objects into the R2 bucket.
   - In the **Destination R2 bucket** > **Overwrite files?**, select "Skip existing".

### When the source bucket is not being read often

1. Use Super Slurper to copy all objects to the R2 bucket.
   - Note that Super Slurper may skip some objects if they are uploaded after it lists the objects to be copied.
2. Enable Sippy on your R2 bucket, then start using the R2 bucket in your application.
   - New uploads will go to the R2 bucket.
   - Objects which were uploaded while Super Slurper was copying the objects will be copied on-demand (by Sippy) when they are requested by the application.

---

# Sippy

URL: https://developers.cloudflare.com/r2/data-migration/sippy/

import { Render } from "~/components";

Sippy is a data migration service that allows you to copy data from other cloud providers to R2 as the data is requested, without paying unnecessary cloud egress fees typically associated with moving large amounts of data.

Migration-specific egress fees are reduced by leveraging requests within the flow of your application where you would already be paying egress fees to simultaneously copy objects to R2.

## How it works

When enabled for an R2 bucket, Sippy implements the following migration strategy across [Workers](/r2/api/workers/), [S3 API](/r2/api/s3/), and [public buckets](/r2/buckets/public-buckets/):

- When an object is requested, it is served from your R2 bucket if it is found.
- If the object is not found in R2, the object will simultaneously be returned from your source storage bucket and copied to R2.
- All other operations, including put and delete, continue to work as usual.

## When is Sippy useful?

Using Sippy as part of your migration strategy can be a good choice when:

- You want to start migrating your data, but you want to avoid paying upfront egress fees to facilitate the migration of your data all at once.
- You want to experiment by serving frequently accessed objects from R2 to eliminate egress fees, without investing time in data migration.
- You have frequently changing data and are looking to conduct a migration while avoiding downtime. Sippy can be used to serve requests while [Super Slurper](/r2/data-migration/super-slurper/) can be used to migrate your remaining data.

If you are looking to migrate all of your data from an existing cloud provider to R2 at one time, we recommend using [Super Slurper](/r2/data-migration/super-slurper/).

## Get started with Sippy

Before getting started, you will need:

- An existing R2 bucket. If you don't already have one, refer to [Create buckets](/r2/buckets/create-buckets/).
- [API credentials](/r2/data-migration/sippy/#create-credentials-for-storage-providers) for your source object storage bucket.
- (Wrangler only) Cloudflare R2 Access Key ID and Secret Access Key with read and write permissions. For more information, refer to [Authentication](/r2/api/tokens/).

### Enable Sippy via the Dashboard

1. From the Cloudflare dashboard, select **R2** from the sidebar.
2. Select the bucket you'd like to migrate objects to.
3. Switch to the **Settings** tab, then scroll down to the **On Demand Migration** card.
4. Select **Enable** and enter details for the AWS / GCS bucket you'd like to migrate objects from. The credentials you enter must have permissions to read from this bucket. Cloudflare also recommends scoping your credentials to only allow reads from this bucket.
5. Select **Enable**.

### Enable Sippy via Wrangler

#### Set up Wrangler

To begin, install [`npm`](https://docs.npmjs.com/getting-started). Then [install Wrangler, the Developer Platform CLI](/workers/wrangler/install-and-update/).

#### Enable Sippy on your R2 bucket

Log in to Wrangler with the [`wrangler login` command](/workers/wrangler/commands/#login). Then run the [`r2 bucket sippy enable` command](/workers/wrangler/commands/#r2-bucket-sippy-enable):

```sh
npx wrangler r2 bucket sippy enable <BUCKET_NAME>
```

This will prompt you to select between supported object storage providers and lead you through setup.

### Enable Sippy via API

For information on required parameters and examples of how to enable Sippy, refer to the [API documentation](/api/resources/r2/subresources/buckets/subresources/sippy/methods/update/). For information about getting started with the Cloudflare API, refer to [Make API calls](/fundamentals/api/how-to/make-api-calls/).

:::note

If your bucket is setup with [jurisdictional restrictions](/r2/reference/data-location/#jurisdictional-restrictions), you will need to pass a `cf-r2-jurisdiction` request header with that jurisdiction. For example, `cf-r2-jurisdiction: eu`.

:::

### View migration metrics

When enabled, Sippy exposes metrics that help you understand the progress of your ongoing migrations.

<table>
	<tbody>
		<th colspan="5" rowspan="1" style="width:220px">
			Metric
		</th>
		<th colspan="5" rowspan="1">
			Description
		</th>
		<tr>
			<td colspan="5" rowspan="1">
				Requests served by Sippy
			</td>
			<td colspan="5" rowspan="1">
				The percentage of overall requests served by R2 over a period of time.{" "}
				<br />A higher percentage indicates that fewer requests need to be made
				to the source bucket.
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				Data migrated by Sippy
			</td>
			<td colspan="5" rowspan="1">
				The amount of data that has been copied from the source bucket to R2
				over a period of time. Reported in bytes.
			</td>
		</tr>
	</tbody>
</table>

To view current and historical metrics:

2. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
3. Go to the [R2 tab](https://dash.cloudflare.com/?to=/:account/r2) and select your bucket.
4. Select the **Metrics** tab.

You can optionally select a time window to query. This defaults to the last 24 hours.

## Disable Sippy on your R2 bucket

### Dashboard

1. From the Cloudflare dashboard, select **R2** from the sidebar.
2. Select the bucket you'd like to disable Sippy for.
3. Switch to the **Settings** tab and scroll down to the **On Demand Migration** card.
4. Press **Disable**.

### Wrangler

To disable Sippy, run the [`r2 bucket sippy disable` command](/workers/wrangler/commands/#r2-bucket-sippy-disable):

```sh
npx wrangler r2 bucket sippy disable <BUCKET_NAME>
```

### API

For more information on required parameters and examples of how to disable Sippy, refer to the [API documentation](/api/resources/r2/subresources/buckets/subresources/sippy/methods/delete/).

## Supported cloud storage providers

Cloudflare currently supports copying data from the following cloud object storage providers to R2:

- Amazon S3
- Google Cloud Storage (GCS)

## R2 API interactions

When Sippy is enabled, it changes the behavior of certain actions on your R2 bucket across [Workers](/r2/api/workers/), [S3 API](/r2/api/s3/), and [public buckets](/r2/buckets/public-buckets/).

<table>
	<tbody>
		<th colspan="5" rowspan="1" style="width:220px">
			Action
		</th>
		<th colspan="5" rowspan="1">
			New behavior
		</th>
		<tr>
			<td colspan="5" rowspan="1">
				GetObject
			</td>
			<td colspan="5" rowspan="1">
				Calls to GetObject will first attempt to retrieve the object from your
				R2 bucket. If the object is not present, the object will be served from
				the source storage bucket and simultaneously uploaded to the requested
				R2 bucket.
				<br />
				<br />
				Additional considerations:
				<ul>
					<li>
						Modifications to objects in the source bucket will not be reflected
						in R2 after the initial copy. Once an object is stored in R2, it
						will not be re-retrieved and updated.
					</li>
					<li>
						Only user-defined metadata that is prefixed by{" "}
						<code>x-amz-meta-</code> in the HTTP response will be migrated.
						Remaining metadata will be omitted.
					</li>
					<li>
						For larger objects (greater than 199 MiB), multiple GET requests may
						be required to fully copy the object to R2.
					</li>
					<li>
						If there are multiple simultaneous GET requests for an object which
						has not yet been fully copied to R2, Sippy may fetch the object from
						the source storage bucket multiple times to serve those requests.
					</li>
				</ul>
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				HeadObject
			</td>
			<td colspan="5" rowspan="1">
				Behaves similarly to GetObject, but only retrieves object metadata. Will
				not copy objects to the requested R2 bucket.
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				PutObject
			</td>
			<td colspan="5" rowspan="1">
				No change to behavior. Calls to PutObject will add objects to the
				requested R2 bucket.
			</td>
		</tr>
		<tr>
			<td colspan="5" rowspan="1">
				DeleteObject
			</td>
			<td colspan="5" rowspan="1">
				No change to behavior. Calls to DeleteObject will delete objects in the
				requested R2 bucket.
				<br />
				<br />
				Additional considerations:
				<ul>
					<li>
						If deletes to objects in R2 are not also made in the source storage
						bucket, subsequent GetObject requests will result in objects being
						retrieved from the source bucket and copied to R2.
					</li>
				</ul>
			</td>
		</tr>
	</tbody>
</table>

Actions not listed above have no change in behavior. For more information, refer to [Workers API reference](/r2/api/workers/workers-api-reference/) or [S3 API compatibility](/r2/api/s3/api/).

## Create credentials for storage providers

### Amazon S3

To copy objects from Amazon S3, Sippy requires access permissions to your bucket. While you can use any AWS Identity and Access Management (IAM) user credentials with the correct permissions, Cloudflare recommends you create a user with a narrow set of permissions.

To create credentials with the correct permissions:

1. Log in to your AWS IAM account.
2. Create a policy with the following format and replace `<BUCKET_NAME>` with the bucket you want to grant access to:

```json
{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": ["s3:GetObject"],
			"Resource": ["arn:aws:s3:::<BucketName>/*"]
		}
	]
}
```

3. Create a new user and attach the created policy to that user.

You can now use both the Access Key ID and Secret Access Key when enabling Sippy.

### Google Cloud Storage

To copy objects from Google Cloud Storage (GCS), Sippy requires access permissions to your bucket. Cloudflare recommends using the Google Cloud predefined `Storage Object Viewer` role.

To create credentials with the correct permissions:

1. Log in to your Google Cloud console.
2. Go to **IAM & Admin** > **Service Accounts**.
3. Create a service account with the predefined `Storage Object Viewer` role.
4. Go to the **Keys** tab of the service account you created.
5. Select **Add Key** > **Create a new key** and download the JSON key file.

You can now use this JSON key file when enabling Sippy via Wrangler or API.

## Caveats

### ETags

<Render file="migrator-etag-caveat" params={{ one: "Sippy" }} />

---

# Super Slurper

URL: https://developers.cloudflare.com/r2/data-migration/super-slurper/

import { InlineBadge, Render } from "~/components";

Super Slurper allows you to quickly and easily copy objects from other cloud providers to an R2 bucket of your choice.

Migration jobs:

- Preserve custom object metadata from source bucket by copying them on the migrated objects on R2.
- Do not delete any objects from source bucket.
- Use TLS encryption over HTTPS connections for safe and private object transfers.

## When to use Super Slurper

Using Super Slurper as part of your strategy can be a good choice if the cloud storage bucket you are migrating consists primarily of objects less than 1 TB. Objects greater than 1 TB will be skipped and need to be copied separately.

For migration use cases that do not meet the above criteria, we recommend using tools such as [rclone](/r2/examples/rclone/).

## Use Super Slurper to migrate data to R2

1. From the Cloudflare dashboard, select **R2** > **Data Migration**.
2. Select **Migrate files**.
3. Select the source cloud storage provider that you will be migrating data from.
4. Enter your source bucket name and associated credentials and select **Next**.
5. Enter your R2 bucket name and associated credentials and select **Next**.
6. After you finish reviewing the details of your migration, select **Migrate files**.

You can view the status of your migration job at any time by selecting your migration from **Data Migration** page.

### Source bucket options

#### Bucket sub path (optional)

This setting specifies the prefix within the source bucket where objects will be copied from.

### Destination R2 bucket options

#### Overwrite files?

This setting determines what happens when an object being copied from the source storage bucket matches the path of an existing object in the destination R2 bucket. There are two options:

- Overwrite (default)
- Skip

## Supported cloud storage providers

Cloudflare currently supports copying data from the following cloud object storage providers to R2:

- Amazon S3
- Cloudflare R2
- Google Cloud Storage (GCS)
- All S3-compatible storage providers

### Tested S3-compatible storage providers

The following S3-compatible storage providers have been tested and verified to work with Super Slurper:

- Backblaze B2
- DigitalOcean Spaces
- Scaleway Object Storage
- Wasabi Cloud Object Storage

Super Slurper should support transfers from all S3-compatible storage providers, but the ones listed have been explicitly tested.

:::note

Have you tested and verified another S3-compatible provider? [Open a pull request](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/r2/data-migration/super-slurper.mdx) or [create a GitHub issue](https://github.com/cloudflare/cloudflare-docs/issues/new).

:::

## Create credentials for storage providers

### Amazon S3

To copy objects from Amazon S3, Super Slurper requires access permissions to your S3 bucket. While you can use any AWS Identity and Access Management (IAM) user credentials with the correct permissions, Cloudflare recommends you create a user with a narrow set of permissions.

To create credentials with the correct permissions:

1. Log in to your AWS IAM account.
2. Create a policy with the following format and replace `<BUCKET_NAME>` with the bucket you want to grant access to:

```json
{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Action": ["s3:Get*", "s3:List*"],
			"Resource": ["arn:aws:s3:::<BUCKET_NAME>", "arn:aws:s3:::<BUCKET_NAME>/*"]
		}
	]
}
```

3. Create a new user and attach the created policy to that user.

You can now use both the Access Key ID and Secret Access Key when defining your source bucket.

### Google Cloud Storage

To copy objects from Google Cloud Storage (GCS), Super Slurper requires access permissions to your GCS bucket. You can use the Google Cloud predefined `Storage Admin` role, but Cloudflare recommends creating a custom role with a narrower set of permissions.

To create a custom role with the necessary permissions:

1. Log in to your Google Cloud console.
2. Go to **IAM & Admin** > **Roles**.
3. Find the `Storage Object Viewer` role and select **Create role from this role**.
4. Give your new role a name.
5. Select **Add permissions** and add the `storage.buckets.get` permission.
6. Select **Create**.

To create credentials with your custom role:

1. Log in to your Google Cloud console.
2. Go to **IAM & Admin** > **Service Accounts**.
3. Create a service account with the your custom role.
4. Go to the **Keys** tab of the service account you created.
5. Select **Add Key** > **Create a new key** and download the JSON key file.

You can now use this JSON key file when enabling Super Slurper.

## Caveats

### ETags

<Render file="migrator-etag-caveat" params={{ one: "Super Slurper" }} />

### Archive storage classes

Objects stored using AWS S3 [archival storage classes](https://aws.amazon.com/s3/storage-classes/#Archive) will be skipped and need to be copied separately. Specifically:

- Files stored using S3 Glacier tiers (not including Glacier Instant Retrieval) will be skipped and logged in the migration log.
- Files stored using S3 Intelligent Tiering and placed in Deep Archive tier will be skipped and logged in the migration log.

---

# Authenticate against R2 API using auth tokens

URL: https://developers.cloudflare.com/r2/examples/authenticate-r2-auth-tokens/

import { Tabs, TabItem } from '~/components';

The following example shows how to authenticate against R2 using the S3 API and an API token. 

:::note
For providing secure access to bucket objects for anonymous users, we recommend using [pre-signed URLs](/r2/api/s3/presigned-urls/) instead.

Pre-signed URLs do not require users to be a member of your organization and enable programmatic application directly.
:::

Ensure you have set the following environmental variables prior to running either example:

```sh
export R2_ACCOUNT_ID=your_account_id
export R2_ACCESS_KEY_ID=your_access_key_id
export R2_SECRET_ACCESS_KEY=your_secret_access_key
export R2_BUCKET_NAME=your_bucket_name
```

<Tabs>
  <TabItem label="JavaScript" icon="seti:javascript">
    Install the `aws-sdk` package for the S3 API:

    ```sh
    npm install aws-sdk
    ```

    ```javascript
    const AWS = require('aws-sdk');
    const crypto = require('crypto');

    const ACCOUNT_ID = process.env.R2_ACCOUNT_ID;
    const ACCESS_KEY_ID = process.env.R2_ACCESS_KEY_ID;
    const SECRET_ACCESS_KEY = process.env.R2_SECRET_ACCESS_KEY;
    const BUCKET_NAME = process.env.R2_BUCKET_NAME;

    // Hash the secret access key
    const hashedSecretKey = crypto.createHash('sha256').update(SECRET_ACCESS_KEY).digest('hex');

    // Configure the S3 client for Cloudflare R2
    const s3Client = new AWS.S3({
        endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
        accessKeyId: ACCESS_KEY_ID,
        secretAccessKey: hashedSecretKey,
        signatureVersion: 'v4',
        region: 'auto' // Cloudflare R2 doesn't use regions, but this is required by the SDK
    });

    // Specify the object key
    const objectKey = '2024/08/02/ingested_0001.parquet';

    // Function to fetch the object
    async function fetchObject() {
        try {
            const params = {
                Bucket: BUCKET_NAME,
                Key: objectKey
            };

            const data = await s3Client.getObject(params).promise();
            console.log('Successfully fetched the object');

            // Process the data as needed
            // For example, to get the content as a Buffer:
            // const content = data.Body;

            // Or to save the file (requires 'fs' module):
            // const fs = require('fs').promises;
            // await fs.writeFile('ingested_0001.parquet', data.Body);

        } catch (error) {
            console.error('Failed to fetch the object:', error);
        }
    }

    fetchObject();
    ```
    </TabItem>
    <TabItem label="Python" icon="seti:python">

    Install the `boto3` S3 API client:

    ```sh
    pip install boto3
    ```

    Run the following Python script with `python3 get_r2_object.py`. Ensure you change `object_key` to point to an existing file in your R2 bucket.

    ```python title="get_r2_object.py"
    import os
    import hashlib
    import boto3
    from botocore.client import Config

    ACCOUNT_ID = os.environ.get('R2_ACCOUNT_ID')
    ACCESS_KEY_ID = os.environ.get('R2_ACCESS_KEY_ID')
    SECRET_ACCESS_KEY = os.environ.get('R2_SECRET_ACCESS_KEY')
    BUCKET_NAME = os.environ.get('R2_BUCKET_NAME')

    # Hash the secret access key using SHA-256
    hashed_secret_key = hashlib.sha256(SECRET_ACCESS_KEY.encode()).hexdigest()

    # Configure the S3 client for Cloudflare R2
    s3_client = boto3.client('s3',
        endpoint_url=f'https://{ACCOUNT_ID}.r2.cloudflarestorage.com',
        aws_access_key_id=ACCESS_KEY_ID,
        aws_secret_access_key=hashed_secret_key,
        config=Config(signature_version='s3v4')
    )

    # Specify the object key
    object_key = '2024/08/02/ingested_0001.parquet'

    try:
        # Fetch the object
        response = s3_client.get_object(Bucket=BUCKET_NAME, Key=object_key)

        print('Successfully fetched the object')

        # Process the response content as needed
        # For example, to read the content:
        # object_content = response['Body'].read()

        # Or to save the file:
        # with open('ingested_0001.parquet', 'wb') as f:
        #     f.write(response['Body'].read())

    except Exception as e:
        print(f'Failed to fetch the object. Error: {str(e)}')
    ```
    </TabItem>
    <TabItem label="Go" icon="seti:go">

    Use `go get` to add the `aws-sdk-go-v2` packages to your Go project:

    ```sh
    go get github.com/aws/aws-sdk-go-v2
    go get github.com/aws/aws-sdk-go-v2/config
    go get github.com/aws/aws-sdk-go-v2/credentials
    go get github.com/aws/aws-sdk-go-v2/service/s3
    ```

    Run the following Go application as a script with `go run main.go`. Ensure you change `objectKey` to point to an existing file in your R2 bucket.

    ```go
    package main

    import (
        "context"
        "crypto/sha256"
        "encoding/hex"
        "fmt"
        "io"
        "log"
        "os"

        "github.com/aws/aws-sdk-go-v2/aws"
        "github.com/aws/aws-sdk-go-v2/config"
        "github.com/aws/aws-sdk-go-v2/credentials"
        "github.com/aws/aws-sdk-go-v2/service/s3"
    )

    func main() {
        // Load environment variables
        accountID := os.Getenv("R2_ACCOUNT_ID")
        accessKeyID := os.Getenv("R2_ACCESS_KEY_ID")
        secretAccessKey := os.Getenv("R2_SECRET_ACCESS_KEY")
        bucketName := os.Getenv("R2_BUCKET_NAME")

        // Hash the secret access key
        hasher := sha256.New()
        hasher.Write([]byte(secretAccessKey))
        hashedSecretKey := hex.EncodeToString(hasher.Sum(nil))

        // Configure the S3 client for Cloudflare R2
        r2Resolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
            return aws.Endpoint{
                URL: fmt.Sprintf("https://%s.r2.cloudflarestorage.com", accountID),
            }, nil
        })

        cfg, err := config.LoadDefaultConfig(context.TODO(),
            config.WithEndpointResolverWithOptions(r2Resolver),
            config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(accessKeyID, hashedSecretKey, "")),
            config.WithRegion("auto"), // Cloudflare R2 doesn't use regions, but this is required by the SDK
        )
        if err != nil {
            log.Fatalf("Unable to load SDK config, %v", err)
        }

        // Create an S3 client
        client := s3.NewFromConfig(cfg)

        // Specify the object key
        objectKey := "2024/08/02/ingested_0001.parquet"

        // Fetch the object
        output, err := client.GetObject(context.TODO(), &s3.GetObjectInput{
            Bucket: aws.String(bucketName),
            Key:    aws.String(objectKey),
        })
        if err != nil {
            log.Fatalf("Unable to fetch object, %v", err)
        }
        defer output.Body.Close()

        fmt.Println("Successfully fetched the object")

        // Process the object content as needed
        // For example, to save the file:
        // file, err := os.Create("ingested_0001.parquet")
        // if err != nil {
        // 	log.Fatalf("Unable to create file, %v", err)
        // }
        // defer file.Close()
        // _, err = io.Copy(file, output.Body)
        // if err != nil {
        // 	log.Fatalf("Unable to write file, %v", err)
        // }

        // Or to read the content:
        content, err := io.ReadAll(output.Body)
        if err != nil {
            log.Fatalf("Unable to read object content, %v", err)
        }
        fmt.Printf("Object content length: %d bytes\n", len(content))
    }
    ```
    </TabItem>
  </Tabs>

---

# Use the Cache API

URL: https://developers.cloudflare.com/r2/examples/cache-api/

Use the [Cache API](/workers/runtime-apis/cache/) to store R2 objects in Cloudflare's cache.

:::note


You will need to [connect a custom domain](/workers/configuration/routing/custom-domains/) or [route](/workers/configuration/routing/routes/) to your Worker in order to use the Cache API. Cache API operations in the Cloudflare Workers dashboard editor, Playground previews, and any `*.workers.dev` deployments will have no impact.


:::

```js

export default {
  async fetch(request, env, context) {
    try {
      const url = new URL(request.url);

      // Construct the cache key from the cache URL
      const cacheKey = new Request(url.toString(), request);
      const cache = caches.default;

      // Check whether the value is already available in the cache
      // if not, you will need to fetch it from R2, and store it in the cache
      // for future access
      let response = await cache.match(cacheKey);

      if (response) {
        console.log(`Cache hit for: ${request.url}.`);
        return response;
      }

      console.log(
        `Response for request url: ${request.url} not present in cache. Fetching and caching request.`
      );

      // If not in cache, get it from R2
      const objectKey = url.pathname.slice(1);
      const object = await env.MY_BUCKET.get(objectKey);
      if (object === null) {
        return new Response('Object Not Found', { status: 404 });
      }

      // Set the appropriate object headers
      const headers = new Headers();
      object.writeHttpMetadata(headers);
      headers.set('etag', object.httpEtag);

      // Cache API respects Cache-Control headers. Setting s-max-age to 10
      // will limit the response to be in cache for 10 seconds max
      // Any changes made to the response here will be reflected in the cached value
      headers.append('Cache-Control', 's-maxage=10');

      response = new Response(object.body, {
        headers,
      });

      // Store the fetched response as cacheKey
      // Use waitUntil so you can return the response without blocking on
      // writing to cache
      context.waitUntil(cache.put(cacheKey, response.clone()));

      return response;
    } catch (e) {
      return new Response('Error thrown ' + e.message);
    }
  },
};
```

---

# Examples

URL: https://developers.cloudflare.com/r2/examples/

import { DirectoryListing, GlossaryTooltip } from "~/components";

Explore the following <GlossaryTooltip term="code example">examples</GlossaryTooltip> of how to use SDKs and other tools with R2.

<DirectoryListing />

---

# Rclone

URL: https://developers.cloudflare.com/r2/examples/rclone/

import { Render, Steps } from "~/components";

<Render file="keys" />
<br />

Rclone is a command-line tool which manages files on cloud storage. You can use rclone to upload objects to R2 concurrently.

## Configure rclone

With [`rclone`](https://rclone.org/install/) installed, you may run [`rclone config`](https://rclone.org/s3/) to configure a new S3 storage provider. You will be prompted with a series of questions for the new provider details.

:::note[Recommendation]
It is recommended that you choose a unique provider name and then rely on all default answers to the prompts.

This will create a `rclone` configuration file, which you can then modify with the preset configuration given below.
:::

<Steps>
1. Create new remote by selecting `n`.
2. Select a name for the new remote. For example, use `r2`.
3. Select the `Amazon S3 Compliant Storage Providers` storage type.
4. Select `Cloudflare R2 storage` for the provider.
5. Select whether you would like to enter AWS credentials manually, or get it from the runtime environment.
6. Enter the AWS Access Key ID.
7. Enter AWS Secret Access Key (password).
8. Select the region to connect to (optional).
9. Select the S3 API endpoint.
</Steps>

:::note
Ensure you are running `rclone` v1.59 or greater ([rclone downloads](https://beta.rclone.org/)). Versions prior to v1.59 may return `HTTP 401: Unauthorized` errors, as earlier versions of `rclone` do not strictly align to the S3 specification in all cases.
:::

### Edit an existing rclone configuration

If you have already configured `rclone` in the past, you may run `rclone config file` to print the location of your `rclone` configuration file:

```sh
rclone config file
# Configuration file is stored at:
# ~/.config/rclone/rclone.conf
```

Then use an editor (`nano` or `vim`, for example) to add or edit the new provider. This example assumes you are adding a new `r2` provider:

```toml
[r2]
type = s3
provider = Cloudflare
access_key_id = abc123
secret_access_key = xyz456
endpoint = https://<accountid>.r2.cloudflarestorage.com
acl = private
```

:::note

If you are using a token with [Object-level permissions](/r2/api/tokens/#permissions), you will need to add `no_check_bucket = true` to the configuration to avoid errors.
:::

You may then use the new `rclone` provider for any of your normal workflows.

## List buckets & objects

The [rclone tree](https://rclone.org/commands/rclone_tree/) command can be used to list the contents of the remote, in this case Cloudflare R2.

```sh
rclone tree r2:
# /
# ├── user-uploads
# │   └── foobar.png
# └── my-bucket-name
#     ├── cat.png
#     └── todos.txt

rclone tree r2:my-bucket-name
# /
# ├── cat.png
# └── todos.txt
```

## Upload and retrieve objects

The [rclone copy](https://rclone.org/commands/rclone_copy/) command can be used to upload objects to an R2 bucket and vice versa - this allows you to upload files up to the 5 TB maximum object size that R2 supports.

```sh
# Upload dog.txt to the user-uploads bucket
rclone copy dog.txt r2:user-uploads/
rclone tree r2:user-uploads
# /
# ├── foobar.png
# └── dog.txt

# Download dog.txt from the user-uploads bucket
rclone copy r2:user-uploads/dog.txt .
```

### A note about multipart upload part sizes

For multipart uploads, part sizes can significantly affect the number of Class A operations that are used, which can alter how much you end up being charged.
Every part upload counts as a separate operation, so larger part sizes will use fewer operations, but might be costly to retry if the upload fails. Also consider that a multipart upload is always going to consume at least 3 times as many operations as a single `PutObject`, because it will include at least one `CreateMultipartUpload`, `UploadPart` & `CompleteMultipartUpload` operations.

Balancing part size depends heavily on your use-case, but these factors can help you minimize your bill, so they are worth thinking about.

You can configure rclone's multipart upload part size using the `--s3-chunk-size` CLI argument. Note that you might also have to adjust the `--s3-upload-cutoff` argument to ensure that rclone is using multipart uploads. Both of these can be set in your configuration file as well. Generally, `--s3-upload-cutoff` will be no less than `--s3-chunk-size`.

```sh
rclone copy long-video.mp4 r2:user-uploads/ --s3-upload-cutoff=100M --s3-chunk-size=100M
```

## Generate presigned URLs

You can also generate presigned links which allow you to share public access to a file temporarily using the [rclone link](https://rclone.org/commands/rclone_link/) command.

```sh
# You can pass the --expire flag to determine how long the presigned link is valid. The --unlink flag isn't supported by R2.
rclone link r2:my-bucket-name/cat.png --expire 3600
# https://<accountid>.r2.cloudflarestorage.com/my-bucket-name/cat.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>
```

---

# Use SSE-C

URL: https://developers.cloudflare.com/r2/examples/ssec/

import { Tabs, TabItem } from "~/components";

The following tutorial shows some snippets for how to use Server-Side Encryption with Customer-Provided Keys (SSE-C) on R2.

## Before you begin

- When using SSE-C, make sure you store your encryption key(s) in a safe place. In the event you misplace them, Cloudflare will be unable to recover the body of any objects encrypted using those keys.
- While SSE-C does provide MD5 hashes, this hash can be used for identification of keys only. The MD5 hash is not used in the encryption process itself.

## Workers

<Tabs>
	<TabItem label="TypeScript" icon="seti:typescript">
		```typescript
		interface Environment {
			R2: R2Bucket
			/**
			 * In this example, your SSE-C is stored as a hexadecimal string (preferably a secret).
			 * The R2 API also supports providing an ArrayBuffer directly, if you want to generate/
			 * store your keys dynamically.
			*/
			SSEC_KEY: string
		}
		export default {
			async fetch(req: Request, env: Env) {
				const { SSEC_KEY, R2 } = env;
				const { pathname: filename } = new URL(req.url);
				switch(req.method) {
					case "GET": {
						const maybeObj = await env.BUCKET.get(filename, {
							onlyIf: req.headers,
							ssecKey: SSEC_KEY,
						});
						if(!maybeObj) {
							return new Response("Not Found", {
								status: 404
							});
						}
						const headers = new Headers();
						maybeObj.writeHttpMetadata(headers);
						return new Response(body, {
							headers
						});
					}
					case 'POST': {
						const multipartUpload = await env.BUCKET.createMultipartUpload(filename, {
							httpMetadata: req.headers,
							ssecKey: SSEC_KEY,
						});
						/**
						 * This example only provides a single-part "multipart" upload.
						 * For multiple parts, the process is the same(the key must be provided)
						 * for every part.
						*/
						const partOne = await multipartUpload.uploadPart(1, req.body, ssecKey);
						const obj = await multipartUpload.complete([partOne]);
						const headers = new Headers();
						obj.writeHttpMetadata(headers);
						return new Response(null, {
							headers,
							status: 201
						});
					}
					case 'PUT': {
						const obj = await env.BUCKET.put(filename, req.body, {
							httpMetadata: req.headers,
							ssecKey: SSEC_KEY,
						});
						const headers = new Headers();
						maybeObj.writeHttpMetadata(headers);
						return new Response(null, {
							headers,
							status: 201
						});
					}
					default: {
						return new Response("Method not allowed", {
							status: 405
						});
					}
				}
			}
		}
		```
	</TabItem>
	<TabItem label="JavaScript" icon="seti:javascript">
		```javascript
		/**
			 * In this example, your SSE-C is stored as a hexadecimal string(preferably a secret).
			 * The R2 API also supports providing an ArrayBuffer directly, if you want to generate/
			 * store your keys dynamically.
		*/
		export default {
			async fetch(req, env) {
				const { SSEC_KEY, R2 } = env;
				const { pathname: filename } = new URL(req.url);
				switch(req.method) {
					case "GET": {
						const maybeObj = await env.BUCKET.get(filename, {
							onlyIf: req.headers,
							ssecKey: SSEC_KEY,
						});
						if(!maybeObj) {
							return new Response("Not Found", {
								status: 404
							});
						}
						const headers = new Headers();
						maybeObj.writeHttpMetadata(headers);
						return new Response(body, {
							headers
						});
					}
					case 'POST': {
						const multipartUpload = await env.BUCKET.createMultipartUpload(filename, {
							httpMetadata: req.headers,
							ssecKey: SSEC_KEY,
						});
						/**
						 * This example only provides a single-part "multipart" upload.
						 * For multiple parts, the process is the same(the key must be provided)
						 * for every part.
						*/
						const partOne = await multipartUpload.uploadPart(1, req.body, ssecKey);
						const obj = await multipartUpload.complete([partOne]);
						const headers = new Headers();
						obj.writeHttpMetadata(headers);
						return new Response(null, {
							headers,
							status: 201
						});
					}
					case 'PUT': {
						const obj = await env.BUCKET.put(filename, req.body, {
							httpMetadata: req.headers,
							ssecKey: SSEC_KEY,
						});
						const headers = new Headers();
						maybeObj.writeHttpMetadata(headers);
						return new Response(null, {
							headers,
							status: 201
						});
					}
					default: {
						return new Response("Method not allowed", {
							status: 405
						});
					}
				}
			}
		}
		```
	</TabItem>
</Tabs>

## S3-API

<Tabs>
	<TabItem label="@aws-sdk/client-s3" icon="seti:typescript">
		```typescript
		import {
			UploadPartCommand,
			PutObjectCommand, S3Client,
			CompleteMultipartUploadCommand,
			CreateMultipartUploadCommand,
			type UploadPartCommandOutput
		} from "@aws-sdk/client-s3";

    	const s3 = new S3Client({
    		endpoint: process.env.R2_ENDPOINT,
    		credentials: {
    			accessKeyId: process.env.R2_ACCESS_KEY_ID,
    			secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
    		},
    	});

    	const SSECustomerAlgorithm = "AES256";
    	const SSECustomerKey = process.env.R2_SSEC_KEY;
    	const SSECustomerKeyMD5 = process.env.R2_SSEC_KEY_MD5;

    	await s3.send(
    		new PutObjectCommand({
    			Bucket: "your-bucket",
    			Key: "single-part",
    			Body: "BeepBoop",
    			SSECustomerAlgorithm,
    			SSECustomerKey,
    			SSECustomerKeyMD5,
    		}),
    	);

    	const multi = await s3.send(
    		new CreateMultipartUploadCommand({
    			Bucket: "your-bucket",
    			Key: "multi-part",
    			SSECustomerAlgorithm,
    			SSECustomerKey,
    			SSECustomerKeyMD5,
    		}),
    	);
    	const UploadId = multi.UploadId;

    	const parts: UploadPartCommandOutput[] = [];

    	parts.push(
    		await s3.send(
    			new UploadPartCommand({
    				Bucket: "your-bucket",
    				Key: "multi-part",
    				UploadId,
    				// 	filledBuf()` generates some random data.
    				// Replace with a function/body of your choice.
    				Body: filledBuf(),
    				PartNumber: 1,
    				SSECustomerAlgorithm,
    				SSECustomerKey,
    				SSECustomerKeyMD5,
    			}),
    		),
    	);
    	parts.push(
    		await s3.send(
    			new UploadPartCommand({
    				Bucket: "your-bucket",
    				Key: "multi-part",
    				UploadId,
    				// 	filledBuf()` generates some random data.
    				// Replace with a function/body of your choice.
    				Body: filledBuf(),
    				PartNumber: 2,
    				SSECustomerAlgorithm,
    				SSECustomerKey,
    				SSECustomerKeyMD5,
    			}),
    		),
    	);
    	await s3.send(
    		new CompleteMultipartUploadCommand({
    			Bucket: "your-bucket",
    			Key: "multi-part",
    			UploadId,
    			MultipartUpload: {
    				Parts: parts.map(({ ETag }, PartNumber) => ({
    					ETag,
    					PartNumber: PartNumber + 1,
    				})),
    			},
    			SSECustomerAlgorithm,
    			SSECustomerKey,
    			SSECustomerKeyMD5,
    		}),
    	);

    	const HeadObjectOutput = await s3.send(
    		new HeadObjectCommand({
    			Bucket: "your-bucket",
    			Key: "multi-part",
    			SSECustomerAlgorithm,
    			SSECustomerKey,
    			SSECustomerKeyMD5,
    		}),
    	);

    	const GetObjectOutput = await s3.send(
    		new GetObjectCommand({
    			Bucket: "your-bucket",
    			Key: "single-part",
    			SSECustomerAlgorithm,
    			SSECustomerKey,
    			SSECustomerKeyMD5,
    		}),
    	);
    ```

  </TabItem>

</Tabs>

---

# Terraform (AWS)

URL: https://developers.cloudflare.com/r2/examples/terraform-aws/

import { Render } from "~/components";

<Render file="keys" />
<br />

This example shows how to configure R2 with Terraform using the [AWS provider](https://github.com/hashicorp/terraform-provider-aws).

:::note[Note for using AWS provider]

For using only the Cloudflare provider, see [Terraform](/r2/examples/terraform/).

:::

With [`terraform`](https://developer.hashicorp.com/terraform/downloads) installed:

1. Create `main.tf` file, or edit your existing Terraform configuration
2. Populate the endpoint URL at `endpoints.s3` with your [Cloudflare account ID](/fundamentals/account/find-account-and-zone-ids/)
3. Populate `access_key` and `secret_key` with the corresponding [R2 API credentials](/r2/api/tokens/).
4. Ensure that `skip_region_validation = true`, `skip_requesting_account_id = true`, and `skip_credentials_validation = true` are set in the provider configuration.

```hcl
terraform {
  required_providers {
    aws = {
      source = "hashicorp/aws"
      version = "~> 5"
    }
  }
}

provider "aws" {
  region = "us-east-1"

  access_key = <R2 Access Key>
  secret_key = <R2 Secret Key>

	# Required for R2.
	# These options disable S3-specific validation on the client (Terraform) side.
  skip_credentials_validation = true
  skip_region_validation      = true
  skip_requesting_account_id  = true

  endpoints {
    s3 = "https://<account id>.r2.cloudflarestorage.com"
  }
}

resource "aws_s3_bucket" "default" {
  bucket = "<org>-test"
}

resource "aws_s3_bucket_cors_configuration" "default" {
  bucket   = aws_s3_bucket.default.id

  cors_rule {
    allowed_methods = ["GET"]
    allowed_origins = ["*"]
  }
}

resource "aws_s3_bucket_lifecycle_configuration" "default" {
  bucket = aws_s3_bucket.default.id

  rule {
    id     = "expire-bucket"
    status = "Enabled"
    expiration {
      days = 1
    }
  }

  rule {
    id     = "abort-multipart-upload"
    status = "Enabled"
    abort_incomplete_multipart_upload {
      days_after_initiation = 1
    }
  }
}
```

You can then use `terraform plan` to view the changes and `terraform apply` to apply changes.

---

# Delete objects

URL: https://developers.cloudflare.com/r2/objects/delete-objects/

import { Render } from "~/components";

You can delete objects from your bucket from the Cloudflare dashboard or using the Wrangler.

## Delete objects via the Cloudflare dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select **R2**.
2. From the **R2** page in the dashboard, locate and select your bucket.
3. From your bucket's page, locate the object you want to delete. You can select multiple objects to delete at one time.
4. Select your objects and select **Delete**.
5. Confirm your choice by selecting **Delete**.

## Delete objects via Wrangler

:::caution

Deleting objects from a bucket is irreversible.

:::

You can delete an object directly by calling `delete` against a `{bucket}/{path/to/object}`.

For example, to delete the object `foo.png` from bucket `test-bucket`:

```sh
wrangler r2 object delete test-bucket/foo.png
```

```sh output

Deleting object "foo.png" from bucket "test-bucket".
Delete complete.
```

<Render file="link-to-workers-r2-api" product="r2"/>

---

# Terraform

URL: https://developers.cloudflare.com/r2/examples/terraform/

import { Render } from "~/components"

<Render file="keys" /><br/>

This example shows how to configure R2 with Terraform using the [Cloudflare provider](https://github.com/cloudflare/terraform-provider-cloudflare).

:::note[Note for using AWS provider]


When using the Cloudflare Terraform provider, you can only manage buckets. To configure items such as CORS and object lifecycles, you will need to use the [AWS Provider](/r2/examples/terraform-aws/).


:::

With [`terraform`](https://developer.hashicorp.com/terraform/downloads) installed, create `main.tf` and copy the content below replacing with your API Token.

```hcl
terraform {
  required_providers {
    cloudflare = {
      source = "cloudflare/cloudflare"
      version = "~> 4"
    }
  }
}

provider "cloudflare" {
  api_token = "<YOUR_API_TOKEN>"
}

resource "cloudflare_r2_bucket" "cloudflare-bucket" {
  account_id = "<YOUR_ACCOUNT_ID>"
  name       = "my-tf-test-bucket"
  location   = "WEUR"
}
```

You can then use `terraform plan` to view the changes and `terraform apply` to apply changes.

---

# Download objects

URL: https://developers.cloudflare.com/r2/objects/download-objects/

import { Render } from "~/components";

You can download objects from your bucket from the Cloudflare dashboard or using the Wrangler.

## Download objects via the Cloudflare dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select **R2**.
2. From the **R2** page in the dashboard, locate and select your bucket.
3. From your bucket's page, locate the object you want to download.
4. At the end of the object's row, select the menu button and click **Download**.

## Download objects via Wrangler

You can download objects from a bucket, including private buckets in your account, directly.

For example, to download `file.bin` from `test-bucket`:

```sh
wrangler r2 object get test-bucket/file.bin
```

```sh output
Downloading "file.bin" from "test-bucket".
Download complete.
```

The file will be downloaded into the current working directory. You can also use the `--file` flag to set a new name for the object as it is downloaded, and the `--pipe` flag to pipe the download to standard output (stdout).

<Render file="link-to-workers-r2-api" product="r2"/>

---

# Objects

URL: https://developers.cloudflare.com/r2/objects/

import { DirectoryListing, Render } from "~/components"

Objects are individual files or data that you store in an R2 bucket.

<DirectoryListing />

<Render file="link-to-workers-r2-api" product="r2"/>

---

# Multipart upload

URL: https://developers.cloudflare.com/r2/objects/multipart-objects/

import { Render } from "~/components";

R2 supports [S3 API's Multipart Upload](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) with some limitations.

## Limitations

Object part sizes must be at least 5MiB but no larger than 5GiB.  All parts except the last one must be the same size.  The last part has no minimum size, but must be the same or smaller than the other parts.

The maximum number of parts is 10,000.

Most S3 clients conform to these expectations.

## Lifecycles

The default object lifecycle policy for multipart uploads is that incompleted uploads will be automatically aborted 7 days.  This can be changed by [configuring a custom lifecycle policy](/r2/buckets/object-lifecycles/).

## ETags

The ETags for objects uploaded via multipart are different than those uploaded with PutObject.

For uploads created after June 21, 2023, R2's multipart ETags now mimic the behavior of S3.  The ETag of each individual part is the MD5 hash of the contents of the part.  The ETag of the completed multipart object is the hash of the MD5 sums of each of the constituent parts concatenated together followed by a hyphen and the number of parts uploaded.

For example, consider a multipart upload with two parts.  If they have the ETags `bce6bf66aeb76c7040fdd5f4eccb78e6` and `8165449fc15bbf43d3b674595cbcc406` respectively, the ETag of the completed multipart upload will be `f77dc0eecdebcd774a2a22cb393ad2ff-2`.

Note that the binary MD5 sums themselves are concatenated and then summed, not the hexadecimal representation. For example, in order to validate the above example on the command line, you would need do the following:

```
echo -n $(echo -n bce6bf66aeb76c7040fdd5f4eccb78e6 | xxd -r -p -)\
$(echo -n 8165449fc15bbf43d3b674595cbcc406 | xxd -r -p -) | md5sum
```

<Render file="link-to-workers-r2-api" product="r2"/>

---

# Upload objects

URL: https://developers.cloudflare.com/r2/objects/upload-objects/

import { Steps, Tabs, TabItem, Render } from "~/components"

You can upload objects to your bucket from using API (both [Workers Binding API](/r2/api/workers/workers-api-reference/) or [compatible S3 API](/r2/api/s3/api/)), rclone, Cloudflare dashboard, or Wrangler.

## Upload objects via Rclone

Rclone is a command-line tool which manages files on cloud storage. You can use rclone to upload objects to R2. Rclone is useful if you wish to upload multiple objects concurrently.

To use rclone, install it onto your machine using their official documentation - [Install rclone](https://rclone.org/install/).

Upload your files to R2 using the `rclone copy` command.

```sh
# Upload a single file
rclone copy /path/to/local/file.txt r2:bucket_name

# Upload everything in a directory
rclone copy /path/to/local/folder r2:bucket_name
```

Verify that your files have been uploaded by listing the objects stored in the destination R2 bucket using `rclone ls` command.

```sh
rclone ls r2:bucket_name
```

For more information, refer to our [rclone example](/r2/examples/rclone/).

## Upload objects via the Cloudflare dashboard

To upload objects to your bucket from the Cloudflare dashboard:

<Steps>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select **R2**.
2. From the **R2** page in the dashboard, locate and select your bucket.
3. Select **Upload**.
4. Choose to either drag and drop your file into the upload area or **select from computer**.
</Steps>

You will receive a confirmation message after a successful upload.

## Upload objects via Wrangler

:::note

Wrangler only supports uploading files up to 315MB in size. To upload large files, we recommend [rclone](/r2/examples/rclone/) or an [S3-compatible](/r2/api/s3/) tool of your choice.

:::

To upload a file to R2, call `put` and provide a name (key) for the object, as well as the path to the file via `--file`:

```sh
wrangler r2 object put test-bucket/dataset.csv --file=dataset.csv
```

```sh output
Creating object "dataset.csv" in bucket "test-bucket".
Upload complete.
```

You can set the `Content-Type` (MIME type), `Content-Disposition`, `Cache-Control` and other HTTP header metadata through optional flags.

:::note
Wrangler's `object put` command only allows you to upload one object at a time.

Use rclone if you wish to upload multiple objects to R2.
:::

<Render file="link-to-workers-r2-api" product="r2"/>

---

# Audit Logs

URL: https://developers.cloudflare.com/r2/platform/audit-logs/

[Audit logs](/fundamentals/account/account-security/review-audit-logs/) provide a comprehensive summary of changes made within your Cloudflare account, including those made to R2 buckets. This functionality is available on all plan types, free of charge, and is always enabled.

## Viewing audit logs

To view audit logs for your R2 buckets:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?account=audit-log) and select your account.
2. Go to **Manage Account** > **Audit Log**.

For more information on how to access and use audit logs, refer to [Review audit logs](/fundamentals/account/account-security/review-audit-logs/).

## Logged operations

The following configuration actions are logged:

<table>
  <tbody>
    <th colspan="5" rowspan="1" style="width:220px">
      Operation
    </th>
    <th colspan="5" rowspan="1">
      Description
    </th>
    <tr>
      <td colspan="5" rowspan="1">
        CreateBucket
      </td>
      <td colspan="5" rowspan="1">
        Creation of a new bucket.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        DeleteBucket
      </td>
      <td colspan="5" rowspan="1">
        Deletion of an existing bucket.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        AddCustomDomain
      </td>
      <td colspan="5" rowspan="1">
        Addition of a custom domain to a bucket.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        RemoveCustomDomain
      </td>
      <td colspan="5" rowspan="1">
        Removal of a custom domain from a bucket.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        ChangeBucketVisibility
      </td>
      <td colspan="5" rowspan="1">
        Change to the managed public access (<code>r2.dev</code>) settings of a bucket.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        PutBucketStorageClass
      </td>
      <td colspan="5" rowspan="1">
        Change to the default storage class of a bucket.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        PutBucketLifecycleConfiguration
      </td>
      <td colspan="5" rowspan="1">
        Change to the object lifecycle configuration of a bucket.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        DeleteBucketLifecycleConfiguration
      </td>
      <td colspan="5" rowspan="1">
        Deletion of the object lifecycle configuration for a bucket.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        PutBucketCors
      </td>
      <td colspan="5" rowspan="1">
        Change to the CORS configuration for a bucket.
      </td>
    </tr>
    <tr>
      <td colspan="5" rowspan="1">
        DeleteBucketCors
      </td>
      <td colspan="5" rowspan="1">
        Deletion of the CORS configuration for a bucket.
      </td>
    </tr>
  </tbody>
</table>

:::note


Logs for data access operations, such as `GetObject` and `PutObject`, are not included in audit logs. To log HTTP requests made to public R2 buckets, use the [HTTP requests](/logs/reference/log-fields/zone/http_requests/) Logpush dataset.


:::

## Example log entry

Below is an example of an audit log entry showing the creation of a new bucket:

```json
{
  "action": { "info": "CreateBucket", "result": true, "type": "create" },
  "actor": {
    "email": "<ACTOR_EMAIL>",
    "id": "3f7b730e625b975bc1231234cfbec091",
    "ip": "fe32:43ed:12b5:526::1d2:13",
    "type": "user"
  },
  "id": "5eaeb6be-1234-406a-87ab-1971adc1234c",
  "interface": "API",
  "metadata": { "zone_name": "r2.cloudflarestorage.com" },
  "newValue": "",
  "newValueJson": {},
  "oldValue": "",
  "oldValueJson": {},
  "owner": { "id": "1234d848c0b9e484dfc37ec392b5fa8a" },
  "resource": { "id": "my-bucket", "type": "r2.bucket" },
  "when": "2024-07-15T16:32:52.412Z"
}

```

---

# Limits

URL: https://developers.cloudflare.com/r2/platform/limits/

import { Render } from "~/components";

| Feature                                                             | Limit                        |
| ------------------------------------------------------------------- | ---------------------------- |
| Data storage per bucket                                             | Unlimited                    |
| Maximum number of buckets per account                               | 1,000,000                    |
| Maximum rate of bucket management operations per bucket<sup>1</sup> | 50 per second                |
| Number of custom domains per bucket                                 | 50                           |
| Object key length                                                   | 1,024 bytes                  |
| Object metadata size                                                | 8,192 bytes                  |
| Object size                                                         | 5 TiB per object<sup>2</sup> |
| Maximum upload size<sup>4</sup>                                     | 5 GiB<sup>3</sup>            |
| Maximum upload parts                                                | 10,000                       |
| Maximum concurrent writes to the same object name (key) | 1 per second <sup>5</sup> | 

<sup>1</sup> Bucket management operations include creating, deleting, listing,
and configuring buckets. This limit does _not_ apply to reading or writing objects to a bucket.
<br /> <sup>2</sup> The object size limit is 5 GiB less than 5 TiB, so 4.995
TiB.
<br /> <sup>3</sup> The max upload size is 5 MiB less than 5 GiB, so 4.995 GiB.
<br /> <sup>4</sup> Max upload size applies to uploading a file via one request,
uploading a part of a multipart upload, or copying into a part of a multipart
upload. If you have a Worker, its inbound request size is constrained by
[Workers request limits](/workers/platform/limits#request-limits). The max
upload size limit does not apply to subrequests.
<br /> <sup>5</sup> Concurrent writes  to the same object name (key) at a higher rate will cause you to see HTTP 429 (rate limited) responses, as you would with other object storage systems.
<br />

Limits specified in MiB (mebibyte), GiB (gibibyte), or TiB (tebibyte) are storage units of measurement based on base-2. 1 GiB (gibibyte) is equivalent to 2<sup>30</sup> bytes (or 1024<sup>3</sup> bytes). This is distinct from 1 GB (gigabyte), which is 10<sup>9</sup> bytes (or 1000<sup>3</sup> bytes).

<Render file="limits_increase" product="workers" />

## Rate limiting on managed public buckets through `r2.dev`

Managed public bucket access through an `r2.dev` subdomain is not intended for production usage and has a variable rate limit applied to it. The `r2.dev` endpoint for your bucket is designed to enable testing.

* If you exceed the rate limit (hundreds of requests/second), requests to your `r2.dev` endpoint will be temporarily throttled and you will receive a `429 Too Many Requests` response.
* Bandwidth (throughput) may also be throttled when using the `r2.dev` endpoint.

For production use cases, connect a [custom domain](/r2/buckets/public-buckets/#custom-domains) to your bucket. Custom domains allow you to serve content from a domain you control (for example, `assets.example.com`), configure fine-grained caching, set up redirect and rewrite rules, mutate content via [Cloudflare Workers](/workers/), and get detailed URL-level analytics for content served from your R2 bucket.

---

# Metrics and analytics

URL: https://developers.cloudflare.com/r2/platform/metrics-analytics/

R2 exposes analytics that allow you to inspect the requests and storage of the buckets in your account.

The metrics displayed for a bucket in the [Cloudflare dashboard](https://dash.cloudflare.com/) are queried from Cloudflare’s [GraphQL Analytics API](/analytics/graphql-api/). You can access the metrics [programmatically](#query-via-the-graphql-api) via GraphQL or HTTP client.

## Metrics

R2 currently has two datasets:

| <div style="width:100px">Dataset </div> | <div style="width:235px">GraphQL Dataset Name </div> | Description                                                          |
| --------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------- |
| Operations                              | `r2OperationsAdaptiveGroups`                         | This dataset consists of the operations taken buckets of an account. |
| Storage                                 | `r2StorageAdaptiveGroups`                            | This dataset consists of the storage of buckets an account.          |

### Operations Dataset

| <div style="width:175px"> Field </div> | Description                                                                                                                                                                                                               |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| actionType                             | The name of the operation performed.                                                                                                                                                                                      |
| actionStatus                           | The status of the operation. Can be `success`, `userError`, or `internalError`.                                                                                                                                           |
| bucketName                             | The bucket this operation was performed on if applicable. For buckets with a jurisdiction specified, you must include the jurisdiction followed by an underscore before the bucket name. For example: eu_your-bucket-name |
| objectName                             | The object this operation was performed on if applicable.                                                                                                                                                                 |
| responseStatusCode                     | The http status code returned by this operation.                                                                                                                                                                          |
| datetime                               | The time of the request.                                                                                                                                                                                                  |

### Storage Dataset

| <div style="width:175px"> Field </div> | Description                                                                                                                                                                                                                                                                                          |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bucketName                             | The bucket this storage value is for. For buckets with a jurisdiction specified, you must include the [jurisdiction](https://developers.cloudflare.com/r2/reference/data-location/#jurisdictional-restrictions) followed by an underscore before the bucket name. For example: `eu_your-bucket-name` |
| payloadSize                            | The size of the objects in the bucket.                                                                                                                                                                                                                                                               |
| metadataSize                           | The size of the metadata of the objects in the bucket.                                                                                                                                                                                                                                               |
| objectCount                            | The number of objects in the bucket.                                                                                                                                                                                                                                                                 |
| uploadCount                            | The number of pending multipart uploads in the bucket.                                                                                                                                                                                                                                               |
| datetime                               | The time that this storage value represents.                                                                                                                                                                                                                                                         |

Metrics can be queried (and are retained) for the past 31 days. These datasets require an `accountTag` filter with your Cloudflare account ID.

## View via the dashboard

Per-bucket analytics for R2 are available in the Cloudflare dashboard. To view current and historical metrics for a bucket:

2. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
3. Go to the [R2 tab](https://dash.cloudflare.com/?to=/:account/r2) and select your bucket.
4. Select the **Metrics** tab.

You can optionally select a time window to query. This defaults to the last 24 hours.

## Query via the GraphQL API

You can programmatically query analytics for your R2 buckets via the [GraphQL Analytics API](/analytics/graphql-api/). This API queries the same dataset as the Cloudflare dashboard, and supports GraphQL [introspection](/analytics/graphql-api/features/discovery/introspection/).

## Examples

### Operations

To query the volume of each operation type on a bucket for a given time period you can run a query as such

```graphql graphql-api-explorer
query R2VolumeExample(
	$accountTag: string!
	$startDate: Time
	$endDate: Time
	$bucketName: string
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			r2OperationsAdaptiveGroups(
				limit: 10000
				filter: {
					datetime_geq: $startDate
					datetime_leq: $endDate
					bucketName: $bucketName
				}
			) {
				sum {
					requests
				}
				dimensions {
					actionType
				}
			}
		}
	}
}
```

The `bucketName` field can be removed to get an account level overview of operations. The volume of operations can be broken down even further by adding more dimensions to the query.

### Storage

To query the storage of a bucket over a given time period you can run a query as such.

```graphql graphql-api-explorer
query R2StorageExample(
	$accountTag: string!
	$startDate: Time
	$endDate: Time
	$bucketName: string
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			r2StorageAdaptiveGroups(
				limit: 10000
				filter: {
					datetime_geq: $startDate
					datetime_leq: $endDate
					bucketName: $bucketName
				}
				orderBy: [datetime_DESC]
			) {
				max {
					objectCount
					uploadCount
					payloadSize
					metadataSize
				}
				dimensions {
					datetime
				}
			}
		}
	}
}
```

---

# Release-notes

URL: https://developers.cloudflare.com/r2/platform/release-notes/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/r2.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Troubleshooting

URL: https://developers.cloudflare.com/r2/platform/troubleshooting/

import { FileTree } from "~/components";

## Troubleshooting 403 / CORS issues with R2

If you are encountering a CORS error despite setting up everything correctly, you may follow this troubleshooting guide to help you.

If you see a 401/403 error above the CORS error in your browser console, you are dealing with a different issue (not CORS related).

If you do have a CORS issue, refer to [Resolving CORS issues](#if-it-is-actually-cors).

### If you are using a custom domain

1. Open developer tools on your browser.
2. Go to the **Network** tab and find the failing request. You may need to reload the page, as requests are only logged after developer tools have been opened.
3. Check the response headers for the following two headers:
- `cf-cache-status`
- `cf-mitigated`

#### If you have a `cf-mitigated` header

Your request was blocked by one of your WAF rules. Inspect your [Security Events](/waf/analytics/security-events/) to identify the cause of the block.

#### If you do not have a `cf-cache-status` header

Your request was blocked by [Hotlink Protection](/waf/tools/scrape-shield/hotlink-protection/).

Edit your Hotlink Protection settings using a [Configuration Rule](/rules/configuration-rules/), or disable it completely.

### If you are using the S3 API

Your request may be incorrectly signed. You may obtain a better error message by trying the request over curl.

Refer to the working S3 signing examples on the [Examples](/r2/examples/aws/) page.

### If it is actually CORS

Here are some common issues with CORS configurations:

- `ExposeHeaders` is missing headers like `ETag`
- `AllowedHeaders` is missing headers like `Authorization` or `Content-Type`
- `AllowedMethods` is missing methods like `POST`/`PUT`

## HTTP 5XX Errors and capacity limitations of Cloudflare R2

When you encounter an HTTP 5XX error, it is usually a sign that your Cloudflare R2 bucket has been overwhelmed by too many concurrent requests. These errors can trigger bucket-wide read and write locks, affecting the performance of all ongoing operations.

To avoid these disruptions, it is important to implement strategies for managing request volume.

Here are some mitigations you can employ:

### Monitor concurrent requests

Track the number of concurrent requests to your bucket. If a client encounters a 5XX error, ensure that it retries the operation and communicates with other clients. By coordinating, clients can collectively slow down, reducing the request rate and maintaining a more stable flow of successful operations.

If your users are directly uploading to the bucket (for example, using the S3 or Workers API), you may not be able to monitor or enforce a concurrency limit. In that case, we recommend bucket sharding.

### Bucket sharding

For higher capacity at the cost of added complexity, consider bucket sharding. This approach distributes reads and writes across multiple buckets, reducing the load on any single bucket.  While sharding cannot prevent a single hot object from exhausting capacity, it can mitigate the overall impact and improve system resilience.

## Objects named `This object is unnamed`

In the Cloudflare dashboard, you can choose to view objects with `/` in the name as folders by selecting **View prefixes as directories**.

For example, an object named `example/object` will be displayed as below.

<FileTree>
- example
  - object
</FileTree>

Object names which end with `/` will cause the Cloudflare dashboard to render the object as a folder with an unnamed object inside.

For example, uploading an object named `example/` into an R2 bucket will be displayed as below.

<FileTree>
- example
  - `This object is unnamed`
</FileTree>

---

# Consistency model

URL: https://developers.cloudflare.com/r2/reference/consistency/

This page details R2's consistency model, including where R2 is strongly, globally consistent and which operations this applies to.

R2 can be described as "strongly consistent", especially in comparison to other distributed object storage systems. This strong consistency ensures that operations against R2 see the latest (accurate) state: clients should be able to observe the effects of any write, update and/or delete operation immediately, globally.

## Terminology

In the context of R2, *strong* consistency and *eventual* consistency have the following meanings:

* **Strongly consistent** - The effect of an operation will be observed globally, immediately, by all clients. Clients will not observe 'stale' (inconsistent) state.
* **Eventually consistent** - Clients may not see the effect of an operation immediately. The state may take a some time (typically seconds to a minute) to propagate globally.

## Operations and Consistency

Operations against R2 buckets and objects adhere to the following consistency guarantees:

<table-wrap>

| Action                                                   | Consistency                                                                                                                                                   |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read-after-write: Write (upload) an object, then read it | Strongly consistent: readers will immediately see the latest object globally                                                                                  |
| Metadata: Update an object's metadata                    | Strongly consistent: readers will immediately see the updated metadata globally                                                                               |
| Deletion: Delete an object                               | Strongly consistent: reads to that object will immediately return a "does not exist" error                                                                    |
| Object listing: List the objects in a bucket             | Strongly consistent: the list operation will list all objects at that point in time                                                                           |
| IAM: Adding/removing R2 Storage permissions              | Eventually consistent: A [new or updated API key](/fundamentals/api/get-started/create-token/) may take up to a minute to have permissions reflected globally |

</table-wrap>

Additional notes:

* In the event two clients are writing (`PUT` or `DELETE`) to the same key, the last writer to complete "wins".
* When performing a multipart upload, read-after-write consistency continues to apply once all parts have been successfully uploaded. In the case the same part is uploaded (in error) from multiple writers, the last write will win.
* Copying an object within the same bucket also follows the same read-after-write consistency that writing a new object would. The "copied" object is immediately readable by all clients once the copy operation completes.

## Caching

:::note


By default, Cloudflare's cache will cache common, cacheable status codes automatically [per our cache documentation](/cache/how-to/configure-cache-status-code/#edge-ttl).


:::

When connecting a [custom domain](/r2/buckets/public-buckets/#custom-domains) to an R2 bucket and enabling caching for objects served from that bucket, the consistency model is necessarily relaxed when accessing content via a domain with caching enabled.

Specifically, you should expect:

* An object you delete from R2, but that is still cached, will still be available. You should [purge the cache](/cache/how-to/purge-cache/) after deleting objects if you need that delete to be reflected.
* By default, Cloudflare’s cache will [cache HTTP 404 (Not Found) responses](/cache/how-to/configure-cache-status-code/#edge-ttl) automatically. If you upload an object to that same path, the cache may continue to return HTTP 404s until the cache TTL (Time to Live) expires and the new object is fetched from R2 or the [cache is purged](/cache/how-to/purge-cache/).
* An object for a given key is overwritten with a new object: the old (previous) object will continue to be served to clients until the cache TTL expires (or the object is evicted) or the cache is purged.

The cache does not affect access via [Worker API bindings](/r2/api/workers/) or the [S3 API](/r2/api/s3/), as these operations are made directly against the bucket and do not transit through the cache.

---

# Data location

URL: https://developers.cloudflare.com/r2/reference/data-location/

import { WranglerConfig } from "~/components";

Learn how the location of data stored in R2 is determined and about the different available inputs that control the physical location where objects in your buckets are stored.

## Automatic (recommended)

When you create a new bucket, the data location is set to Automatic by default. Currently, this option chooses a bucket location in the closest available region to the create bucket request based on the location of the caller.

## Location Hints

Location Hints are optional parameters you can provide during bucket creation to indicate the primary geographical location you expect data will be accessed from.

Using Location Hints can be a good choice when you expect the majority of access to data in a bucket to come from a different location than where the create bucket request originates. Keep in mind Location Hints are a best effort and not a guarantee, and they should only be used as a way to optimize performance by placing regularly updated content closer to users.

### Set hints via the Cloudflare dashboard

You can choose to automatically create your bucket in the closest available region based on your location or choose a specific location from the list.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select **R2**.
2. Select **Create bucket**.
3. Enter a name for the bucket.
4. Under **Location**, leave _None_ selected for automatic selection or choose a region from the list.
5. Select **Create bucket** to complete the bucket creation process.

### Set hints via the S3 API

You can set the Location Hint via the `LocationConstraint` parameter using the S3 API:

```js
await S3.send(
	new CreateBucketCommand({
		Bucket: "YOUR_BUCKET_NAME",
		CreateBucketConfiguration: {
			LocationConstraint: "WNAM",
		},
	}),
);
```

Refer to [Examples](/r2/examples/) for additional examples from other S3 SDKs.

### Available hints

The following hint locations are supported:

| Hint | Hint description      |
| ---- | --------------------- |
| wnam | Western North America |
| enam | Eastern North America |
| weur | Western Europe        |
| eeur | Eastern Europe        |
| apac | Asia-Pacific          |
| oc   | Oceania               |

### Additional considerations

Location Hints are only honored the first time a bucket with a given name is created. If you delete and recreate a bucket with the same name, the original bucket’s location will be used.

## Jurisdictional Restrictions

Jurisdictional Restrictions guarantee objects in a bucket are stored within a specific jurisdiction.

Use Jurisdictional Restrictions when you need to ensure data is stored and processed within a jurisdiction to meet data residency requirements, including local regulations such as the [GDPR](https://gdpr-info.eu/) or [FedRAMP](https://blog.cloudflare.com/cloudflare-achieves-fedramp-authorization/).

### Set jurisdiction via the Cloudflare dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select R2.
2. Select **Create bucket**.
3. Enter a name for the bucket.
4. Under **Location**, select **Specify jurisdiction** and choose a jurisdiction from the list.
5. Select **Create bucket** to complete the bucket creation process.

### Using jurisdictions from Workers

To access R2 buckets that belong to a jurisdiction from [Workers](/workers/), you will need to specify the jurisdiction as well as the bucket name as part of your [bindings](/r2/api/workers/workers-api-usage/#3-bind-your-bucket-to-a-worker) in your [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
[[r2_buckets]]
bindings = [
  { binding = "MY_BUCKET", bucket_name = "<YOUR_BUCKET_NAME>", jurisdiction = "<JURISDICTION>" }
]
```

</WranglerConfig>

For more information on getting started, refer to [Use R2 from Workers](/r2/api/workers/workers-api-usage/).

### Using jurisdictions with the S3 API

When interacting with R2 resources that belong to a defined jurisdiction with the S3 API or existing S3-compatible SDKs, you must specify the [jurisdiction](#available-jurisdictions) in your S3 endpoint:

`https://<ACCOUNT_ID>.<JURISDICTION>.r2.cloudflarestorage.com`

You can use your jurisdiction-specific endpoint for any [supported S3 API operations](/r2/api/s3/api/). When using a jurisdiction endpoint, you will not be able to access R2 resources outside of that jurisdiction.

The example below shows how to create an R2 bucket in the `eu` jurisdiction using the [`@aws-sdk/client-s3`](https://www.npmjs.com/package/@aws-sdk/client-s3) package for JavaScript.

```js
import { S3Client, CreateBucketCommand } from "@aws-sdk/client-s3";
const S3 = new S3Client({
	endpoint: "https://<account_id>.eu.r2.cloudflarestorage.com",
	credentials: {
		accessKeyId: "<access_key_id",
		secretAccessKey: "<access_key_secret>",
	},
	region: "auto",
});
await S3.send(
	new CreateBucketCommand({
		Bucket: "YOUR_BUCKET_NAME",
	}),
);
```

Refer to [Examples](/r2/examples/) for additional examples from other S3 SDKs.

### Available jurisdictions

The following jurisdictions are supported:

| Jurisdiction | Jurisdiction description |
| ------------ | ------------------------ |
| eu           | European Union           |
| fedramp      | FedRAMP                  |

:::note

Cloudflare Enterprise customers may contact their account team or [Cloudflare Support](/support/contacting-cloudflare-support/) to get access to the FedRAMP jurisdiction.
:::

### Limitations

The following services do not interact with R2 resources with assigned jurisdictions:

- [Super Slurper](/r2/data-migration/) (_coming soon_)
- [Logpush](/logs/get-started/enable-destinations/r2/). As a workaround to this limitation, you can set up a [Logpush job using an S3-compatible endpoint](/data-localization/how-to/r2/#send-logs-to-r2-via-s3-compatible-endpoint) to store logs in an R2 bucket in the jurisdiction of your choice.

### Additional considerations

Once an R2 bucket is created, the jurisdiction cannot be changed.

---

# Data security

URL: https://developers.cloudflare.com/r2/reference/data-security/

This page details the data security properties of R2, including encryption-at-rest (EAR), encryption-in-transit (EIT), and Cloudflare's compliance certifications.

## Encryption at Rest

All objects stored in R2, including their metadata, are encrypted at rest. Encryption and decryption are automatic, do not require user configuration to enable, and do not impact the effective performance of R2.

Encryption keys are managed by Cloudflare and securely stored in the same key management systems we use for managing encrypted data across Cloudflare internally.

Objects are encrypted using [AES-256](https://www.cloudflare.com/learning/ssl/what-is-encryption/), a widely tested, highly performant and industry-standard encryption algorithm. R2 uses GCM (Galois/Counter Mode) as its preferred mode.

## Encryption in Transit

Data transfer between a client and R2 is secured using the same [Transport Layer Security](https://www.cloudflare.com/learning/ssl/transport-layer-security-tls/) (TLS/SSL) supported on all Cloudflare domains.

Access over plaintext HTTP (without TLS/SSL) can be disabled by connecting a [custom domain](/r2/buckets/public-buckets/#custom-domains) to your R2 bucket and enabling [Always Use HTTPS](/ssl/edge-certificates/additional-options/always-use-https/).

:::note


R2 custom domains use Cloudflare for SaaS certificates and cannot be customized. Even if you have [Advanced Certificate Manager](/ssl/edge-certificates/advanced-certificate-manager/), the advanced certificate will not be used due to [certificate prioritization](/ssl/reference/certificate-and-hostname-priority/).


:::

## Compliance

To learn more about Cloudflare's adherence to industry-standard security compliance certifications, visit the Cloudflare [Trust Hub](https://www.cloudflare.com/trust-hub/compliance-resources/).

---

# Reference

URL: https://developers.cloudflare.com/r2/reference/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Durability

URL: https://developers.cloudflare.com/r2/reference/durability/

R2 was designed for data durability and resilience and provides 99.999999999% (eleven 9s) of annual durability, which describes the likelihood of data loss.

For example, if you store 1,000,000 objects on R2, you can expect to lose an object once every 100,000 years, which is the same level of durability as other major providers.

:::caution


Keep in mind that if you accidentally delete an object, you are responsible for implementing your own solution for backups.


:::

---

# Protect an R2 Bucket with Cloudflare Access

URL: https://developers.cloudflare.com/r2/tutorials/cloudflare-access/

import { Render } from "~/components";

You can secure access to R2 buckets using [Cloudflare Access](/cloudflare-one/applications/configure-apps/).

Access allows you to only allow specific users, groups or applications within your organization to access objects within a bucket, or specific sub-paths, based on policies you define.

:::note

For providing secure access to bucket objects for anonymous users, we recommend using [pre-signed URLs](/r2/api/s3/presigned-urls/) instead.

Pre-signed URLs do not require users to be a member of your organization and enable programmatic application directly.

:::

## 1. Create a bucket

_If you have an existing R2 bucket, you can skip this step._

You will need to create an R2 bucket. Follow the [R2 get started guide](/r2/get-started/) to create a bucket before returning to this guide.

## 2. Create an Access application

Within the **Zero Trust** section of the Cloudflare Dashboard, you will need to create an Access application and a policy to restrict access to your R2 bucket.

If you have not configured Cloudflare Access before, we recommend:

- Configuring an [identity provider](/cloudflare-one/identity/) first to enable Access to use your organization's single-sign on (SSO) provider as an authentication method.

To create an Access application for your R2 bucket:

1. Go to [**Access**](https://one.dash.cloudflare.com/?to=/:account/access/apps) and select **Add an application**
2. Select **Self-hosted**.
3. Enter an **Application name**.
4. Select **Add a public hostname** and enter the application domain. The **Domain** must be a domain hosted on Cloudflare, and the **Subdomain** part of the custom domain you will connect to your R2 bucket. For example, if you want to serve files from `behind-access.example.com` and `example.com` is a domain within your Cloudflare account, then enter `behind-access` in the subdomain field and select `example.com` from the **Domain** list.
5. Add [Access policies](/cloudflare-one/policies/access/) to control who can connect to your application. This should be an **Allow** policy so that users can access objects within the bucket behind this Access application.

   :::note
   Ensure that your policies only allow the users within your organization that need access to this R2 bucket.
   :::

6. Follow the remaining [self-hosted application creation steps](/cloudflare-one/applications/configure-apps/self-hosted-public-app/) to publish the application.

## 3. Connect a custom domain

:::caution

You should create an Access application before connecting a custom domain to your bucket, as connecting a custom domain will otherwise make your bucket public by default.

:::

You will need to [connect a custom domain](/r2/buckets/public-buckets/#connect-a-bucket-to-a-custom-domain) to your bucket in order to configure it as an Access application. Make sure the custom domain **is the same domain** you entered when configuring your Access policy.

<Render file="custom-domain-steps" />

## 4. Test your Access policy

Visit the custom domain you connected to your R2 bucket, which should present a Cloudflare Access authentication page with your selected identity provider(s) and/or authentication methods.

For example, if you connected Google and/or GitHub identity providers, you can log in with those providers. If the login is successful and you pass the Access policies configured in this guide, you will be able to access (read/download) objects within the R2 bucket.

If you cannot authenticate or receive a block page after authenticating, check that you have an [Access policy](/cloudflare-one/applications/configure-apps/self-hosted-public-app/#1-add-your-application-to-access) configured within your Access application that explicitly allows the group your user account is associated with.

## Next steps

- Learn more about [Access applications](/cloudflare-one/applications/configure-apps/) and how to configure them.
- Understand how to use [pre-signed URLs](/r2/api/s3/presigned-urls/) to issue time-limited and prefix-restricted access to objects for users not within your organization.
- Review the [documentation on using API tokens to authenticate](/r2/api/tokens/) against R2 buckets.

---

# Unicode interoperability

URL: https://developers.cloudflare.com/r2/reference/unicode-interoperability/

R2 is built on top of Workers and supports Unicode natively. One nuance of Unicode that is often overlooked is the issue of [filename interoperability](https://en.wikipedia.org/wiki/Filename#Encoding_indication_interoperability) due to [Unicode equivalence](https://en.wikipedia.org/wiki/Unicode_equivalence).

Based on feedback from our users, we have chosen to NFC-normalize key names before storing by default. This means that `Héllo` and `Héllo`, for example, are the same object in R2 but different objects in other storage providers. Although `Héllo` and `Héllo` may be different character byte sequences, they are rendered the same.

R2 preserves the encoding for display though. When you list the objects, you will get back the last encoding you uploaded with.

There are still some platform-specific differences to consider:

* Windows and macOS filenames are case-insensitive while R2 and Linux are not.
* Windows console support for Unicode can be error-prone. Make sure to run `chcp 65001` before using command-line tools or use Cygwin if your object names appear to be incorrect.
* Linux allows distinct files that are unicode-equivalent because filenames are byte streams. Unicode-equivalent filenames on Linux will point to the same R2 object.

If it is important for you to be able to bypass the unicode equivalence and use byte-oriented key names, contact your Cloudflare account team.

---

# Tutorials

URL: https://developers.cloudflare.com/r2/tutorials/

import { GlossaryTooltip, ListTutorials, YouTubeVideos } from "~/components";

View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with R2.

## Docs

<ListTutorials />

## Videos

<YouTubeVideos products={["R2"]} />

---

# Mastodon

URL: https://developers.cloudflare.com/r2/tutorials/mastodon/

[Mastodon](https://joinmastodon.org/) is a popular [fediverse](https://en.wikipedia.org/wiki/Fediverse) software. This guide will explain how to configure R2 to be the object storage for a self hosted Mastodon instance, for either [a new instance](#set-up-a-new-instance) or [an existing instance](#migrate-to-r2).

## Set up a new instance

You can set up a self hosted Mastodon instance in multiple ways. Refer to the [official documentation](https://docs.joinmastodon.org/) for more details. When you reach the [Configuring your environment](https://docs.joinmastodon.org/admin/config/#files) step in the Mastodon documentation after installation, refer to the procedures below for the next steps.

### 1. Determine the hostname to access files

Different from the default hostname of your Mastodon instance, object storage for files requires a unique hostname. As an example, if you set up your Mastodon's hostname to be `mastodon.example.com`, you can use `mastodon-files.example.com` or `files.example.com` for accessing files. This means that when visiting your instance on `mastodon.example.com`, whenever there are media attached to a post such as an image or a video, the file will be served under the hostname determined at this step, such as `mastodon-files.example.com`.

:::note


If you move from R2 to another S3 compatible service later on, you can continue using the same hostname determined in this step. We do not recommend changing the hostname after the instance has been running to avoid breaking historical file references. In such a scenario, [Bulk Redirects](/rules/url-forwarding/bulk-redirects/) can be used to instruct requests reaching the previous hostname to refer to the new hostname.


:::

### 2. Create and set up an R2 bucket

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?account=r2).
2. From **Account Home**, select **R2**.
3. From **R2**, select **Create bucket**.
4. Enter your bucket name and then select **Create bucket**. This name is internal when setting up your Mastodon instance and is not publicly accessible.
5. Once the bucket is created, navigate to the **Settings** tab of this bucket and copy the value of **S3 API**.
6. From the **Settings** tab, select **Connect Domain** and enter the hostname from step 1.
7. Navigate back to the R2's overview page and select **Manage R2 API Tokens**.
8. Select **Create API token**.
9. Name your token `Mastodon` by selecting the pencil icon next to the API name and grant it the **Edit** permission. Select **Create API Token** to finalize token creation.
10. Copy the values of **Access Key ID** and **Secret Access Key**.

### 3. Configure R2 for Mastodon

While configuring your Mastodon instance based on the official [configuration file](https://github.com/mastodon/mastodon/blob/main/.env.production.sample), replace the **File storage** section with the following details.

```
S3_ENABLED=true
S3_ALIAS_HOST={{mastodon-files.example.com}}                  # Change to the hostname determined in step 1
S3_BUCKET={{your-bucket-name}}                                # Change to the bucket name set in step 2
S3_ENDPOINT=https://{{unique-id}}.r2.cloudflarestorage.com/   # Change the {{unique-id}} to the part of S3 API retrieved in step 2
AWS_ACCESS_KEY_ID={{your-access-key-id}}                      # Change to the Access Key ID retrieved in step 2
AWS_SECRET_ACCESS_KEY={{your-secret-access-key}}              # Change to the Secret Access Key retrieved in step 2
S3_PROTOCOL=https
S3_PERMISSION=private
```

After configuration, you can run your instance. After the instance is running, upload a media attachment and verify the attachment is retrieved from the hostname set above. When navigating back to the bucket's page in R2, you should see the following structure.

![Mastodon bucket structure after instance is set up and running](~/assets/images/r2/mastodon-r2-bucket-structure.png)

## Migrate to R2

If you already have an instance running, you can migrate the media files to R2 and benefit from [no egress cost](/r2/pricing/).

### 1. Set up an R2 bucket and start file migration

1. (Optional) To minimize the number of migrated files, you can use the [Mastodon admin CLI](https://docs.joinmastodon.org/admin/tootctl/#media) to clean up unused files.
2. Set up an R2 bucket ready for file migration by following steps 1 and 2 from [Setting up a new instance](#set-up-a-new-instance) section above.
3. Migrate all the media files to R2. Refer to the [examples](/r2/examples/) provided to connect various providers together. If you currently host these media files locally, you can use [`rclone`](/r2/examples/rclone/) to upload these local files to R2.

### 2. (Optional) Set up file path redirects

While the file migration is in progress, which may take a while, you can prepare file path redirect settings.

If you had the media files hosted locally, you will likely need to set up redirects. By default, media files hosted locally would have a path similar to `https://mastodon.example.com/cache/...`, which needs to be redirected to a path similar to `https://mastodon-files.example.com/cache/...` after the R2 bucket is up and running alongside your Mastodon instance. If you already use another S3 compatible object storage service and would like to keep the same hostname, you do not need to set up redirects.

[Bulk Redirects](/rules/url-forwarding/bulk-redirects/) are available for all plans. Refer to [Create Bulk Redirects in the dashboard](/rules/url-forwarding/bulk-redirects/create-dashboard/) for more information.

![List of Source URLs and their new Target URLs as part of Bulk Redirects](~/assets/images/r2/mastodon-r2-bulk-redirects.png)

### 3. Verify bucket and redirects

Depending on your migration plan, you can verify if the bucket is accessible publicly and the redirects work correctly. To verify, open an existing uploaded media file with a path like `https://mastodon.example.com/cache/...` and replace the hostname from `mastodon.example.com` to `mastocon-files.example.com` and visit the new path. If the file opened correctly, proceed to the final step.

### 4. Finalize migration

Your instance may be still running during migration, and during migration, you likely have new media files created either through direct uploads or fetched from other federated instances. To upload only the newly created files, you can use a program like [`rclone`](/r2/examples/rclone/). Note that when re-running the sync program, all existing files will be checked using at least [Class B operations](/r2/pricing/#class-b-operations).

Once all the files are synced, you can restart your Mastodon instance with the new object storage configuration as mentioned in [step 3](#3-configure-r2-for-mastodon) of Set up a new instance.

---

# Postman

URL: https://developers.cloudflare.com/r2/tutorials/postman/

Postman is an API platform that makes interacting with APIs easier. This guide will explain how to use Postman to make authenticated R2 requests to create a bucket, upload a new object, and then retrieve the object. The R2 [Postman collection](https://www.postman.com/cloudflare-r2/workspace/cloudflare-r2/collection/20913290-14ddd8d8-3212-490d-8647-88c9dc557659?action=share\&creator=20913290) includes a complete list of operations supported by the platform.

## 1. Purchase R2

This guide assumes that you have made a Cloudflare account and purchased R2.

## 2. Explore R2 in Postman

Explore R2's publicly available [Postman collection](https://www.postman.com/cloudflare-r2/workspace/cloudflare-r2/collection/20913290-14ddd8d8-3212-490d-8647-88c9dc557659?action=share\&creator=20913290). The collection is organized into a `Buckets` folder for bucket-level operations and an `Objects` folder for object-level operations. Operations in the `Objects > Upload` folder allow for adding new objects to R2.

## 3. Configure your R2 credentials

In the [Postman dashboard](https://www.postman.com/cloudflare-r2/workspace/cloudflare-r2/collection/20913290-14ddd8d8-3212-490d-8647-88c9dc557659?action=share\&creator=20913290\&ctx=documentation), select the **Cloudflare R2** collection and navigate to the **Variables** tab. In **Variables**, you can set variables within the R2 collection. They will be used to authenticate and interact with the R2 platform. Remember to always select **Save** after updating a variable.

To execute basic operations, you must set the `account-id`, `r2-access-key-id`, and `r2-secret-access-key` variables in the Postman dashboard > **Variables**.

To do this:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?account=r2).
2. In **Account Home**, select **R2**.
3. In **R2**, under **Manage R2 API Tokens** on the right side of the dashboard, copy your Cloudflare account ID.
4. Go back to the [Postman dashboard](https://www.postman.com/cloudflare-r2/workspace/cloudflare-r2/collection/20913290-14ddd8d8-3212-490d-8647-88c9dc557659?action=share\&creator=20913290\&ctx=documentation).
5. Set the **CURRENT VALUE** of `account-id` to your Cloudflare account ID and select **Save**.

Next, generate an R2 API token:

1. Go to the Cloudflare dashboard > **R2**.
2. On the right hand sidebar, select **Manage R2 API Tokens**.
3. Select **Create API token**.
4. Name your token **Postman** by selecting the pencil icon next to the API name and grant it the **Edit** permission.

Guard this token and the **Access Key ID** and **Secret Access Key** closely. You will not be able to review these values again after finishing this step. Anyone with this information can fully interact with all of your buckets.

After you have created your API token in the Cloudflare dashboard:

1. Go to the [Postman dashboard](https://www.postman.com/cloudflare-r2/workspace/cloudflare-r2/collection/20913290-14ddd8d8-3212-490d-8647-88c9dc557659?action=share\&creator=20913290\&ctx=documentation) > **Variables**.
2. Copy `Access Key ID` value from the Cloudflare dashboard and paste it into Postman’s `r2-access-key-id` variable value and select **Save**.
3. Copy the `Secret Access Key` value from the Cloudflare dashboard and paste it into Postman’s `r2-secret-access-key` variable value and select **Save**.

By now, you should have `account-id`, `r2-secret-access-key`, and `r2-access-key-id` set in Postman.

To verify the token:

1. In the Postman dashboard, select the **Cloudflare R2** folder dropdown arrow > **Buckets** folder dropdown arrow > **`GET`ListBuckets**.
2. Select **Send**.

The Postman collection uses AWS SigV4 authentication to complete the handshake.

You should see a `200 OK` response with a list of existing buckets. If you receive an error, ensure your R2 subscription is active and Postman variables are saved correctly.

## 4. Create a bucket

In the Postman dashboard:

1. Go to **Variables**.
2. Set the `r2-bucket` variable value as the name of your R2 bucket and select **Save**.
3. Select the **Cloudflare R2** folder dropdown arrow > **Buckets** folder dropdown arrow > **`PUT`CreateBucket** and select **Send**.

You should see a `200 OK` response. If you run the `ListBuckets` request again, your bucket will appear in the list of results.

## 5. Add an object

You will now add an object to your bucket:

1. Go to **Variables** in the Postman dashboard.
2. Set `r2-object` to `cat-pic.jpg` and select **Save**.
3. Select **Cloudflare R2** folder dropdown arrow > **Objects** folder dropdown arrow > **Multipart** folder dropdown arrow > **`PUT`PutObject** and select **Send**.
4. Go to **Body** and choose **binary** before attaching your cat picture.
5. Select **Send** to add the cat picture to your R2 bucket.

After a few seconds, you should receive a `200 OK` response.

## 6. Get an object

It only takes a few more more clicks to download our cat friend using the `GetObject` request.

1. Select the **Cloudflare R2** folder dropdown arrow > **Objects** folder dropdown arrow > **`GET`GetObject**.
2. Select **Send**.

The R2 team will keep this collection up to date as we expand R2 features set. You can explore the rest of the R2 Postman collection by experimenting with other operations.

---

# Use event notification to summarize PDF files on upload

URL: https://developers.cloudflare.com/r2/tutorials/summarize-pdf/

import { Render, PackageManagers, Details, WranglerConfig } from "~/components";

In this tutorial, you will learn how to use [event notifications](/r2/buckets/event-notifications/) to process a PDF file when it is uploaded to an R2 bucket. You will use [Workers AI](/workers-ai/) to summarize the PDF and store the summary as a text file in the same bucket.

## Prerequisites

To continue, you will need:

- A [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages) with access to R2.
- Have an existing R2 bucket. Refer to [Get started tutorial for R2](/r2/get-started/#2-create-a-bucket).
- Install [`Node.js`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).

<Details header="Node.js version manager">
	Use a Node version manager like [Volta](https://volta.sh/) or
	[nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change
	Node.js versions. [Wrangler](/workers/wrangler/install-and-update/), discussed
	later in this guide, requires a Node version of `16.17.0` or later.
</Details>

## 1. Create a new project

You will create a new Worker project that will use [Static Assets](/workers/static-assets/) to serve the front-end of your application. A user can upload a PDF file using this front-end, which will then be processed by your Worker.

Create a new Worker project by running the following commands:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"pdf-summarizer"}
/>

    <Render
    	file="c3-post-run-steps"
    	product="workers"
    	params={{
    	category: "hello-world",
    	type: "Worker only",
    	lang: "TypeScript",
    	}}
    />

Navigate to the `pdf-summarizer` directory:

```sh frame="none"
cd pdf-summarizer
```

## 2. Create the front-end

Using Static Assets, you can serve the front-end of your application from your Worker. To use Static Assets, you need to add the required bindings to your Wrangler file.

<WranglerConfig>

```toml
[assets]
directory = "public"
```

</WranglerConfig>

Next, create a `public` directory and add an `index.html` file. The `index.html` file should contain the following HTML code:

<details>
<summary>
Select to view the HTML code
</summary>

```html
<!doctype html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<title>PDF Summarizer</title>
		<style>
			body {
				font-family: Arial, sans-serif;
				display: flex;
				flex-direction: column;
				min-height: 100vh;
				margin: 0;
				background-color: #fefefe;
			}
			.content {
				flex: 1;
				display: flex;
				justify-content: center;
				align-items: center;
			}
			.upload-container {
				background-color: #f0f0f0;
				padding: 20px;
				border-radius: 8px;
				box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
			}
			.upload-button {
				background-color: #4caf50;
				color: white;
				padding: 10px 15px;
				border: none;
				border-radius: 4px;
				cursor: pointer;
				font-size: 16px;
			}
			.upload-button:hover {
				background-color: #45a049;
			}
			footer {
				background-color: #f0f0f0;
				color: white;
				text-align: center;
				padding: 10px;
				width: 100%;
			}
			footer a {
				color: #333;
				text-decoration: none;
				margin: 0 10px;
			}
			footer a:hover {
				text-decoration: underline;
			}
		</style>
	</head>
	<body>
		<div class="content">
			<div class="upload-container">
				<h2>Upload PDF File</h2>
				<form id="uploadForm" onsubmit="return handleSubmit(event)">
					<input
						type="file"
						id="pdfFile"
						name="pdfFile"
						accept=".pdf"
						required
					/>
					<button type="submit" id="uploadButton" class="upload-button">
						Upload
					</button>
				</form>
			</div>
		</div>

		<footer>
			<a
				href="https://developers.cloudflare.com/r2/buckets/event-notifications/"
				target="_blank"
				>R2 Event Notification</a
			>
			<a
				href="https://developers.cloudflare.com/queues/get-started/#3-create-a-queue"
				target="_blank"
				>Cloudflare Queues</a
			>
			<a href="https://developers.cloudflare.com/workers-ai/" target="_blank"
				>Workers AI</a
			>
			<a
				href="https://github.com/harshil1712/pdf-summarizer-r2-event-notification"
				target="_blank"
				>GitHub Repo</a
			>
		</footer>

		<script>
			handleSubmit = async (event) => {
				event.preventDefault();

				// Disable the upload button and show a loading message
				const uploadButton = document.getElementById("uploadButton");
				uploadButton.disabled = true;
				uploadButton.textContent = "Uploading...";

				// get form data
				const formData = new FormData(event.target);
				const file = formData.get("pdfFile");

				if (file) {
					// call /api/upload endpoint and send the file
					await fetch("/api/upload", {
						method: "POST",
						body: formData,
					});

					event.target.reset();
				} else {
					console.log("No file selected");
				}
				uploadButton.disabled = false;
				uploadButton.textContent = "Upload";
			};
		</script>
	</body>
</html>
```

</details>

To view the front-end of your application, run the following command and navigate to the URL displayed in the terminal:

```sh
npm run dev
```

```txt output
 ⛅️ wrangler 3.80.2
-------------------

⎔ Starting local server...
[wrangler:inf] Ready on http://localhost:8787
╭───────────────────────────╮
│  [b] open a browser       │
│  [d] open devtools        │
│  [l] turn off local mode  │
│  [c] clear console        │
│  [x] to exit              │
╰───────────────────────────╯
```

When you open the URL in your browser, you will see that there is a file upload form. If you try uploading a file, you will notice that the file is not uploaded to the server. This is because the front-end is not connected to the back-end. In the next step, you will update your Worker that will handle the file upload.

## 3. Handle file upload

To handle the file upload, you will first need to add the R2 binding. In the Wrangler file, add the following code:

<WranglerConfig>

```toml
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "<R2_BUCKET_NAME>"
```

</WranglerConfig>

Replace `<R2_BUCKET_NAME>` with the name of your R2 bucket.

Next, update the `src/index.ts` file. The `src/index.ts` file should contain the following code:

```ts title="src/index.ts"
export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Get the pathname from the request
		const pathname = new URL(request.url).pathname;

		if (pathname === "/api/upload" && request.method === "POST") {
			// Get the file from the request
			const formData = await request.formData();
			const file = formData.get("pdfFile") as File;

			// Upload the file to Cloudflare R2
			const upload = await env.MY_BUCKET.put(file.name, file);
			return new Response("File uploaded successfully", { status: 200 });
		}

		return new Response("incorrect route", { status: 404 });
	},
} satisfies ExportedHandler<Env>;
```

The above code does the following:

- Check if the request is a POST request to the `/api/upload` endpoint. If it is, it gets the file from the request and uploads it to Cloudflare R2 using the [Workers API](/r2/api/workers/).
- If the request is not a POST request to the `/api/upload` endpoint, it returns a 404 response.

Since the Worker code is written in TypeScript, you should run the following command to add the necessary type definitions. While this is not required, it will help you avoid errors.

<Render file="request-dot-clone-warning" product="workers" />

```sh
npm run cf-typegen
```

You can restart the developer server to test the changes:

```sh
npm run dev
```

## 4. Create a queue

:::note

You will need a [Workers Paid plan](/workers/platform/pricing/) to create and use [Queues](/queues/) and Cloudflare Workers to consume event notifications.

:::

Event notifications capture changes to data in your R2 bucket. You will need to create a new queue `pdf-summarize` to receive notifications:

```sh
npx wrangler queues create pdf-summarizer
```

Add the binding to the Wrangler file:

<WranglerConfig>

```toml title="wrangler.toml"
[[queues.consumers]]
queue = "pdf-summarizer"
```

</WranglerConfig>

## 5. Handle event notifications

Now that you have a queue to receive event notifications, you need to update the Worker to handle the event notifications. You will need to add a Queue handler that will extract the textual content from the PDF, use Workers AI to summarize the content, and then save it in the R2 bucket.

Update the `src/index.ts` file to add the Queue handler:

```ts title="src/index.ts"
export default {
	async fetch(request, env, ctx): Promise<Response> {
		// No changes in the fetch handler
	},
	async queue(batch, env) {
		for (let message of batch.messages) {
			console.log(`Processing the file: ${message.body.object.key}`);
		}
	},
} satisfies ExportedHandler<Env>;
```

The above code does the following:

- The `queue` handler is called when a new message is added to the queue. It loops through the messages in the batch and logs the name of the file.

For now the `queue` handler is not doing anything. In the next steps, you will update the `queue` handler to extract the textual content from the PDF, use Workers AI to summarize the content, and then add it to the bucket.

## 6. Extract the textual content from the PDF

To extract the textual content from the PDF, the Worker will use the [unpdf](https://github.com/unjs/unpdf) library. The `unpdf` library provides utilities to work with PDF files.

Install the `unpdf` library by running the following command:

<PackageManagers pkg="unpdf" />

Update the `src/index.ts` file to import the required modules from the `unpdf` library:

```ts title="src/index.ts" ins={1}
import { extractText, getDocumentProxy } from "unpdf";
```

Next, update the `queue` handler to extract the textual content from the PDF:

```ts title="src/index.ts" ins={4-15}
async queue(batch, env) {
  for(let message of batch.messages) {
    console.log(`Processing file: ${message.body.object.key}`);
    // Get the file from the R2 bucket
    const file = await env.MY_BUCKET.get(message.body.object.key);
    if (!file) {
				console.error(`File not found: ${message.body.object.key}`);
				continue;
			}
    // Extract the textual content from the PDF
    const buffer = await file.arrayBuffer();
    const document = await getDocumentProxy(new Uint8Array(buffer));

    const {text} = await extractText(document, {mergePages: true});
    console.log(`Extracted text: ${text.substring(0, 100)}...`);
    }
}
```

The above code does the following:

- The `queue` handler gets the file from the R2 bucket.
- The `queue` handler extracts the textual content from the PDF using the `unpdf` library.
- The `queue` handler logs the textual content.

## 7. Use Workers AI to summarize the content

To use Workers AI, you will need to add the Workers AI binding to the Wrangler file. The Wrangler file should contain the following code:

<WranglerConfig>

```toml title="wrangler.toml"
[ai]
binding = "AI"
```

</WranglerConfig>

Execute the following command to add the AI type definition:

```sh
npm run cf-typegen
```

Update the `src/index.ts` file to use Workers AI to summarize the content:

```ts title="src/index.ts" ins={7-15}
async queue(batch, env) {
  for(let message of batch.messages) {
    // Extract the textual content from the PDF
    const {text} = await extractText(document, {mergePages: true});
    console.log(`Extracted text: ${text.substring(0, 100)}...`);

    // Use Workers AI to summarize the content
    const result: AiSummarizationOutput = await env.AI.run(
    "@cf/facebook/bart-large-cnn",
      {
        input_text: text,
      }
    );
    const summary = result.summary;
    console.log(`Summary: ${summary.substring(0, 100)}...`);
  }
}
```

The `queue` handler now uses Workers AI to summarize the content.

## 8. Add the summary to the R2 bucket

Now that you have the summary, you need to add it to the R2 bucket. Update the `src/index.ts` file to add the summary to the R2 bucket:

```ts title="src/index.ts" ins={8-14}
async queue(batch, env) {
  for(let message of batch.messages) {
    // Extract the textual content from the PDF
    // ...
    // Use Workers AI to summarize the content
    // ...

    // Add the summary to the R2 bucket
    const upload = await env.MY_BUCKET.put(`${message.body.object.key}-summary.txt`, summary, {
					httpMetadata: {
						contentType: 'text/plain',
					},
		});
		console.log(`Summary added to the R2 bucket: ${upload.key}`);
  }
}
```

The queue handler now adds the summary to the R2 bucket as a text file.

## 9. Enable event notifications

Your `queue` handler is ready to handle incoming event notification messages. You need to enable event notifications with the [`wrangler r2 bucket notification create` command](/workers/wrangler/commands/#r2-bucket-notification-create) for your bucket. The following command creates an event notification for the `object-create` event type for the `pdf` suffix:

```sh
npx wrangler r2 bucket notification create <R2_BUCKET_NAME> --event-type object-create --queue pdf-summarizer --suffix "pdf"
```

Replace `<R2_BUCKET_NAME>` with the name of your R2 bucket.

An event notification is created for the `pdf` suffix. When a new file with the `pdf` suffix is uploaded to the R2 bucket, the `pdf-summarizer` queue is triggered.

## 10. Deploy your Worker

To deploy your Worker, run the [`wrangler deploy`](/workers/wrangler/commands/#deploy) command:

```sh
npx wrangler deploy
```

In the output of the `wrangler deploy` command, copy the URL. This is the URL of your deployed application.

## 11. Test

To test the application, navigate to the URL of your deployed application and upload a PDF file. Alternatively, you can use the [Cloudflare dashboard](https://dash.cloudflare.com/) to upload a PDF file.

To view the logs, you can use the [`wrangler tail`](/workers/wrangler/commands/#tail) command.

```sh
npx wrangler tail
```

You will see the logs in your terminal. You can also navigate to the Cloudflare dashboard and view the logs in the Workers Logs section.

If you check your R2 bucket, you will see the summary file.

## Conclusion

In this tutorial, you learned how to use R2 event notifications to process an object on upload. You created an application to upload a PDF file, and created a consumer Worker that creates a summary of the PDF file. You also learned how to use Workers AI to summarize the content of the PDF file, and upload the summary to the R2 bucket.

You can use the same approach to process other types of files, such as images, videos, and audio files. You can also use the same approach to process other types of events, such as object deletion, and object update.

If you want to view the code for this tutorial, you can find it on [GitHub](https://github.com/harshil1712/pdf-summarizer-r2-event-notification).

---

# Log and store upload events in R2 with event notifications

URL: https://developers.cloudflare.com/r2/tutorials/upload-logs-event-notifications/

import { Render, PackageManagers, WranglerConfig } from "~/components";

This example provides a step-by-step guide on using [event notifications](/r2/buckets/event-notifications/) to capture and store R2 upload logs in a separate bucket.

![Push-Based R2 Event Notifications](~/assets/images/reference-architecture/event-notifications-for-storage/pushed-based-event-notification.svg)

## Prerequisites

To continue, you will need:

- A subscription to [Workers Paid](/workers/platform/pricing/#workers), required for using queues.

## 1. Install Wrangler

To begin, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/#install-wrangler) to install Wrangler, the Cloudflare Developer Platform CLI.

## 2. Create R2 buckets

You will need to create two R2 buckets:

- `example-upload-bucket`: When new objects are uploaded to this bucket, your [consumer Worker](/queues/get-started/#4-create-your-consumer-worker) will write logs.
- `example-log-sink-bucket`: Upload logs from `example-upload-bucket` will be written to this bucket.

To create the buckets, run the following Wrangler commands:

```sh
npx wrangler r2 bucket create example-upload-bucket
npx wrangler r2 bucket create example-log-sink-bucket
```

## 3. Create a queue

:::note

You will need a [Workers Paid plan](/workers/platform/pricing/) to create and use [Queues](/queues/) and Cloudflare Workers to consume event notifications.

:::

Event notifications capture changes to data in `example-upload-bucket`. You will need to create a new queue to receive notifications:

```sh
npx wrangler queues create example-event-notification-queue
```

## 4. Create a Worker

Before you enable event notifications for `example-upload-bucket`, you need to create a [consumer Worker](/queues/reference/how-queues-works/#create-a-consumer-worker) to receive the notifications.

Create a new Worker with C3 (`create-cloudflare` CLI). [C3](/pages/get-started/c3/) is a command-line tool designed to help you set up and deploy new applications, including Workers, to Cloudflare.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"consumer-worker"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

Then, move into your newly created directory:

```sh
cd consumer-worker
```

## 5. Configure your Worker

In your Worker project's [[Wrangler configuration file](/workers/wrangler/configuration/)](/workers/wrangler/configuration/), add a [queue consumer](/workers/wrangler/configuration/#queues) and [R2 bucket binding](/workers/wrangler/configuration/#r2-buckets). The queues consumer bindings will register your Worker as a consumer of your future event notifications and the R2 bucket bindings will allow your Worker to access your R2 bucket.

<WranglerConfig>

```toml
name = "event-notification-writer"
main = "src/index.ts"
compatibility_date = "2024-03-29"
compatibility_flags = ["nodejs_compat"]

[[queues.consumers]]
queue = "example-event-notification-queue"
max_batch_size = 100
max_batch_timeout = 5

[[r2_buckets]]
binding = "LOG_SINK"
bucket_name = "example-log-sink-bucket"
```

</WranglerConfig>

## 6. Write event notification messages to R2

Add a [`queue` handler](/queues/configuration/javascript-apis/#consumer) to `src/index.ts` to handle writing batches of notifications to our log sink bucket (you do not need a [fetch handler](/workers/runtime-apis/handlers/fetch/)):

```ts
export interface Env {
	LOG_SINK: R2Bucket;
}

export default {
	async queue(batch, env): Promise<void> {
		const batchId = new Date().toISOString().replace(/[:.]/g, "-");
		const fileName = `upload-logs-${batchId}.json`;

		// Serialize the entire batch of messages to JSON
		const fileContent = new TextEncoder().encode(
			JSON.stringify(batch.messages),
		);

		// Write the batch of messages to R2
		await env.LOG_SINK.put(fileName, fileContent, {
			httpMetadata: {
				contentType: "application/json",
			},
		});
	},
} satisfies ExportedHandler<Env>;
```

## 7. Deploy your Worker

To deploy your consumer Worker, run the [`wrangler deploy`](/workers/wrangler/commands/#deploy) command:

```sh
npx wrangler deploy
```

## 8. Enable event notifications

Now that you have your consumer Worker ready to handle incoming event notification messages, you need to enable event notifications with the [`wrangler r2 bucket notification create` command](/workers/wrangler/commands/#r2-bucket-notification-create) for `example-upload-bucket`:

```sh
npx wrangler r2 bucket notification create example-upload-bucket --event-type object-create --queue example-event-notification-queue
```

## 9. Test

Now you can test the full end-to-end flow by uploading an object to `example-upload-bucket` in the Cloudflare dashboard. After you have uploaded an object, logs will appear in `example-log-sink-bucket` in a few seconds.

---

# Analytics

URL: https://developers.cloudflare.com/realtime/turn/analytics/

Cloudflare Realtime TURN service counts ingress and egress usage in bytes. You can access this real-time and historical data using the TURN analytics API. You can see TURN usage data in a time series or aggregate that shows traffic in bytes over time.

Cloudflare TURN analytics is available over the GraphQL API only.

:::note[API token permissions]

You will need the "Account Analytics" permission on your API token to make queries to the Realtime GraphQL API. 
:::

:::note

See [GraphQL API](/analytics/graphql-api/) for more information on how to set up your GraphQL client. The examples below use the same GraphQL endpoint at `https://api.cloudflare.com/client/v4/graphql`. 
:::

## TURN traffic data filters

You can filter the data in TURN analytics on:

* Datetime range
* TURN Key ID
* TURN Username
* Custom identifier

:::note


[Custom identifiers](/realtime/turn/replacing-existing/#tag-users-with-custom-identifiers) are useful for accounting usage for different users in your system.


:::

## Useful TURN analytics queries

Below are some example queries for common usecases. You can modify them to adapt your use case and get different views to the analytics data.

### Top TURN keys by egress

```
query{
  viewer {
    usage: accounts(filter: { accountTag: "8846293bd06d1af8c106d89ec1454fe6" }) {
        callsTurnUsageAdaptiveGroups(
          filter: {
          datetimeMinute_gt: "2024-07-15T02:07:07Z"
          datetimeMinute_lt: "2024-08-10T02:07:05Z"
        }
          limit: 2
          orderBy: [sum_egressBytes_DESC]
        ) {
          dimensions {
            keyId
          }
          sum {
            egressBytes
          }
        }
      }
    }
  }


```

```
{
  "data": {
    "viewer": {
      "usage": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "dimensions": {
                "keyId": "74007022d80d7ebac4815fb776b9d3ed"
              },
              "sum": {
                "egressBytes": 502614982
              }
            },
            {
              "dimensions": {
                "keyId": "6b9e68b07dfee8cc2d116e4c51d6a957"
              },
              "sum": {
                "egressBytes": 4853235
              }
            }
          ]
        }
      ]
    }
  },
  "errors": null
}
```

### Top TURN custom identifiers

```
query{
  viewer {
    usage: accounts(filter: { accountTag: "8846293bd06d1af8c106d89ec1454fe6" }) {
        callsTurnUsageAdaptiveGroups(
          filter: {
          datetimeMinute_gt: "2024-07-15T02:07:07Z"
          datetimeMinute_lt: "2024-08-10T02:07:05Z"
        }
          limit: 100
          orderBy: [sum_egressBytes_DESC]
        ) {
          dimensions {
            customIdentifier
          }
          sum {
            egressBytes
          }
        }
      }
    }
  }
```

```
{
  "data": {
    "viewer": {
      "usage": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "dimensions": {
                "customIdentifier": "custom-id-333"
              },
              "sum": {
                "egressBytes": 269850354
              }
            },
            {
              "dimensions": {
                "customIdentifier": "custom-id-555"
              },
              "sum": {
                "egressBytes": 162641324
              }
            },
            {
              "dimensions": {
                "customIdentifier": "custom-id-112"
              },
              "sum": {
                "egressBytes": 70123304
              }
            }
          ]
        }
      ]
    }
  },
  "errors": null
}
```

### Usage for a specific custom identifier

```
query{
  viewer {
    usage: accounts(filter: { accountTag: "8846293bd06d1af8c106d89ec1454fe6" }) {
        callsTurnUsageAdaptiveGroups(
          filter: {
          datetimeMinute_gt: "2024-07-15T02:07:07Z"
          datetimeMinute_lt: "2024-08-10T02:07:05Z"
          customIdentifier: "tango"
        }
          limit: 100
          orderBy: []
        ) {
          dimensions {
            keyId
            customIdentifier
          }
          sum {
            egressBytes
          }
        }
      }
    }
  }

```

```
{
  "data": {
    "viewer": {
      "usage": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "dimensions": {
                "customIdentifier": "tango",
                "keyId": "74007022d80d7ebac4815fb776b9d3ed"
              },
              "sum": {
                "egressBytes": 162641324
              }
            }
          ]
        }
      ]
    }
  },
  "errors": null
}
```

### Usage as a timeseries (for graphs)

```
query{
  viewer {
    usage: accounts(filter: { accountTag: "8846293bd06d1af8c106d89ec1454fe6" }) {
        callsTurnUsageAdaptiveGroups(
          filter: {
          datetimeMinute_gt: "2024-07-15T02:07:07Z"
          datetimeMinute_lt: "2024-08-10T02:07:05Z"
        }
          limit: 100
          orderBy: [datetimeMinute_ASC]
        ) {
          dimensions {
            datetimeMinute
          }
          sum {
            egressBytes
          }
        }
      }
    }
  }



```

```
{
  "data": {
    "viewer": {
      "usage": [
        {
          "callsTurnUsageAdaptiveGroups": [
            {
              "dimensions": {
                "datetimeMinute": "2024-08-01T17:09:00Z"
              },
              "sum": {
                "egressBytes": 4570704
              }
            },
            {
              "dimensions": {
                "datetimeMinute": "2024-08-01T17:10:00Z"
              },
              "sum": {
                "egressBytes": 27203016
              }
            },
            {
              "dimensions": {
                "datetimeMinute": "2024-08-01T17:11:00Z"
              },
              "sum": {
                "egressBytes": 9067412
              }
            },
            {
              "dimensions": {
                "datetimeMinute": "2024-08-01T17:17:00Z"
              },
              "sum": {
                "egressBytes": 10059322
              }
            },
            ...
           ]
        }
      ]
    }
  },
  "errors": null
}
```

---

# Custom TURN domains

URL: https://developers.cloudflare.com/realtime/turn/custom-domains/

Cloudflare Realtime TURN service supports using custom domains for UDP, and TCP - but not TLS protocols. Custom domains do not affect any of the performance of Cloudflare Realtime TURN and is set up via a simple CNAME DNS record on your domain.

| Protocol      | Custom domains | Primary port | Alternate port |
| ------------- | -------------- | ------------ | -------------- |
| STUN over UDP | ✅              | 3478/udp     | 53/udp         |
| TURN over UDP | ✅              | 3478/udp     | 53 udp         |
| TURN over TCP | ✅              | 3478/tcp     | 80/tcp         |
| TURN over TLS | No             | 5349/tcp     | 443/tcp        |

## Setting up a CNAME record

To use custom domains for TURN, you must create a CNAME DNS record pointing to `turn.cloudflare.com`.

:::caution


Do not resolve the address of `turn.cloudflare.com` or `stun.cloudflare.com` or use an IP address as the value you input to your DNS record. Only CNAME records are supported.


:::

Any DNS provider, including Cloudflare DNS can be used to set up a CNAME for custom domains.

:::note


If Cloudflare's authoritative DNS service is used, the record must be set to [DNS-only or "grey cloud" mode](/dns/proxy-status/#dns-only-records).\`


:::

There is no additional charge to using a custom hostname with Cloudflare Realtime TURN.

---

# FAQ

URL: https://developers.cloudflare.com/realtime/turn/faq/

## General

### What is Cloudflare Realtime TURN pricing? How exactly is it calculated?

Cloudflare TURN pricing is based on the data sent from the Cloudflare edge to the TURN client, as described in [RFC 8656 Figure 1](https://datatracker.ietf.org/doc/html/rfc8656#fig-turn-model). This means data sent from the TURN server to the TURN client and captures all data, including TURN overhead, following successful authentication.

Pricing for Cloudflare Realtime TURN service is $0.05 per GB of data used.

Cloudflare's STUN service at `stun.cloudflare.com` is free and unlimited.

There is a free tier of 1,000 GB before any charges start. Cloudflare Realtime billing appears as a single line item on your Cloudflare bill, covering both SFU and TURN.

Traffic between Cloudflare Realtime TURN and Cloudflare Realtime SFU or Cloudflare Stream (WHIP/WHEP) does not incur any charges.

<div class="full-img">

```mermaid
---
title: Cloudflare Realtime TURN pricing
---
flowchart LR
    Client[TURN Client]
    Server[TURN Server]

    Client -->|"Ingress (free)"| Server
    Server -->|"Egress (charged)"| Client

    Server <-->|Not part of billing| PeerA[Peer A]
```

</div>

### Is Realtime TURN HIPAA/GDPR/FedRAMP compliant?

Please view Cloudflare's [certifications and compliance resources](https://www.cloudflare.com/trust-hub/compliance-resources/) and contact your Cloudflare enterprise account manager for more information.

### Is Realtime TURN end-to-end encrypted?

TURN protocol, [RFC 8656](https://datatracker.ietf.org/doc/html/rfc8656), does not discuss encryption beyond wrapper protocols such as TURN over TLS. If you are using TURN with WebRTC will encrypt data at the WebRTC level.

### What regions does Cloudflare Realtime TURN operate at?

Cloudflare Realtime TURN server runs on [Cloudflare's global network](https://www.cloudflare.com/network) - a growing global network of thousands of machines distributed across hundreds of locations, with the notable exception of the Cloudflare's [China Network](/china-network/).

### Does Cloudflare Realtime TURN use the Cloudflare Backbone or is there any "magic" Cloudflare do to speed connection up?

Cloudflare Realtime TURN allocations are homed in the nearest available Cloudflare data center to the TURN client via anycast routing. If both ends of a connection are using Cloudflare Realtime TURN, Cloudflare will be able to control the routing and, if possible, route TURN packets through the Cloudflare backbone.

### What is the difference between Cloudflare Realtime TURN with a enterprise plan vs self-serve (pay with your credit card) plans?

There is no performance or feature level difference for Cloudflare Realtime TURN service in enterprise or self-serve plans, however those on [enterprise plans](https://www.cloudflare.com/enterprise/) will get the benefit of priority support, predictable flat-rate pricing and SLA guarantees.

### Does Cloudflare Realtime TURN run in the Cloudflare China Network?

Cloudflare's [China Network](/china-network/) does not participate in serving Realtime traffic and TURN traffic from China will connect to Cloudflare locations outside of China.

### How long does it take for TURN activity to be available in analytics?

TURN usage shows up in analytics in 30 seconds.

## Technical

### I need to allowlist (whitelist) Cloudflare Realtime TURN IP addresses. Which IP addresses should I use?

Cloudflare Realtime TURN is easy to use by IT administrators who have strict firewalls because it requires very few IP addresses to be allowlisted compared to other providers. You must allowlist both IPv6 and IPv4 addresses.

Please allowlist the following IP addresses:

- `2a06:98c1:3200::1/128`
- `2606:4700:48::1/128`
- `141.101.90.1/32`
- `162.159.207.1/32`

:::caution[Watch for IP changes]

Cloudflare tries to, but cannot guarantee that the IP addresses used for the TURN service won't change. If you are allowlisting IP addresses and do not have a enterprise contract, you must set up alerting that detects changes the DNS response from `turn.cloudflare.com` (A and AAAA records) and update the hardcoded IP address(es) accordingly within 14 days of the DNS change.

For more details about static IPs, guarantees and other arrangements please discuss with your enterprise account team.

Your enterprise team will be able to provide additional addresses to allowlist as future backup to achieve address diversity while still keeping a short list of IPs.

:::

### I would like to hardcode IP addresses used for TURN in my application to save a DNS lookup

Although this is not recommended, we understand there is a very small set of circumstances where hardcoding IP addresses might be useful. In this case, you must set up alerting that detects changes the DNS response from `turn.cloudflare.com` (A and AAAA records) and update the hardcoded IP address(es) accordingly within 14 days of the DNS change. Note that this DNS response could return more than one IP address. In addition, you must set up a failover to a DNS query if there is a problem connecting to the hardcoded IP address. Cloudflare tries to, but cannot guarantee that the IP address used for the TURN service won't change unless this is in your enterprise contract. For more details about static IPs, guarantees and other arrangements please discuss with your enterprise account team.

### I see that TURN IP are published above. Do you also publish IPs for STUN?

TURN service at `turn.cloudflare.com` will also respond to binding requests ("STUN requests").

### Does Cloudflare Realtime TURN support the expired IETF RFC draft "draft-uberti-behave-turn-rest-00"?

The Cloudflare Realtime credential generation function returns a JSON structure similar to the [expired RFC draft "draft-uberti-behave-turn-rest-00"](https://datatracker.ietf.org/doc/html/draft-uberti-behave-turn-rest-00), but it does not include the TTL value. If you need a response in this format, you can modify the JSON from the Cloudflare Realtime credential generation endpoint to the required format in your backend server or Cloudflare Workers.

### I am observing packet loss when using Cloudflare Realtime TURN - how can I debug this?

Packet loss is normal in UDP and can happen occasionally even on reliable connections. However, if you observe systematic packet loss, consider the following:

- Are you sending or receiving data at a high rate (>50-100Mbps) from a single TURN client? Realtime TURN might be dropping packets to signal you to slow down.
- Are you sending or receiving large amounts of data with very small packet sizes (high packet rate > 5-10kpps) from a single TURN client? Cloudflare Realtime might be dropping packets.
- Are you sending packets to new unique addresses at a high rate resembling to [port scanning](https://en.wikipedia.org/wiki/Port_scanner) behavior?

### I plan to use Realtime TURN at scale. What is the rate at which I can issue credentials?

There is no defined limit for credential issuance. Start at 500 credentials/sec and scale up linearly. Ensure you use more than 50% of the issued credentials.

### What is the maximum value I can use for TURN credential expiry time?

You can set a expiration time for a credential up to 48 hours in the future. If you need your TURN allocation to last longer than this, you will need to [update](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/setConfiguration) the TURN credentials.

### Does Realtime TURN support IPv6?

Yes. Cloudflare Realtime is available over both IPv4 and IPv6 for TURN Client to TURN server communication, however it does not issue relay addresses in IPv6 as described in [RFC 6156](https://datatracker.ietf.org/doc/html/rfc6156).

### Does Realtime TURN issue IPv6 relay addresses?

No. Realtime TURN will not respect `REQUESTED-ADDRESS-FAMILY` STUN attribute if specified and will issue IPv4 addresses only.

### Does Realtime TURN support TCP relaying?

No. Realtime does not implement [RFC6062](https://datatracker.ietf.org/doc/html/rfc6062) and will not respect `REQUESTED-TRANSPORT` STUN attribute.

### I am unable to make CreatePermission or ChannelBind requests with certain IP addresses. Why is that?

Cloudflare Realtime denies CreatePermission or ChannelBind requests if private IP ranges (e.g loopback addresses, linklocal unicast or multicast blocks) or IP addresses that are part of [BYOIP](/byoip/) are used.

If you are a Cloudflare BYOIP customer and wish to connect to your BYOIP ranges with Realtime TURN, please reach out to your account manager for further details.

### What is the maximum duration limit for a TURN allocation?

There is no maximum duration limit for a TURN allocation. Per [RFC 8656 Section 3.2](https://datatracker.ietf.org/doc/html/rfc8656#section-3.2), once a relayed transport address is allocated, a client must keep the allocation alive. To do this, the client periodically sends a Refresh request to the server. The Refresh request needs to be authenticated with a valid TURN credential. The maximum duration for a credential is 48 hours. If a longer allocation is required, a new credential must be generated at least every 48 hours.

### How often does Cloudflare perform maintenance on a server that is actively handling a TURN allocation? What is the impact of this?

Even though this is not common, in certain scenarios TURN allocations may be disrupted. This could be caused by maintenance on the Cloudflare server handling the allocation or could be related to Internet network topology changes that cause TURN packets to arrive at a different Cloudflare datacenter. Regardless of the reason, [ICE restart](https://datatracker.ietf.org/doc/html/rfc8445#section-2.4) support by clients is highly recommended.

### What will happen if TURN credentials expire while the TURN allocation is in use?

Cloudflare Realtime will immediately stop billing and recording usage for analytics. After a short delay, the connection will be disconnected.

---

# Generate Credentials

URL: https://developers.cloudflare.com/realtime/turn/generate-credentials/

Cloudflare will issue TURN keys, but these keys cannot be used as credentials with `turn.cloudflare.com`. To use TURN, you need to create credentials with a expiring TTL value.

## Create a TURN key

To create a TURN credential, you first need to create a TURN key using [Dashboard](https://dash.cloudflare.com/?to=/:account/calls), or the [API](/api/resources/calls/subresources/turn/methods/create/).

You should keep your TURN key on the server side (don't share it with the browser/app). A TURN key is a long-term secret that allows you to generate unlimited, shorter lived TURN credentials for TURN clients.

With a TURN key you can:

* Generate TURN credentials that expire
* Revoke previously issued TURN credentials

## Create credentials

You should generate short-lived credentials for each TURN user. In order to create credentials, you should have a back-end service that uses your TURN Token ID and API token to generate credentials. It will make an API call like this:

```bash
curl https://rtc.live.cloudflare.com/v1/turn/keys/$TURN_KEY_ID/credentials/generate-ice-servers \
--header "Authorization: Bearer $TURN_KEY_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{"ttl": 86400}'
```

The JSON response below can then be passed on to your front-end application:

```json
{
  "iceServers": [
		{
			"urls": [
				"stun:stun.cloudflare.com:3478",
				"stun:stun.cloudflare.com:53",
				"turn:turn.cloudflare.com:3478?transport=udp",
				"turn:turn.cloudflare.com:53?transport=udp",
				"turn:turn.cloudflare.com:3478?transport=tcp",
				"turn:turn.cloudflare.com:80?transport=tcp",
				"turns:turn.cloudflare.com:5349?transport=tcp",
				"turns:turn.cloudflare.com:443?transport=tcp"
			],
			"username": "bc91b63e2b5d759f8eb9f3b58062439e0a0e15893d76317d833265ad08d6631099ce7c7087caabb31ad3e1c386424e3e",
			"credential": "ebd71f1d3edbc2b0edae3cd5a6d82284aeb5c3b8fdaa9b8e3bf9cec683e0d45fe9f5b44e5145db3300f06c250a15b4a0"
		}
	]
}
```

:::note
The list of returned URLs contains URLs with the primary and alternate ports. The alternate port 53 is known to be blocked by web browsers, and the TURN URL will time out if used in browsers. If you are using trickle ICE, this will not cause issues. Without trickle ICE you might want to filter out the URL with port 53 to avoid waiting for a timeout.
:::

Use `iceServers` as follows when instantiating the `RTCPeerConnection`:

```js
const myPeerConnection = new RTCPeerConnection({
  iceServers: [
    {
      urls: [
				"stun:stun.cloudflare.com:3478",
				"stun:stun.cloudflare.com:53",
				"turn:turn.cloudflare.com:3478?transport=udp",
				"turn:turn.cloudflare.com:53?transport=udp",
				"turn:turn.cloudflare.com:3478?transport=tcp",
				"turn:turn.cloudflare.com:80?transport=tcp",
				"turns:turn.cloudflare.com:5349?transport=tcp",
				"turns:turn.cloudflare.com:443?transport=tcp"
      ],
			"username": "bc91b63e2b5d759f8eb9f3b58062439e0a0e15893d76317d833265ad08d6631099ce7c7087caabb31ad3e1c386424e3e",
			"credential": "ebd71f1d3edbc2b0edae3cd5a6d82284aeb5c3b8fdaa9b8e3bf9cec683e0d45fe9f5b44e5145db3300f06c250a15b4a0"
    },
  ],
});

```

The `ttl` value can be adjusted to expire the short lived key in a certain amount of time. This value should be larger than the time you'd expect the users to use the TURN service. For example, if you're using TURN for a video conferencing app, the value should be set to the longest video call you'd expect to happen in the app.

When using short-lived TURN credentials with WebRTC, credentials can be refreshed during a WebRTC session using the `RTCPeerConnection` [`setConfiguration()`](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/setConfiguration) API.

## Revoke credentials

Short lived credentials can also be revoked before their TTL expires with a API call like this:

```bash
curl --request POST \
https://rtc.live.cloudflare.com/v1/turn/keys/$TURN_KEY_ID/credentials/$USERNAME/revoke \
--header "Authorization: Bearer $TURN_KEY_API_TOKEN"
```

---

# TURN Service

URL: https://developers.cloudflare.com/realtime/turn/

Separately from the SFU, Realtime offers a managed TURN service. TURN acts as a relay point for traffic between WebRTC clients like the browser and SFUs, particularly in scenarios where direct communication is obstructed by NATs or firewalls. TURN maintains an allocation of public IP addresses and ports for each session, ensuring connectivity even in restrictive network environments.

Using Cloudflare Realtime TURN service is available free of charge when used together with the Realtime SFU. Otherwise, it costs $0.05/real-time GB outbound from Cloudflare to the TURN client.

## Service address and ports

| Protocol      | Primary address     | Primary port | Alternate port |
| ------------- | ------------------- | ------------ | -------------- |
| STUN over UDP | stun.cloudflare.com | 3478/udp     | 53/udp         |
| TURN over UDP | turn.cloudflare.com | 3478/udp     | 53 udp         |
| TURN over TCP | turn.cloudflare.com | 3478/tcp     | 80/tcp         |
| TURN over TLS | turn.cloudflare.com | 5349/tcp     | 443/tcp        |

:::note[Note]
Use of alternate port 53 only by itself is not recommended. Port 53 is blocked by many ISPs, and by popular browsers such as [Chrome](https://chromium.googlesource.com/chromium/src.git/+/refs/heads/master/net/base/port_util.cc#44) and [Firefox](https://github.com/mozilla/gecko-dev/blob/master/netwerk/base/nsIOService.cpp#L132). It is useful only in certain specific scenerios.
:::

## Regions

Realtime TURN service is available in every Cloudflare data center.

When a client tries to connect to `turn.cloudflare.com`, it _automatically_ connects to the Cloudflare location closest to them. We achieve this using anycast routing.

To learn more about the architecture that makes this possible, read this [technical deep-dive about Realtime](https://blog.cloudflare.com/cloudflare-calls-anycast-webrtc).

## Protocols and Ciphers for TURN over TLS

TLS versions supported include TLS 1.1, TLS 1.2, and TLS 1.3.

| OpenSSL Name                  | TLS 1.1 | TLS 1.2 | TLS 1.3 |
| ----------------------------- | ------- | ------- | ------- |
| AEAD-AES128-GCM-SHA256        | No      | No      | ✅      |
| AEAD-AES256-GCM-SHA384        | No      | No      | ✅      |
| AEAD-CHACHA20-POLY1305-SHA256 | No      | No      | ✅      |
| ECDHE-ECDSA-AES128-GCM-SHA256 | No      | ✅      | No      |
| ECDHE-RSA-AES128-GCM-SHA256   | No      | ✅      | No      |
| ECDHE-RSA-AES128-SHA          | ✅      | ✅      | No      |
| AES128-GCM-SHA256             | No      | ✅      | No      |
| AES128-SHA                    | ✅      | ✅      | No      |
| AES256-SHA                    | ✅      | ✅      | No      |

## MTU

There is no specific MTU limit for Cloudflare Realtime TURN service.

## Limits

Cloudflare Realtime TURN service places limits on:

- Unique IP address you can communicate with per relay allocation (>5 new IP/sec)
- Packet rate outbound and inbound to the relay allocation (>5-10 kpps)
- Data rate outbound and inbound to the relay allocation (>50-100 Mbps)

:::note[Limits apply to each TURN allocation independently]

Each limit is for a single TURN allocation (single TURN user) and not account wide. Same limit will apply to each user regardless of the number of unique TURN users.

:::

These limits are suitable for high-demand applications and also have burst rates higher than those documented above. Hitting these limits will result in packet drops.

---

# Replacing existing TURN servers

URL: https://developers.cloudflare.com/realtime/turn/replacing-existing/

If you are a existing TURN provider but would like to switch to providing Cloudflare Realtime TURN for your customers, there is a few considerations.

## Benefits

Cloudflare Realtime TURN service can reduce tangible and untangible costs associated with TURN servers:

* Server costs (AWS EC2 etc)
* Bandwidth costs (Egress, load balancing etc)
* Time and effort to set up a TURN process and maintenance of server
* Scaling the servers up and down
* Maintain the TURN server with security and feature updates
* Maintain high availability

## Recommendations

### Separate environments with TURN keys

When using Cloudflare Realtime TURN service at scale, consider separating environments such as "testing", "staging" or "production" with TURN keys. You can create up to 1,000 TURN keys in your account, which can be used to generate end user credentials.

There is no limit to how many end-user credentials you can create with a particular TURN key.

### Tag users with custom identifiers

Cloudflare Realtime TURN service lets you tag each credential with a custom identifier as you generate a credential like below:

```bash null {4}
curl https://rtc.live.cloudflare.com/v1/turn/keys/$TURN_KEY_ID/credentials/generate \
--header "Authorization: Bearer $TURN_KEY_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{"ttl": 864000, "customIdentifier": "user4523958"}'
```

Use this field to aggregate usage for a specific user or group of users and collect analytics.

### Monitor usage

You can monitor account wide usage with the [GraphQL analytics API](/realtime/turn/analytics/). This is useful for keeping track of overall usage for billing purposes, watching for unexpected changes. You can get timeseries data from TURN analytics with various filters in place.

### Monitor for credential abuse

If you share TURN credentials with end users, credential abuse is possible. You can monitor for abuse by tagging each credential with custom identifiers and monitoring for top custom identifiers in your application via the [GraphQL analytics API](/realtime/turn/analytics/).

## How to bill end users for their TURN usage

When billing for TURN usage in your application, it's crucial to understand and account for adaptive sampling in TURN analytics. This system employs adaptive sampling to efficiently handle large datasets while maintaining accuracy.

The sampling process in TURN analytics works on two levels:

* At data collection: Usage data points may be sampled if they are generated too quickly.
* At query time: Additional sampling may occur if the query is too complex or covers a large time range.

To ensure accurate billing, write a single query that sums TURN usage per customer per time period, returning a single value. Avoid using queries that list usage for multiple customers simultaneously.

By following these guidelines and understanding how TURN analytics handles sampling, you can ensure more accurate billing for your end users based on their TURN usage.

:::note


Cloudflare Realtime only bills for traffic from Cloudflare's servers to your client, called `egressBytes`.


:::

### Example queries

:::caution[Incorrect approach example]


Querying TURN usage for multiple customers in a single query can lead to inaccurate results. This is because the usage pattern of one customer could affect the sampling rate applied to another customer's data, potentially skewing the results.


:::

```
query{
  viewer {
    usage: accounts(filter: { accountTag: "8846293bd06d1af8c106d89ec1454fe6" }) {
        callsTurnUsageAdaptiveGroups(
          filter: {
          datetimeMinute_gt: "2024-07-15T02:07:07Z"
          datetimeMinute_lt: "2024-08-10T02:07:05Z"
        }
          limit: 100
          orderBy: [customIdentifier_ASC]
        ) {
          dimensions {
            customIdentifier
          }
          sum {
            egressBytes
          }
        }
      }
    }
  }
```

Below is a query that queries usage only for a single customer.

```
query{
  viewer {
    usage: accounts(filter: { accountTag: "8846293bd06d1af8c106d89ec1454fe6" }) {
        callsTurnUsageAdaptiveGroups(
          filter: {
          datetimeMinute_gt: "2024-07-15T02:07:07Z"
          datetimeMinute_lt: "2024-08-10T02:07:05Z"
          customIdentifier: "myCustomer1111"
        }
          limit: 1
          orderBy: [customIdentifier_ASC]
        ) {
          dimensions {
            customIdentifier
          }
          sum {
            egressBytes
          }
        }
      }
    }
  }

```

---

# TURN Feature Matrix

URL: https://developers.cloudflare.com/realtime/turn/rfc-matrix/

## TURN client to TURN server protocols

| Protocol | Support | Relevant specification                                                                                    |
| -------- | ------- | --------------------------------------------------------------------------------------------------------- |
| UDP      | ✅       | [RFC 5766](https://datatracker.ietf.org/doc/html/rfc5766)                                                 |
| TCP      | ✅       | [RFC 5766](https://datatracker.ietf.org/doc/html/rfc5766)                                                 |
| TLS      | ✅       | [RFC 5766](https://datatracker.ietf.org/doc/html/rfc5766)                                                 |
| DTLS     | No      | [draft-petithuguenin-tram-turn-dtls-00](http://tools.ietf.org/html/draft-petithuguenin-tram-turn-dtls-00) |

## TURN client to TURN server protocols

| Protocol                                        | Support                                                                                                                        | Relevant specification                                                                                               |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| TURN (base RFC)                                 | ✅                                                                                                                              | [RFC 5766](https://datatracker.ietf.org/doc/html/rfc5766)                                                            |
| TURN REST API                                   | ✅ (See [FAQ](/realtime/turn/faq/#does-cloudflare-realtime-turn-support-the-expired-ietf-rfc-draft-draft-uberti-behave-turn-rest-00)) | [draft-uberti-behave-turn-rest-00](http://tools.ietf.org/html/draft-uberti-behave-turn-rest-00)                      |
| Origin field in TURN (Multi-tenant TURN Server) | ✅                                                                                                                              | [draft-ietf-tram-stun-origin-06](https://tools.ietf.org/html/draft-ietf-tram-stun-origin-06)                         |
| ALPN support for STUN & TURN                    | ✅                                                                                                                              | [RFC 7443](https://datatracker.ietf.org/doc/html/rfc7443)                                                            |
| TURN Bandwidth draft specs                      | No                                                                                                                             | [draft-thomson-tram-turn-bandwidth-01](http://tools.ietf.org/html/draft-thomson-tram-turn-bandwidth-01)              |
| TURN-bis (with dual allocation) draft specs     | No                                                                                                                             | [draft-ietf-tram-turnbis-04](http://tools.ietf.org/html/draft-ietf-tram-turnbis-04)                                  |
| TCP relaying TURN extension                     | No                                                                                                                             | [RFC 6062](https://datatracker.ietf.org/doc/html/rfc6062)                                                            |
| IPv6 extension for TURN                         | No                                                                                                                             | [RFC 6156](https://datatracker.ietf.org/doc/html/rfc6156)                                                            |
| oAuth third-party TURN/STUN authorization       | No                                                                                                                             | [RFC 7635](https://datatracker.ietf.org/doc/html/rfc7635)                                                            |
| DTLS support (for TURN)                         | No                                                                                                                             | [draft-petithuguenin-tram-stun-dtls-00](https://datatracker.ietf.org/doc/html/draft-petithuguenin-tram-stun-dtls-00) |
| Mobile ICE (MICE) support                       | No                                                                                                                             | [draft-wing-tram-turn-mobility-02](http://tools.ietf.org/html/draft-wing-tram-turn-mobility-02)                      |

---

# What is TURN?

URL: https://developers.cloudflare.com/realtime/turn/what-is-turn/

## What is TURN?

TURN (Traversal Using Relays around NAT) is a protocol that assists in traversing Network Address Translators (NATs) or firewalls in order to facilitate peer-to-peer communications. It is an extension of the STUN (Session Traversal Utilities for NAT) protocol and is defined in [RFC 8656](https://datatracker.ietf.org/doc/html/rfc8656).

## How do I use TURN?

Just like you would use a web browser or cURL to use the HTTP protocol, you need to use a tool or a library to use TURN protocol in your application.

Most users of TURN will use it as part of a WebRTC library, such as the one in their browser or part of [Pion](https://github.com/pion/webrtc), [webrtc-rs](https://github.com/webrtc-rs/webrtc) or [libwebrtc](https://webrtc.googlesource.com/src/).

You can use TURN directly in your application too. [Pion](https://github.com/pion/turn) offers a TURN client library in Golang, so does [webrtc-rs](https://github.com/webrtc-rs/webrtc/tree/master/turn) in Rust.

## Key concepts to know when understanding TURN

1. **NAT (Network Address Translation)**: A method used by routers to map multiple private IP addresses to a single public IP address. This is commonly done by home internet routers so multiple computers in the same network can share a single public IP address.

2. **TURN Server**: A relay server that acts as an intermediary for traffic between clients behind NATs. Cloudflare Realtime TURN service is a example of a TURN server.

3. **TURN Client**: An application or device that uses the TURN protocol to communicate through a TURN server. This is your application. It can be a web application using the WebRTC APIs or a native application running on mobile or desktop.

4. **Allocation**: When a TURN server creates an allocation, the TURN server reserves an IP and a port unique to that client.

5. **Relayed Transport Address**: The IP address and port reserved on the TURN server that others on the Internet can use to send data to the TURN client.

## How TURN Works

1. A TURN client sends an Allocate request to a TURN server.
2. The TURN server creates an allocation and returns a relayed transport address to the client.
3. The client can then give this relayed address to its peers.
4. When a peer sends data to the relayed address, the TURN server forwards it to the client.
5. When the client wants to send data to a peer, it sends it through the TURN server, which then forwards it to the peer.

## TURN vs VPN

TURN works similar to a VPN (Virtual Private Network). However TURN servers and VPNs serve different purposes and operate in distinct ways.

A VPN is a general-purpose tool that encrypts all internet traffic from a device, routing it through a VPN server to enhance privacy, security, and anonymity. It operates at the network layer, affects all internet activities, and is often used to bypass geographical restrictions or secure connections on public Wi-Fi.

A TURN server is a specialized tool used by specific applications, particularly for real-time communication. It operates at the application layer, only affecting traffic for applications that use it, and serves as a relay to traverse NATs and firewalls when direct connections between peers are not possible. While a VPN impacts overall internet speed and provides anonymity, a TURN server only affects the performance of specific applications using it.

## Why is TURN Useful?

TURN is often valuable in scenarios where direct peer-to-peer communication is impossible due to NAT or firewall restrictions. Here are some key benefits:

1. **NAT Traversal**: TURN provides a way to establish connections between peers that are both behind NATs, which would otherwise be challenging or impossible.

2. **Firewall Bypassing**: In environments with strict firewall policies, TURN can enable communication that would otherwise be blocked.

3. **Consistent Connectivity**: TURN offers a reliable fallback method when direct or NAT-assisted connections fail.

4. **Privacy**: By relaying traffic through a TURN server, the actual IP addresses of the communicating parties can be hidden from each other.

5. **VoIP and Video Conferencing**: TURN is crucial for applications like Voice over IP (VoIP) and video conferencing, ensuring reliable connections regardless of network configuration.

6. **Online Gaming**: TURN can help online games establish peer-to-peer connections between players behind different types of NATs.

7. **IoT Device Communication**: Internet of Things (IoT) devices can use TURN to communicate when they're behind NATs or firewalls.

---

# Add additional audio tracks

URL: https://developers.cloudflare.com/stream/edit-videos/adding-additional-audio-tracks/

A video must be uploaded before additional audio tracks can be attached to it. In the following example URLs, the video’s UID is referenced as `VIDEO_UID`.

To add an audio track to a video a [Cloudflare API Token](https://www.cloudflare.com/a/account/my-account) is required.

The API will make a best effort to handle any mismatch between the duration of the uploaded audio file and the video duration, though we recommend uploading audio files that match the duration of the video. If the duration of the audio file is longer than the video, the additional audio track will be truncated to match the video duration. If the duration of the audio file is shorter than the video, silence will be appended at the end of the audio track to match the video duration.

## Upload via a link

If you have audio files stored in a cloud storage bucket, you can simply pass a HTTP link for the file. Stream will fetch the file and make it available for streaming.

`label` is required and must uniquely identify the track amongst other audio track labels for the specified video.

```bash
curl -X POST \
 -H 'Authorization: Bearer <API_TOKEN>' \
 -d '{"url": "https://www.examplestorage.com/audio_file.mp3", "label": "Example Audio Label"}' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/audio/copy
```

```json title="Example response to add additional audio tracks"
{
 "result": {
   "uid": "<AUDIO_UID>",
   "label": "Example Audio Label",
   "default": false
   "status": "queued"
 },
 "success": true,
 "errors": [],
 "messages": []
}
```

The `uid` uniquely identifies the audio track and can be used for editing or deleting the audio track. Please see instructions below on how to perform these operations.

The `default` field denotes whether the audio track will be played by default in a player. Additional audio tracks have a `false` default status, but can be edited following instructions below.

The `status` field will change to `ready` after the audio track is successfully uploaded and encoded. Should an error occur during this process, the status will denote `error`.

## Upload via HTTP

Make an HTTP request and include the audio file as an input with the name set to `file`.

Audio file uploads cannot exceed 200 MB in size. If your audio file is larger, compress the file prior to upload.

The form input `label` is required and must uniquely identify the track amongst other audio track labels for the specified video.

Note that cURL `-F` flag automatically configures the content-type header and maps `audio_file.mp3` to a form input called `file`.

```bash
curl -X POST \
 -H 'Authorization: Bearer <API_TOKEN>' \
 -F file=@/Desktop/audio_file.mp3 \
 -F label='Example Audio Label' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/audio
```

```json title="Example response to add Additional audio tracks"
{
 "result": {
   "uid": "<AUDIO_UID>",
   "label": "Example Audio Label",
   "default": false
   "status": "queued"
 },
 "success": true,
 "errors": [],
 "messages": []
}
```

## List the additional audio tracks on a video

To view additional audio tracks added to a video:

```bash
curl \
 -H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/audio
```

```json title="Example response to get the audio tracks associated with a video"
{
  "result": {
    "audio": [
      {
        "uid": "<AUDIO_UID>",
        "label": "Example Audio Label",
        "default": false,
        "status": "ready"
      },
      {
        "uid": "<AUDIO_UID>",
        "label": "Another Audio Label",
        "default": false,
        "status": "ready"
      }
    ]
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

Note this API will not return information for audio attached to the video upload.

## Edit an additional audio track

To edit the `default` status or `label` of an additional audio track:

```bash
curl -X PATCH \
 -H 'Authorization: Bearer <API_TOKEN>' \
 -d '{"label": "Edited Audio Label", "default": true}' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/audio/<AUDIO_UID>
```

Editing the `default` status of an audio track to `true` will mark all other audio tracks on the video `default` status to `false`.

```json title="Example response to edit the audio tracks associated with a video"
{
  "result": {
    "uid": "<AUDIO_UID>",
    "label": "Edited Audio Label",
    "default": true
    "status": "ready"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

## Delete an additional audio track

To remove an additional audio track associated with your video:

```bash
curl -X DELETE \
 -H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/audio/<AUDIO_UID>
```

Deleting a `default` audio track is not allowed.  You must assign another audio track as `default` prior to deletion.

If there is an entry in `errors` response field, the audio track has not been
deleted.

```json title="Example response to delete an audio track"
{
  "result": "ok",
  "success": true,
  "errors": [],
  "messages": []
}
```

---

# Add captions

URL: https://developers.cloudflare.com/stream/edit-videos/adding-captions/

Adding captions and subtitles to your video library.

## Add or modify a caption

There are two ways to add captions to a video: generating via AI or uploading a
caption file.

To create or modify a caption on a video a [Cloudflare API Token](https://www.cloudflare.com/a/account/my-account) is required.

The `<LANGUAGE_TAG>` must adhere to the [BCP 47 format](http://www.unicode.org/reports/tr35/#Unicode_Language_and_Locale_Identifiers). For convenience, many common
language codes are provided [at the bottom of this document](#most-common-language-codes).
If the language you are adding is not included in the table, you can find the value
through the [The IANA registry](https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry), which maintains a list of language codes. To find the
value to send, search for the language. Below is an example value from IANA when
we look for the value to send for a Turkish subtitle:

```bash
%%
Type: language
Subtag: tr
Description: Turkish
Added: 2005-10-16
Suppress-Script: Latn
%%
```

The `Subtag` code indicates a value of `tr`. This is the value you should send
as the `language` at the end of the HTTP request.

A label is generated from the provided language. The label will be visible for
user selection in the player. For example, if sent `tr`, the label `Türkçe` will
be created; if sent `de`, the label `Deutsch` will be created.

### Generate a caption

Generated captions use artificial intelligence based speech-to-text technology
to generate closed captions for your videos.

A video must be uploaded and in a ready state before captions can be generated.
In the following example URLs, the video's UID is referenced as `<VIDEO_UID>`.
To receive webhooks when a video transitions to ready after upload, follow the
instructions provided in [using webhooks](/stream/manage-video-library/using-webhooks/).

Captions can be generated for the following languages:

- `cs` - Czech
- `nl` - Dutch
- `en` - English
- `fr` - French
- `de` - German
- `it` - Italian
- `ja` - Japanese
- `ko` - Korean
- `pl` - Polish
- `pt` - Portuguese
- `ru` - Russian
- `es` - Spanish

When generating captions, generate them for the spoken language in the audio.

Videos may include captions for several languages, but each language must be unique.
For example, a video may have English, French, and German captions associated
with it, but it cannot have two English captions. If you have already uploaded
an English language caption for a video, you must first delete it in order to
create an English generated caption. Instructions on how to delete a caption can be found below.

The `<LANGUAGE_TAG>` must adhere to the BCP 47 format. The tag for English is `en`.
You may specify a region in the tag, such as `en-GB`, which will render a label
that shows `British English` for the caption.

```bash
curl -X POST \
-H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>/generate
```

Example response:

```json
{
  "result": {
    "language": "en",
    "label": "English (auto-generated)",
    "generated": true,
    "status": "inprogress"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

The result will provide a `status` denoting the progress of the caption generation.\
There are three statuses: inprogress, ready, and error. Note that
(auto-generated) is applied to the label.

Once the generated caption is ready, it will automatically appear in the video
player and video manifest.

If the caption enters an error state, you may attempt to re-generate it by
first deleting it and then using the endpoint listed above.
Instructions on deletion are provided below.

### Upload a file

Note two changes if you edit a generated caption: the generated field will
change to `false` and the (auto-generated) portion of the label will be removed.

To create or replace a caption file:

```bash
curl -X PUT \
 -H 'Authorization: Bearer <API_TOKEN>' \
 -F file=@/Users/mickie/Desktop/example_caption.vtt \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>
```

### Example Response to Add or Modify a Caption

```json
{
  "result": {
    "language": "en",
    "label": "English",
    "generated": false,
    "status": "ready"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

## List the captions associated with a video

To view captions associated with a video.
Note this results list will also include generated captions that are `inprogress`
and `error` status:

```bash
curl -H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions
```

### Example response to get the captions associated with a video

```json
{
  "result": [
    {
      "language": "en",
      "label": "English (auto-generated)",
      "generated": true,
      "status": "inprogress"
    },
    {
      "language": "de",
      "label": "Deutsch",
      "generated": false,
      "status": "ready"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}
```

## Fetch a caption file

To view the WebVTT caption file, you may make a GET request:

```bash
curl \
-H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>/vtt
```

### Example response to get the caption file for a video

``` text
WEBVTT

1
00:00:00.000 --> 00:00:01.560
This is an example of

2
00:00:01.560 --> 00:00:03.880
a WebVTT caption response.
```

## Delete the captions

To remove a caption associated with your video:

```bash
curl -X DELETE \
 -H 'Authorization: Bearer <API_TOKEN>' \
 https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>
```

If there is an entry in `errors` response field, the caption has not been
deleted.

### Example response to delete the caption

```json
{
  "result": "",
  "success": true,
  "errors": [],
  "messages": []
}
```

## Limitations

* A video must be uploaded before a caption can be attached to it. In the following
  example URLs, the video's ID is referenced as `media_id`.
* Stream only supports [WebVTT](https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API)
  formatted caption files. If you have a differently formatted caption file,
  use [a tool to convert your file to WebVTT](https://subtitletools.com/convert-to-vtt-online)
  prior to uploading it.
* Videos may include several language captions, but each language must be unique.
  For example, a video may have English, French, and German captions associated
  with it, but it cannot have two French captions.
* Each caption file is limited to 10 MB in size. [Contact support](/support/contacting-cloudflare-support/)
  if you need to upload a larger file.

## Most common language codes

| Language Code | Language         |
| ------------- | ---------------- |
| zh            | Mandarin Chinese |
| hi            | Hindi            |
| es            | Spanish          |
| en            | English          |
| ar            | Arabic           |
| pt            | Portuguese       |
| bn            | Bengali          |
| ru            | Russian          |
| ja            | Japanese         |
| de            | German           |
| pa            | Panjabi          |
| jv            | Javanese         |
| ko            | Korean           |
| vi            | Vietnamese       |
| fr            | French           |
| ur            | Urdu             |
| it            | Italian          |
| tr            | Turkish          |
| fa            | Persian          |
| pl            | Polish           |
| uk            | Ukrainian        |
| my            | Burmese          |
| th            | Thai             |

---

# Edit videos

URL: https://developers.cloudflare.com/stream/edit-videos/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Apply watermarks

URL: https://developers.cloudflare.com/stream/edit-videos/applying-watermarks/

You can add watermarks to videos uploaded using the Stream API.

To add watermarks to your videos, first create a watermark profile. A watermark profile describes the image you would like to be used as a watermark and the position of that image. Once you have a watermark profile, you can use it as an option when uploading videos.

## Quick start

Watermark profile has many customizable options. However, the default parameters generally work for most cases. Please see "Profiles" below for more details.

### Step 1: Create a profile

```bash
curl -X POST -H 'Authorization: Bearer <API_TOKEN>' \
-F file=@/Users/rchen/cloudflare.png \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks
```

### Step 2: Specify the profile UID at upload

```bash
tus-upload --chunk-size 5242880 \
--header Authentication 'Bearer <API_TOKEN>' \
--metadata watermark <WATERMARK_UID> \
/Users/rchen/cat.mp4 https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream
```

### Step 3: Done

![Screenshot of a video with Cloudflare watermark at top right](~/assets/images/stream/cat.png)

## Profiles

To create, list, delete, or get information about the profile, you will need your
[Cloudflare API token](https://www.cloudflare.com/a/account/my-account).

### Optional parameters



* `name` string default: *empty string*

  * A short description for the profile. For example, "marketing videos."

* `opacity` float default: 1.0

  * Translucency of the watermark. 0.0 means completely transparent, and 1.0 means completely opaque. Note that if the watermark is already semi-transparent, setting this to 1.0 will not make it completely opaque.

* `padding` float default: 0.05

  * Blank space between the adjacent edges (determined by position) of the video and the watermark. 0.0 means no padding, and 1.0 means padded full video width or length.

  * Stream will make sure that the watermark will be at about the same position across videos with different dimensions.

* `scale` float default: 0.15

  * The size of the watermark relative to the overall size of the video. This parameter will adapt to horizontal and vertical videos automatically. 0.0 means no scaling (use the size of the watermark as-is), and 1.0 fills the entire video.

  * The algorithm will make sure that the watermark will look about the same size across videos with different dimensions.

* `position` string (enum) default: "upperRight"

  * Location of the watermark. Valid positions are: `upperRight`, `upperLeft`, `lowerLeft`, `lowerRight`, and `center`.

    :::note

    Note that `center` will ignore the `padding` parameter.
    :::



## Creating a Watermark profile

### Use Case 1: Upload a local image file directly

To upload the image directly, please send a POST request using `multipart/form-data` as the content-type and specify the file under the `file` key. All other fields are optional.

```bash
curl -X POST -H "Authorization: Bearer <API_TOKEN>" \
-F file=@{path-to-image-locally} \
-F name='marketing videos' \
-F opacity=1.0 \
-F padding=0.05 \
-F scale=0.15 \
-F position=upperRight \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks
```

### Use Case 2: Pass a URL to an image

To specify a URL for upload, please send a POST request using `application/json` as the content-type and specify the file location using the `url` key. All other fields are optional.

```bash
curl -X POST -H "Authorization: Bearer <API_TOKEN>" \
-H 'Content-Type: application/json' \
-d '{
  "url": "{url-to-image}",
  "name": "marketing videos",
  "opacity": 1.0,
  "padding": 0.05,
  "scale": 0.15,
  "position": "upperRight"
}' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks
```

#### Example response to creating a watermark profile

```json
{
  "result": {
    "uid": "d6373709b7681caa6c48ef2d8c73690d",
    "size": 11248,
    "height": 240,
    "width": 720,
    "created": "2020-07-29T00:16:55.719265Z",
    "downloadedFrom": null,
    "name": "marketing videos",
    "opacity": 1.0,
    "padding": 0.05,
    "scale": 0.15,
    "position": "upperRight"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

`downloadedFrom` will be populated if the profile was created via downloading from URL.

## Using a watermark profile on a video

Once you created a watermark profile, you can now use the profile at upload time for watermarking videos.

### Basic uploads

Unfortunately, Stream does not currently support specifying watermark profile at upload time for Basic Uploads.

### Upload video with a link

```bash
curl -X POST -H "Authorization: Bearer <API_TOKEN>" \
-H 'Content-Type: application/json' \
-d '{
  "url": "{url-to-video}",
  "watermark": {
    "uid": "<WATERMARK_UID>"
  }
}' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/copy
```

#### Example response to upload video with a link

```json null {10,11,12,13,14,15,16,17,18,19,20,21,22}
{
  "result": {
    "uid": "8d3a5b80e7437047a0fb2761e0f7a645",
    "thumbnail": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg",

    "playback": {
      "hls": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8",
      "dash": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.mpd"
    },
    "watermark": {
      "uid": "d6373709b7681caa6c48ef2d8c73690d",
      "size": 11248,
      "height": 240,
      "width": 720,
      "created": "2020-07-29T00:16:55.719265Z",
      "downloadedFrom": null,
      "name": "marketing videos",
      "opacity": 1.0,
      "padding": 0.05,
      "scale": 0.15,
      "position": "upperRight"
    }

}
```

### Upload video with tus

```bash
tus-upload --chunk-size 5242880 \
--header Authentication 'Bearer <API_TOKEN>' \
--metadata watermark <WATERMARK_UID> \
<PATH_TO_VIDEO> https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream
```

### Direct creator uploads

The video uploaded with the generated unique one-time URL will be watermarked with the profile specified.

```bash
curl -X POST -H "Authorization: Bearer <API_TOKEN>" \
-H 'Content-Type: application/json' \
-d '{
  "maxDurationSeconds": 3600,
  "watermark": {
    "uid": "<WATERMARK_UID>"
  }
}' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/direct_upload
```

#### Example response to direct user uploads

{/* <!-- videodelivery.net is correct domain. See STREAM-4364 --> */}

```json
{
  "result": {
    "uploadURL": "https://upload.videodelivery.net/c32d98dd671e4046a33183cd5b93682b",
    "uid": "c32d98dd671e4046a33183cd5b93682b",
    "watermark": {
      "uid": "d6373709b7681caa6c48ef2d8c73690d",
      "size": 11248,
      "height": 240,
      "width": 720,
      "created": "2020-07-29T00:16:55.719265Z",
      "downloadedFrom": null,
      "name": "marketing videos",
      "opacity": 1.0,
      "padding": 0.05,
      "scale": 0.15,
      "position": "upperRight"
    }
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

`watermark` will be `null` if no watermark was specified.

## Get a watermark profile

To view a watermark profile that you created:

```bash
curl -H "Authorization: Bearer <API_TOKEN>" \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks/<WATERMARK_UID>
```

### Example response to get a watermark profile

```json
{
  "result": {
    "uid": "d6373709b7681caa6c48ef2d8c73690d",
    "size": 11248,
    "height": 240,
    "width": 720,
    "created": "2020-07-29T00:16:55.719265Z",
    "downloadedFrom": null,
    "name": "marketing videos",
    "opacity": 1.0,
    "padding": 0.05,
    "scale": 0.15,
    "position": "center"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

## List watermark profiles

To list watermark profiles that you created:

```bash
curl -H "Authorization: Bearer <API_TOKEN>" \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks/
```

### Example response to list watermark profiles

```json
{
  "result": [
    {
      "uid": "9de16afa676d64faaa7c6c4d5047e637",
      "size": 207710,
      "height": 626,
      "width": 1108,
      "created": "2020-07-29T00:23:35.918472Z",
      "downloadedFrom": null,
      "name": "marketing videos",
      "opacity": 1.0,
      "padding": 0.05,
      "scale": 0.15,
      "position": "upperLeft"
    },
    {
      "uid": "9c50cff5ab16c4aec0bcb03c44e28119",
      "size": 207710,
      "height": 626,
      "width": 1108,
      "created": "2020-07-29T00:16:46.735377Z",
      "downloadedFrom": "https://company.com/logo.png",
      "name": "internal training videos",
      "opacity": 1.0,
      "padding": 0.05,
      "scale": 0.15,
      "position": "center"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}
```

## Delete a  watermark profile

To delete a watermark profile that you created:

```bash
curl -X DELETE -H 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/watermarks/<WATERMARK_UID>
```

If the operation was successful, it will return a success response:

```json
{
  "result": "",
  "success": true,
  "errors": [],
  "messages": []
}
```

## Limitations

* Once the watermark profile is created, you cannot change its parameters. If you need to edit your watermark profile, please delete it and create a new one.
* Once the watermark is applied to a video, you cannot change the watermark without re-uploading the video to apply a different profile.
* Once the watermark is applied to a video, deleting the watermark profile will not also remove the watermark from the video.
* The maximum file size is 2MiB (2097152 bytes), and only PNG files are supported.

---

# Add player enhancements

URL: https://developers.cloudflare.com/stream/edit-videos/player-enhancements/

With player enhancements, you can modify your video player to incorporate elements of your branding such as your logo, and customize additional options to present to your viewers.

The player enhancements are automatically applied to videos using the Stream Player, but you will need to add the details via the `publicDetails` property when using your own player.

## Properties

* `title`: The title that appears when viewers hover over the video. The title may differ from the file name of the video.
* `share_link`: Provides the user with a click-to-copy option to easily share the video URL. This is commonly set to the URL of the page that the video is embedded on.
* `channel_link`: The URL users will be directed to when selecting the logo from the video player.
* `logo`: A valid HTTPS URL for the image of your logo.

## Customize your own player

The example below includes every property you can set via `publicDetails`.

```bash
curl --location --request POST "https://api.cloudflare.com/client/v4/accounts/<$ACCOUNT_ID>/stream/<$VIDEO_UID>" \
--header "Authorization: Bearer <$SECRET>" \
--header 'Content-Type: application/json' \
--data-raw '{
    "publicDetails": {
        "title": "Optional video title",
        "share_link": "https://my-cool-share-link.cloudflare.com",
        "channel_link": "https://www.cloudflare.com/products/cloudflare-stream/",
        "logo": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/94/Cloudflare_Logo.png/480px-Cloudflare_Logo.png"
    }
}' | jq ".result.publicDetails"
```

Because the `publicDetails` properties are optional, you can choose which properties to include. In the example below, only the `logo` is added to the video.

```bash
curl --location --request POST "https://api.cloudflare.com/client/v4/accounts/<$ACCOUNT_ID>/stream/<$VIDEO_UID>" \
--header "Authorization: Bearer <$SECRET>" \
--header 'Content-Type: application/json' \
--data-raw '{
    "publicDetails": {
        "logo": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/94/Cloudflare_Logo.png/480px-Cloudflare_Logo.png"
    }
}'
```

You can also pull the JSON by using the endpoint below.

`https://customer-<ID>.cloudflarestream.com/<VIDEO_ID>/metadata/playerEnhancementInfo.json`

## Update player properties via the Cloudflare dashboard

1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Stream** > **Videos**.
3. Select a video from the list to edit it.
4. Select the **Public Details** tab.
5. From **Public Details**, enter information in the text fields for the properties you want to set.
6. When you are done, select **Save**.

---

# Clip videos

URL: https://developers.cloudflare.com/stream/edit-videos/video-clipping/

With video clipping, also referred to as "trimming" or changing the length of the video, you can change the start and end points of a video so viewers only see a specific "clip" of the video. For example, if you have a 20 minute video but only want to share a five minute clip from the middle of the video, you can clip the video to remove the content before and after the five minute clip.

Refer to the [Video clipping API documentation](/api/resources/stream/subresources/clip/methods/create/) for more information.

:::note[Note:]


Clipping works differently for live streams and recordings. For more information, refer to [Live instant clipping](/stream/stream-live/live-instant-clipping/).


:::

## Prerequisites

Before you can clip a video, you will need an API token. For more information on creating an API token, refer to [Creating API tokens](/fundamentals/api/get-started/create-token/).

## Required parameters

To clip your video, determine the start and end times you want to use from the existing video to create the new video. Use the `videoUID` and the start end times to make your request.

:::note


Clipped videos will not inherit the `scheduledDeletion` date. To set the deletion date, you must clip the video first and then set the deletion date.


:::

```json title="Required parameters"
{
    "clippedFromVideoUID": "0ea62994907491cf9ebefb0a34c1e2c6",
    "startTimeSeconds": 20,
    "endTimeSeconds": 40
}
```

* **`clippedFromVideoUID`**: The unique identifier for the video used to create the new, clipped video.
* **`startTimeSeconds`**: The timestamp from the existing video that indicates when the new video begins.
* **`endTimeSeconds`**: The timestamp from the existing video that indicates when the new video ends. <br/><br/>

```bash title="Example: Clip a video" {5,6,7}
curl --location --request POST 'https://api.cloudflare.com/client/v4/accounts/<YOUR_ACCOUND_ID_HERE>/stream/clip' \
--header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clippedFromVideoUID": "0ea62994907491cf9ebefb0a34c1e2c6",
    "startTimeSeconds": 10,
    "endTimeSeconds": 15
    }'
```

You can check whether your video is ready to play after selecting your account from the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/stream). While the clipped video processes, the video status response displays **Queued**. When the clipping process is complete, the video status changes to **Ready** and displays the new name of the clipped video and the new duration.

To receive a notification when your video is done processing and ready to play, you can [subscribe to webhook notifications](/stream/manage-video-library/using-webhooks/).

## Set video name

When you clip a video, you can also specify a new name for the clipped video. In the example below, the `name` field indicates the new name to use for the clipped video.

```json title="Example: Specify a custom name" {6}
{
    "clippedFromVideoUID": "0ea62994907491cf9ebefb0a34c1e2c6",
    "startTimeSeconds": 10,
    "endTimeSeconds": 15,
    "meta": {
      "name": "overriding-filename-clip.mp4"
    }
}
```

When the video has been clipped and processed, your newly named video displays in your Cloudflare dashboard in the list videos.

## Add a watermark

You can also add a custom watermark to your video. For more information on watermarks and uploading a watermark profile, refer to [Apply watermarks](/stream/edit-videos/applying-watermarks).

```json title="Example: Clip a video, set a new video name, and apply a watermark" {5,6,9}
{
    "clippedFromVideoUID": "0ea62994907491cf9ebefb0a34c1e2c6",
    "startTimeSeconds": 10,
    "endTimeSeconds": 15,
    "watermark": {
        "uid": "4babd675387c3d927f58c41c761978fe"
    },
    "meta": {
      "name": "overriding-filename-clip.mp4"
    }
}
```

## Require signed URLs

When clipping a video, you can make a video private and accessible only to certain users by [requiring a signed URL](/stream/viewing-videos/securing-your-stream/).

```json title="Example: Clip a video and require signed URLs" {5}
{
    "clippedFromVideoUID": "0ea62994907491cf9ebefb0a34c1e2c6",
    "startTimeSeconds": 10,
    "endTimeSeconds": 15,
    "requireSignedURLs": true,
    "meta": {
      "name": "signed-urls-demo.mp4"
    }
}
```

After the video clipping is complete, you can open the Cloudflare dashboard and video list to locate your video. When you select the video, the **Settings** tab displays a checkmark next to **Require Signed URLs**.

## Specify a thumbnail image

You can also specify a thumbnail image for your video using a percentage value. To convert the thumbnail's timestamp from seconds to a percentage, divide the timestamp you want to use by the total duration of the video. For more information about thumbnails, refer to [Display thumbnails](/stream/viewing-videos/displaying-thumbnails).

```json title="Example: Clip a video with a thumbnail generated at the 50% mark" {5}
{
    "clippedFromVideoUID": "0ea62994907491cf9ebefb0a34c1e2c6",
    "startTimeSeconds": 10,
    "endTimeSeconds": 15,
    "thumbnailTimestampPct": 0.5,
    "meta": {
      "name": "thumbnail_percentage.mp4"
    }
}
```

---

# Android (ExoPlayer)

URL: https://developers.cloudflare.com/stream/examples/android/

import { Render } from "~/components"

<Render file="prereqs" />

<Render file="android_playback_code_snippet" />

### Download and run an example app

1. Download [this example app](https://github.com/googlecodelabs/exoplayer-intro.git) from the official Android developer docs, following [this guide](https://developer.android.com/codelabs/exoplayer-intro#4).
2. Open and run the [exoplayer-codelab-04 example app](https://github.com/googlecodelabs/exoplayer-intro/tree/main/exoplayer-codelab-04) using [Android Studio](https://developer.android.com/studio).
3. Replace the `media_url_dash` URL on [this line](https://github.com/googlecodelabs/exoplayer-intro/blob/main/exoplayer-codelab-04/src/main/res/values/strings.xml#L21) with the DASH manifest URL for your video.

For more, see [read the docs](/stream/viewing-videos/using-own-player/ios/).

---

# dash.js

URL: https://developers.cloudflare.com/stream/examples/dash-js/

```html
<html>
	<head>
		<script src="https://cdn.dashjs.org/latest/dash.all.min.js"></script>
	</head>
	<body>
		<div>
			<div class="code">
				<video
					data-dashjs-player=""
					autoplay=""
					src="https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.mpd"
					controls="true"
				></video>
			</div>
		</div>
	</body>
</html>
```

Refer to the [dash.js documentation](https://github.com/Dash-Industry-Forum/dash.js/) for more information.

---

# hls.js

URL: https://developers.cloudflare.com/stream/examples/hls-js/

```html
<html>
	<head>
		<script src="//cdn.jsdelivr.net/npm/hls.js@latest"></script>
	</head>
	<body>
		<video id="video"></video>
		<script>
			if (Hls.isSupported()) {
				const video = document.getElementById('video');
				const hls = new Hls();
				hls.attachMedia(video);
				hls.on(Hls.Events.MEDIA_ATTACHED, () => {
					hls.loadSource(
						'https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8'
					);
				});
			}

			video.play();
		</script>
	</body>
</html>
```

Refer to the [hls.js documentation](https://github.com/video-dev/hls.js/blob/master/docs/API.md) for more information.

---

# Examples

URL: https://developers.cloudflare.com/stream/examples/

import { ListExamples } from "~/components";

<ListExamples directory="stream/examples/" />

---

# iOS (AVPlayer)

URL: https://developers.cloudflare.com/stream/examples/ios/

import { Render } from "~/components"

<Render file="prereqs" />

<Render file="ios_playback_code_snippet" />

### Download and run an example app

1. Download [this example app](https://developer.apple.com/documentation/avfoundation/offline_playback_and_storage/using_avfoundation_to_play_and_persist_http_live_streams) from Apple's developer docs
2. Open and run the app using [Xcode](https://developer.apple.com/xcode/).
3. Search in Xcode for `m3u8`, and open the `Streams` file
4. Replace the value of `playlist_url` with the HLS manifest URL for your video.

![Screenshot of a video with Cloudflare watermark at top right](~/assets/images/stream/ios-example-screenshot-edit-hls-url.png)

5. Click the Play button in Xcode to run the app, and play your video.

For more, see [read the docs](/stream/viewing-videos/using-own-player/ios/).

---

# Shaka Player

URL: https://developers.cloudflare.com/stream/examples/shaka-player/

First, create a video element, using the poster attribute to set a preview thumbnail image. Refer to [Display thumbnails](/stream/viewing-videos/displaying-thumbnails/) for instructions on how to generate a thumbnail image using Cloudflare Stream.

```html
<video
	id="video"
	width="640"
	poster="https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg"
	controls
	autoplay
></video>
```

Then listen for `DOMContentLoaded` event, create a new instance of Shaka Player, and load the manifest URI.

```javascript
// Replace the manifest URI with an HLS or DASH manifest from Cloudflare Stream
const manifestUri =
	'https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.mpd';

document.addEventListener('DOMContentLoaded', () => {
	const video = document.getElementById('video');
  const player = new shaka.Player(video);
	await player.load(manifestUri);
});
```

Refer to the [Shaka Player documentation](https://github.com/shaka-project/shaka-player) for more information.

---

# RTMPS playback

URL: https://developers.cloudflare.com/stream/examples/rtmps_playback/

import { Render } from "~/components";

<Render file="prereqs_first_start_live_streaming" />

Copy the RTMPS _playback_ key for your live input from the [Stream Dashboard](https://dash.cloudflare.com/?to=/:account/stream/inputs) or the [Stream API](/stream/stream-live/start-stream-live/#use-the-api), and paste it into the URL below, replacing `<RTMPS_PLAYBACK_KEY>`:

```sh title="RTMPS playback with ffplay"
ffplay -analyzeduration 1 -fflags -nobuffer -sync ext 'rtmps://live.cloudflare.com:443/live/<RTMPS_PLAYBACK_KEY>'
```

For more, refer to [Play live video in native apps with less than one second latency](/stream/viewing-videos/using-own-player/#play-live-video-in-native-apps-with-less-than-1-second-latency).

---

# SRT playback

URL: https://developers.cloudflare.com/stream/examples/srt_playback/

import { Render } from "~/components";

<Render file="prereqs_first_start_live_streaming" />

Copy the **SRT Playback URL** for your live input from the [Stream Dashboard](https://dash.cloudflare.com/?to=/:account/stream/inputs) or the [Stream API](/stream/stream-live/start-stream-live/#use-the-api), and paste it into the URL below, replacing `<SRT_PLAYBACK_URL>`:

```sh title="SRT playback with ffplay"
ffplay -analyzeduration 1 -fflags -nobuffer -probesize 32 -sync ext '<SRT_PLAYBACK_URL>'
```

For more, refer to [Play live video in native apps with less than one second latency](/stream/viewing-videos/using-own-player/#play-live-video-in-native-apps-with-less-than-1-second-latency).

---

# Stream Player

URL: https://developers.cloudflare.com/stream/examples/stream-player/

```html
<html>
	<head> </head>
	<body>
		<div style="position: relative; padding-top: 56.25%;">
		<iframe
			src="https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/iframe?poster=https%3A%2F%2Fcustomer-f33zs165nr7gyfy4.cloudflarestream.com%2F6b9e68b07dfee8cc2d116e4c51d6a957%2Fthumbnails%2Fthumbnail.jpg%3Ftime%3D%26height%3D600"
			style="border: none; position: absolute; top: 0; left: 0; height: 100%; width: 100%;"
			allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
			allowfullscreen="true"
		></iframe>
		</div>
	</body>
</html>
```

Refer to the [Using the Stream Player](/stream/viewing-videos/using-the-stream-player/) for more information.

---

# Video.js

URL: https://developers.cloudflare.com/stream/examples/video-js/

```html
<html>
	<head>
		<link
			href="https://cdnjs.cloudflare.com/ajax/libs/video.js/7.10.2/video-js.min.css"
			rel="stylesheet"
		/>
		<script src="https://cdnjs.cloudflare.com/ajax/libs/video.js/7.10.2/video.min.js"></script>
	</head>
	<body>
		<video-js id="vid1" controls preload="auto">
			<source
				src="https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8"
				type="application/x-mpegURL"
			/>
		</video-js>

		<script>
			const vid = document.getElementById('vid1');
			const player = videojs(vid);
		</script>
	</body>
</html>
```

Refer to the [Video.js documentation](https://docs.videojs.com/) for more information.

---

# Vidstack

URL: https://developers.cloudflare.com/stream/examples/vidstack/

## Installation

There's a few options to choose from when getting started with Vidstack, follow any of the links
below to get setup. You can replace the player `src` with `https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8` to test Cloudflare Stream.

* [Angular](https://www.vidstack.io/docs/player/getting-started/installation/angular?provider=video)
* [React](https://www.vidstack.io/docs/player/getting-started/installation/react?provider=video)
* [Svelte](https://www.vidstack.io/docs/player/getting-started/installation/svelte?provider=video)
* [Vue](https://www.vidstack.io/docs/player/getting-started/installation/vue?provider=video)
* [Solid](https://www.vidstack.io/docs/player/getting-started/installation/solid?provider=video)
* [Web Components](https://www.vidstack.io/docs/player/getting-started/installation/web-components?provider=video)
* [CDN](https://www.vidstack.io/docs/player/getting-started/installation/cdn?provider=video)

## Examples

Feel free to check out [Vidstack Examples](https://github.com/vidstack/examples) for
building with various JS frameworks and styling options (e.g., CSS or Tailwind CSS).

---

# Stream WordPress plugin

URL: https://developers.cloudflare.com/stream/examples/wordpress/

Before you begin, ensure Cloudflare Stream is enabled on your account and that you have a [Cloudflare API key](/fundamentals/api/get-started/keys/).

## Configure the Cloudflare Stream WordPress plugin

1. Log in to your WordPress account.
2. Download the **Cloudflare Stream plugin**.
3. Expand the **Settings** menu from the navigation menu and select **Cloudflare Stream**.
4. On the **Cloudflare Stream settings** page, enter your email, account ID, and API key.

## Upload video with Cloudflare Stream WordPress plugin

After configuring the Stream Plugin in WordPress, you can upload videos directly to Stream from WordPress.

To upload a video using the Stream plugin:

1. Navigate to the **Add New Post** page in WordPress.
2. Select the **Add Block** icon.
3. Enter **Stream** in the search bar to search for the Cloudflare Stream Video plugin.
4. Select **Cloudflare Stream Video** to add the **Stream** block to your post.
5. Select **Upload** button to choose the video to upload.

---

# GraphQL Analytics API

URL: https://developers.cloudflare.com/stream/getting-analytics/fetching-bulk-analytics/

Stream provides analytics about both live video and video uploaded to Stream, via the GraphQL API described below, as well as in the [Stream dashboard](https://dash.cloudflare.com/?to=/:account/stream/analytics).

The Stream Analytics API uses the Cloudflare GraphQL Analytics API, which can be used across many Cloudflare products. For more about GraphQL, rate limits, filters, and sorting, refer to the [Cloudflare GraphQL Analytics API docs](/analytics/graphql-api).

## Getting started

1. [Generate a Cloudflare API token](https://dash.cloudflare.com/profile/api-tokens) with the **Account Analytics** permission.
2. Use a GraphQL client of your choice to make your first query. [Postman](https://www.postman.com/) has a built-in GraphQL client which can help you run your first query and introspect the GraphQL schema to understand what is possible.

Refer to the sections below for available metrics, dimensions, fields, and example queries.

## Server side analytics

Stream collects data about the number of minutes of video delivered to viewers for all live and on-demand videos played via HLS or DASH, regardless of whether or not you use the [Stream Player](/stream/viewing-videos/using-the-stream-player/).

### Filters and Dimensions

| Field               | Description                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `date`              | Date                                                                                                     |
| `datetime`          | DateTime                                                                                                 |
| `uid`               | UID of the video                                                                                         |
| `clientCountryName` | ISO 3166 alpha2 country code from the client who viewed the video                                        |
| `creator`           | The [Creator ID](/stream/manage-video-library/creator-id/) associated with individual videos, if present |

Some filters, like `date`, can be used with operators, such as `gt` (greater than) and `lt` (less than), as shown in the example query below. For more advanced filtering options, refer to [filtering](/analytics/graphql-api/features/filtering/).

### Metrics

| Node                                | Field           | Description                |
| ----------------------------------- | --------------- | -------------------------- |
| `streamMinutesViewedAdaptiveGroups` | `minutesViewed` | Minutes of video delivered |

### Example

#### Get minutes viewed by country

```graphql graphql-api-explorer title="GraphQL request"
query StreamGetMinutesExample($accountTag: string!, $start: Date, $end: Date) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			streamMinutesViewedAdaptiveGroups(
				filter: { date_geq: $start, date_lt: $end }
				orderBy: [sum_minutesViewed_DESC]
				limit: 100
			) {
				sum {
					minutesViewed
				}
				dimensions {
					uid
					clientCountryName
				}
			}
		}
	}
}
```

```json title="GraphQL response"
{
	"data": {
		"viewer": {
			"accounts": [
				{
					"streamMinutesViewedAdaptiveGroups": [
						{
							"dimensions": {
								"clientCountryName": "US",
								"uid": "73c514082b154945a753d0011e9d7525"
							},
							"sum": {
								"minutesViewed": 2234
							}
						},
						{
							"dimensions": {
								"clientCountryName": "CN",
								"uid": "73c514082b154945a753d0011e9d7525"
							},
							"sum": {
								"minutesViewed": 700
							}
						},
						{
							"dimensions": {
								"clientCountryName": "IN",
								"uid": "73c514082b154945a753d0011e9d7525"
							},
							"sum": {
								"minutesViewed": 553
							}
						}
					]
				}
			]
		}
	},
	"errors": null
}
```

## Pagination

GraphQL API supports seek pagination: using filters, you can specify the last video UID so the response only includes data for videos after the last video UID.

The query below will return data for 2 videos that follow video UID `5646153f8dea17f44d542a42e76cfd`:

```graphql graphql-api-explorer='{"uId": "5646153f8dea17f44d542a42e76cfd"}' title="GraphQL query"
query StreamPaginationExample(
	$accountTag: string!
	$start: Date
	$end: Date
	$uId: string
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			videoPlaybackEventsAdaptiveGroups(
				filter: { date_geq: $start, date_lt: $end, uid_gt: $uId }
				orderBy: [uid_ASC]
				limit: 2
			) {
				count
				sum {
					timeViewedMinutes
				}
				dimensions {
					uid
				}
			}
		}
	}
}
```

Here are the steps to implementing pagination:

1. Call the first query without uid_gt filter to get the first set of videos
2. Grab the last video UID from the response from the first query
3. Call next query by specifying uid_gt property and set it to the last video UID. This will return the next set of videos

For more on pagination, refer to the [Cloudflare GraphQL Analytics API docs](/analytics/graphql-api/features/pagination/).

## Limitations

- The maximum query interval in a single query is 31 days
- The maximum data retention period is 90 days

---

# Analytics

URL: https://developers.cloudflare.com/stream/getting-analytics/

Stream provides server-side analytics that can be used to:

* Identify most viewed video content in your app or platform.
* Identify where content is viewed from and when it is viewed.
* Understand which creators on your platform are publishing the most viewed content, and analyze trends.

You can access data via the [Stream dashboard](https://dash.cloudflare.com/?to=/:account/stream/analytics) or via the [GraphQL Analytics API](/stream/getting-analytics/fetching-bulk-analytics).

Users will need the **Analytics** permission to access analytics via Dash or GraphQL.

---

# Get live viewer counts

URL: https://developers.cloudflare.com/stream/getting-analytics/live-viewer-count/

The Stream player has full support for live viewer counts by default. To get the viewer count for live videos for use with third party players, make a `GET` request to the `/views` endpoint.

```bash
https://customer-<CODE>.cloudflarestream.com/<INPUT_ID>/views
```

Below is a response for a live video with several active viewers:

```json
{ "liveViewers": 113 }
```

---

# Manage creators

URL: https://developers.cloudflare.com/stream/manage-video-library/creator-id/

You can set the creator field with an internal user ID at the time a tokenized upload URL is requested. When the video is uploaded, the creator property is automatically set to the internal user ID which can be used for analytics data or when searching for videos by a specific creator.

For basic uploads, you will need to add the Creator ID after you upload the video.

## Upload from URL

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/copy" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"url":"https://example.com/myvideo.mp4","creator": "<CREATOR_ID>","thumbnailTimestampPct":0.529241,"allowedOrigins":["example.com"],"requireSignedURLs":true,"watermark":{"uid":"ea95132c15732412d22c1476fa83f27a"}}'
```

**Response**

```json null {35}
{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"allowedOrigins": ["example.com"],
		"created": "2014-01-02T02:20:00Z",
		"duration": 300,
		"input": {
			"height": 1080,
			"width": 1920
		},
		"maxDurationSeconds": 300,
		"meta": {},
		"modified": "2014-01-02T02:20:00Z",
		"uploadExpiry": "2014-01-02T02:20:00Z",
		"playback": {
			"hls": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8",
			"dash": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.mpd"
		},
		"preview": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/watch",
		"readyToStream": true,
		"requireSignedURLs": true,
		"size": 4190963,
		"status": {
			"state": "ready",
			"pctComplete": "100.000000",
			"errorReasonCode": "",
			"errorReasonText": ""
		},
		"thumbnail": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg",
		"thumbnailTimestampPct": 0.529241,
		"creator": "<CREATOR_ID>",
		"uid": "6b9e68b07dfee8cc2d116e4c51d6a957",
		"liveInput": "fc0a8dc887b16759bfd9ad922230a014",
		"uploaded": "2014-01-02T02:20:00Z",
		"watermark": {
			"uid": "6b9e68b07dfee8cc2d116e4c51d6a957",
			"size": 29472,
			"height": 600,
			"width": 400,
			"created": "2014-01-02T02:20:00Z",
			"downloadedFrom": "https://company.com/logo.png",
			"name": "Marketing Videos",
			"opacity": 0.75,
			"padding": 0.1,
			"scale": 0.1,
			"position": "center"
		}
	}
}
```

## Set default creators for videos

You can associate videos with a single creator by setting a default creator ID value, which you can later use for searching for videos by creator ID or for analytics data.

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/live_inputs" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"DefaultCreator":"1234"}'
```

If you have multiple creators who start live streams, [create a live input](/stream/get-started/#step-1-create-a-live-input) for each creator who will live stream and then set a `DefaultCreator` value per input. Setting the default creator ID for each input ensures that any recorded videos streamed from the creator's input will inherit the `DefaultCreator` value.

At this time, you can only manage the default creator ID values via the API.

## Update creator in existing videos

To update the creator property in existing videos, make a `POST` request to the video object endpoint with a JSON payload specifying the creator property as show in the example below.

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/<VIDEO_UID>" \
--header "Authorization: Bearer <AUTH_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"creator":"test123"}'
```

## Direct creator upload

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/direct_upload" \
--header "Authorization: Bearer <AUTH_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"maxDurationSeconds":300,"expiry":"2021-01-02T02:20:00Z","creator": "<CREATOR_ID>", "thumbnailTimestampPct":0.529241,"allowedOrigins":["example.com"],"requireSignedURLs":true,"watermark":{"uid":"ea95132c15732412d22c1476fa83f27a"}}'
```

**Response**

```json null {8}
{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"uploadURL": "www.example.com/samplepath",
		"uid": "ea95132c15732412d22c1476fa83f27a",
		"creator": "<CREATOR_ID>",
		"watermark": {
			"uid": "ea95132c15732412d22c1476fa83f27a",
			"size": 29472,
			"height": 600,
			"width": 400,
			"created": "2014-01-02T02:20:00Z",
			"downloadedFrom": "https://company.com/logo.png",
			"name": "Marketing Videos",
			"opacity": 0.75,
			"padding": 0.1,
			"scale": 0.1,
			"position": "center"
		}
	}
}
```

## Get videos by Creator ID

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream?after=2014-01-02T02:20:00Z&before=2014-01-02T02:20:00Z&include_counts=false&creator=<CREATOR_ID>&limit=undefined&asc=false&status=downloading,queued,inprogress,ready,error" \
--header "Authorization: Bearer <API_TOKEN>"
```

**Response**

```json null {36}
{
	"success": true,
	"errors": [],
	"messages": [],
	"result": [
		{
			"allowedOrigins": ["example.com"],
			"created": "2014-01-02T02:20:00Z",
			"duration": 300,
			"input": {
				"height": 1080,
				"width": 1920
			},
			"maxDurationSeconds": 300,
			"meta": {},
			"modified": "2014-01-02T02:20:00Z",
			"uploadExpiry": "2014-01-02T02:20:00Z",
			"playback": {
				"hls": "https://customer-<CODE>.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.m3u8",
				"dash": "https://customer-<CODE>.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/manifest/video.mpd"
			},
			"preview": "https://customer-<CODE>.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/watch",
			"readyToStream": true,
			"requireSignedURLs": true,
			"size": 4190963,
			"status": {
				"state": "ready",
				"pctComplete": "100.000000",
				"errorReasonCode": "",
				"errorReasonText": ""
			},
			"thumbnail": "https://customer-<CODE>.cloudflarestream.com/ea95132c15732412d22c1476fa83f27a/thumbnails/thumbnail.jpg",
			"thumbnailTimestampPct": 0.529241,
			"creator": "some-creator-id",
			"uid": "ea95132c15732412d22c1476fa83f27a",
			"liveInput": "fc0a8dc887b16759bfd9ad922230a014",
			"uploaded": "2014-01-02T02:20:00Z",
			"watermark": {
				"uid": "ea95132c15732412d22c1476fa83f27a",
				"size": 29472,
				"height": 600,
				"width": 400,
				"created": "2014-01-02T02:20:00Z",
				"downloadedFrom": "https://company.com/logo.png",
				"name": "Marketing Videos",
				"opacity": 0.75,
				"padding": 0.1,
				"scale": 0.1,
				"position": "center"
			}
		}
	],
	"total": "35586",
	"range": "1000"
}
```

## tus

Add the Creator ID via the `Upload-Creator` header. For more information, refer to [Resumable and large files (tus)](/stream/uploading-videos/resumable-uploads/#set-creator-property).

## Query by Creator ID with GraphQL

After you set the creator property, you can use the [GraphQL API](/analytics/graphql-api/) to filter by a specific creator. Refer to [Fetching bulk analytics](/stream/getting-analytics/fetching-bulk-analytics) for more information about available metrics and filters.

---

# Search for videos

URL: https://developers.cloudflare.com/stream/manage-video-library/searching/

You can search for videos by name through the Stream API by adding a `search` query parameter to the [list media files](/api/resources/stream/methods/list/) endpoint.

## What you will need

To make API requests you will need a [Cloudflare API token](https://www.cloudflare.com/a/account/my-account) and your Cloudflare [account ID](https://www.cloudflare.com/a/overview/).

## cURL example

This example lists media where the name matches `puppy.mp4`.

```bash
curl -X GET "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream?search=puppy" \
     -H "Authorization: Bearer <API_TOKEN>" \
     -H "Content-Type: application/json"
```

---

# Use webhooks

URL: https://developers.cloudflare.com/stream/manage-video-library/using-webhooks/

import { Details } from "~/components"

Webhooks notify your service when videos successfully finish processing and are ready to stream or if your video enters an error state.

## Subscribe to webhook notifications

To subscribe to receive webhook notifications on your service or modify an existing subscription, you will need a [Cloudflare API token](https://dash.cloudflare.com/profile/api-tokens).

The webhook notification URL must include the protocol. Only `http://` or `https://` is supported.

```bash
curl -X PUT --header 'Authorization: Bearer <API_TOKEN>' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/webhook \
--data '{"notificationUrl":"<WEBHOOK_NOTIFICATION_URL>"}'
```

```json title="Example response"
{
  "result": {
    "notificationUrl": "http://www.your-service-webhook-handler.com",
    "modified": "2019-01-01T01:02:21.076571Z"
    "secret": "85011ed3a913c6ad5f9cf6c5573cc0a7"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

## Notifications

When a video on your account finishes processing, you will receive a `POST` request notification with information about the video.

Note the `status` field indicates whether the video processing finished successfully.

```javascript title="Example POST request body sent in response to successful encoding"
{
    "uid": "dd5d531a12de0c724bd1275a3b2bc9c6",
    "readyToStream": true,
    "status": {
      "state": "ready"
    },
    "meta": {},
    "created": "2019-01-01T01:00:00.474936Z",
    "modified": "2019-01-01T01:02:21.076571Z",
    // ...
  }
```

When a video is done processing and all quality levels are encoded, the `state` field returns a `ready` state. The `ready` state can be useful if picture quality is important to you, and you only want to enable video playback when the highest quality levels are available.

If higher quality renditions are still processing, videos may sometimes return the `state` field as `ready` and an additional `pctComplete` state that is not `100`. When `pctComplete` reaches `100`, all quality resolutions are available for the video.

When at least one quality level is encoded and ready to be streamed, the `readyToStream` value returns `true`.

## Error codes

If a video could not process successfully, the `state` field returns `error`, and the `errReasonCode` returns one of the values listed below.

* `ERR_NON_VIDEO` – The upload is not a video.
* `ERR_DURATION_EXCEED_CONSTRAINT` – The video duration exceeds the constraints defined in the direct creator upload.
* `ERR_FETCH_ORIGIN_ERROR` – The video failed to download from the URL.
* `ERR_MALFORMED_VIDEO` – The video is a valid file but contains corrupt data that cannot be recovered.
* `ERR_DURATION_TOO_SHORT` – The video's duration is shorter than 0.1 seconds.
* `ERR_UNKNOWN` – If Stream cannot automatically determine why the video returned an error, the `ERR_UNKNOWN` code will be used.

In addition to the `state` field, a video's `readyToStream` field must also be `true` for a video to play.

```bash title="Example error response" {2,4,7}
{
  "readyToStream": true,
  "status": {
    "state": "error",
    "step": "encoding",
    "pctComplete": "39",
    "errReasonCode": "ERR_MALFORMED_VIDEO",
    "errReasonText": "The video was deemed to be corrupted or malformed.",
  }
}
```


<Details header="Example: POST body for successful video encoding">

```json
{
 "uid": "6b9e68b07dfee8cc2d116e4c51d6a957",
 "creator": null,
 "thumbnail": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg",
 "thumbnailTimestampPct": 0,
 "readyToStream": true,
 "status": {
   "state": "ready",
   "pctComplete": "39.000000",
   "errorReasonCode": "",
   "errorReasonText": ""
 },
 "meta": {
   "filename": "small.mp4",
   "filetype": "video/mp4",
   "name": "small.mp4",
   "relativePath": "null",
   "type": "video/mp4"
 },
 "created": "2022-06-30T17:53:12.512033Z",
 "modified": "2022-06-30T17:53:21.774299Z",
 "size": 383631,
 "preview": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/watch",
 "allowedOrigins": [],
 "requireSignedURLs": false,
 "uploaded": "2022-06-30T17:53:12.511981Z",
 "uploadExpiry": "2022-07-01T17:53:12.511973Z",
 "maxSizeBytes": null,
 "maxDurationSeconds": null,
 "duration": 5.5,
 "input": {
   "width": 560,
   "height": 320
 },
 "playback": {
   "hls": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8",
   "dash": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.mpd"
 },
 "watermark": null
}
```


</Details>

## Verify webhook authenticity

Cloudflare Stream will sign the webhook requests sent to your notification URLs and include the signature of each request in the `Webhook-Signature` HTTP header. This allows your application to verify the webhook requests are sent by Stream.

To verify a signature, you need to retrieve your webhook signing secret. This value is returned in the API response when you create or retrieve the webhook.

To verify the signature, get the value of the `Webhook-Signature` header, which will look similar to the example below.

`Webhook-Signature: time=1230811200,sig1=60493ec9388b44585a29543bcf0de62e377d4da393246a8b1c901d0e3e672404`

### 1. Parse the signature

Retrieve the `Webhook-Signature` header from the webhook request and split the string using the `,` character.

Split each value again using the `=` character.

The value for `time` is the current [UNIX time](https://en.wikipedia.org/wiki/Unix_time) when the server sent the request. `sig1` is the signature of the request body.

At this point, you should discard requests with timestamps that are too old for your application.

### 2. Create the signature source string

Prepare the signature source string and concatenate the following strings:

* Value of the `time` field for example `1230811200`
* Character `.`
* Webhook request body (complete with newline characters, if applicable)

Every byte in the request body must remain unaltered for successful signature verification.

### 3. Create the expected signature

Compute an HMAC with the SHA256 function (HMAC-SHA256) using your webhook secret and the source string from step 2.
This step depends on the programming language used by your application.

Cloudflare's signature will be encoded to hex.

### 4. Compare expected and actual signatures

Compare the signature in the request header to the expected signature. Preferably, use a constant-time comparison function to compare the signatures.

If the signatures match, you can trust that Cloudflare sent the webhook.

## Limitations

* Webhooks will only be sent after video processing is complete, and the body will indicate whether the video processing succeeded or failed.
* Only one webhook subscription is allowed per-account.

## Examples

**Golang**

Using [crypto/hmac](https://golang.org/pkg/crypto/hmac/#pkg-overview):

```go
package main

import (
 "crypto/hmac"
 "crypto/sha256"
 "encoding/hex"
 "log"
)

func main() {
 secret := []byte("secret from the Cloudflare API")
 message := []byte("string from step 2")

 hash := hmac.New(sha256.New, secret)
 hash.Write(message)

 hashToCheck := hex.EncodeToString(hash.Sum(nil))

 log.Println(hashToCheck)
}

```

**Node.js**

```js

    var crypto = require('crypto');

    var key = 'secret from the Cloudflare API';
    var message = 'string from step 2';

    var hash = crypto.createHmac('sha256', key).update(message);

    hash.digest('hex');
```

**Ruby**

```ruby
    require 'openssl'

    key = 'secret from the Cloudflare API'
    message = 'string from step 2'

    OpenSSL::HMAC.hexdigest('sha256', key, message)
```

**In JavaScript (for example, to use in Cloudflare Workers)**

```javascript
    const key = 'secret from the Cloudflare API';
    const message = 'string from step 2';

    const getUtf8Bytes = str =>
      new Uint8Array(
        [...decodeURIComponent(encodeURIComponent(str))].map(c => c.charCodeAt(0))
      );

    const keyBytes = getUtf8Bytes(key);
    const messageBytes = getUtf8Bytes(message);

    const cryptoKey = await crypto.subtle.importKey(
      'raw', keyBytes, { name: 'HMAC', hash: 'SHA-256' },
      true, ['sign']
    );
    const sig = await crypto.subtle.sign('HMAC', cryptoKey, messageBytes);

    [...new Uint8Array(sig)].map(b => b.toString(16).padStart(2, '0')).join('');
```

---

# Add custom ingest domains

URL: https://developers.cloudflare.com/stream/stream-live/custom-domains/

With custom ingest domains, you can configure your RTMPS feeds to use an ingest URL that you specify instead of using `live.cloudflare.com.`

1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Click **Stream** > **Live Inputs**.
3. Click the **Settings** button above the list. The **Custom Input Domains** page displays.
4. Under **Domain**, add your domain and click **Add domain**.
5. At your DNS provider, add a CNAME record that points to `live.cloudflare.com`. If your DNS provider is Cloudflare, this step is done automatically.

If you are using Cloudflare for DNS, ensure the [**Proxy status**](/dns/proxy-status/) of your ingest domain is **DNS only** (grey-clouded).

## Delete a custom domain

1. From the **Custom Input Domains** page under **Hostnames**, locate the domain.
2. Click the menu icon under **Action**. Click **Delete**.

---

# Download live stream videos

URL: https://developers.cloudflare.com/stream/stream-live/download-stream-live-videos/

You can enable downloads for live stream videos from the Cloudflare dashboard. Videos are available for download after they enter the **Ready** state.

:::note


Downloadable MP4s are only available for live recordings under four hours. Live recordings exceeding four hours can be played at a later time but cannot be downloaded as an MP4.


:::

1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Click **Stream** > **Live Inputs**.
3. Click a live input from the list to select it.
4. Under **Videos created by live input**, locate your video and click to select it.
5. Under **Settings**, select **Enable MP4 Downloads**.
6. Click **Save**. You will see a progress bar as the video generates a download link.
7. When the download link is ready, under **Download URL**, copy the URL and enter it in a browser to download the video.

---

# DVR for Live

URL: https://developers.cloudflare.com/stream/stream-live/dvr-for-live/

Stream Live supports "DVR mode" on an opt-in basis to allow viewers to rewind,
resume, and fast-forward a live broadcast. To enable DVR mode, add the
`dvrEnabled=true` query parameter to the Stream Player embed source or the HLS
manifest URL.

## Stream Player

``` html title="Stream Player embed format"
<div style="position: relative; padding-top: 56.25%;">
  <iframe
    src="https://customer-<CODE>.cloudflarestream.com/<INPUT_ID|VIDEO_ID>/iframe?dvrEnabled=true"
    style="border: none; position: absolute; top: 0; left: 0; height: 100%; width: 100%;"
    allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
    allowfullscreen="true"
  ></iframe>
</div>
```

When DVR mode is enabled the Stream Player will:

- Show a timeline the viewer can scrub/seek, similar to watching an on-demand
  video. The timeline will automatically scale to show the growing duration of
  the broadcast while it is live.
- The "LIVE" indicator will show grey if the viewer is behind the live edge or
  red if they are watching the latest content. Clicking that indicator will jump
  forward to the live edge.
- If the viewer pauses the player, it will resume playback from that time instead
  of jumping forward to the live edge.

## HLS manifest for custom players

``` text title="HLS manifest URL format"
https://customer-<CODE>.cloudflarestream.com/<INPUT_ID|VIDEO_ID>/manifest/video.m3u8?dvrEnabled=true
```

Custom players using a DVR-capable HLS manifest may need additional
configuration to surface helpful controls or information. Refer to your player
library for additional information.

## Video ID or Input ID

Stream Live allows loading the Player or HLS manifest by Video ID or Live Input
ID. Refer to [Watch a live stream](/stream/stream-live/watch-live-stream/) for how to
retrieve these URLs and compare these options. There are additional
considerations when using DVR mode:

**Recommended:** Use DVR Mode on a Video ID URL:

- When the player loads, it will start playing the active broadcast if it is
  still live or play the recording if the broadcast has concluded.

DVR Mode on a Live Input ID URL:

- When the player loads, it will start playing the currently live broadcast if
  there is one (refer to [Live Input Status](/stream/stream-live/watch-live-stream/#live-input-status)).
- If the viewer is still watching _after the broadcast ends,_ they can continue
  to watch. However, if the player or manifest is then reloaded, it will show the
  latest broadcast or "Stream has not yet started" (`HTTP 204`). Past broadcasts
  are not available by Live Input ID.

## Known Limitations

- When using DVR Mode and a player/manifest created using a Live Input ID, the
  player may stall when trying to switch quality levels if a viewer is still
  watching after a broadcast has concluded.
- Performance may be degraded for DVR-enabled broadcasts longer than three hours.
  Manifests are limited to a maxiumum of 7,200 segments. Segment length is
  determined by the keyframe interval, also called GOP size.
- DVR Mode relies on Version 8 of the HLS manifest specification. Stream uses
  HLS Version 6 in all other contexts. HLS v8 offers extremely broad compatibility
  but may not work with certain old player libraries or older devices.
- DVR Mode is not available for DASH manifests.

---

# Stream live video

URL: https://developers.cloudflare.com/stream/stream-live/

Cloudflare Stream lets you or your users [stream live video](https://www.cloudflare.com/learning/video/what-is-live-streaming/), and play live video in your website or app, without managing and configuring any of your own infrastructure.

## How Stream works

Stream handles video streaming end-to-end, from ingestion through delivery.

1. For each live stream, you create a unique live input, either using the Stream Dashboard or API.
2. Each live input has a unique Stream Key, that you provide to the creator who is streaming live video.
3. Creators use this Stream Key to broadcast live video to Cloudflare Stream, over either RTMPS or SRT.
4. Cloudflare Stream encodes this live video at multiple resolutions and delivers it to viewers, using Cloudflare's Global Network. You can play video on your website using the [Stream Player](/stream/viewing-videos/using-the-stream-player/) or using [any video player that supports HLS or DASH](/stream/viewing-videos/using-own-player/).

![Diagram the explains the live stream workflow](~/assets/images/stream/live-stream-workflow.png)

## RTMP reconnections

As long as your streaming software reconnects, Stream Live will continue to ingest and stream your live video. Make sure the streaming software you use to push RTMP feeds automatically reconnects if the connection breaks. Some apps like OBS reconnect automatically while other apps like FFmpeg require custom configuration.

## Bitrate estimates at each quality level (bitrate ladder)

Cloudflare Stream transcodes and makes live streams available to viewers at multiple quality levels. This is commonly referred to as [Adaptive Bitrate Streaming (ABR)](https://www.cloudflare.com/learning/video/what-is-adaptive-bitrate-streaming).

With ABR, client video players need to be provided with estimates of how much bandwidth will be needed to play each quality level (ex: 1080p). Stream creates and updates these estimates dynamically by analyzing the bitrate of your users' live streams. This ensures that live video plays at the highest quality a viewer has adequate bandwidth to play, even in cases where the broadcaster's software or hardware provides incomplete or inaccurate information about the bitrate of their live content.

### How it works

If a live stream contains content with low visual complexity, like a slideshow presentation, the bandwidth estimates provided in the HLS and DASH manifests will be lower —  a stream like this has a low bitrate and requires relatively little bandwidth, even at high resolution.  This ensures that as many viewers as possible view the highest quality level.

Conversely, if a live stream contains content with high visual complexity, like live sports with motion and camera panning, the bandwidth estimates provided in the manifest will be higher — a stream like this has a high bitrate and requires more bandwidth. This ensures that viewers with inadequate bandwidth switch down to a lower quality level, and their playback does not buffer.

### How you benefit

If you're building a creator platform or any application where your end users create their own live streams, your end users likely use streaming software or hardware that you cannot control. In practice, these live streaming setups often send inaccurate or incomplete information about the bitrate of a given live stream, or are misconfigured by end users.

Stream adapts based on the live video that we actually receive, rather than blindly trusting the advertised bitrate. This means that even in cases where your end users' settings are less than ideal, client video players will still receive the most accurate bitrate estimates possible, ensuring the highest quality video playback for your viewers, while avoiding pushing configuration complexity back onto your users.

## Transition from live playback to a recording

Recordings are available for live streams within 60 seconds after a live stream ends.

You can check a video's status to determine if it's ready to view by making a [`GET` request to the `stream` endpoint](/stream/stream-live/watch-live-stream/#use-the-api) and viewing the `state` or by [using the Cloudflare dashboard](/stream/stream-live/watch-live-stream/#use-the-dashboard).

After the live stream ends, you can [replay live stream recordings](/stream/stream-live/replay-recordings/) in the `ready` state by using one of the playback URLs.

## Billing

Stream Live is billed identically to the rest of Cloudflare Stream.

* You pay $5 per 1000 minutes of recorded video.
* You pay $1 per 1000 minutes of delivered video.

All Stream Live videos are automatically recorded. There is no additional cost for encoding and packaging live videos.

---

# Record and replay live streams

URL: https://developers.cloudflare.com/stream/stream-live/replay-recordings/

Live streams are automatically recorded, and available instantly once a live stream ends. To get a list of recordings for a given input ID, make a [`GET` request to `/live_inputs/<UID>/videos`](/api/resources/stream/subresources/live_inputs/methods/get/) and filter for videos where `state` is set to `ready`:

```bash title="Request"
curl -X GET \
-H "Authorization: Bearer <API_TOKEN>" \
https://dash.cloudflare.com/api/v4/accounts/<ACCOUNT_ID>/stream/live_inputs/<LIVE_INPUT_UID>/videos
```

```json title="Response" {10}
{
  "result": [
...
    {
      "uid": "6b9e68b07dfee8cc2d116e4c51d6a957",
      "thumbnail": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg",
      "thumbnailTimestampPct": 0,
      "readyToStream": true,
      "status": {
        "state": "ready",
        "pctComplete": "100.000000",
        "errorReasonCode": "",
        "errorReasonText": ""
      },
      "meta": {
        "name": "Stream Live Test 22 Sep 21 22:12 UTC"
      },
      "created": "2021-09-22T22:12:53.587306Z",
      "modified": "2021-09-23T00:14:05.591333Z",
      "size": 0,
      "preview": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/watch",
      "allowedOrigins": [],
      "requireSignedURLs": false,
      "uploaded": "2021-09-22T22:12:53.587288Z",
      "uploadExpiry": null,
      "maxSizeBytes": null,
      "maxDurationSeconds": null,
      "duration": 7272,
      "input": {
        "width": 640,
        "height": 360
      },
      "playback": {
        "hls": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8",
        "dash": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.mpd"
      },
      "watermark": null,
      "liveInput": "34036a0695ab5237ce757ac53fd158a2"
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}
```

---

# Start a live stream

URL: https://developers.cloudflare.com/stream/stream-live/start-stream-live/

import { InlineBadge, Render, Badge } from "~/components";

After you subscribe to Stream, you can create Live Inputs in Dash or via the API. Broadcast to your new Live Input using RTMPS or SRT. SRT supports newer video codecs and makes using accessibility features, such as captions and multiple audio tracks, easier.

<Render file="srt-supported-modes" />

**First time live streaming?** You will need software to send your video to Cloudflare. [Learn how to go live on Stream using OBS Studio](/stream/examples/obs-from-scratch/).

## Use the dashboard

**Step 1:** [Create a live input via the Stream Dashboard](https://dash.cloudflare.com/?to=/:account/stream/inputs/create).

![Create live input field from dashboard](~/assets/images/stream/create-live-input-from-stream-dashboard.png)

**Step 2:** Copy the RTMPS URL and key, and use them with your live streaming application. We recommend using [Open Broadcaster Software (OBS)](https://obsproject.com/) to get started.

![Example of RTMPS URL field](~/assets/images/stream/copy-rtmps-url-from-stream-dashboard.png)

**Step 3:** Go live and preview your live stream in the Stream Dashboard

In the Stream Dashboard, within seconds of going live, you will see a preview of what your viewers will see. To add live video playback to your website or app, refer to [Play videos](/stream/viewing-videos).

## Use the API

To start a live stream programmatically, make a `POST` request to the `/live_inputs` endpoint:

```bash title="Request"
curl -X POST \
--header "Authorization: Bearer <API_TOKEN>" \
--data '{"meta": {"name":"test stream"},"recording": { "mode": "automatic" }}' \
https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/live_inputs
```

```json title="Response"
{
	"uid": "f256e6ea9341d51eea64c9454659e576",
	"rtmps": {
		"url": "rtmps://live.cloudflare.com:443/live/",
		"streamKey": "MTQ0MTcjM3MjI1NDE3ODIyNTI1MjYyMjE4NTI2ODI1NDcxMzUyMzcf256e6ea9351d51eea64c9454659e576"
	},
	"created": "2021-09-23T05:05:53.451415Z",
	"modified": "2021-09-23T05:05:53.451415Z",
	"meta": {
		"name": "test stream"
	},
	"status": null,
	"recording": {
		"mode": "automatic",
		"requireSignedURLs": false,
		"allowedOrigins": null,
		"hideLiveViewerCount": false
	},
	"deleteRecordingAfterDays": null,
	"preferLowLatency": false
}
```

#### Optional API parameters

[API Reference Docs for `/live_inputs`](/api/resources/stream/subresources/live_inputs/methods/create/)

- `preferLowLatency` boolean default: `false` <InlineBadge preset="beta" />

  - When set to true, this live input will be enabled for the beta Low-Latency HLS pipeline. The Stream built-in player will automatically use LL-HLS when possible. (Recording `mode` property must also be set to `automatic`.)

- `deleteRecordingAfterDays` integer default: `null` (any)

  - Specifies a date and time when the recording, not the input, will be deleted. This property applies from the time the recording is made available and ready to stream. After the recording is deleted, it is no longer viewable and no longer counts towards storage for billing. Minimum value is `30`, maximum value is `1096`.

    When the stream ends, a `scheduledDeletion` timestamp is calculated using the `deleteRecordingAfterDays` value if present.

    Note that if the value is added to a live input while a stream is live, the property will only apply to future streams.

- `timeoutSeconds` integer default: `0`

  - The `timeoutSeconds` property specifies how long a live feed can be disconnected before it results in a new video being created.

The following four properties are nested under the `recording` object.

- `mode` string default: `off`

  - When the mode property is set to `automatic`, the live stream will be automatically available for viewing using HLS/DASH. In addition, the live stream will be automatically recorded for later replays. By default, recording mode is set to `off`, and the input will not be recorded or available for playback.

- `requireSignedURLs` boolean default: `false`

  - The `requireSignedURLs` property indicates if signed URLs are required to view the video. This setting is applied by default to all videos recorded from the input. In addition, if viewing a video via the live input ID, this field takes effect over any video-level settings.

- `allowedOrigins` integer default: `null` (any)

  - The `allowedOrigins` property can optionally be invoked to provide a list of allowed origins. This setting is applied by default to all videos recorded from the input. In addition, if viewing a video via the live input ID, this field takes effect over any video-level settings.

- `hideLiveViewerCount` boolean default: `false`

  - Restrict access to the live viewer count and remove the value from the player.

## Manage live inputs

You can update live inputs by making a `PUT` request:

```bash title="Request"
curl --request PUT \
https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/live_inputs/{input_id} \
--header "Authorization: Bearer <API_TOKEN>" \
--data '{"meta": {"name":"test stream 1"},"recording": { "mode": "automatic", "timeoutSeconds": 10 }}'
```

Delete a live input by making a `DELETE` request:

```bash title="Request"
curl --request DELETE \
https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/live_inputs/{input_id} \
--header "Authorization: Bearer <API_TOKEN>"
```

## Recommendations, requirements and limitations

### Recommendations

- Your creators should use an appropriate bitrate for their live streams, typically well under 12Mbps (12000Kbps). High motion, high frame rate content typically should use a higher bitrate, while low motion content like slide presentations should use a lower bitrate.
- Your creators should use a [GOP duration](https://en.wikipedia.org/wiki/Group_of_pictures) (keyframe interval) of between 2 to 8 seconds. The default in most encoding software and hardware, including Open Broadcaster Software (OBS), is within this range. Setting a lower GOP duration will reduce latency for viewers, while also reducing encoding efficiency. Setting a higher GOP duration will improve encoding efficiency, while increasing latency for viewers. This is a tradeoff inherent to video encoding, and not a limitation of Cloudflare Stream.
- When possible, select CBR (constant bitrate) instead of VBR (variable bitrate) as CBR helps to ensure a stable streaming experience while preventing buffering and interruptions.

#### Low-Latency HLS broadcast recommendations <Badge text="Beta" variant="caution" size="small" />

- For lowest latency, use a GOP size (keyframe interval) of 1 or 2 seconds.
- Broadcast to the RTMP endpoint if possible.
- If using OBS, select the "ultra low" latency profile.

### Requirements

- Closed GOPs are required. This means that if there are any B frames in the video, they should always refer to frames within the same GOP. This setting is the default in most encoding software and hardware, including [OBS Studio](https://obsproject.com/).
- Stream Live only supports H.264 video and AAC audio codecs as inputs. This requirement does not apply to inputs that are relayed to Stream Connect outputs. Stream Live supports ADTS but does not presently support LATM.
- Clients must be configured to reconnect when a disconnection occurs. Stream Live is designed to handle reconnection gracefully by continuing the live stream.

### Limitations

- Watermarks cannot yet be used with live videos.
- If a live video exceeds seven days in length, the recording will be truncated to seven days. Only the first seven days of live video content will be recorded.

---

# Simulcast (restream) videos

URL: https://developers.cloudflare.com/stream/stream-live/simulcasting/

import { Render } from "~/components"

Simulcasting lets you forward your live stream to third-party platforms such as Twitch, YouTube, Facebook, Twitter, and more. You can simulcast to up to 50 concurrent destinations from each live input. To begin simulcasting, select an input and add one or more Outputs.

<Render file="chromecast_limitations" />

## Add an Output using the API

Add an Output to start retransmitting live video. You can add or remove Outputs at any time during a broadcast to start and stop retransmitting.

```bash title="Request"
curl -X POST \
--data '{"url": "rtmp://a.rtmp.youtube.com/live2","streamKey": "<redacted>"}' \
-H "Authorization: Bearer <API_TOKEN>" \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/live_inputs/<INPUT_UID>/outputs
```

```json title="Response"
{
  "result": {
    "uid": "6f8339ed45fe87daa8e7f0fe4e4ef776",
    "url": "rtmp://a.rtmp.youtube.com/live2",
    "streamKey": "<redacted>"
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

## Control when you start and stop simulcasting

You can enable and disable individual live outputs via the [API](/api/resources/stream/subresources/live_inputs/subresources/outputs/methods/update/) or [Stream dashboard](https://dash.cloudflare.com/?to=/:account/stream/inputs), allowing you to:

* Start a live stream, but wait to start simulcasting to YouTube and Twitch until right before the content begins.
* Stop simulcasting before the live stream ends, to encourage viewers to transition from a third-party service like YouTube or Twitch to a direct live stream.
* Give your own users manual control over when they go live to specific simulcasting destinations.

When a live output is disabled, video is not simulcast to the live output, even when actively streaming to the corresponding live input.

By default, all live outputs are enabled.

### Enable outputs from the dashboard:

1. From Live Inputs in the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/stream/inputs), select an input from the list.
2. Under **Outputs** > **Enabled**, set the toggle to enabled or disabled.

## Manage outputs

| Command                                                                  | Method   | Endpoint                                                                 |
| ------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------ |
| [List outputs](/api/resources/stream/subresources/live_inputs/methods/list/)      | `GET`    | `accounts/:account_identifier/stream/live_inputs`                        |
| [Delete outputs](/api/resources/stream/subresources/live_inputs/methods/delete/) | `DELETE` | `accounts/:account_identifier/stream/live_inputs/:live_input_identifier` |
| [List All Outputs Associated With A Specified Live Input](/api/resources/stream/subresources/live_inputs/subresources/outputs/methods/list/) | `GET` | `/accounts/{account_id}/stream/live_inputs/{live_input_identifier}/outputs` |
| [Delete An Output](/api/resources/stream/subresources/live_inputs/subresources/outputs/methods/delete/) | `DELETE` | `/accounts/{account_id}/stream/live_inputs/{live_input_identifier}/outputs/{output_identifier}` |

If the associated live input is already retransmitting to this output when you make the `DELETE` request, that output will be disconnected within 30 seconds.

---

# Live Instant Clipping

URL: https://developers.cloudflare.com/stream/stream-live/live-instant-clipping/

Stream supports generating clips of live streams and recordings so creators and viewers alike can highlight short, engaging pieces of a longer broadcast or recording. Live instant clips can be created by end users and do not result in additional storage fees or new entries in the video library.

:::note[Note:]


Clipping works differently for uploaded / on-demand videos. For more information, refer to [Clip videos](/stream/edit-videos/video-clipping/).


:::

## Prerequisites

When configuring a [Live input](/stream/stream-live/start-stream-live/), ensure "Live Playback and Recording" (`mode`) is enabled.

API keys are not needed to generate a preview or clip, but are needed to create Live Inputs.

Live instant clips are generated dynamically from the recording of a live stream. When generating clips manifests or MP4s, always reference the Video ID, not the Live Input ID. If the recording is deleted, the instant clip will no longer be available.

## Preview manifest

To help users replay and seek recent content, request a preview manifest by adding a `duration` parameter to the HLS manifest URL:

```txt title="Preview Manifest"
https://customer-<CODE>.cloudflarestream.com/<VIDEO_ID||INPUT_ID>/manifest/video.m3u8?duration=5m
```



* `duration` string duration of the preview, up to 5 minutes as either a number of seconds ("30s") or minutes ("3m")


When the preview manifest is delivered, inspect the headers for two properties:



* `preview-start-seconds` float seconds into the start of the live stream or recording that the preview manifest starts. Useful in applications that allow a user to select a range from the preview because the clip will need to reference its offset from the *broadcast* start time, not the *preview* start time.
* `stream-media-id` string the video ID of the live stream or recording. Useful in applications that render the player using an *input* ID because the clip URL should reference the *video* ID.


This manifest can be played and seeked using any HLS-compatible player.

### Reading headers

Reading headers when loading a manifest requires adjusting how players handle
the response. For example, if using [HLS.js](https://github.com/video-dev/hls.js)
and the default loader, override the `pLoader` (playlist loader) class:

```js
let currentPreviewStart;
let currentPreviewVideoID;

// Override the pLoader (playlist loader) to read the manifest headers:
class pLoader extends Hls.DefaultConfig.loader {
  constructor(config) {
    super(config);
    var load = this.load.bind(this);
    this.load = function (context, config, callbacks) {
      if (context.type == 'manifest') {
        var onSuccess = callbacks.onSuccess;
        // copy the existing onSuccess handler to fire it later.

        callbacks.onSuccess = function (response, stats, context, networkDetails) {
          // The fourth argument here is undocumented in HLS.js but contains
          // the response object for the manifest fetch, which gives us headers:

          currentPreviewStart =
            parseFloat(networkDetails.getResponseHeader('preview-start-seconds'));
          // Save the start time of the preview manifest

          currentPreviewVideoID =
            networkDetails.getResponseHeader('stream-media-id');
          // Save the video ID in case the preview was loaded with an input ID

          onSuccess(response, stats, context);
          // And fire the exisint success handler.
        };
      }
      load(context, config, callbacks);
    };
  }
}

// Specify the new loader class when setting up HLS
const hls = new Hls({
  pLoader: pLoader,
});
```

## Clip manifest

To play a clip of a live stream or recording, request a clip manifest with a duration and a start time, relative to the start of the live stream.

```txt title="Clip Manifest"
https://customer-<CODE>.cloudflarestream.com/<VIDEO_ID>/manifest/clip.m3u8?time=600s&duration=30s
```



* `time` string start time of the clip in seconds, from the start of the live stream or recording
* `duration` string duration of the clip in seconds, up to 60 seconds max


This manifest can be played and seeked using any HLS-compatible player.

## Clip MP4 download

An MP4 of the clip can also be generated dynamically to be saved and shared on other platforms.

```txt title="Clip MP4 Download"
https://customer-<CODE>.cloudflarestream.com/<VIDEO_ID>/clip.mp4?time=600s&duration=30s&filename=clip.mp4
```



* `time` string start time of the clip in seconds, from the start of the live stream or recording (example: "500s")
* `duration` string duration of the clip in seconds, up to 60 seconds max (example: "60s")
* `filename` string *(optional)* a filename for the clip

---

# Watch a live stream

URL: https://developers.cloudflare.com/stream/stream-live/watch-live-stream/

import { Render } from "~/components"

When a [Live Input](/stream/stream-live/start-stream-live/) begins receiving a
broadcast, a new video is automatically created if the input's `mode` property
is set to `automatic`.

To watch, Stream offers a built-in Player or you use a custom player with the
HLS and DASH manifests.

<Render file="chromecast_limitations" />

## View by Live Input ID or Video ID

Whether you use the Stream Player or a custom player with a manifest, you can
reference the Live Input ID or a specific Video ID. The main difference is what
happens when a broadcast concludes.

Use a Live Input ID in instances where a player should always show the active
broadcast, if there is one, or a "Stream has not started" message if the input
is idle. This option is best for cases where a page is dedicated to a creator, channel, or
recurring program. The Live Input ID is provisioned for you when you create the
input; it will not change.

Use a Video ID in instances where a player should be used to display a single
broadcast or its recording once the broadcast has concluded. This option is best for cases where
a page is dedicated to a one-time event, specific episode/occurance, or date.
There is a _new_ Video ID generated for each broadcast _when it starts._

Using DVR mode, explained below, there are additional considerations.

Stream's URLs are all templatized for easy generation:

**Stream built-in Player URL format:**

```
https://customer-<CODE>.cloudflarestream.com/<INPUT_ID|VIDEO_ID>/iframe
```

A full embed code can be generated in Dash or with the API.

**HLS Manifest URL format:**

```
https://customer-<CODE>.cloudflarestream.com/<INPUT_ID|VIDEO_ID>/manifest/video.m3u8
```

You can also retrieve the embed code or manifest URLs from Dash or the API.

## Use the dashboard

To get the Stream built-in player embed code or HLS Manifest URL for a custom player:

1. Log in to your [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Stream** > **Live Inputs**.
3. Select a live input from the list.
4. Locate the **Embed** and **HLS Manifest URL** beneath the video.
5. Determine which option to use and then select **Click to copy** beneath your choice.

The embed code or manifest URL retrieved in Dash will reference the Live Input ID.

## Use the API

To retrieve the player code or manifest URLs via the API, fetch the Live Input's
list of videos:

```bash title="Request"
curl -X GET \
-H "Authorization: Bearer <API_TOKEN>" \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/live_inputs/<LIVE_INPUT_UID>/videos
```

A live input will have multiple videos associated with it, one for each broadcast.
If there is an active broadcast, the first video in the response will have a
`live-inprogress` status. Other videos in the response represent recordings
which can be played on-demand.

Each video in the response, including the active broadcast if there is one,
contains the HLS and DASH URLs and a link to the Stream player. Noteworthy
properties include:

- `preview` -- Link to the Stream player to watch
- `playback`.`hls` -- HLS Manifest
- `playback`.`dash` -- DASH Manifest

In the example below, the state of the live video is `live-inprogress` and the
state for previously recorded video is `ready`.

```json title="Response" {4,7,21,28,32,46}
{
  "result": [
    {
      "uid": "6b9e68b07dfee8cc2d116e4c51d6a957",
      "thumbnail": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg",

      "status": {
        "state": "live-inprogress",
        "errorReasonCode": "",
        "errorReasonText": ""
      },
      "meta": {
        "name": "Stream Live Test 23 Sep 21 05:44 UTC"
      },
      "created": "2021-09-23T05:44:30.453838Z",
      "modified": "2021-09-23T05:44:30.453838Z",
      "size": 0,
      "preview": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/watch",
      ...

      "playback": {
        "hls": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8",
        "dash": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.mpd"
      },
      ...
    },
    {
      "uid": "6b9e68b07dfee8cc2d116e4c51d6a957",
      "thumbnail": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg",
      "thumbnailTimestampPct": 0,
      "readyToStream": true,
      "status": {
        "state": "ready",
        "pctComplete": "100.000000",
        "errorReasonCode": "",
        "errorReasonText": ""
      },
      "meta": {
        "name": "CFTV Staging 22 Sep 21 22:12 UTC"
      },
      "created": "2021-09-22T22:12:53.587306Z",
      "modified": "2021-09-23T00:14:05.591333Z",
      "size": 0,
      "preview": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/watch",
      ...
      "playback": {
        "hls": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8",
        "dash": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.mpd"
      },
    }
  ],
}
```

These will reference the Video ID.

## Live input status

You can check whether a live input is currently streaming and what its active
video ID is by making a request to its `lifecycle` endpoint. The Stream player
does this automatically to show a note when the input is idle. Custom players
may require additional support.

```bash
curl -X GET \
-H "Authorization: Bearer <API_TOKEN>" \
https://customer-<CODE>.cloudflarestream.com/<INPUT_ID>/lifecycle
```

In the example below, the response indicates the `ID` is for an input with an active `videoUID`. The `live` status value indicates the input is actively streaming.

```json
{
    "isInput": true,
    "videoUID": "55b9b5ce48c3968c6b514c458959d6a",
    "live": true
}
```

```json
{
    "isInput": true,
    "videoUID": null,
    "live": false
}
```

When viewing a live stream via the live input ID, the `requireSignedURLs` and `allowedOrigins` options in the live input recording settings are used. These settings are independent of the video-level settings.

## Live stream recording playback

After a live stream ends, a recording is automatically generated and available within 60 seconds. To ensure successful video viewing and playback, keep the following in mind:

* If a live stream ends while a viewer is watching, viewers using the Stream player should wait 60 seconds and then reload the player to view the recording of the live stream.
* After a live stream ends, you can check the status of the recording via the API. When the video state is `ready`, you can use one of the manifest URLs to stream the recording.

While the recording of the live stream is generating, the video may report as `not-found` or `not-started`.

If you are not using the Stream player for live stream recordings, refer to [Record and replay live streams](/stream/stream-live/replay-recordings/) for more information on how to replay a live stream recording.

---

# Receive Live Webhooks

URL: https://developers.cloudflare.com/stream/stream-live/webhooks/

import { AvailableNotifications } from "~/components"

Stream Live offers webhooks to notify your service when an Input connects, disconnects, or encounters an error with Stream Live.

<AvailableNotifications product="Stream" />

## Subscribe to Stream Live Webhooks

1. Log in to your Cloudflare account and click **Notifications**.
2. From the **Notifications** page, click the **Destinations** tab.
3. On the **Destinations** page under **Webhooks**, click **Create**.
4. Enter the information for your webhook and click **Save and Test**.
5. To create the notification, from the **Notifications** page, click the **All Notifications** tab.
6. Next to **Notifications**, click **Add**.
7. Under the list of products, locate **Stream** and click **Select**.
8. Enter a name and optional description.
9. Under **Webhooks**, click **Add webhook** and click your newly created webhook.
10. Click **Next**.
11. By default, you will receive webhook notifications for all Live Inputs. If you only wish to receive webhooks for certain inputs, enter a comma-delimited list of Input IDs in the text field.
12. When you are done, click **Create**.<br/><br/>

```json title="Example webhook payload"
{
  "name": "Live Webhook Test",
  "text": "Notification type: Stream Live Input\nInput ID: eb222fcca08eeb1ae84c981ebe8aeeb6\nEvent type: live_input.disconnected\nUpdated at: 2022-01-13T11:43:41.855717910Z",
  "data": {
    "notification_name": "Stream Live Input",
    "input_id": "eb222fcca08eeb1ae84c981ebe8aeeb6",
    "event_type": "live_input.disconnected",
    "updated_at": "2022-01-13T11:43:41.855717910Z"
  },
  "ts": 1642074233
}
```

The `event_type` property of the data object will either be `live_input.connected`, `live_input.disconnected`, or `live_input.errored`.

If there are issues detected with the input, the `event_type` will be `live_input.errored`. Additional data will be under the `live_input_errored` json key and will include a `code` with one of the values listed below.

## Error codes

* `ERR_GOP_OUT_OF_RANGE` – The input GOP size or keyframe interval is out of range.
* `ERR_UNSUPPORTED_VIDEO_CODEC` – The input video codec is unsupported for the protocol used.
* `ERR_UNSUPPORTED_AUDIO_CODEC` – The input audio codec is unsupported for the protocol used.
* `ERR_STORAGE_QUOTA_EXHAUSTED` – The account storage quota has been exceeded. Delete older content or purcahse additional storage.
* `ERR_MISSING_SUBSCRIPTION` – Unauthorized to start a live stream. Check subscription or log into Dash for details.

```json title="Example live_input.errored webhook payload"
{
  "name": "Live Webhook Test",
  "text": "Notification type: Stream Live Input\nInput ID: 2c28dd2cc444cb77578c4840b51e43a8\nEvent type: live_input.errored\nUpdated at: 2024-07-09T18:07:51.077371662Z\nError Code: ERR_GOP_OUT_OF_RANGE\nError Message: Input GOP size or keyframe interval is out of range.\nVideo Codec: \nAudio Codec: ",
  "data": {
    "notification_name": "Stream Live Input",
    "input_id": "eb222fcca08eeb1ae84c981ebe8aeeb6",
    "event_type": "live_input.errored",
    "updated_at": "2024-07-09T18:07:51.077371662Z",
    "live_input_errored": {
      "error": {
        "code": "ERR_GOP_OUT_OF_RANGE",
        "message": "Input GOP size or keyframe interval is out of range."
      },
      "video_codec": "",
      "audio_codec": ""
    }
  },
  "ts": 1720548474,
}
```

---

# Transform videos

URL: https://developers.cloudflare.com/stream/transform-videos/

Media Transformations let you optimize and manipulate videos stored _outside_ of the Cloudflare Stream. Transformed videos and images are served from one of your zones on Cloudflare.

To transform a video or image, you must [enable transformations](/stream/transform-videos/#getting-started) for your zone. If your zone already has Image Transformations enabled, you can also optimize videos with Media Transformations.

## Getting started

You can dynamically optimize and generate still images from videos that are stored _outside_ of Cloudflare Stream with Media Transformations.

Cloudflare will automatically cache every transformed video or image on our global network so that you store only the original image at your origin.

To enable transformations on your zone:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Go to **Stream** > **Transformations**.
3. Locate the specific zone where you want to enable transformations.
4. Select **Enable** for zone.

## Transform a video by URL

You can convert and resize videos by requesting them via a specially-formatted URL, without writing any code. The URL format is:

```
https://example.com/cdn-cgi/media/<OPTIONS>/<SOURCE-VIDEO>
```

- `example.com`: Your website or zone on Cloudflare, with Transformations enabled.
- `/cdn-cgi/media/`: A prefix that identifies a special path handled by Cloudflare's built-in media transformation service.
- `<OPTIONS>`: A comma-separated list of options. Refer to the available options below.
- `<SOURCE-VIDEO>`: A full URL (starting with `https://` or `http://`) of the original asset to resize.

For example, this URL will source an HD video from an R2 bucket, shorten it, crop and resize it as a square, and remove the audio.

```
https://example.com/cdn-cgi/media/mode=video,time=5s,duration=5s,width=500,height=500,fit=crop,audio=false/https://pub-8613b7f94d6146408add8fefb52c52e8.r2.dev/aus-mobile-demo.mp4
```

The result is an MP4 that can be used in an HTML video element without a player library.

## Options

### `mode`

Specifies the kind of output to generate.

- `video`: Outputs an H.264/AAC optimized MP4 file.
- `frame`: Outputs a still image.
- `spritesheet`: Outputs a JPEG with multiple frames.

### `time`

Specifies when to start extracting the output in the input file. Depends on `mode`:

- When `mode` is `spritesheet` or `video`, specifies the timestamp where the output will start.
- When `mode` is `frame`, specifies the timestamp from which to extract the still image.
- Formats as a time string, for example: 5s, 2m
- Acceptable range: 0 – 30s
- Default: 0

### `duration`

The duration of the output video or spritesheet. Depends on `mode`:

- When `mode` is `video`, specifies the duration of the output.
- When `mode` is `spritesheet`, specifies the time range from which to select frames.
- Acceptable range: 1s - 60s (or 1m)
- Default: input duration or 30 seconds, whichever is shorter

### `fit`

In combination with `width` and `height`, specifies how to resize and crop the output. If the output is resized, it will always resize proportionally so content is not stretched.

- `contain`: Respecting aspect ratio, scales a video up or down to be entirely contained within output dimensions.
- `scale-down`: Same as contain, but downscales to fit only. Do not upscale.
- `cover`: Respecting aspect ratio, scales a video up or down to entirely cover the output dimensions, with a center-weighted crop of the remainder.

### `height`

Specifies maximum height of the output in pixels. Exact behavior depends on `fit`.

- Acceptable range: 10-2000 pixels

### `width`

Specifies the maximum width of the image in pixels. Exact behavior depends on `fit`.

- Acceptable range: 10-2000 pixels

### `audio`

When `mode` is `video`, specifies whether or not to include the source audio in the output.

- `true`: Includes source audio.
- `false`: Output will be silent.
- Default: `true`

### `format`

If `mode` is `frame`, specifies the image output format.

- Acceptable options: `jpg`, `png`

## Source video requirements

Input video must be less than 100MB.

Input video should be an MP4 with H.264 encoded video and AAC or MP3 encoded audio. Other formats may work but are untested.

## Limitations

Media Transformations are currently in beta. During this period:

- Transformations are available for all enabled zones free-of-charge.
- Restricting allowed origins for transformations are coming soon.
- Outputs from Media Transformations will be cached, but if they must be regenerated, the origin fetch is not cached and may result in subsequent requests to the origin asset.

## Pricing

Media Transformations will be free for all customers while in beta.

After that, Media Transforamtions and Image Transformations will use the same subscriptions and usage metrics.

- Generating a still frame (single image) from a video counts as 1 transformation.
- Generating an optimized video counts as 1 transformation _per second of the output_ video.
- Each unique transformation is only billed once per month.
- All Media and Image Transformations cost $0.50 per 1,000 monthly unique transformation operations, with a free monthly allocation of 5,000.

---

# Define source origin

URL: https://developers.cloudflare.com/stream/transform-videos/sources/

When optimizing remote videos, you can specify which origins can be used as the source for transformed videos. By default, Cloudflare accepts only source videos from the zone where your transformations are served.

On this page, you will learn how to define and manage the origins for the source videos that you want to optimize.

:::note
The allowed origins setting applies to requests from Cloudflare Workers. 

If you use a Worker to optimize remote videos via a `fetch()` subrequest, then this setting may conflict with existing logic that handles source videos.
:::

## Configure origins

To get started, you must have [transformations enabled on your zone](/stream/transform-videos/#getting-started).

In the Cloudflare dashboard, go to **Stream** > **Transformations** and select the zone where you want to serve transformations.

In **Sources**, you can configure the origins for transformations on your zone.

![Enable allowed origins from the Cloudflare dashboard](~/assets/images/images/allowed-origins.png)

## Allow source videos only from allowed origins

You can restrict source videos to **allowed origins**, which applies transformations only to source videos from a defined list.

By default, your accepted sources are set to **allowed origins**. Cloudflare will always allow source videos from the same zone where your transformations are served.

If you request a transformation with a source video from outside your **allowed origins**, then the video will be rejected. For example, if you serve transformations on your zone `a.com` and do not define any additional origins, then `a.com/video.mp4` can be used as a source video, but `b.com/video.mp4` will return an error.

To define a new origin:

1. From **Sources**, select **Add origin**.
2. Under **Domain**, specify the domain for the source video. Only valid web URLs will be accepted.

![Add the origin for source videos in the Cloudflare dashboard](~/assets/images/images/add-origin.png)

When you add a root domain, subdomains are not accepted. In other words, if you add `b.com`, then source videos from `media.b.com` will be rejected.

To support individual subdomains, define an additional origin such as `media.b.com`. If you add only `media.b.com` and not the root domain, then source videos from the root domain (`b.com`) and other subdomains (`cdn.b.com`) will be rejected.

To support all subdomains, use the `*` wildcard at the beginning of the root domain. For example, `*.b.com` will accept source videos from the root domain (like `b.com/video.mp4`) as well as from subdomains (like `media.b.com/video.mp4` or `cdn.b.com/video.mp4`).

3. Optionally, you can specify the **Path** for the source video. If no path is specified, then source videos from all paths on this domain are accepted.

Cloudflare checks whether the defined path is at the beginning of the source path. If the defined path is not present at the beginning of the path, then the source video will be rejected.

For example, if you define an origin with domain `b.com` and path `/themes`, then `b.com/themes/video.mp4` will be accepted but `b.com/media/themes/video.mp4` will be rejected.

4. Select **Add**. Your origin will now appear in your list of allowed origins.
5. Select **Save**. These changes will take effect immediately.

When you configure **allowed origins**, only the initial URL of the source video is checked. Any redirects, including URLs that leave your zone, will be followed, and the resulting video will be transformed.

If you change your accepted sources to **any origin**, then your list of sources will be cleared and reset to default.

## Allow source videos from any origin

When your accepted sources are set to **any origin**, any publicly available video can be used as the source video for transformations on this zone.

**Any origin** is less secure and may allow third parties to serve transformations on your zone.

---

# Direct creator uploads

URL: https://developers.cloudflare.com/stream/uploading-videos/direct-creator-uploads/

Direct creator uploads let your end users upload videos directly to Cloudflare Stream without exposing your API token to clients.

- If your video is a [basic upload](/stream/uploading-videos/direct-creator-uploads/#basic-uploads) under 200 MB and users do not need resumable uploads, generate a URL that accepts an HTTP post request.

- If your video is over 200 MB or if you need to allow users to [resume interrupted uploads](/stream/uploading-videos/direct-creator-uploads/#resumable-uploads), generate a URL using the tus protocol.

In either case, you must specify a maximum duration to reserve for the user's upload to ensure it can be accommodated within your available storage.

## Basic uploads

Use this option if your users upload videos under 200 MB, and you do not need to allow resumable uploads.

1. Generate a unique, one-time upload URL using the [Direct upload API](/api/resources/stream/subresources/direct_upload/methods/create/).

```sh title="Generate upload"
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/direct_upload \
--header 'Authorization: Bearer <API_TOKEN>' \
 --data '{
    "maxDurationSeconds": 3600
 }'
```

{/* <!-- videodelivery.net is correct domain. See STREAM-4364 --> */}

```json output {3}
{
	"result": {
		"uploadURL": "https://upload.videodelivery.net/f65014bc6ff5419ea86e7972a047ba22",
		"uid": "f65014bc6ff5419ea86e7972a047ba22"
	},
	"success": true,
	"errors": [],
	"messages": []
}
```

2. With the `uploadURL` from the previous step, users can upload video files that are limited to 200 MB in size. Refer to the example request below.

{/* <!-- videodelivery.net is correct domain. See STREAM-4364 --> */}

```bash {3} title="Upload a video to the unique one-time upload URL"
curl --request POST \
  --form file=@/Users/mickie/Downloads/example_video.mp4 \
  https://upload.videodelivery.net/f65014bc6ff5419ea86e7972a047ba22
```

A successful upload will receive a `200` HTTP status code response. If the upload does not meet
the upload constraints defined at time of creation or is larger than 200 MB in size, you will receive a `4xx` HTTP status code response.

## Resumable uploads

1. Create your own API endpoint that returns an upload URL.

The example below shows how to build a Worker to get a URL you can use to upload your video. The one-time upload URL is returned in the `Location` header of the response, not in the response body.

```javascript {23} title="Example API endpoint"
export async function onRequest(context) {
	const { request, env } = context;
	const { CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN } = env;
	const endpoint = `https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/stream?direct_user=true`;

	const response = await fetch(endpoint, {
		method: "POST",
		headers: {
			Authorization: `bearer ${CLOUDFLARE_API_TOKEN}`,
			"Tus-Resumable": "1.0.0",
			"Upload-Length": request.headers.get("Upload-Length"),
			"Upload-Metadata": request.headers.get("Upload-Metadata"),
		},
	});

	const destination = response.headers.get("Location");

	return new Response(null, {
		headers: {
			"Access-Control-Expose-Headers": "Location",
			"Access-Control-Allow-Headers": "*",
			"Access-Control-Allow-Origin": "*",
			Location: destination,
		},
	});
}
```

2. Use this API endpoint **directly** in your tus client. A common mistake is to extract the upload URL from your new API endpoint, and use this directly. See below for a complete example of how to use the API from Step 1 with the uppy tus client.

```html {35} title="Upload a video using the uppy tus client"
<html>
	<head>
		<link
			href="https://releases.transloadit.com/uppy/v3.0.1/uppy.min.css"
			rel="stylesheet"
		/>
	</head>
	<body>
		<div id="drag-drop-area" style="height: 300px"></div>
		<div class="for-ProgressBar"></div>
		<button class="upload-button" style="font-size: 30px; margin: 20px">
			Upload
		</button>
		<div class="uploaded-files" style="margin-top: 50px">
			<ol></ol>
		</div>
		<script type="module">
			import {
				Uppy,
				Tus,
				DragDrop,
				ProgressBar,
			} from "https://releases.transloadit.com/uppy/v3.0.1/uppy.min.mjs";

			const uppy = new Uppy({ debug: true, autoProceed: true });

			const onUploadSuccess = (el) => (file, response) => {
				const li = document.createElement("li");
				const a = document.createElement("a");
				a.href = response.uploadURL;
				a.target = "_blank";
				a.appendChild(document.createTextNode(file.name));
				li.appendChild(a);

				document.querySelector(el).appendChild(li);
			};

			uppy
				.use(DragDrop, { target: "#drag-drop-area" })
				.use(Tus, {
					endpoint: "/api/get-upload-url",
					chunkSize: 150 * 1024 * 1024,
				})
				.use(ProgressBar, {
					target: ".for-ProgressBar",
					hideAfterFinish: false,
				})
				.on("upload-success", onUploadSuccess(".uploaded-files ol"));

			const uploadBtn = document.querySelector("button.upload-button");
			uploadBtn.addEventListener("click", () => uppy.upload());
		</script>
	</body>
</html>
```

For more details on using tus and example client code, refer to [Resumable and large files (tus)](/stream/uploading-videos/resumable-uploads/).

## Upload-Metadata header syntax

You can apply the [same constraints](/api/resources/stream/subresources/direct_upload/methods/create/) as Direct Creator Upload via basic upload when using tus. To do so, you must pass the `expiry` and `maxDurationSeconds` as part of the `Upload-Metadata` request header as part of the first request (made by the Worker in the example above.) The `Upload-Metadata` values are ignored from subsequent requests that do the actual file upload.

The `Upload-Metadata` header should contain key-value pairs. The keys are text and the values should be encoded in base64. Separate the key and values by a space, _not_ an equal sign. To join multiple key-value pairs, include a comma with no additional spaces.

In the example below, the `Upload-Metadata` header is instructing Stream to only accept uploads with max video duration of 10 minutes, uploaded prior to the expiry timestamp, and to make this video private:

`'Upload-Metadata: maxDurationSeconds NjAw,requiresignedurls,expiry MjAyNC0wMi0yN1QwNzoyMDo1MFo='`

`NjAw` is the base64 encoded value for "600" (or 10 minutes).
`MjAyNC0wMi0yN1QwNzoyMDo1MFo=` is the base64 encoded value for "2024-02-27T07:20:50Z" (an RFC3339 format timestamp)

## Track upload progress

After the creation of a unique one-time upload URL, you may wish to retain the unique identifier (`uid`) returned in the response to track the progress of a user's upload.

You can do that two ways:

- [Search for a video](/stream/manage-video-library/searching/) with the UID to check the status.

- [Create a webhook subscription](/stream/manage-video-library/using-webhooks/) to receive notifications about the video status. These notifications include the video's UID.

## Billing considerations

Direct Creator Upload links count towards your storage limit even if your users have not yet uploaded video to this URL. If the link expires before it is used or the upload cannot be processed, the storage reservation will be released. Otherwise, once the upload is encoded, its true duration will be counted toward storage and the reservation will be released.

For a detailed breakdown of pricing and example scenarios, refer to [Pricing](/stream/pricing/).

---

# Upload videos

URL: https://developers.cloudflare.com/stream/uploading-videos/

Before you upload your video, review the options for uploading a video, supported formats, and recommendations.

## Upload options

| Upload method	| When to use |
|---------------|-------------|
|[Stream Dashboard](https://dash.cloudflare.com/?to=/:account/stream)| Upload videos from the Stream Dashboard without writing any code.
|[Upload with a link](/stream/uploading-videos/upload-via-link/)| Upload videos using a link, such as an S3 bucket or content management system.
|[Upload video file](/stream/uploading-videos/upload-video-file/)| Upload videos stored on a computer.
|[Direct creator uploads](/stream/uploading-videos/direct-creator-uploads/)| Allows end users of your website or app to upload videos directly to Cloudflare Stream.


## Supported video formats


:::note
Files must be less than 30 GB, and content should be encoded and uploaded in the same frame rate it was recorded.
:::

- MP4
- MKV
- MOV
- AVI
- FLV
- MPEG-2 TS
- MPEG-2 PS
- MXF
- LXF
- GXF
- 3GP
- WebM
- MPG
- Quicktime

## Recommendations for on-demand videos

- Optional but ideal settings:
  - MP4 containers
  - AAC audio codec
  - H264 video codec
  - 60 or fewer frames per second
- Closed GOP (_Only required for live streaming._)
- Mono or Stereo audio. Stream will mix audio tracks with more than two channels down to stereo.

---

# Player API

URL: https://developers.cloudflare.com/stream/uploading-videos/player-api/

Attributes are added in the `<stream>` tag without quotes, as you can see below:

```
<stream attribute-added-here src="5d5bc37ffcf54c9b82e996823bffbb81"></stream>
```

Multiple attributes can be used together, added one after each other like this:

```
<stream attribute-1 attribute-2 attribute-3 src="5d5bc37ffcf54c9b82e996823bffbb81"></stream>
```

## Supported attributes

* `autoplay` boolean

  * Tells the browser to immediately start downloading the video and play it as soon as it can. Note that mobile browsers generally do not support this attribute, the user must tap the screen to begin video playback. Please consider mobile users or users with Internet usage limits as some users do not have unlimited Internet access before using this attribute.

  :::note
  To disable video autoplay, the `autoplay` attribute needs to be removed altogether as this attribute. Setting `autoplay="false"` will not work; the video will autoplay if the attribute is there in the `<stream>` tag.

In addition, some browsers now prevent videos with audio from playing automatically. You may add the `mute` attribute to allow your videos to autoplay. For more information, see [new video policies for iOS](https://webkit.org/blog/6784/new-video-policies-for-ios/).
  :::

* `controls` boolean

  * Shows the default video controls such as buttons for play/pause, volume controls. You may choose to build buttons and controls that work with the player. [See an example.](/stream/viewing-videos/using-own-player/)

* `height` integer

  * The height of the video's display area, in CSS pixels.

* `loop` boolean

  * A Boolean attribute; if included in the HTML tag, player will, automatically seek back to the start upon reaching the end of the video.

* `muted` boolean

  * A Boolean attribute which indicates the default setting of the audio contained in the video. If set, the audio will be initially silenced.

* `preload` string | null

  * This enumerated attribute is intended to provide a hint to the browser about what the author thinks will lead to the best user experience. You may choose to include this attribute as a boolean attribute without a value, or you may specify the value `preload="auto"` to preload the beginning of the video. Not including the attribute or using `preload="metadata"` will just load the metadata needed to start video playback when requested.

  :::note
  The `<video>` element does not force the browser to follow the value of this attribute; it is a mere hint. Even though the `preload="none"` option is a valid HTML5 attribute, Stream player will always load some metadata to initialize the player. The amount of data loaded in this case is negligible.
  :::

* `poster` string

  * A URL for an image to be shown before the video is started or while the video is downloading. If this attribute is not specified, a thumbnail image of the video is shown.

* `src` string

  * The video id from the video you've uploaded to Cloudflare Stream should be included here.

* `width` integer

  * The width of the video's display area, in CSS pixels.

## Methods

* `play()` Promise

  * Start video playback.

* `pause()` null

  * Pause video playback.

## Properties

* `autoplay`

  * Sets or returns whether the autoplay attribute was set, allowing video playback to start upon load.

* `controls`

  * Sets or returns whether the video should display controls (like play/pause etc.)

* `currentTime`

  * Returns the current playback time in seconds. Setting this value seeks the video to a new time.

* `duration` readonly

  * Returns the duration of the video in seconds.

* `ended` readonly

  * Returns whether the video has ended.

* `loop`

  * Sets or returns whether the video should start over when it reaches the end

* `muted`

  * Sets or returns whether the audio should be played with the video

* `paused` readonly

  * Returns whether the video is paused

* `preload`

  * Sets or returns whether the video should be preloaded upon element load.

* `volume`

  * Sets or returns volume from 0.0 (silent) to 1.0 (maximum value)

## Events

### Standard video element events

Stream supports most of the [standardized media element events](https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Media_events).

* `abort`

  * Sent when playback is aborted; for example, if the media is playing and is restarted from the beginning, this event is sent.

* `canplay`

  * Sent when enough data is available that the media can be played, at least for a couple of frames.

* `canplaythrough`

  * Sent when the entire media can be played without interruption, assuming the download rate remains at least at the current level. It will also be fired when playback is toggled between paused and playing. Note: Manually setting the currentTime will eventually fire a canplaythrough event in firefox. Other browsers might not fire this event.

* `durationchange`

  * The metadata has loaded or changed, indicating a change in duration of the media. This is sent, for example, when the media has loaded enough that the duration is known.

* `ended`

  * Sent when playback completes.

* `error`

  * Sent when an error occurs. (for example, the video has not finished encoding yet, or the video fails to load due to an incorrect signed URL)

* `loadeddata`

  * The first frame of the media has finished loading.

* `loadedmetadata`

   * The media's metadata has finished loading; all attributes now contain as much useful information as they are going to.

* `loadstart`

  * Sent when loading of the media begins.

* `pause`

  * Sent when the playback state is changed to paused (paused property is true).

* `play`

  * Sent when the playback state is no longer paused, as a result of the play method, or the autoplay attribute.

* `playing`

  * Sent when the media has enough data to start playing, after the play event, but also when recovering from being stalled, when looping media restarts, and after seeked, if it was playing before seeking.

* `progress`

  * Sent periodically to inform interested parties of progress downloading the media. Information about the current amount of the media that has been downloaded is available in the media element's buffered attribute.

* `ratechange`

  * Sent when the playback speed changes.

* `seeked`

  * Sent when a seek operation completes.

* `seeking`

  * Sent when a seek operation begins.

* `stalled`

  * Sent when the user agent is trying to fetch media data, but data is unexpectedly not forthcoming.

* `suspend`

  * Sent when loading of the media is suspended; this may happen either because the download has completed or because it has been paused for any other reason.

* `timeupdate`

  * The time indicated by the element's currentTime attribute has changed.

* `volumechange`

  * Sent when the audio volume changes (both when the volume is set and when the muted attribute is changed).

* `waiting`

  * Sent when the requested operation (such as playback) is delayed pending the completion of another operation (such as a seek).

### Non-standard events

Non-standard events are prefixed with `stream-` to distinguish them from standard events.

* `stream-adstart`

  * Fires when `ad-url` attribute is present and the ad begins playback

* `stream-adend`

  * Fires when `ad-url` attribute is present and the ad finishes playback

* `stream-adtimeout`

  * Fires when `ad-url` attribute is present and the ad took too long to load.

---

# Resumable and large files (tus)

URL: https://developers.cloudflare.com/stream/uploading-videos/resumable-uploads/

import { PackageManagers } from "~/components";

If you have a video over 200 MB, we recommend using the [tus protocol](https://tus.io/) for resumable file uploads. A resumable upload ensures that the upload can be interrupted and resumed without uploading the previous data again.

## Requirements

- Resumable uploads require a minimum chunk size of 5,242,880 bytes unless the entire file is less than this amount. For better performance when the client connection is expected to be reliable, increase the chunk size to 52,428,800 bytes.
- Maximum chunk size is 209,715,200 bytes.
- Chunk size must be divisible by 256 KiB (256x1024 bytes). Round your chunk size to the nearest multiple of 256 KiB. Note that the final chunk of an upload that fits within a single chunk is exempt from this requirement.

## Prerequisites

Before you can upload a video using tus, you will need to download a tus client.

For more information, refer to the [tus Python client](https://github.com/tus/tus-py-client) which is available through pip, Python's package manager.

```python title="Install Python client"
pip install -U tus.py
```

## Upload a video using tus

```sh title="Upload using tus"
tus-upload --chunk-size 52428800 --header \
Authorization "Bearer <API_TOKEN>"
<PATH_TO_VIDEO> https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream
```

```sh title="tus response"
INFO Creating file endpoint
INFO Created: https://api.cloudflare.com/client/v4/accounts/d467d4f0fcbcd9791b613bc3a9599cdc/stream/dd5d531a12de0c724bd1275a3b2bc9c6
...
```

### Golang example

Before you begin, import a tus client such as [go-tus](https://github.com/eventials/go-tus) to upload from your Go applications.

The `go-tus` library does not return the response headers to the calling function, which makes it difficult to read the video ID from the `stream-media-id` header. As a workaround, create a [Direct Creator Upload](/stream/uploading-videos/direct-creator-uploads/) link. That API response will include the TUS endpoint as well as the video ID. Setting a Creator ID is not required.

```go title="Upload with Golang"
package main

import (
	"net/http"
	"os"

	tus "github.com/eventials/go-tus"
)

func main() {
	accountID := "<ACCOUNT_ID>"

	f, err := os.Open("videofile.mp4")

	if err != nil {
		panic(err)
	}

	defer f.Close()

	headers := make(http.Header)
	headers.Add("Authorization", "Bearer <API_TOKEN>")

	config := &tus.Config{
		ChunkSize:           50 * 1024 * 1024, // Required a minimum chunk size of 5 MB, here we use 50 MB.
		Resume:              false,
		OverridePatchMethod: false,
		Store:               nil,
		Header:              headers,
		HttpClient:          nil,
	}

	client, _ := tus.NewClient("https://api.cloudflare.com/client/v4/accounts/"+ accountID +"/stream", config)

	upload, _ := tus.NewUploadFromFile(f)

	uploader, _ := client.CreateUpload(upload)

	uploader.Upload()
}
```

You can also get the progress of the upload if you are running the upload in a goroutine.

```go title="Get progress of upload"
// returns the progress percentage.
upload.Progress()

// returns whether or not the upload is complete.
upload.Finished()
```

Refer to [go-tus](https://github.com/eventials/go-tus) for functionality such as resuming uploads.

### Node.js example

Before you begin, install the tus-js-client.

<PackageManagers pkg="tus-js-client" />

Create an `index.js` file and configure:

- The API endpoint with your Cloudflare Account ID.
- The request headers to include an API token.

```js title="Configure index.js"
var fs = require("fs");
var tus = require("tus-js-client");

// Specify location of file you would like to upload below
var path = __dirname + "/test.mp4";
var file = fs.createReadStream(path);
var size = fs.statSync(path).size;
var mediaId = "";

var options = {
	endpoint: "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream",
	headers: {
		Authorization: "Bearer <API_TOKEN>",
	},
	chunkSize: 50 * 1024 * 1024, // Required a minimum chunk size of 5 MB. Here we use 50 MB.
	retryDelays: [0, 3000, 5000, 10000, 20000], // Indicates to tus-js-client the delays after which it will retry if the upload fails.
	metadata: {
		name: "test.mp4",
		filetype: "video/mp4",
		// Optional if you want to include a watermark
		// watermark: '<WATERMARK_UID>',
	},
	uploadSize: size,
	onError: function (error) {
		throw error;
	},
	onProgress: function (bytesUploaded, bytesTotal) {
		var percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
		console.log(bytesUploaded, bytesTotal, percentage + "%");
	},
	onSuccess: function () {
		console.log("Upload finished");
	},
	onAfterResponse: function (req, res) {
		return new Promise((resolve) => {
			var mediaIdHeader = res.getHeader("stream-media-id");
			if (mediaIdHeader) {
				mediaId = mediaIdHeader;
			}
			resolve();
		});
	},
};

var upload = new tus.Upload(file, options);
upload.start();
```

## Specify upload options

The tus protocol allows you to add optional parameters in the [`Upload-Metadata` header](https://tus.io/protocols/resumable-upload.html#upload-metadata).

### Supported options in `Upload-Metadata`

Setting arbitrary metadata values in the `Upload-Metadata` header sets values in the [meta key in Stream API](/api/resources/stream/methods/list/).

- `name`

  - Setting this key will set `meta.name` in the API and display the value as the name of the video in the dashboard.

- `requiresignedurls`

  - If this key is present, the video playback for this video will be required to use signed URLs after upload.

- `scheduleddeletion`

  - Specifies a date and time when a video will be deleted. After a video is deleted, it is no longer viewable and no longer counts towards storage for billing. The specified date and time cannot be earlier than 30 days or later than 1,096 days from the video's created timestamp.

- `allowedorigins`

  - An array of strings listing origins allowed to display the video. This will set the [allowed origins setting](/stream/viewing-videos/securing-your-stream/#security-considerations) for the video.

- `thumbnailtimestamppct`

  - Specify the default thumbnail [timestamp percentage](/stream/viewing-videos/displaying-thumbnails/). Note that percentage is a floating point value between 0.0 and 1.0.

- `watermark`

  - The watermark profile UID.

## Set creator property

Setting a creator value in the `Upload-Creator` header can be used to identify the creator of the video content, linking the way you identify your users or creators to videos in your Stream account.

For examples of how to set and modify the creator ID, refer to [Associate videos with creators](/stream/manage-video-library/creator-id/).

## Get the video ID when using tus

When an initial tus request is made, Stream responds with a URL in the `Location` header. While this URL may contain the video ID, it is not recommend to parse this URL to get the ID.

Instead, you should use the `stream-media-id` HTTP header in the response to retrieve the video ID.

For example, a request made to `https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream` with the tus protocol will contain a HTTP header like the following:

```
stream-media-id: cab807e0c477d01baq20f66c3d1dfc26cf
```

---

# Upload with a link

URL: https://developers.cloudflare.com/stream/uploading-videos/upload-via-link/

import { LinkButton } from "~/components"

If you have videos stored in a cloud storage bucket, you can pass a HTTP link for the file, and Stream will fetch the file on your behalf.

## Make an HTTP request

Make a `POST` request to the Stream API using the link to your video.

```bash
curl \
--data '{"url":"https://storage.googleapis.com/zaid-test/Watermarks%20Demo/cf-ad-original.mp4","meta":{"name":"My First Stream Video"}}' \
--header "Authorization: Bearer <API_TOKEN>" \
https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/copy
```

## Check video status

Stream must download and encode the video, which can take a few seconds to a few minutes depending on the length of your video.

When the `readyToStream` value returns `true`, your video is ready for streaming.

You can optionally use [webhooks](/stream/manage-video-library/using-webhooks/) which will notify you when the video is ready to stream or if an error occurs.

```json {3,6}
{
  "result": {
    "uid": "6b9e68b07dfee8cc2d116e4c51d6a957",
    "thumbnail": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg",
    "thumbnailTimestampPct": 0,
    "readyToStream": false,
    "status": {
      "state": "downloading"
    },
    "meta": {
      "downloaded-from": "https://storage.googleapis.com/zaid-test/Watermarks%20Demo/cf-ad-original.mp4",
      "name": "My First Stream Video"
    },
    "created": "2020-10-16T20:20:17.872170843Z",
    "modified": "2020-10-16T20:20:17.872170843Z",
    "size": 9032701,
    "preview": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/watch",
    "allowedOrigins": [],
    "requireSignedURLs": false,
    "uploaded": "2020-10-16T20:20:17.872170843Z",
    "uploadExpiry": null,
    "maxSizeBytes": 0,
    "maxDurationSeconds": 0,
    "duration": -1,
    "input": {
      "width": -1,
      "height": -1
    },
    "playback": {
      "hls": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8",
      "dash": "https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.mpd"
    },
    "watermark": null
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

After the video is uploaded, you can use the video `uid` shown in the example response above to play the video using the [Stream video player](/stream/viewing-videos/using-the-stream-player/).

If you are using your own player or rendering the video in a mobile app, refer to [using your own player](/stream/viewing-videos/using-the-stream-player/using-the-player-api/).

---

# Basic video uploads

URL: https://developers.cloudflare.com/stream/uploading-videos/upload-video-file/

## Basic Uploads

For files smaller than 200 MB, you can use simple form-based uploads.

## Upload through the Cloudflare dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/).
2. From the navigation menu, select **Stream**.
3. On the **Overview** page, drag and drop your video into the **Quick upload** area. You can also click to browse for the file on your machine.

After the video finishes uploading, the video appears in the list.

## Upload with the Stream API

Make a `POST` request with the `content-type` header set to `multipart/form-data` and include the media as an input with the name set to `file`.

```bash title="Upload video POST request"
curl --request POST \
--header "Authorization: Bearer <API_TOKEN>" \
--form file=@/Users/user_name/Desktop/my-video.mp4 \
https://api.cloudflare.com/client/v4/accounts/{account_id}/stream
```

:::note
Note that cURL's `--form` flag automatically configures the `content-type` header and maps `my-video.mp4` to a form input called `file`.
:::

---

# Display thumbnails

URL: https://developers.cloudflare.com/stream/viewing-videos/displaying-thumbnails/

:::note


Stream thumbnails are not supported for videos with non-square pixels.


:::

## Use Case 1: Generating a thumbnail on-the-fly

A thumbnail from your video can be generated using a special link where you specify the time from the video you'd like to get the thumbnail from.

`https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg?time=1s&height=270`

<img src="https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg?time=1s&height=270" alt="Example of thumbnail image generated from example video" />

Using the `poster` query parameter in the embed URL, you can set a thumbnail to any time in your video. If [signed URLs](/stream/viewing-videos/securing-your-stream/) are required, you must use a signed URL instead of video UIDs.

```html
<iframe
  src="https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/iframe?poster=https%3A%2F%2Fcustomer-f33zs165nr7gyfy4.cloudflarestream.com%2F6b9e68b07dfee8cc2d116e4c51d6a957%2Fthumbnails%2Fthumbnail.jpg%3Ftime%3D%26height%3D600"
  style="border: none; position: absolute; top: 0; left: 0; height: 100%; width: 100%;"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen="true"
></iframe>
```

Supported URL attributes are:

* **`time`** (default `0s`, configurable) time from the video for example `8m`, `5m2s`
* **`height`** (default `640`)
* **`width`** (default `640`)
* **`fit`** (default `crop`) to clarify what to do when requested height and width does not match the original upload, which should be one of:
  * **`crop`** cut parts of the video that doesn't fit in the given size
  * **`clip`** preserve the entire frame and decrease the size of the image within given size
  * **`scale`** distort the image to fit the given size
  * **`fill`** preserve the entire frame and fill the rest of the requested size with black background

## Use Case 2: Set the default thumbnail timestamp using the API

By default, the Stream Player sets the thumbnail to the first frame of the video. You can change this on a per-video basis by setting the "thumbnailTimestampPct" value using the API:

```bash
curl -X POST \
-H "Authorization: Bearer <API_TOKEN>" \
-d '{"thumbnailTimestampPct": 0.5}' \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>
```

`thumbnailTimestampPct` is a value between 0.0 (the first frame of the video) and 1.0 (the last frame of the video). For example, you wanted the thumbnail to be the frame at the half way point of your videos, you can set the `thumbnailTimestampPct` value to 0.5. Using relative values in this way allows you to set the default thumbnail even if you or your users' videos vary in duration.

## Use Case 3: Generating animated thumbnails

Stream supports animated GIFs as thumbnails. Viewing animated thumbnails does not count toward billed minutes delivered or minutes viewed in [Stream Analytics](/stream/getting-analytics/).

### Animated GIF thumbnails

` https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.gif?time=1s&height=200&duration=4s`

<img src="https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.gif?time=1s&height=200&duration=4s" alt="Animated gif example, generated on-demand from Cloudflare Stream" />

Supported URL attributes for animated thumbnails are:

* **`time`** (default `0s`) time from the video for example `8m`, `5m2s`
* **`height`** (default `640`)
* **`width`** (default `640`)
* **`fit`** (default `crop`) to clarify what to do when requested height and width does not match the original upload, which should be one of:
  * **`crop`** cut parts of the video that doesn't fit in the given size
  * **`clip`** preserve the entire frame and decrease the size of the image within given size
  * **`scale`** distort the image to fit the given size
  * **`fill`** preserve the entire frame and fill the rest of the requested size with black background
* **`duration`** (default `5s`)
* **`fps`** (default `8`)

---

# Download videos

URL: https://developers.cloudflare.com/stream/viewing-videos/download-videos/

When you upload a video to Stream, it can be streamed using HLS/DASH. However, for certain use-cases (such as offline viewing), you may want to download the MP4. You can enable MP4 support on a per video basis by following the steps below:

1. Enable MP4 support by making a POST request to the `/downloads` endpoint (example below)
2. Save the MP4 URL provided by the response to the `/downloads` endpoint. This MP4 URL will become functional when the MP4 is ready in the next step.
3. Poll the `/downloads `endpoint until the `status` field is set to `ready` to inform you when the MP4 is available. You can now use the MP4 URL from step 2.

## Generate downloadable files

You can enable downloads for an uploaded video once it is ready to view by making an HTTP request to the `/downloads` endpoint.

To get notified when a video is ready to view, refer to [Using webhooks](/stream/manage-video-library/using-webhooks/#notifications).

The downloads API response will include all available download types for the video, the download URL for each type, and the processing status of the download file.

```bash title="Request"
curl -X POST \
-H "Authorization: Bearer <API_TOKEN>" \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/downloads
```

```json title="Response"
{
	"result": {
		"default": {
			"status": "inprogress",
			"url": "https://customer-<CODE>.cloudflarestream.com/<VIDEO_UID>/downloads/default.mp4",
			"percentComplete": 75.0
		}
	},
	"success": true,
	"errors": [],
	"messages": []
}
```

## Get download links

You can view all available downloads for a video by making a `GET` HTTP request to the downloads API. The response for creating and fetching downloads are the same.

```bash title="Request"
curl -X GET \
-H "Authorization: Bearer <API_TOKEN>" \
https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/downloads
```

```json title="Response"
{
	"result": {
		"default": {
			"status": "ready",
			"url": "https://customer-<CODE>.cloudflarestream.com/<VIDEO_UID>/downloads/default.mp4",
			"percentComplete": 100.0
		}
	},
	"success": true,
	"errors": [],
	"messages": []
}
```

## Customize download file name

You can customize the name of downloadable files by adding the `filename` query string parameter at the end of the URL.

In the example below, adding `?filename=MY_VIDEO.mp4` to the URL will change the file name to `MY_VIDEO.mp4`.

`https://customer-<CODE>.cloudflarestream.com/<VIDEO_UID>/downloads/default.mp4?filename=MY_VIDEO.mp4`

The `filename` can be a maximum of 120 characters long and composed of `abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_` characters. The extension (.mp4) is appended automatically.

## Retrieve downloads

The generated MP4 download files can be retrieved via the link in the download API response.

```sh
curl -L https://customer-<CODE>.cloudflarestream.com/<VIDEO_UID>/downloads/default.mp4 > download.mp4
```

## Secure video downloads

If your video is public, the MP4 will also be publicly accessible. If your video is private and requires a signed URL for viewing, the MP4 will not be publicly accessible. To access the MP4 for a private video, you can generate a signed URL just as you would for regular viewing with an additional flag called `downloadable` set to `true`.

Download links will not work for videos which already require signed URLs if the `downloadable` flag is not present in the token.

For more details about using signed URLs with videos, refer to [Securing your Stream](/stream/viewing-videos/securing-your-stream/).

**Example token payload**

```json null {6}
{
    "sub": <VIDEO_UID>,
    "kid": <KEY_ID>,
    "exp": 1537460365,
    "nbf": 1537453165,
    "downloadable": true,
    "accessRules": [
      {
        "type": "ip.geoip.country",
        "action": "allow",
        "country": [
          "GB"
        ]
      },
      {
        "type": "any",
        "action": "block"
      }
    ]
  }
```

## Billing for MP4 downloads

MP4 downloads are billed in the same way as streaming of the video. You will be billed for the duration of the video each time the MP4 for the video is downloaded. For example, if you have a 10 minute video that is downloaded 100 times during the month, the downloads will count as 1000 minutes of minutes served.

You will not incur any additional cost for storage when you enable MP4s.

---

# Play video

URL: https://developers.cloudflare.com/stream/viewing-videos/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Secure your Stream

URL: https://developers.cloudflare.com/stream/viewing-videos/securing-your-stream/

## Signed URLs / Tokens

By default, videos on Stream can be viewed by anyone with just a video id. If you want to make your video private by default and only give access to certain users, you can use the signed URL feature. When you mark a video to require signed URL, it can no longer be accessed publicly with only the video id. Instead, the user will need a signed url token to watch or download the video.

Here are some common use cases for using signed URLs:

- Restricting access so only logged in members can watch a particular video
- Let users watch your video for a limited time period (ie. 24 hours)
- Restricting access based on geolocation

### Making a video require signed URLs

Since video ids are effectively public within signed URLs, you will need to turn on `requireSignedURLs` on for your videos. This option will prevent any public links, such as `watch.cloudflarestream.com/{video_uid}`, from working.

Restricting viewing can be done by updating the video's metadata.

```bash
curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/{video_uid}" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/json"
--data "{\"uid\": \"<VIDEO_UID>\", \"requireSignedURLs\": true }"
```

Response:

```json null {5}
{
  "result": {
    "uid": "<VIDEO_UID>",
    ...
    "requireSignedURLs": true
  },
  "success": true,
  "errors": [],
  "messages": []
}
```

## Two Ways to Generate Signed Tokens

You can program your app to generate token in two ways:

- **Low-volume or testing: Use the `/token` endpoint to generate a short-lived signed token.** This is recommended for testing purposes or if you are generating less than 1,000 tokens per day. It requires making an API call to Cloudflare for each token. The default result is valid for 1 hour.

- **Recommended: Use a signing key to create tokens.** If you have thousands of daily users or need to generate a high volume of tokens, you can create tokens yourself using a signing key. This way, you do not need to call a Stream API each time you need to generate a token.

## Option 1: Using the /token endpoint

You can call the `/token` endpoint for any video that is marked private to get a signed URL token which expires in one hour. This method does not support [Live WebRTC](/stream/webrtc-beta/).

```bash
curl --request POST \
https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/{video_uid}/token \
--header "Authorization: Bearer <API_TOKEN>"
```

You will see a response similar to this if the request succeeds:

```json
{
	"result": {
		"token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImNkYzkzNTk4MmY4MDc1ZjJlZjk2MTA2ZDg1ZmNkODM4In0.eyJraWQiOiJjZGM5MzU5ODJmODA3NWYyZWY5NjEwNmQ4NWZjZDgzOCIsImV4cCI6IjE2MjE4ODk2NTciLCJuYmYiOiIxNjIxODgyNDU3In0.iHGMvwOh2-SuqUG7kp2GeLXyKvMavP-I2rYCni9odNwms7imW429bM2tKs3G9INms8gSc7fzm8hNEYWOhGHWRBaaCs3U9H4DRWaFOvn0sJWLBitGuF_YaZM5O6fqJPTAwhgFKdikyk9zVzHrIJ0PfBL0NsTgwDxLkJjEAEULQJpiQU1DNm0w5ctasdbw77YtDwdZ01g924Dm6jIsWolW0Ic0AevCLyVdg501Ki9hSF7kYST0egcll47jmoMMni7ujQCJI1XEAOas32DdjnMvU8vXrYbaHk1m1oXlm319rDYghOHed9kr293KM7ivtZNlhYceSzOpyAmqNFS7mearyQ"
	},
	"success": true,
	"errors": [],
	"messages": []
}
```

To render the video, insert the `token` value in place of the `video id`:

```html
<iframe
	src="https://customer-<CODE>.cloudflarestream.com/eyJhbGciOiJSUzI1NiIsImtpZCI6ImNkYzkzNTk4MmY4MDc1ZjJlZjk2MTA2ZDg1ZmNkODM4In0.eyJraWQiOiJjZGM5MzU5ODJmODA3NWYyZWY5NjEwNmQ4NWZjZDgzOCIsImV4cCI6IjE2MjE4ODk2NTciLCJuYmYiOiIxNjIxODgyNDU3In0.iHGMvwOh2-SuqUG7kp2GeLXyKvMavP-I2rYCni9odNwms7imW429bM2tKs3G9INms8gSc7fzm8hNEYWOhGHWRBaaCs3U9H4DRWaFOvn0sJWLBitGuF_YaZM5O6fqJPTAwhgFKdikyk9zVzHrIJ0PfBL0NsTgwDxLkJjEAEULQJpiQU1DNm0w5ctasdbw77YtDwdZ01g924Dm6jIsWolW0Ic0AevCLyVdg501Ki9hSF7kYST0egcll47jmoMMni7ujQCJI1XEAOas32DdjnMvU8vXrYbaHk1m1oXlm319rDYghOHed9kr293KM7ivtZNlhYceSzOpyAmqNFS7mearyQ/iframe"
	style="border: none;"
	height="720"
	width="1280"
	allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
	allowfullscreen="true"
></iframe>
```

If you are using your own player, replace the video id in the manifest URL with the `token` value:

`https://customer-<CODE>.cloudflarestream.com/eyJhbGciOiJSUzI1NiIsImtpZCI6ImNkYzkzNTk4MmY4MDc1ZjJlZjk2MTA2ZDg1ZmNkODM4In0.eyJraWQiOiJjZGM5MzU5ODJmODA3NWYyZWY5NjEwNmQ4NWZjZDgzOCIsImV4cCI6IjE2MjE4ODk2NTciLCJuYmYiOiIxNjIxODgyNDU3In0.iHGMvwOh2-SuqUG7kp2GeLXyKvMavP-I2rYCni9odNwms7imW429bM2tKs3G9INms8gSc7fzm8hNEYWOhGHWRBaaCs3U9H4DRWaFOvn0sJWLBitGuF_YaZM5O6fqJPTAwhgFKdikyk9zVzHrIJ0PfBL0NsTgwDxLkJjEAEULQJpiQU1DNm0w5ctasdbw77YtDwdZ01g924Dm6jIsWolW0Ic0AevCLyVdg501Ki9hSF7kYST0egcll47jmoMMni7ujQCJI1XEAOas32DdjnMvU8vXrYbaHk1m1oXlm319rDYghOHed9kr293KM7ivtZNlhYceSzOpyAmqNFS7mearyQ/manifest/video.m3u8`

### Customizing default restrictions

If you call the `/token` endpoint without any body, it will return a token that expires in one hour. Let's say you want to let a user watch a particular video for the next 12 hours. Here's how you'd do it with a Cloudflare Worker:

```javascript
export default {
	async fetch(request, env, ctx) {
		const signed_url_restrictions = {
			//limit viewing for the next 12 hours
			exp: Math.floor(Date.now() / 1000) + 12 * 60 * 60,
		};

		const init = {
			method: "POST",
			headers: {
				Authorization: "Bearer <API_TOKEN>",
				"content-type": "application/json;charset=UTF-8",
			},
			body: JSON.stringify(signed_url_restrictions),
		};

		const signedurl_service_response = await fetch(
			"https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/{video_uid}/token",
			init,
		);

		return new Response(
			JSON.stringify(await signedurl_service_response.json()),
			{ status: 200 },
		);
	},
};
```

The returned token will expire after 12 hours.

Let's take this a step further and add 2 additional restrictions:

- Allow the signed URL token to be used for MP4 downloads (assuming the video has downloads enabled)
- Block users from US and Mexico from viewing or downloading the video

To achieve this, we can specify additional restrictions in the `signed_url_restrictions` object in our sample code:

```javascript
export default {
	async fetch(request, env, ctx) {
		const signed_url_restrictions = {
			//limit viewing for the next 2 hours
			exp: Math.floor(Date.now() / 1000) + 12 * 60 * 60,
			downloadable: true,
			accessRules: [
				{ type: "ip.geoip.country", country: ["US", "MX"], action: "block" },
			],
		};

		const init = {
			method: "POST",
			headers: {
				Authorization: "Bearer <API_TOKEN>",
				"content-type": "application/json;charset=UTF-8",
			},
			body: JSON.stringify(signed_url_restrictions),
		};

		const signedurl_service_response = await fetch(
			"https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/{video_uid}/token",
			init,
		);

		return new Response(
			JSON.stringify(await signedurl_service_response.json()),
			{ status: 200 },
		);
	},
};
```

## Option 2: Using a signing key to create signed tokens

If you are generating a high-volume of tokens, using [Live WebRTC](/stream/webrtc-beta/), or need to customize the access rules, generate new tokens using a signing key so you do not need to call the Stream API each time.

### Step 1: Call the `/stream/key` endpoint _once_ to obtain a key

```bash
curl --request POST \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/keys" \
--header "Authorization: Bearer <API_TOKEN>"
```

The response will return `pem` and `jwk` values.

```json
{
	"result": {
		"id": "8f926b2b01f383510025a78a4dcbf6a",
		"pem": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcEFJQkFBS0NBUUVBemtHbXhCekFGMnBIMURiWmgyVGoyS3ZudlBVTkZmUWtNeXNCbzJlZzVqemRKTmRhCmtwMEphUHhoNkZxOTYveTBVd0lBNjdYeFdHb3kxcW1CRGhpdTVqekdtYW13NVgrYkR3TEdTVldGMEx3QnloMDYKN01Rb0xySHA3MDEycXBVNCtLODUyT1hMRVVlWVBrOHYzRlpTQ2VnMVdLRW5URC9oSmhVUTFsTmNKTWN3MXZUbQpHa2o0empBUTRBSFAvdHFERHFaZ3lMc1Vma2NsRDY3SVRkZktVZGtFU3lvVDVTcnFibHNFelBYcm9qaFlLWGk3CjFjak1yVDlFS0JCenhZSVEyOVRaZitnZU5ya0t4a2xMZTJzTUFML0VWZkFjdGkrc2ZqMkkyeEZKZmQ4aklmL2UKdHBCSVJZVDEza2FLdHUyYmk0R2IrV1BLK0toQjdTNnFGODlmTHdJREFRQUJBb0lCQUYzeXFuNytwNEtpM3ZmcgpTZmN4ZmRVV0xGYTEraEZyWk1mSHlaWEFJSnB1MDc0eHQ2ZzdqbXM3Tm0rTFVhSDV0N3R0bUxURTZacy91RXR0CjV3SmdQTjVUaFpTOXBmMUxPL3BBNWNmR2hFN1pMQ2wvV2ZVNXZpSFMyVDh1dGlRcUYwcXpLZkxCYk5kQW1MaWQKQWl4blJ6UUxDSzJIcmlvOW1KVHJtSUUvZENPdG80RUhYdHpZWjByOVordHRxMkZrd3pzZUdaK0tvd09JaWtvTgp2NWFOMVpmRGhEVG0wdG1Vd0tLbjBWcmZqalhRdFdjbFYxTWdRejhwM2xScWhISmJSK29PL1NMSXZqUE16dGxOCm5GV1ZEdTRmRHZsSjMyazJzSllNL2tRVUltT3V5alY3RTBBcm5vR2lBREdGZXFxK1UwajluNUFpNTJ6aTBmNloKdFdvwdju39xOFJWQkwxL2tvWFVmYk00S04ydVFadUdjaUdGNjlCRDJ1S3o1eGdvTwowVTBZNmlFNG9Cek5GUW5hWS9kayt5U1dsQWp2MkgraFBrTGpvZlRGSGlNTmUycUVNaUFaeTZ5cmRkSDY4VjdIClRNRllUQlZQaHIxT0dxZlRmc00vRktmZVhWY1FvMTI1RjBJQm5iWjNSYzRua1pNS0hzczUyWE1DZ1lFQTFQRVkKbGIybDU4blVianRZOFl6Uk1vQVo5aHJXMlhwM3JaZjE0Q0VUQ1dsVXFZdCtRN0NyN3dMQUVjbjdrbFk1RGF3QgpuTXJsZXl3S0crTUEvU0hlN3dQQkpNeDlVUGV4Q3YyRW8xT1loMTk3SGQzSk9zUythWWljemJsYmJqU0RqWXVjCkdSNzIrb1FlMzJjTXhjczJNRlBWcHVibjhjalBQbnZKd0k5aUpGVUNnWUVBMjM3UmNKSEdCTjVFM2FXLzd3ekcKbVBuUm1JSUczeW9UU0U3OFBtbHo2bXE5eTVvcSs5aFpaNE1Fdy9RbWFPMDF5U0xRdEY4QmY2TFN2RFh4QWtkdwpWMm5ra0svWWNhWDd3RHo0eWxwS0cxWTg3TzIwWWtkUXlxdjMybG1lN1JuVDhwcVBDQTRUWDloOWFVaXh6THNoCkplcGkvZFhRWFBWeFoxYXV4YldGL3VzQ2dZRUFxWnhVVWNsYVlYS2dzeUN3YXM0WVAxcEwwM3h6VDR5OTBOYXUKY05USFhnSzQvY2J2VHFsbGVaNCtNSzBxcGRmcDM5cjIrZFdlemVvNUx4YzBUV3Z5TDMxVkZhT1AyYk5CSUpqbwpVbE9ldFkwMitvWVM1NjJZWVdVQVNOandXNnFXY21NV2RlZjFIM3VuUDVqTVVxdlhRTTAxNjVnV2ZiN09YRjJyClNLYXNySFVDZ1lCYmRvL1orN1M3dEZSaDZlamJib2h3WGNDRVd4eXhXT2ZMcHdXNXdXT3dlWWZwWTh4cm5pNzQKdGRObHRoRXM4SHhTaTJudEh3TklLSEVlYmJ4eUh1UG5pQjhaWHBwNEJRNTYxczhjR1Z1ZSszbmVFUzBOTDcxZApQL1ZxUWpySFJrd3V5ckRFV2VCeEhUL0FvVEtEeSt3OTQ2SFM5V1dPTGJvbXQrd3g0NytNdWc9PQotLS0tLUVORCBSU0EgUFJJVkFURSBLRVktLS0tLQo=",
		"jwk": "eyJ1c2UiOiJzaWciLCJrdHkiOiJSU0EiLCJraWQiOiI4ZjkyNmIyYjAxZjM4MzUxNzAwMjVhNzhhNGRjYmY2YSIsImFsZyI6IlJTMjU2IiwibiI6InprR214QnpBRjJwSDFEYlpoMlRqMkt2bnZQVU5GZlFrTXlzQm8yZWc1anpkSk5kYWtwMEphUHhoNkZxOTZfeTBVd0lBNjdYeFdHb3kxcW1CRGhpdTVqekdtYW13NVgtYkR3TEdTVldGMEx3QnloMDY3TVFvTHJIcDcwMTJxcFU0LUs4NTJPWExFVWVZUGs4djNGWlNDZWcxV0tFblREX2hKaFVRMWxOY0pNY3cxdlRtR2tqNHpqQVE0QUhQX3RxRERxWmd5THNVZmtjbEQ2N0lUZGZLVWRrRVN5b1Q1U3JxYmxzRXpQWHJvamhZS1hpNzFjak1yVDlFS0JCenhZSVEyOVRaZi1nZU5ya0t4a2xMZTJzTUFMX0VWZkFjdGktc2ZqMkkyeEZKZmQ4aklmX2V0cEJJUllUMTNrYUt0dTJiaTRHYi1XUEstS2hCN1M2cUY4OWZMdyIsImUiOiJBUUFCIiwiZCI6IlhmS3FmdjZuZ3FMZTktdEo5ekY5MVJZc1ZyWDZFV3RreDhmSmxjQWdtbTdUdmpHM3FEdU9henMyYjR0Um9mbTN1MjJZdE1UcG16LTRTMjNuQW1BODNsT0ZsTDJsX1VzNy1rRGx4OGFFVHRrc0tYOVo5VG0tSWRMWlB5NjJKQ29YU3JNcDhzRnMxMENZdUowQ0xHZEhOQXNJcllldUtqMllsT3VZZ1Q5MEk2MmpnUWRlM05oblN2MW42MjJyWVdURE94NFpuNHFqQTRpS1NnMl9sbzNWbDhPRU5PYlMyWlRBb3FmUld0LU9OZEMxWnlWWFV5QkRQeW5lVkdxRWNsdEg2Zzc5SXNpLU04ek8yVTJjVlpVTzdoOE8tVW5mYVRhd2xnei1SQlFpWTY3S05Yc1RRQ3VlZ2FJQU1ZVjZxcjVUU1Ai2odx5iT0xSX3BtMWFpdktyUSIsInAiOiI5X1o5ZUpGTWI5X3E4UlZCTDFfa29YVWZiTTRLTjJ1UVp1R2NpR0Y2OUJEMnVLejV4Z29PMFUwWTZpRTRvQnpORlFuYVlfZGsteVNXbEFqdjJILWhQa0xqb2ZURkhpTU5lMnFFTWlBWnk2eXJkZEg2OFY3SFRNRllUQlZQaHIxT0dxZlRmc01fRktmZVhWY1FvMTI1RjBJQm5iWjNSYzRua1pNS0hzczUyWE0iLCJxIjoiMVBFWWxiMmw1OG5VYmp0WThZelJNb0FaOWhyVzJYcDNyWmYxNENFVENXbFVxWXQtUTdDcjd3TEFFY243a2xZNURhd0JuTXJsZXl3S0ctTUFfU0hlN3dQQkpNeDlVUGV4Q3YyRW8xT1loMTk3SGQzSk9zUy1hWWljemJsYmJqU0RqWXVjR1I3Mi1vUWUzMmNNeGNzMk1GUFZwdWJuOGNqUFBudkp3STlpSkZVIiwiZHAiOiIyMzdSY0pIR0JONUUzYVdfN3d6R21QblJtSUlHM3lvVFNFNzhQbWx6Nm1xOXk1b3EtOWhaWjRNRXdfUW1hTzAxeVNMUXRGOEJmNkxTdkRYeEFrZHdWMm5ra0tfWWNhWDd3RHo0eWxwS0cxWTg3TzIwWWtkUXlxdjMybG1lN1JuVDhwcVBDQTRUWDloOWFVaXh6THNoSmVwaV9kWFFYUFZ4WjFhdXhiV0ZfdXMiLCJkcSI6InFaeFVVY2xhWVhLZ3N5Q3dhczRZUDFwTDAzeHpUNHk5ME5hdWNOVEhYZ0s0X2NidlRxbGxlWjQtTUswcXBkZnAzOXIyLWRXZXplbzVMeGMwVFd2eUwzMVZGYU9QMmJOQklKam9VbE9ldFkwMi1vWVM1NjJZWVdVQVNOandXNnFXY21NV2RlZjFIM3VuUDVqTVVxdlhRTTAxNjVnV2ZiN09YRjJyU0thc3JIVSIsInFpIjoiVzNhUDJmdTB1N1JVWWVubzIyNkljRjNBaEZzY3NWam55NmNGdWNGanNIbUg2V1BNYTU0dS1MWFRaYllSTFBCOFVvdHA3UjhEU0NoeEhtMjhjaDdqNTRnZkdWNmFlQVVPZXRiUEhCbGJudnQ1M2hFdERTLTlYVF8xYWtJNngwWk1Mc3F3eEZuZ2NSMF93S0V5Zzh2c1BlT2gwdlZsamkyNkpyZnNNZU9fakxvIn0=",
		"created": "2021-06-15T21:06:54.763937286Z"
	},
	"success": true,
	"errors": [],
	"messages": []
}
```

Save these values as they won't be shown again. You will use these values later to generate the tokens. The pem and jwk fields are base64-encoded, you must decode them before using them (an example of this is shown in step 2).

### Step 2: Generate tokens using the key

Once you generate the key in step 1, you can use the `pem` or `jwk` values to generate self-signing URLs on your own. Using this method, you do not need to call the Stream API each time you are creating a new token.

Here's an example Cloudflare Worker script which generates tokens that expire in 60 minutes and only work for users accessing the video from UK. In lines 2 and 3, you will configure the `id` and `jwk` values from step 1:

```javascript
// Global variables
const jwkKey = "{PRIVATE-KEY-IN-JWK-FORMAT}";
const keyID = "<KEY_ID>";
const videoUID = "<VIDEO_UID>";
// expiresTimeInS is the expired time in second of the video
const expiresTimeInS = 3600;

// Main function
async function streamSignedUrl() {
	const encoder = new TextEncoder();
	const expiresIn = Math.floor(Date.now() / 1000) + expiresTimeInS;
	const headers = {
		alg: "RS256",
		kid: keyID,
	};
	const data = {
		sub: videoUID,
		kid: keyID,
		exp: expiresIn,
		accessRules: [
			{
				type: "ip.geoip.country",
				action: "allow",
				country: ["GB"],
			},
			{
				type: "any",
				action: "block",
			},
		],
	};

	const token = `${objectToBase64url(headers)}.${objectToBase64url(data)}`;

	const jwk = JSON.parse(atob(jwkKey));

	const key = await crypto.subtle.importKey(
		"jwk",
		jwk,
		{
			name: "RSASSA-PKCS1-v1_5",
			hash: "SHA-256",
		},
		false,
		["sign"],
	);

	const signature = await crypto.subtle.sign(
		{ name: "RSASSA-PKCS1-v1_5" },
		key,
		encoder.encode(token),
	);

	const signedToken = `${token}.${arrayBufferToBase64Url(signature)}`;

	return signedToken;
}

// Utilities functions
function arrayBufferToBase64Url(buffer) {
	return btoa(String.fromCharCode(...new Uint8Array(buffer)))
		.replace(/=/g, "")
		.replace(/\+/g, "-")
		.replace(/\//g, "_");
}

function objectToBase64url(payload) {
	return arrayBufferToBase64Url(
		new TextEncoder().encode(JSON.stringify(payload)),
	);
}
```

### Step 3: Rendering the video

If you are using the Stream Player, insert the token returned by the Worker in Step 2 in place of the video id:

```html
<iframe
	src="https://customer-<CODE>.cloudflarestream.com/eyJhbGciOiJSUzI1NiIsImtpZCI6ImNkYzkzNTk4MmY4MDc1ZjJlZjk2MTA2ZDg1ZmNkODM4In0.eyJraWQiOiJjZGM5MzU5ODJmODA3NWYyZWY5NjEwNmQ4NWZjZDgzOCIsImV4cCI6IjE2MjE4ODk2NTciLCJuYmYiOiIxNjIxODgyNDU3In0.iHGMvwOh2-SuqUG7kp2GeLXyKvMavP-I2rYCni9odNwms7imW429bM2tKs3G9INms8gSc7fzm8hNEYWOhGHWRBaaCs3U9H4DRWaFOvn0sJWLBitGuF_YaZM5O6fqJPTAwhgFKdikyk9zVzHrIJ0PfBL0NsTgwDxLkJjEAEULQJpiQU1DNm0w5ctasdbw77YtDwdZ01g924Dm6jIsWolW0Ic0AevCLyVdg501Ki9hSF7kYST0egcll47jmoMMni7ujQCJI1XEAOas32DdjnMvU8vXrYbaHk1m1oXlm319rDYghOHed9kr293KM7ivtZNlhYceSzOpyAmqNFS7mearyQ/iframe"
	style="border: none;"
	height="720"
	width="1280"
	allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
	allowfullscreen="true"
></iframe>
```

If you are using your own player, replace the video id in the manifest url with the `token` value:

`https://customer-<CODE>.cloudflarestream.com/eyJhbGciOiJSUzI1NiIsImtpZCI6ImNkYzkzNTk4MmY4MDc1ZjJlZjk2MTA2ZDg1ZmNkODM4In0.eyJraWQiOiJjZGM5MzU5ODJmODA3NWYyZWY5NjEwNmQ4NWZjZDgzOCIsImV4cCI6IjE2MjE4ODk2NTciLCJuYmYiOiIxNjIxODgyNDU3In0.iHGMvwOh2-SuqUG7kp2GeLXyKvMavP-I2rYCni9odNwms7imW429bM2tKs3G9INms8gSc7fzm8hNEYWOhGHWRBaaCs3U9H4DRWaFOvn0sJWLBitGuF_YaZM5O6fqJPTAwhgFKdikyk9zVzHrIJ0PfBL0NsTgwDxLkJjEAEULQJpiQU1DNm0w5ctasdbw77YtDwdZ01g924Dm6jIsWolW0Ic0AevCLyVdg501Ki9hSF7kYST0egcll47jmoMMni7ujQCJI1XEAOas32DdjnMvU8vXrYbaHk1m1oXlm319rDYghOHed9kr293KM7ivtZNlhYceSzOpyAmqNFS7mearyQ/manifest/video.m3u8`

### Revoking keys

You can create up to 1,000 keys and rotate them at your convenience.
Once revoked all tokens created with that key will be invalidated.

```bash
curl --request DELETE \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/keys/{key_id}" \
--header "Authorization: Bearer <API_TOKEN>"

# Response:
{
  "result": "Revoked",
  "success": true,
  "errors": [],
  "messages": []
}
```

## Supported Restrictions

| Property Name | Description                                                                                                                                                                                                                                                |     |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- |
| exp           | Expiration. A unix epoch timestamp after which the token will stop working. Cannot be greater than 24 hours in the future from when the token is signed                                                                                                    |     |
| nbf           | _Not Before_ value. A unix epoch timestamp before which the token will not work                                                                                                                                                                            |     |
| downloadable  | if true, the token can be used to download the mp4 (assuming the video has downloads enabled)                                                                                                                                                              |     |
| accessRules   | An array that specifies one or more ip and geo restrictions. accessRules are evaluated first-to-last. If a Rule matches, the associated action is applied and no further rules are evaluated. A token may have at most 5 members in the accessRules array. |     |

### accessRules Schema

Each accessRule must include 2 required properties:

- `type`: supported values are `any`, `ip.src` and `ip.geoip.country`
- `action`: support values are `allow` and `block`

Depending on the rule type, accessRules support 2 additional properties:

- `country`: an array of 2-letter country codes in [ISO 3166-1 Alpha 2](https://www.iso.org/obp/ui/#search) format.
- `ip`: an array of ip ranges. It is recommended to include both IPv4 and IPv6 variants in a rule if possible. Having only a single variant in a rule means that rule will ignore the other variant. For example, an IPv4-based rule will never be applicable to a viewer connecting from an IPv6 address. CIDRs should be preferred over specific IP addresses. Some devices, such as mobile, may change their IP over the course of a view. Video Access Control are evaluated continuously while a video is being viewed. As a result, overly strict IP rules may disrupt playback.

**_Example 1: Block views from a specific country_**

```txt
...
"accessRules": [
	{
		"type": "ip.geoip.country",
		"action": "block",
		"country": ["US", "DE", "MX"],
	},
]
```

The first rule matches on country, US, DE, and MX here. When that rule matches, the block action will have the token considered invalid. If the first rule doesn't match, there are no further rules to evaluate. The behavior in this situation is to consider the token valid.

**_Example 2: Allow only views from specific country or IPs_**

```txt
...
"accessRules": [
	{
		"type": "ip.geoip.country",
		"country": ["US", "MX"],
		"action": "allow",
	},
	{
		"type": "ip.src",
		"ip": ["93.184.216.0/24", "2400:cb00::/32"],
		"action": "allow",
	},
	{
		"type": "any",
		"action": "block",
	},
]
```

The first rule matches on country, US and MX here. When that rule matches, the allow action will have the token considered valid. If it doesn't match we continue evaluating rules

The second rule is an IP rule matching on CIDRs, 93.184.216.0/24 and 2400:cb00::/32. When that rule matches, the allow action will consider the rule valid.

If the first two rules don't match, the final rule of any will match all remaining requests and block those views.

## Security considerations

### Hotlinking Protection

By default, Stream embed codes can be used on any domain. If needed, you can limit the domains a video can be embedded on from the Stream dashboard.

In the dashboard, you will see a text box by each video labeled `Enter allowed origin domains separated by commas`. If you click on it, you can list the domains that the Stream embed code should be able to be used on.
`

- `*.badtortilla.com` covers `a.badtortilla.com`, `a.b.badtortilla.com` and does not cover `badtortilla.com`
- `example.com` does not cover [www.example.com](http://www.example.com) or any subdomain of example.com
- `localhost` requires a port if it is not being served over HTTP on port 80 or over HTTPS on port 443
- There is no path support - `example.com` covers `example.com/\*`

You can also control embed limitation programmatically using the Stream API. `uid` in the example below refers to the video id.

```bash
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/{video_uid} \
--header "Authorization: Bearer <API_TOKEN>" \
--data "{\"uid\": \"<VIDEO_UID>\", \"allowedOrigins\": [\"example.com\"]}"
```

### Allowed Origins

The Allowed Origins feature lets you specify which origins are allowed for playback. This feature works even if you are using your own video player. When using your own video player, Allowed Origins restricts which domain the HLS/DASH manifests and the video segments can be requested from.

### Signed URLs

Combining signed URLs with embedding restrictions allows you to strongly control how your videos are viewed. This lets you serve only trusted users while preventing the signed URL from being hosted on an unknown site.

---

# Create indexes

URL: https://developers.cloudflare.com/vectorize/best-practices/create-indexes/

import { Render } from "~/components";

Indexes are the "atom" of Vectorize. Vectors are inserted into an index and enable you to query the index for similar vectors for a given input vector.

Creating an index requires three inputs:

- A name, for example `prod-search-index` or `recommendations-idx-dev`.
- The (fixed) [dimension size](#dimensions) of each vector, for example 384 or 1536.
- The (fixed) [distance metric](#distance-metrics) to use for calculating vector similarity.

An index cannot be created using the same name as an index that is currently active on your account. However, an index can be created with a name that belonged to an index that has been deleted.

The configuration of an index cannot be changed after creation.

## Create an index

### wrangler CLI

<Render file="vectorize-wrangler-version" />

<Render file="vectorize-legacy" />

To create an index with `wrangler`:

```sh
npx wrangler vectorize create your-index-name --dimensions=NUM_DIMENSIONS --metric=SELECTED_METRIC
```

To create an index that can accept vector embeddings from Worker's AI's [`@cf/baai/bge-base-en-v1.5`](/workers-ai/models/#text-embeddings) embedding model, which outputs vectors with 768 dimensions, use the following command:

```sh
npx wrangler vectorize create your-index-name --dimensions=768 --metric=cosine
```

### HTTP API

Vectorize also supports creating indexes via [REST API](/api/resources/vectorize/subresources/indexes/methods/create/).

For example, to create an index directly from a Python script:

```py
import requests

url = "https://api.cloudflare.com/client/v4/accounts/{}/vectorize/v2/indexes".format("your-account-id")

headers = {
    "Authorization": "Bearer <your-api-token>"
}

body = {
	"name": "demo-index"
	"description": "some index description",
  "config": {
    "dimensions": 1024,
    "metric": "euclidean"
  },
}

resp = requests.post(url, headers=headers, json=body)

print('Status Code:', resp.status_code)
print('Response JSON:', resp.json())
```

This script should print the response with a status code `201`, along with a JSON response body indicating the creation of an index with the provided configuration.

## Dimensions

Dimensions are determined from the output size of the machine learning (ML) model used to generate them, and are a function of how the model encodes and describes features into a vector embedding.

The number of output dimensions can determine vector search accuracy, search performance (latency), and the overall size of the index. Smaller output dimensions can be faster to search across, which can be useful for user-facing applications. Larger output dimensions can provide more accurate search, especially over larger datasets and/or datasets with substantially similar inputs.

The number of dimensions an index is created for cannot change. Indexes expect to receive dense vectors with the same number of dimensions.

The following table highlights some example embeddings models and their output dimensions:

| Model / Embeddings API                   | Output dimensions | Use-case                   |
| ---------------------------------------- | ----------------- | -------------------------- |
| Workers AI - `@cf/baai/bge-base-en-v1.5` | 768               | Text                       |
| OpenAI - `ada-002`                       | 1536              | Text                       |
| Cohere - `embed-multilingual-v2.0`       | 768               | Text                       |
| Google Cloud - `multimodalembedding`     | 1408              | Multi-modal (text, images) |

:::note[Learn more about Workers AI]

Refer to the [Workers AI documentation](/workers-ai/models/#text-embeddings) to learn about its built-in embedding models.
:::

## Distance metrics

Distance metrics are functions that determine how close vectors are from each other. Vectorize indexes support the following distance metrics:

| Metric        | Details                                                                                                                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cosine`      | Distance is measured between `-1` (most dissimilar) to `1` (identical). `0` denotes an orthogonal vector.                                                                                          |
| `euclidean`   | Euclidean (L2) distance. `0` denotes identical vectors. The larger the positive number, the further the vectors are apart.                                                                         |
| `dot-product` | Negative dot product. Larger negative values _or_ smaller positive values denote more similar vectors. A score of `-1000` is more similar than `-500`, and a score of `15` more similar than `50`. |

Determining the similarity between vectors can be subjective based on how the machine-learning model that represents features in the resulting vector embeddings. For example, a score of `0.8511` when using a `cosine` metric means that two vectors are close in distance, but whether data they represent is _similar_ is a function of how well the model is able to represent the original content.

When querying vectors, you can specify Vectorize to use either:

- High-precision scoring, which increases the precision of the query matches scores as well as the accuracy of the query results.
- Approximate scoring for faster response times. Using approximate scoring, returned scores will be an approximation of the real distance/similarity between your query and the returned vectors. Refer to [Control over scoring precision and query accuracy](/vectorize/best-practices/query-vectors/#control-over-scoring-precision-and-query-accuracy).

Distance metrics cannot be changed after index creation, and that each metric has a different scoring function.

---

# Best practices

URL: https://developers.cloudflare.com/vectorize/best-practices/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Insert vectors

URL: https://developers.cloudflare.com/vectorize/best-practices/insert-vectors/

import { Render } from "~/components";

Vectorize indexes allow you to insert vectors at any point: Vectorize will optimize the index behind the scenes to ensure that vector search remains efficient, even as new vectors are added or existing vectors updated.

:::note[Insert vs Upsert]

If the same vector id is _inserted_ twice in a Vectorize index, the index would reflect the vector that was added first.

If the same vector id is _upserted_ twice in a Vectorize index, the index would reflect the vector that was added last.

Use the upsert operation if you want to overwrite the vector value for a vector id that already exists in an index.

:::

## Supported vector formats

Vectorize supports vectors in three formats:

- An array of floating point numbers (converted into a JavaScript `number[]` array).
- A [Float32Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array)
- A [Float64Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array)

In most cases, a `number[]` array is the easiest when dealing with other APIs, and is the return type of most machine-learning APIs.

## Metadata

Metadata is an optional set of key-value pairs that can be attached to a vector on insert or upsert, and allows you to embed or co-locate data about the vector itself.

Metadata keys cannot be empty, contain the dot character (`.`), contain the double-quote character (`"`), or start with the dollar character (`$`).

Metadata can be used to:

- Include the object storage key, database UUID or other identifier to look up the content the vector embedding represents.
- Store JSON data (up to the [metadata limits](/vectorize/platform/limits/)), which can allow you to skip additional lookups for smaller content.
- Keep track of dates, timestamps, or other metadata that describes when the vector embedding was generated or how it was generated.

For example, a vector embedding representing an image could include the path to the [R2 object](/r2/) it was generated from, the format, and a category lookup:

```ts
{ id: '1', values: [32.4, 74.1, 3.2, ...], metadata: { path: 'r2://bucket-name/path/to/image.png', format: 'png', category: 'profile_image' } }
```

### Performance Tips When Filtering by Metadata

When creating metadata indexes for a large Vectorize index, we encourage users to think ahead and plan how they will query for vectors with filters on this metadata.

Carefully consider the cardinality of metadata values in relation to your queries. Cardinality is the level of uniqueness of data values within a set. Low cardinality means there are only a few unique values: for instance, the number of planets in the Solar System; the number of countries in the world. High cardinality means there are many unique values: UUIv4 strings; timestamps with millisecond precision.

High cardinality is good for the selectiveness of the equal (`$eq`) filter. For example, if you want to find vectors associated with one user's id. But the filter is not going to help if all vectors have the same value. That's an example of extreme low cardinality.

High cardinality can also impact range queries, which searches across multiple unqiue metadata values. For example, an indexed metadata value using millisecond timestamps will see lower performance if the range spans long periods of time in which thousands of vectors with unique timestamps were written.

Behind the scenes, Vectorize uses a reverse index to map values to vector ids. If the number of unique values in a particular range is too high, then that requires reading large portions of the index (a full index scan in the worst case). This would lead to memory issues, so Vectorize will degrade performance and the accuracy of the query in order to finish the request.

One approach for high cardinality data is to somehow create buckets where more vectors get grouped to the same value. Continuing the millisecond timestamp example, let's imagine we typically filter with date ranges that have 5 minute increments of granularity. We could use a timestamp which is rounded down to the last 5 minute point. This "windows" our metadata values into 5 minute increments. And we can still store the original millisecond timestamp as a separate non-indexed field.

## Namespaces

Namespaces provide a way to segment the vectors within your index. For example, by customer, merchant or store ID.

To associate vectors with a namespace, you can optionally provide a `namespace: string` value when performing an insert or upsert operation. When querying, you can pass the namespace to search within as an optional parameter to your query.

A namespace can be up to 64 characters (bytes) in length and you can have up to 1,000 namespaces per index. Refer to the [Limits](/vectorize/platform/limits/) documentation for more details.

When a namespace is specified in a query operation, only vectors within that namespace are used for the search. Namespace filtering is applied before vector search, increasing the precision of the matched results.

To insert vectors with a namespace:

```ts
// Mock vectors
// 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, ...],
		namespace: "text",
	},
	{
		id: "2",
		values: [15.1, 19.2, 15.8, ...],
		namespace: "images",
	},
	{
		id: "3",
		values: [0.16, 1.2, 3.8, ...],
		namespace: "pdfs",
	},
];

// Insert your vectors, returning a count of the vectors inserted and their vector IDs.
let inserted = await env.TUTORIAL_INDEX.insert(sampleVectors);
```

To query vectors within a namespace:

```ts
// Your queryVector will be searched against vectors within the namespace (only)
let matches = await env.TUTORIAL_INDEX.query(queryVector, {
	namespace: "images",
});
```

## Improve Write Throughput

One way to reduce the time to make updates visible in queries is to batch more vectors into fewer requests. This is important for write-heavy workloads. To see how many vectors you can write in a single request, please refer to the [Limits](/vectorize/platform/limits/) page.

Vectorize writes changes immeditely to a write ahead log for durability. To make these writes visible for reads, an asynchronous job needs to read the current index files from R2, create an updated index, write the new index files back to R2, and commit the change. To keep the overhead of writes low and improve write throughput, Vectorize will combine multiple changes together into a single batch. It sets the maximum size of a batch to 200,000 total vectors or to 1,000 individual updates, whichever limit it hits first.

For example, let's say we have 250,000 vectors we would like to insert into our index. We decide to insert them one at a time, calling the insert API 250,000 times. Vectorize will only process 1000 vectors in each job, and will need to work through 250 total jobs. This could take at least an hour to do.

The better approach is to batch our updates. For example, we can split our 250,000 vectors into 100 files, where each file has 2,500 vectors. We would call the insert HTTP API 100 times. Vectorize would update the index in only 2 or 3 jobs. All 250,000 vectors will visible in queries within minutes.

## Examples

### Workers API

Use the `insert()` and `upsert()` methods available on an index from within a Cloudflare Worker to insert vectors into the current index.

```ts
// Mock vectors
// 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" },
	},
];

// Insert your vectors, returning a count of the vectors inserted and their vector IDs.
let inserted = await env.TUTORIAL_INDEX.insert(sampleVectors);
```

Refer to [Vectorize API](/vectorize/reference/client-api/) for additional examples.

### wrangler CLI

:::note[Cloudflare API rate limit]

Please use a maximum of 5000 vectors per embeddings.ndjson file to prevent the global [rate limit](/fundamentals/api/reference/limits/) for the Cloudflare API.

:::

You can bulk upload vector embeddings directly:

- The file must be in newline-delimited JSON (NDJSON format): each complete vector must be newline separated, and not within an array or object.
- Vectors must be complete and include a unique string `id` per vector.

An example NDJSON formatted file:

```json
{ "id": "4444", "values": [175.1, 167.1, 129.9], "metadata": {"url": "/products/sku/918318313"}}
{ "id": "5555", "values": [158.8, 116.7, 311.4], "metadata": {"url": "/products/sku/183183183"}}
{ "id": "6666", "values": [113.2, 67.5, 11.2], "metadata": {"url": "/products/sku/717313811"}}
```

<Render file="vectorize-wrangler-version" />

```sh
wrangler vectorize insert <your-index-name> --file=embeddings.ndjson
```

### HTTP API

Vectorize also supports inserting vectors via the [REST API](/api/resources/vectorize/subresources/indexes/methods/insert/), which allows you to operate on a Vectorize index from existing machine-learning tooling and languages (including Python).

For example, to insert embeddings in [NDJSON format](#workers-api) directly from a Python script:

```py
import requests

url = "https://api.cloudflare.com/client/v4/accounts/{}/vectorize/v2/indexes/{}/insert".format("your-account-id", "index-name")

headers = {
    "Authorization": "Bearer <your-api-token>"
}

with open('embeddings.ndjson', 'rb') as embeddings:
    resp = requests.post(url, headers=headers, files=dict(vectors=embeddings))
    print(resp)
```

This code would insert the vectors defined in `embeddings.ndjson` into the provided index. Python libraries, including Pandas, also support the NDJSON format via the built-in `read_json` method:

```py
import pandas as pd
data = pd.read_json('embeddings.ndjson', lines=True)
```

---

# Query vectors

URL: https://developers.cloudflare.com/vectorize/best-practices/query-vectors/

Querying an index, or vector search, enables you to search an index by providing an input vector and returning the nearest vectors based on the [configured distance metric](/vectorize/best-practices/create-indexes/#distance-metrics).

Optionally, you can apply [metadata filters](/vectorize/reference/metadata-filtering/) or a [namespace](/vectorize/best-practices/insert-vectors/#namespaces) to narrow the vector search space.

## Example query

To pass a vector as a query to an index, use the `query()` method on the index itself.

A query vector is either an array of JavaScript numbers, 32-bit floating point or 64-bit floating point numbers: `number[]`, `Float32Array`, or `Float64Array`. Unlike when [inserting vectors](/vectorize/best-practices/insert-vectors/), a query vector does not need an ID or metadata.

```ts
// query vector dimensions must match the Vectorize index dimension being queried
let queryVector = [54.8, 5.5, 3.1, ...];
let matches = await env.YOUR_INDEX.query(queryVector);
```

This would return a set of matches resembling the following, based on the distance metric configured for the Vectorize index. Example response with `cosine` distance metric:

```json
{
	"count": 5,
	"matches": [
		{ "score": 0.999909486, "id": "5" },
		{ "score": 0.789848214, "id": "4" },
		{ "score": 0.720476967, "id": "4444" },
		{ "score": 0.463884663, "id": "6" },
		{ "score": 0.378282232, "id": "1" }
	]
}
```

You can optionally change the number of results returned and/or whether results should include metadata and values:

```ts
// query vector dimensions must match the Vectorize index dimension being queried
let queryVector = [54.8, 5.5, 3.1, ...];
// topK defaults to 5; returnValues defaults to false; returnMetadata defaults to "none"
let matches = await env.YOUR_INDEX.query(queryVector, {
	topK: 1,
	returnValues: true,
	returnMetadata: "all",
});
```

This would return a set of matches resembling the following, based on the distance metric configured for the Vectorize index. Example response with `cosine` distance metric:

```json
{
	"count": 1,
	"matches": [
		{
			"score": 0.999909486,
			"id": "5",
			"values": [58.79999923706055, 6.699999809265137, 3.4000000953674316, ...],
			"metadata": { "url": "/products/sku/55519183" }
		}
	]
}
```

Refer to [Vectorize API](/vectorize/reference/client-api/) for additional examples.

## Query by vector identifier

Vectorize now offers the ability to search for vectors similar to a vector that is already present in the index using the `queryById()` operation. This can be considered as a single operation that combines the `getById()` and the `query()` operation.

```ts
// the query operation would yield results if a vector with id `some-vector-id` is already present in the index.
let matches = await env.YOUR_INDEX.queryById("some-vector-id");
```

## Control over scoring precision and query accuracy

When querying vectors, you can specify to either use high-precision scoring, thereby increasing the precision of the query matches scores as well as the accuracy of the query results, or use approximate scoring for faster response times.
Using approximate scoring, returned scores will be an approximation of the real distance/similarity between your query and the returned vectors; this is the query's default as it's a nice trade-off between accuracy and latency.

High-precision scoring is enabled by setting `returnValues: true` on your query. This setting tells Vectorize to use the original vector values for your matches, allowing the computation of exact match scores and increasing the accuracy of the results. Because it processes more data, though, high-precision scoring will increase the latency of queries.

## Workers AI

If you are generating embeddings from a [Workers AI](/workers-ai/models/#text-embeddings) text embedding model, the response type from `env.AI.run()` is an object that includes both the `shape` of the response vector - e.g. `[1,768]` - and the vector `data` as an array of vectors:

```ts
interface EmbeddingResponse {
	shape: number[];
	data: number[][];
}

let userQuery = "a query from a user or service";
const queryVector: EmbeddingResponse = await env.AI.run(
	"@cf/baai/bge-base-en-v1.5",
	{
		text: [userQuery],
	},
);
```

When passing the vector to the `query()` method of a Vectorize index, pass only the vector embedding itself on the `.data` sub-object, and not the top-level response.

For example:

```ts
let matches = await env.TEXT_EMBEDDINGS.query(queryVector.data[0], { topK: 1 });
```

Passing `queryVector` or `queryVector.data` will cause `query()` to return an error.

## OpenAI

When using OpenAI's [JavaScript client API](https://github.com/openai/openai-node) and [Embeddings API](https://platform.openai.com/docs/guides/embeddings/what-are-embeddings), the response type from `embeddings.create` is an object that includes the model, usage information and the requested vector embedding.

```ts
const openai = new OpenAI({ apiKey: env.YOUR_OPENAPI_KEY });

let userQuery = "a query from a user or service";

let embeddingResponse = await openai.embeddings.create({
	input: userQuery,
	model: "text-embedding-ada-002",
});
```

Similar to Workers AI, you will need to provide the vector embedding itself (`.embedding[0]`) and not the `EmbeddingResponse` wrapper when querying a Vectorize index:

```ts
let matches = await env.TEXT_EMBEDDINGS.query(embeddingResponse.embedding[0], {
	topK: 1,
});
```

---

# Vectorize and Workers AI

URL: https://developers.cloudflare.com/vectorize/get-started/embeddings/

import { Render, PackageManagers, WranglerConfig } from "~/components";

<Render file="vectorize-ga" />

Vectorize allows you to generate [vector embeddings](/vectorize/reference/what-is-a-vector-database/) using a machine-learning model, including the models available in [Workers AI](/workers-ai/).

:::note[New to Vectorize?]

If this is your first time using Vectorize or a vector database, start with the [Vectorize Get started guide](/vectorize/get-started/intro/).

:::

This guide will instruct you through:

- Creating a Vectorize index.
- Connecting a [Cloudflare Worker](/workers/) to your index.
- Using [Workers AI](/workers-ai/) to generate vector embeddings.
- Using Vectorize to query those vector embeddings.

## Prerequisites

To continue:

1. Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages) if you have not already.
2. Install [`npm`](https://docs.npmjs.com/getting-started).
3. Install [`Node.js`](https://nodejs.org/en/). Use a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change Node.js versions. [Wrangler](/workers/wrangler/install-and-update/) requires a Node version of `16.17.0` or later.

## 1. Create a Worker

You will create a new project that will contain a Worker script, which will act as the client application for your Vectorize index.

Open your terminal and create a new project named `embeddings-tutorial` by running the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"embeddings-tutorial"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

This will create a new `embeddings-tutorial` directory. Your new `embeddings-tutorial` directory will include:

- A `"Hello World"` [Worker](/workers/get-started/guide/#3-write-code) at `src/index.ts`.
- A [`wrangler.jsonc`](/workers/wrangler/configuration/) configuration file. `wrangler.jsonc` is how your `embeddings-tutorial` Worker will access your index.

:::note

If you are familiar with Cloudflare Workers, or initializing projects in a Continuous Integration (CI) environment, initialize a new project non-interactively by setting `CI=true` as an [environmental variable](/workers/configuration/environment-variables/) when running `create cloudflare@latest`.

For example: `CI=true npm create cloudflare@latest embeddings-tutorial --type=simple --git --ts --deploy=false` will create a basic "Hello World" project ready to build on.

:::

## 2. Create an index

A vector database is distinct from a traditional SQL or NoSQL database. A vector database is designed to store vector embeddings, which are representations of data, but not the original data itself.

To create your first Vectorize index, change into the directory you just created for your Workers project:

```sh
cd embeddings-tutorial
```

<Render file="vectorize-legacy" />

To create an index, use the `wrangler vectorize create` command and provide a name for the index. A good index name is:

- A combination of lowercase and/or numeric ASCII characters, shorter than 32 characters, starts with a letter, and uses dashes (-) instead of spaces.
- Descriptive of the use-case and environment. For example, "production-doc-search" or "dev-recommendation-engine".
- Only used for describing the index, and is not directly referenced in code.

In addition, define both the `dimensions` of the vectors you will store in the index, as well as the distance `metric` used to determine similar vectors when creating the index. **This configuration cannot be changed later**, as a vector database is configured for a fixed vector configuration.

<Render file="vectorize-wrangler-version" />

Run the following `wrangler vectorize` command, ensuring that the `dimensions` are set to `768`: this is important, as the Workers AI model used in this tutorial outputs vectors with 768 dimensions.

```sh
npx wrangler vectorize create embeddings-index --dimensions=768 --metric=cosine
```

```sh output
✅ Successfully created index 'embeddings-index'

[[vectorize]]
binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
index_name = "embeddings-index"
```

This will create a new vector database, and output the [binding](/workers/runtime-apis/bindings/) configuration needed in the next step.

## 3. Bind your Worker to your index

You must create a binding for your Worker to connect to your Vectorize index. [Bindings](/workers/runtime-apis/bindings/) allow your Workers to access resources, like Vectorize or R2, from Cloudflare Workers. You create bindings by updating your Wrangler file.

To bind your index to your Worker, add the following to the end of your Wrangler file:

<WranglerConfig>

```toml
[[vectorize]]
binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
index_name = "embeddings-index"
```

</WranglerConfig>

Specifically:

- The value (string) you set for `<BINDING_NAME>` will be used to reference this database in your Worker. In this tutorial, name your binding `VECTORIZE`.
- The binding must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). For example, `binding = "MY_INDEX"` or `binding = "PROD_SEARCH_INDEX"` would both be valid names for the binding.
- Your binding is available in your Worker at `env.<BINDING_NAME>` and the Vectorize [client API](/vectorize/reference/client-api/) is exposed on this binding for use within your Workers application.

## 4. Set up Workers AI

Before you deploy your embedding example, ensure your Worker uses your model catalog, including the [text embedding model](/workers-ai/models/#text-embeddings) built-in.

From within the `embeddings-tutorial` directory, open your Wrangler file in your editor and add the new `[[ai]]` binding to make Workers AI's models available in your Worker:

<WranglerConfig>

```toml
[[vectorize]]
binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
index_name = "embeddings-index"

[ai]
binding = "AI" # available in your Worker on env.AI
```

</WranglerConfig>

With Workers AI ready, you can write code in your Worker.

## 5. Write code in your Worker

To write code in your Worker, go to your `embeddings-tutorial` Worker and open the `src/index.ts` file. The `index.ts` file is where you configure your Worker's interactions with your Vectorize index.

Clear the content of `index.ts`. Paste the following code snippet into your `index.ts` file. On the `env` parameter, replace `<BINDING_NAME>` with `VECTORIZE`:

```typescript
export interface Env {
	VECTORIZE: Vectorize;
	AI: Ai;
}
interface EmbeddingResponse {
	shape: number[];
	data: number[][];
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		let path = new URL(request.url).pathname;
		if (path.startsWith("/favicon")) {
			return new Response("", { status: 404 });
		}

		// You only need to generate vector embeddings once (or as
		// data changes), not on every request
		if (path === "/insert") {
			// In a real-world application, you could read content from R2 or
			// a SQL database (like D1) and pass it to Workers AI
			const stories = [
				"This is a story about an orange cloud",
				"This is a story about a llama",
				"This is a story about a hugging emoji",
			];
			const modelResp: EmbeddingResponse = await env.AI.run(
				"@cf/baai/bge-base-en-v1.5",
				{
					text: stories,
				},
			);

			// Convert the vector embeddings into a format Vectorize can accept.
			// Each vector needs an ID, a value (the vector) and optional metadata.
			// In a real application, your ID would be bound to the ID of the source
			// document.
			let vectors: VectorizeVector[] = [];
			let id = 1;
			modelResp.data.forEach((vector) => {
				vectors.push({ id: `${id}`, values: vector });
				id++;
			});

			let inserted = await env.VECTORIZE.upsert(vectors);
			return Response.json(inserted);
		}

		// Your query: expect this to match vector ID. 1 in this example
		let userQuery = "orange cloud";
		const queryVector: EmbeddingResponse = await env.AI.run(
			"@cf/baai/bge-base-en-v1.5",
			{
				text: [userQuery],
			},
		);

		let matches = await env.VECTORIZE.query(queryVector.data[0], {
			topK: 1,
		});
		return Response.json({
			// Expect a vector ID. 1 to be your top match with a score of
			// ~0.89693683
			// This tutorial uses a cosine distance metric, where the closer to one,
			// the more similar.
			matches: matches,
		});
	},
} satisfies ExportedHandler<Env>;
```

## 6. Deploy your Worker

Before deploying your Worker globally, log in with your Cloudflare account by running:

```sh
npx wrangler login
```

You will be directed to a web page asking you to log in to the Cloudflare dashboard. After you have logged in, you will be asked if Wrangler can make changes to your Cloudflare account. Scroll down and select **Allow** to continue.

From here, deploy your Worker to make your project accessible on the Internet. To deploy your Worker, run:

```sh
npx wrangler deploy
```

Preview your Worker at `https://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.dev`.

## 7. Query your index

You can now visit the URL for your newly created project to insert vectors and then query them.

With the URL for your deployed Worker (for example,`https://embeddings-tutorial.<YOUR_SUBDOMAIN>.workers.dev/`), open your browser and:

1. Insert your vectors first by visiting `/insert`.
2. Query your index by visiting the index route - `/`.

This should return the following JSON:

```json
{
	"matches": {
		"count": 1,
		"matches": [
			{
				"id": "1",
				"score": 0.89693683
			}
		]
	}
}
```

Extend this example by:

- Adding more inputs and generating a larger set of vectors.
- Accepting a custom query parameter passed in the URL, for example via `URL.searchParams`.
- Creating a new index with a different [distance metric](/vectorize/best-practices/create-indexes/#distance-metrics) and observing how your scores change in response to your inputs.

By finishing this tutorial, you have successfully created a Vectorize index, used Workers AI to generate vector embeddings, and deployed your project globally.

## Next steps

- Build a [generative AI chatbot](/workers-ai/guides/tutorials/build-a-retrieval-augmented-generation-ai/) using Workers AI and Vectorize.
- Learn more about [how vector databases work](/vectorize/reference/what-is-a-vector-database/).
- Read [examples](/vectorize/reference/client-api/) on how to use the Vectorize API from Cloudflare Workers.

---

# Get started

URL: https://developers.cloudflare.com/vectorize/get-started/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Introduction to Vectorize

URL: https://developers.cloudflare.com/vectorize/get-started/intro/

import { Render, PackageManagers, WranglerConfig } from "~/components";

<Render file="vectorize-ga" />

Vectorize is Cloudflare's vector database. Vector databases allow you to use machine learning (ML) models to perform semantic search, recommendation, classification and anomaly detection tasks, as well as provide context to LLMs (Large Language Models).

This guide will instruct you through:

- Creating your first Vectorize index.
- Connecting a [Cloudflare Worker](/workers/) to your index.
- Inserting and performing a similarity search by querying your index.

## Prerequisites

:::note[Workers Free or Paid plans required]

Vectorize is available to all users on the [Workers Free or Paid plans](/workers/platform/pricing/#workers).

:::

To continue, you will need:

1. Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages) if you have not already.
2. Install [`npm`](https://docs.npmjs.com/getting-started).
3. Install [`Node.js`](https://nodejs.org/en/). Use a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change Node.js versions. [Wrangler](/workers/wrangler/install-and-update/) requires a Node version of `16.17.0` or later.

## 1. Create a Worker

:::note[New to Workers?]

Refer to [How Workers works](/workers/reference/how-workers-works/) to learn about the Workers serverless execution model works. Go to the [Workers Get started guide](/workers/get-started/guide/) to set up your first Worker.

:::

You will create a new project that will contain a Worker, which will act as the client application for your Vectorize index.

Create a new project named `vectorize-tutorial` by running:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"vectorize-tutorial"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

This will create a new `vectorize-tutorial` directory. Your new `vectorize-tutorial` directory will include:

- A `"Hello World"` [Worker](/workers/get-started/guide/#3-write-code) at `src/index.ts`.
- A [`wrangler.jsonc`](/workers/wrangler/configuration/) configuration file. `wrangler.jsonc` is how your `vectorize-tutorial` Worker will access your index.

:::note

If you are familiar with Cloudflare Workers, or initializing projects in a Continuous Integration (CI) environment, initialize a new project non-interactively by setting `CI=true` as an [environmental variable](/workers/configuration/environment-variables/) when running `create cloudflare@latest`.

For example: `CI=true npm create cloudflare@latest vectorize-tutorial --type=simple --git --ts --deploy=false` will create a basic "Hello World" project ready to build on.

:::

## 2. Create an index

A vector database is distinct from a traditional SQL or NoSQL database. A vector database is designed to store vector embeddings, which are representations of data, but not the original data itself.

To create your first Vectorize index, change into the directory you just created for your Workers project:

```sh
cd vectorize-tutorial
```

<Render file="vectorize-legacy" />

To create an index, you will need to use the `wrangler vectorize create` command and provide a name for the index. A good index name is:

- A combination of lowercase and/or numeric ASCII characters, shorter than 32 characters, starts with a letter, and uses dashes (-) instead of spaces.
- Descriptive of the use-case and environment. For example, "production-doc-search" or "dev-recommendation-engine".
- Only used for describing the index, and is not directly referenced in code.

In addition, you will need to define both the `dimensions` of the vectors you will store in the index, as well as the distance `metric` used to determine similar vectors when creating the index. A `metric` can be euclidean, cosine, or dot product. **This configuration cannot be changed later**, as a vector database is configured for a fixed vector configuration.

<Render file="vectorize-wrangler-version" />

Run the following `wrangler vectorize` command:

```sh
npx wrangler vectorize create tutorial-index --dimensions=32 --metric=euclidean
```

```sh output
🚧 Creating index: 'tutorial-index'
✅ Successfully created a new Vectorize index: 'tutorial-index'
📋 To start querying from a Worker, add the following binding configuration into 'wrangler.toml':

[[vectorize]]
binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
index_name = "tutorial-index"
```

The command above will create a new vector database, and output the [binding](/workers/runtime-apis/bindings/) configuration needed in the next step.

## 3. Bind your Worker to your index

You must create a binding for your Worker to connect to your Vectorize index. [Bindings](/workers/runtime-apis/bindings/) allow your Workers to access resources, like Vectorize or R2, from Cloudflare Workers. You create bindings by updating the worker's Wrangler file.

To bind your index to your Worker, add the following to the end of your Wrangler file:

<WranglerConfig>

```toml
[[vectorize]]
binding = "VECTORIZE" # available in your Worker on env.VECTORIZE
index_name = "tutorial-index"
```

</WranglerConfig>

Specifically:

- The value (string) you set for `<BINDING_NAME>` will be used to reference this database in your Worker. In this tutorial, name your binding `VECTORIZE`.
- The binding must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). For example, `binding = "MY_INDEX"` or `binding = "PROD_SEARCH_INDEX"` would both be valid names for the binding.
- Your binding is available in your Worker at `env.<BINDING_NAME>` and the Vectorize [client API](/vectorize/reference/client-api/) is exposed on this binding for use within your Workers application.

## 4. [Optional] Create metadata indexes

Vectorize allows you to add up to 10KiB of metadata per vector into your index, and also provides the ability to filter on that metadata while querying vectors. To do so you would need to specify a metadata field as a "metadata index" for your Vectorize index.

:::note[When to create metadata indexes?]

As of today, the metadata fields on which vectors can be filtered need to be specified before the vectors are inserted, and it is recommended that these metadata fields are specified right after the creation of a Vectorize index.

:::

To enable vector filtering on a metadata field during a query, use a command like:

```sh
npx wrangler vectorize create-metadata-index tutorial-index --property-name=url --type=string
```

```sh output
📋 Creating metadata index...
✅ Successfully enqueued metadata index creation request. Mutation changeset identifier: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
```

Here `url` is the metadata field on which filtering would be enabled. The `--type` parameter defines the data type for the metadata field; `string`, `number` and `boolean` types are supported.

It typically takes a few seconds for the metadata index to be created. You can check the list of metadata indexes for your Vectorize index by running:

```sh
npx wrangler vectorize list-metadata-index tutorial-index
```

```sh output
📋 Fetching metadata indexes...
┌──────────────┬────────┐
│ propertyName │ type   │
├──────────────┼────────┤
│ url          │ String │
└──────────────┴────────┘
```

You can create up to 10 metadata indexes per Vectorize index.

For metadata indexes of type `number`, the indexed number precision is that of float64.

For metadata indexes of type `string`, each vector indexes the first 64B of the string data truncated on UTF-8 character boundaries to the longest well-formed UTF-8 substring within that limit, so vectors are filterable on the first 64B of their value for each indexed property.

See [Vectorize Limits](/vectorize/platform/limits/) for a complete list of limits.

## 5. Insert vectors

Before you can query a vector database, you need to insert vectors for it to query against. These vectors would be generated from data (such as text or images) you pass to a machine learning model. However, this tutorial will define static vectors to illustrate how vector search works on its own.

First, go to your `vectorize-tutorial` Worker and open the `src/index.ts` file. The `index.ts` file is where you configure your Worker's interactions with your Vectorize index.

Clear the content of `index.ts`, and paste the following code snippet into your `index.ts` file. On the `env` parameter, replace `<BINDING_NAME>` with `VECTORIZE`:

```typescript
export interface Env {
	// This makes your vector index methods available on env.VECTORIZE.*
	// For example, env.VECTORIZE.insert() or query()
	VECTORIZE: Vectorize;
}

// Sample vectors: 32 dimensions wide.
//
// Vectors from popular machine-learning models are typically ~100 to 1536 dimensions
// wide (or wider still).
const sampleVectors: Array<VectorizeVector> = [
	{
		id: "1",
		values: [
			0.12, 0.45, 0.67, 0.89, 0.23, 0.56, 0.34, 0.78, 0.12, 0.9, 0.24, 0.67,
			0.89, 0.35, 0.48, 0.7, 0.22, 0.58, 0.74, 0.33, 0.88, 0.66, 0.45, 0.27,
			0.81, 0.54, 0.39, 0.76, 0.41, 0.29, 0.83, 0.55,
		],
		metadata: { url: "/products/sku/13913913" },
	},
	{
		id: "2",
		values: [
			0.14, 0.23, 0.36, 0.51, 0.62, 0.47, 0.59, 0.74, 0.33, 0.89, 0.41, 0.53,
			0.68, 0.29, 0.77, 0.45, 0.24, 0.66, 0.71, 0.34, 0.86, 0.57, 0.62, 0.48,
			0.78, 0.52, 0.37, 0.61, 0.69, 0.28, 0.8, 0.53,
		],
		metadata: { url: "/products/sku/10148191" },
	},
	{
		id: "3",
		values: [
			0.21, 0.33, 0.55, 0.67, 0.8, 0.22, 0.47, 0.63, 0.31, 0.74, 0.35, 0.53,
			0.68, 0.45, 0.55, 0.7, 0.28, 0.64, 0.71, 0.3, 0.77, 0.6, 0.43, 0.39, 0.85,
			0.55, 0.31, 0.69, 0.52, 0.29, 0.72, 0.48,
		],
		metadata: { url: "/products/sku/97913813" },
	},
	{
		id: "4",
		values: [
			0.17, 0.29, 0.42, 0.57, 0.64, 0.38, 0.51, 0.72, 0.22, 0.85, 0.39, 0.66,
			0.74, 0.32, 0.53, 0.48, 0.21, 0.69, 0.77, 0.34, 0.8, 0.55, 0.41, 0.29,
			0.7, 0.62, 0.35, 0.68, 0.53, 0.3, 0.79, 0.49,
		],
		metadata: { url: "/products/sku/418313" },
	},
	{
		id: "5",
		values: [
			0.11, 0.46, 0.68, 0.82, 0.27, 0.57, 0.39, 0.75, 0.16, 0.92, 0.28, 0.61,
			0.85, 0.4, 0.49, 0.67, 0.19, 0.58, 0.76, 0.37, 0.83, 0.64, 0.53, 0.3,
			0.77, 0.54, 0.43, 0.71, 0.36, 0.26, 0.8, 0.53,
		],
		metadata: { url: "/products/sku/55519183" },
	},
];

export default {
	async fetch(request, env, ctx): Promise<Response> {
		let path = new URL(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.
			const inserted = await env.VECTORIZE.insert(sampleVectors);

			// Return the mutation identifier for this insert operation
			return Response.json(inserted);
		}

		return Response.json({ text: "nothing to do... yet" }, { status: 404 });
	},
} satisfies ExportedHandler<Env>;
```

In the code above, you:

1. Define a binding to your Vectorize index from your Workers code. This binding matches the `binding` value you set in the `wrangler.jsonc` file under the `"vectorise"` key.
2. Specify a set of example vectors that you will query against in the next step.
3. Insert those vectors into the index and confirm it was successful.

In the next step, you will expand the Worker to query the index and the vectors you insert.

## 6. Query vectors

In this step, you will take a vector representing an incoming query and use it to search your index.

First, go to your `vectorize-tutorial` Worker and open the `src/index.ts` file. The `index.ts` file is where you configure your Worker's interactions with your Vectorize index.

Clear the content of `index.ts`. Paste the following code snippet into your `index.ts` file. On the `env` parameter, replace `<BINDING_NAME>` with `VECTORIZE`:

```typescript
export interface Env {
	// This makes your vector index methods available on env.VECTORIZE.*
	// For example, env.VECTORIZE.insert() or query()
	VECTORIZE: Vectorize;
}

// Sample vectors: 32 dimensions wide.
//
// Vectors from popular machine-learning models are typically ~100 to 1536 dimensions
// wide (or wider still).
const sampleVectors: Array<VectorizeVector> = [
	{
		id: "1",
		values: [
			0.12, 0.45, 0.67, 0.89, 0.23, 0.56, 0.34, 0.78, 0.12, 0.9, 0.24, 0.67,
			0.89, 0.35, 0.48, 0.7, 0.22, 0.58, 0.74, 0.33, 0.88, 0.66, 0.45, 0.27,
			0.81, 0.54, 0.39, 0.76, 0.41, 0.29, 0.83, 0.55,
		],
		metadata: { url: "/products/sku/13913913" },
	},
	{
		id: "2",
		values: [
			0.14, 0.23, 0.36, 0.51, 0.62, 0.47, 0.59, 0.74, 0.33, 0.89, 0.41, 0.53,
			0.68, 0.29, 0.77, 0.45, 0.24, 0.66, 0.71, 0.34, 0.86, 0.57, 0.62, 0.48,
			0.78, 0.52, 0.37, 0.61, 0.69, 0.28, 0.8, 0.53,
		],
		metadata: { url: "/products/sku/10148191" },
	},
	{
		id: "3",
		values: [
			0.21, 0.33, 0.55, 0.67, 0.8, 0.22, 0.47, 0.63, 0.31, 0.74, 0.35, 0.53,
			0.68, 0.45, 0.55, 0.7, 0.28, 0.64, 0.71, 0.3, 0.77, 0.6, 0.43, 0.39, 0.85,
			0.55, 0.31, 0.69, 0.52, 0.29, 0.72, 0.48,
		],
		metadata: { url: "/products/sku/97913813" },
	},
	{
		id: "4",
		values: [
			0.17, 0.29, 0.42, 0.57, 0.64, 0.38, 0.51, 0.72, 0.22, 0.85, 0.39, 0.66,
			0.74, 0.32, 0.53, 0.48, 0.21, 0.69, 0.77, 0.34, 0.8, 0.55, 0.41, 0.29,
			0.7, 0.62, 0.35, 0.68, 0.53, 0.3, 0.79, 0.49,
		],
		metadata: { url: "/products/sku/418313" },
	},
	{
		id: "5",
		values: [
			0.11, 0.46, 0.68, 0.82, 0.27, 0.57, 0.39, 0.75, 0.16, 0.92, 0.28, 0.61,
			0.85, 0.4, 0.49, 0.67, 0.19, 0.58, 0.76, 0.37, 0.83, 0.64, 0.53, 0.3,
			0.77, 0.54, 0.43, 0.71, 0.36, 0.26, 0.8, 0.53,
		],
		metadata: { url: "/products/sku/55519183" },
	},
];

export default {
	async fetch(request, env, ctx): Promise<Response> {
		let path = new URL(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 env.VECTORIZE.insert(sampleVectors);

			// Return the mutation identifier for this insert operation
			return Response.json(inserted);
		}

		// return Response.json({text: "nothing to do... yet"}, { status: 404 })

		// In a real application, you would take a user query. For example, "what is a
		// vector database" - and transform it into a vector embedding first.
		//
		// In this example, you will construct a vector that should
		// match vector id #4
		const queryVector: Array<number> = [
			0.13, 0.25, 0.44, 0.53, 0.62, 0.41, 0.59, 0.68, 0.29, 0.82, 0.37, 0.5,
			0.74, 0.46, 0.57, 0.64, 0.28, 0.61, 0.73, 0.35, 0.78, 0.58, 0.42, 0.32,
			0.77, 0.65, 0.49, 0.54, 0.31, 0.29, 0.71, 0.57,
		]; // vector of dimensions 32

		// Query your index and return the three (topK = 3) most similar vector
		// IDs with their similarity score.
		//
		// By default, vector values are not returned, as in many cases the
		// vector id and scores are sufficient to map the vector back to the
		// original content it represents.
		const matches = await env.VECTORIZE.query(queryVector, {
			topK: 3,
			returnValues: true,
			returnMetadata: "all",
		});

		return Response.json({
			// This will return the closest vectors: the vectors are arranged according
			// to their scores. Vectors that are more similar would show up near the top.
			// In this example, Vector id #4 would turn out to be the most similar to the queried vector.
			// You return the full set of matches so you can check the possible scores.
			matches: matches,
		});
	},
} satisfies ExportedHandler<Env>;
```

You can also use the Vectorize `queryById()` operation to search for vectors similar to a vector that is already present in the index.

## 7. Deploy your Worker

Before deploying your Worker globally, log in with your Cloudflare account by running:

```sh
npx wrangler login
```

You will be directed to a web page asking you to log in to the Cloudflare dashboard. After you have logged in, you will be asked if Wrangler can make changes to your Cloudflare account. Scroll down and select **Allow** to continue.

From here, you can deploy your Worker to make your project accessible on the Internet. To deploy your Worker, run:

```sh
npx wrangler deploy
```

Once deployed, preview your Worker at `https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev`.

## 8. Query your index

To insert vectors and then query them, use the URL for your deployed Worker, such as `https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev/`. Open your browser and:

1. Insert your vectors first by visiting `/insert`. This should return the below JSON:

```json
// https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev/insert
{
	"mutationId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

The mutationId here refers to a unique identifier that corresponds to this asynchronous insert operation. Typically it takes a few seconds for inserted vectors to be available for querying.

You can use the index info operation to check the last processed mutation:

```sh
npx wrangler vectorize info tutorial-index
```

```sh output
📋 Fetching index info...
┌────────────┬─────────────┬──────────────────────────────────────┬──────────────────────────┐
│ dimensions │ vectorCount │ processedUpToMutation                │ processedUpToDatetime    │
├────────────┼─────────────┼──────────────────────────────────────┼──────────────────────────┤
│ 32         │ 5           │ xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx │ YYYY-MM-DDThh:mm:ss.SSSZ │
└────────────┴─────────────┴──────────────────────────────────────┴──────────────────────────┘
```

Subsequent inserts using the same vector ids will return a mutation id, but it would not change the index vector count since the same vector ids cannot be inserted twice. You will need to use an `upsert` operation instead to update the vector values for an id that already exists in an index.

2. Query your index - expect your query vector of `[0.13, 0.25, 0.44, ...]` to be closest to vector ID `4` by visiting the root path of `/` . This query will return the three (`topK: 3`) closest matches, as well as their vector values and metadata.

You will notice that `id: 4` has a `score` of `0.46348256`. Because you are using `euclidean` as our distance metric, the closer the score to `0.0`, the closer your vectors are.

```json
// https://vectorize-tutorial.<YOUR_SUBDOMAIN>.workers.dev/
{
	"matches": {
		"count": 3,
		"matches": [
			{
				"id": "4",
				"score": 0.46348256,
				"values": [
					0.17, 0.29, 0.42, 0.57, 0.64, 0.38, 0.51, 0.72, 0.22, 0.85, 0.39,
					0.66, 0.74, 0.32, 0.53, 0.48, 0.21, 0.69, 0.77, 0.34, 0.8, 0.55, 0.41,
					0.29, 0.7, 0.62, 0.35, 0.68, 0.53, 0.3, 0.79, 0.49
				],
				"metadata": {
					"url": "/products/sku/418313"
				}
			},
			{
				"id": "3",
				"score": 0.52920616,
				"values": [
					0.21, 0.33, 0.55, 0.67, 0.8, 0.22, 0.47, 0.63, 0.31, 0.74, 0.35, 0.53,
					0.68, 0.45, 0.55, 0.7, 0.28, 0.64, 0.71, 0.3, 0.77, 0.6, 0.43, 0.39,
					0.85, 0.55, 0.31, 0.69, 0.52, 0.29, 0.72, 0.48
				],
				"metadata": {
					"url": "/products/sku/97913813"
				}
			},
			{
				"id": "2",
				"score": 0.6337869,
				"values": [
					0.14, 0.23, 0.36, 0.51, 0.62, 0.47, 0.59, 0.74, 0.33, 0.89, 0.41,
					0.53, 0.68, 0.29, 0.77, 0.45, 0.24, 0.66, 0.71, 0.34, 0.86, 0.57,
					0.62, 0.48, 0.78, 0.52, 0.37, 0.61, 0.69, 0.28, 0.8, 0.53
				],
				"metadata": {
					"url": "/products/sku/10148191"
				}
			}
		]
	}
}
```

From here, experiment by passing a different `queryVector` and observe the results: the matches and the `score` should change based on the change in distance between the query vector and the vectors in our index.

In a real-world application, the `queryVector` would be the vector embedding representation of a query from a user or system, and our `sampleVectors` would be generated from real content. To build on this example, read the [vector search tutorial](/vectorize/get-started/embeddings/) that combines Workers AI and Vectorize to build an end-to-end application with Workers.

By finishing this tutorial, you have successfully created and queried your first Vectorize index, a Worker to access that index, and deployed your project globally.

## Related resources

- [Build an end-to-end vector search application](/vectorize/get-started/embeddings/) using Workers AI and Vectorize.
- Learn more about [how vector databases work](/vectorize/reference/what-is-a-vector-database/).
- Read [examples](/vectorize/reference/client-api/) on how to use the Vectorize API from Cloudflare Workers.
- [Euclidean Distance vs Cosine Similarity](https://www.baeldung.com/cs/euclidean-distance-vs-cosine-similarity).
- [Dot product](https://en.wikipedia.org/wiki/Dot_product).

---

# Examples

URL: https://developers.cloudflare.com/vectorize/examples/

import { GlossaryTooltip, DirectoryListing } from "~/components"

Explore the following <GlossaryTooltip term="code example">examples</GlossaryTooltip> for Vectorize.

<DirectoryListing directory="vectorize/examples/" />

---

# Changelog

URL: https://developers.cloudflare.com/vectorize/platform/changelog/

import { ProductReleaseNotes } from "~/components";

{/* <!-- Actual content lives in /src/content/release-notes/vectorize.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Limits

URL: https://developers.cloudflare.com/vectorize/platform/limits/

The following limits apply to accounts, indexes and vectors (as specified):

| Feature                                                       | Current Limit                       |
| ------------------------------------------------------------- | ----------------------------------- |
| Indexes per account                                           | 50,000 (Workers Paid) / 100 (Free)  |
| Maximum dimensions per vector                                 | 1536 dimensions                     |
| Maximum vector ID length                                      | 64 bytes                            |
| Metadata per vector                                           | 10KiB                               |
| Maximum returned results (`topK`) with values or metadata     | 20                                  |
| Maximum returned results (`topK`) without values and metadata | 100                                 |
| Maximum upsert batch size (per batch)                         | 1000 (Workers) / 5000 (HTTP API)    |
| Maximum index name length                                     | 64 bytes                            |
| Maximum vectors per index                                     | 5,000,000                           |
| Maximum namespaces per index                                  | 50,000 (Workers Paid) / 1000 (Free) |
| Maximum namespace name length                                 | 64 bytes                            |
| Maximum vectors upload size                                   | 100 MB                              |
| Maximum metadata indexes per Vectorize index                  | 10                                  |
| Maximum indexed data per metadata index per vector            | 64 bytes                            |

## Limits V1 (deprecated)

The following limits apply to accounts, indexes and vectors (as specified):

| Feature                               | Current Limit                    |
| ------------------------------------- | -------------------------------- |
| Indexes per account                   | 100 indexes                      |
| Maximum dimensions per vector         | 1536 dimensions                  |
| Maximum vector ID length              | 64 bytes                         |
| Metadata per vector                   | 10KiB                            |
| Maximum returned results (`topK`)     | 20                               |
| Maximum upsert batch size (per batch) | 1000 (Workers) / 5000 (HTTP API) |
| Maximum index name length             | 63 bytes                         |
| Maximum vectors per index             | 200,000                          |
| Maximum namespaces per index          | 1000 namespaces                  |
| Maximum namespace name length         | 63 bytes                         |

---

# Pricing

URL: https://developers.cloudflare.com/vectorize/platform/pricing/

import { Render } from "~/components";

<Render file="vectorize-ga" />

Vectorize bills are based on:

- **Queried Vector Dimensions**: The total number of vector dimensions queried. If you have 10,000 vectors with 384-dimensions in an index, and make 100 queries against that index, your total queried vector dimensions would sum to 3.878 million (`(10000 + 100) * 384`).
- **Stored Vector Dimensions**: The total number of vector dimensions stored. If you have 1,000 vectors with 1536-dimensions in an index, your stored vector dimensions would sum to 1.536 million (`1000 * 1536`).

You are not billed for CPU, memory, "active index hours", or the number of indexes you create. If you are not issuing queries against your indexes, you are not billed for queried vector dimensions.

## Billing metrics

<Render file="vectorize-pricing" />

### Usage examples

The following table defines a number of example use-cases and the estimated monthly cost for querying a Vectorize index. These estimates do not include the Vectorize usage that is part of the Workers Free and Paid plans.

| Workload   | Dimensions per vector | Stored dimensions | Queries per month | Calculation                                                               | Estimated total                |
| ---------- | --------------------- | ----------------- | ----------------- | ------------------------------------------------------------------------- | ------------------------------ |
| Experiment | 384                   | 5,000 vectors     | 10,000            | `((10000+5000)*384*(0.01/1000000))      + (5000*384*(0.05/100000000))`    | $0.06 / mo <sup>included</sup> |
| Scaling    | 768                   | 25,000 vectors    | 50,000            | `((50000+25000)*768*(0.01/1000000))     + (25000*768*(0.05/100000000))`   | $0.59 / mo <sup>most</sup>     |
| Production | 768                   | 50,000 vectors    | 200,000           | `((200000+50000)*768*(0.01/1000000))    + (50000*768*(0.05/100000000))`   | $1.94 / mo                     |
| Large      | 768                   | 250,000 vectors   | 500,000           | `((500000+250000)*768*(0.01/1000000))   + (250000*768*(0.05/100000000))`  | $5.86 / mo                     |
| XL         | 1536                  | 500,000 vectors   | 1,000,000         | `((1000000+500000)*1536*(0.01/1000000)) + (500000*1536*(0.05/100000000))` | $23.42 / mo                    |

<sup>included</sup> All of this usage would fall into the Vectorize usage
included in the Workers Free or Paid plan.

<sup>most</sup> Most of this usage would fall into the Vectorize usage included
within the Workers Paid plan.

## Frequently Asked Questions

Frequently asked questions related to Vectorize pricing:

- Will Vectorize always have a free tier?

Yes, the [Workers free tier](/workers/platform/pricing/#workers) will always include the ability to prototype and experiment with Vectorize for free.

- What happens if I exceed the monthly included reads, writes and/or storage on the paid tier?

You will be billed for the additional reads, writes and storage according to [Vectorize's pricing](#billing-metrics).

- Does Vectorize charge for data transfer / egress?

No.

- Do queries I issue from the HTTP API or the Wrangler command-line count as billable usage?

Yes: any queries you issue against your index, including from the Workers API, HTTP API and CLI all count as usage.

- Does an empty index, with no vectors, contribute to storage?

No. Empty indexes do not count as stored vector dimensions.

---

# Platform

URL: https://developers.cloudflare.com/vectorize/platform/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Vectorize API

URL: https://developers.cloudflare.com/vectorize/reference/client-api/

import { Render, WranglerConfig } from "~/components";

This page covers the Vectorize API available within [Cloudflare Workers](/workers/), including usage examples.

## Operations

### Insert vectors

```ts
let vectorsToInsert = [
	{ id: "123", values: [32.4, 6.5, 11.2, 10.3, 87.9] },
	{ id: "456", values: [2.5, 7.8, 9.1, 76.9, 8.5] },
];
let inserted = await env.YOUR_INDEX.insert(vectorsToInsert);
```

Inserts vectors into the index. Vectorize inserts are asynchronous and the insert operation returns a mutation identifier unique for that operation. It typically takes a few seconds for inserted vectors to be available for querying in a Vectorize index.

If vectors with the same vector ID already exist in the index, only the vectors with new IDs will be inserted.

If you need to update existing vectors, use the [upsert](#upsert-vectors) operation.

### Upsert vectors

```ts
let vectorsToUpsert = [
	{ id: "123", values: [32.4, 6.5, 11.2, 10.3, 87.9] },
	{ id: "456", values: [2.5, 7.8, 9.1, 76.9, 8.5] },
	{ id: "768", values: [29.1, 5.7, 12.9, 15.4, 1.1] },
];
let upserted = await env.YOUR_INDEX.upsert(vectorsToUpsert);
```

Upserts vectors into an index. Vectorize upserts are asynchronous and the upsert operation returns a mutation identifier unique for that operation. It typically takes a few seconds for upserted vectors to be available for querying in a Vectorize index.

An upsert operation will insert vectors into the index if vectors with the same ID do not exist, and overwrite vectors with the same ID.

Upserting does not merge or combine the values or metadata of an existing vector with the upserted vector: the upserted vector replaces the existing vector in full.

### Query vectors

```ts
let queryVector = [32.4, 6.55, 11.2, 10.3, 87.9];
let matches = await env.YOUR_INDEX.query(queryVector);
```

Query an index with the provided vector, returning the score(s) of the closest vectors based on the configured distance metric.

- Configure the number of returned matches by setting `topK` (default: 5)
- Return vector values by setting `returnValues: true` (default: false)
- Return vector metadata by setting `returnMetadata: 'indexed'` or `returnMetadata: 'all'` (default: 'none')

```ts
let matches = await env.YOUR_INDEX.query(queryVector, {
	topK: 5,
	returnValues: true,
	returnMetadata: "all",
});
```

#### topK

The `topK` can be configured to specify the number of matches returned by the query operation. Vectorize now supports an upper limit of `100` for the `topK` value. However, for a query operation with `returnValues` set to `true` or `returnMetadata` set to `all`, `topK` would be limited to a maximum value of `20`.

#### returnMetadata

The `returnMetadata` field provides three ways to fetch vector metadata while querying:

1. `none`: Do not fetch metadata.
2. `indexed`: Fetched metadata only for the indexed metadata fields. There is no latency overhead with this option, but long text fields may be truncated.
3. `all`: Fetch all metadata associated with a vector. Queries may run slower with this option, and `topK` would be limited to 20.

:::note[`topK` and `returnMetadata` for legacy Vectorize indexes]

For legacy Vectorize (V1) indexes, `topK` is limited to 20, and the `returnMetadata` is a boolean field.

:::

### Query vectors by ID

```ts
let matches = await env.YOUR_INDEX.queryById("some-vector-id");
```

Query an index using a vector that is already present in the index.

Query options remain the same as the query operation described above.

```ts
let matches = await env.YOUR_INDEX.queryById("some-vector-id", {
	topK: 5,
	returnValues: true,
	returnMetadata: "all",
});
```

### Get vectors by ID

```ts
let ids = ["11", "22", "33", "44"];
const vectors = await env.YOUR_INDEX.getByIds(ids);
```

Retrieves the specified vectors by their ID, including values and metadata.

### Delete vectors by ID

```ts
let idsToDelete = ["11", "22", "33", "44"];
const deleted = await env.YOUR_INDEX.deleteByIds(idsToDelete);
```

Deletes the vector IDs provided from the current index. Vectorize deletes are asynchronous and the delete operation returns a mutation identifier unique for that operation. It typically takes a few seconds for vectors to be removed from the Vectorize index.

### Retrieve index details

```ts
const details = await env.YOUR_INDEX.describe();
```

Retrieves the configuration of a given index directly, including its configured `dimensions` and distance `metric`.

### Create Metadata Index

Enable metadata filtering on the specified property. Limited to 10 properties.

<Render file="vectorize-wrangler-version" />

Run the following `wrangler vectorize` command:

```sh
wrangler vectorize create-metadata-index <index-name> --property-name='some-prop' --type='string'
```

### Delete Metadata Index

Allow Vectorize to delete the specified metadata index.

<Render file="vectorize-wrangler-version" />

Run the following `wrangler vectorize` command:

```sh
wrangler vectorize delete-metadata-index <index-name> --property-name='some-prop'
```

### List Metadata Indexes

List metadata properties on which metadata filtering is enabled.

<Render file="vectorize-wrangler-version" />

Run the following `wrangler vectorize` command:

```sh
wrangler vectorize list-metadata-index <index-name>
```

### Get Index Info

Get additional details about the index.

<Render file="vectorize-wrangler-version" />

Run the following `wrangler vectorize` command:

```sh
wrangler vectorize info <name>
```

## Vectors

A vector represents the vector embedding output from a machine learning model.

- `id` - a unique `string` identifying the vector in the index. This should map back to the ID of the document, object or database identifier that the vector values were generated from.
- `namespace` - an optional partition key within a index. Operations are performed per-namespace, so this can be used to create isolated segments within a larger index.
- `values` - an array of `number`, `Float32Array`, or `Float64Array` as the vector embedding itself. This must be a dense array, and the length of this array must match the `dimensions` configured on the index.
- `metadata` - an optional set of key-value pairs that can be used to store additional metadata alongside a vector.

```ts
let vectorExample = {
	id: "12345",
	values: [32.4, 6.55, 11.2, 10.3, 87.9],
	metadata: {
		key: "value",
		hello: "world",
		url: "r2://bucket/some/object.json",
	},
};
```

## Binding to a Worker

[Bindings](/workers/runtime-apis/bindings/) allow you to attach resources, including Vectorize indexes or R2 buckets, to your Worker.

Bindings are defined in either the [Wrangler configuration file](/workers/wrangler/configuration/) associated with your Workers project, or via the Cloudflare dashboard for your project.

Vectorize indexes are bound by name. A binding for an index named `production-doc-search` would resemble the below:

<WranglerConfig>

```toml
[[vectorize]]
binding = "PROD_SEARCH" # the index will be available as env.PROD_SEARCH in your Worker
index_name = "production-doc-search"
```

</WranglerConfig>

Refer to the [bindings documentation](/workers/wrangler/configuration/#vectorize-indexes) for more details.

## TypeScript Types

<Render file="wrangler-typegen" product="workers" />

---

# Reference

URL: https://developers.cloudflare.com/vectorize/reference/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Metadata filtering

URL: https://developers.cloudflare.com/vectorize/reference/metadata-filtering/

import { Render, PackageManagers } from "~/components";

In addition to providing an input vector to your query, you can also filter by [vector metadata](/vectorize/best-practices/insert-vectors/#metadata) associated with every vector. Query results will only include vectors that match the `filter` criteria, meaning that `filter` is applied first, and the `topK` results are taken from the filtered set.

By using metadata filtering to limit the scope of a query, you can filter by specific customer IDs, tenant, product category or any other metadata you associate with your vectors.

## Metadata indexes

Vectorize supports [namespace](/vectorize/best-practices/insert-vectors/#namespaces) filtering by default, but to filter on another metadata property of your vectors, you'll need to create a metadata index. You can create up to 10 metadata indexes per Vectorize index.

Metadata indexes for properties of type `string`, `number` and `boolean` are supported. Please refer to [Create metadata indexes](/vectorize/get-started/intro/#4-optional-create-metadata-indexes) for details.

You can store up to 10KiB of metadata per vector. See [Vectorize Limits](/vectorize/platform/limits/) for a complete list of limits.

For metadata indexes of type `number`, the indexed number precision is that of float64.

For metadata indexes of type `string`, each vector indexes the first 64B of the string data truncated on UTF-8 character boundaries to the longest well-formed UTF-8 substring within that limit, so vectors are filterable on the first 64B of their value for each indexed property.

:::note[Enable metadata filtering]

Vectors upserted before a metadata index was created won't have their metadata contained in that index. Upserting/re-upserting vectors after it was created will have them indexed as expected. Please refer to [Create metadata indexes](/vectorize/get-started/intro/#4-optional-create-metadata-indexes) for details.

:::

## Supported operations

An optional `filter` property on `query()` method specifies metadata filters:

| Operator | Description              |
| -------- | ------------------------ |
| `$eq`    | Equals                   |
| `$ne`    | Not equals               |
| `$in`    | In                       |
| `$nin`   | Not in                   |
| `$lt`    | Less than                |
| `$lte`   | Less than or equal to    |
| `$gt`    | Greater than             |
| `$gte`   | Greater than or equal to |

- `filter` must be non-empty object whose compact JSON representation must be less than 2048 bytes.
- `filter` object keys cannot be empty, contain `" | .` (dot is reserved for nesting), start with `$`, or be longer than 512 characters.
- For `$eq` and `$ne`, `filter` object non-nested values can be `string`, `number`, `boolean`, or `null` values.
- For `$in` and `$nin`, `filter` object values can be arrays of `string`, `number`, `boolean`, or `null` values.
- Upper-bound range queries (i.e. `$lt` and `$lte`) can be combined with lower-bound range queries (i.e. `$gt` and `$gte`) within the same filter. Other combinations are not allowed.
- For range queries (i.e. `$lt`, `$lte`, `$gt`, `$gte`), `filter` object non-nested values can be `string` or `number` values. Strings are ordered lexicographically.
- Range queries involving a large number of vectors (~10M and above) may experience reduced accuracy.

### Namespace versus metadata filtering

Both [namespaces](/vectorize/best-practices/insert-vectors/#namespaces) and metadata filtering narrow the vector search space for a query. Consider the following when evaluating both filter types:

- A namespace filter is applied before metadata filter(s).
- A vector can only be part of a single namespace with the documented [limits](/vectorize/platform/limits/). Vector metadata can contain multiple key-value pairs up to [metadata per vector limits](/vectorize/platform/limits/). Metadata values support different types (`string`, `boolean`, and others), therefore offering more flexibility.

### Valid `filter` examples

#### Implicit `$eq` operator

```json
{ "streaming_platform": "netflix" }
```

#### Explicit operator

```json
{ "someKey": { "$ne": "hbo" } }
```

#### `$in` operator

```json
{ "someKey": { "$in": ["hbo", "netflix"] } }
```

#### `$nin` operator

```json
{ "someKey": { "$nin": ["hbo", "netflix"] } }
```

#### Range query involving numbers

```json
{ "timestamp": { "$gte": 1734242400, "$lt": 1734328800 } }
```

#### Range query involving strings

Range queries can implement **prefix searching** on string metadata fields. This is also like a **starts_with** filter.

For example, the following filter matches all values starting with "net":

```json
{ "someKey": { "$gte": "net", "$lt": "neu" } }
```

#### Implicit logical `AND` with multiple keys

```json
{ "pandas.nice": 42, "someKey": { "$ne": "someValue" } }
```

#### Keys define nesting with `.` (dot)

```json
{ "pandas.nice": 42 }


// looks for { "pandas": { "nice": 42 } }
```

## Examples

### Add metadata

<Render file="vectorize-legacy" />

With the following index definition:

```sh
npx wrangler vectorize create tutorial-index --dimensions=32 --metric=cosine
```

Create metadata indexes:

```sh
npx wrangler vectorize create-metadata-index tutorial-index --property-name=url --type=string
```

```sh
npx wrangler vectorize create-metadata-index tutorial-index --property-name=streaming_platform --type=string
```

Metadata can be added when [inserting or upserting vectors](/vectorize/best-practices/insert-vectors/#examples).

```ts
const newMetadataVectors: Array<VectorizeVector> = [
	{
		id: "1",
		values: [32.4, 74.1, 3.2, ...],
		metadata: { url: "/products/sku/13913913", streaming_platform: "netflix" },
	},
	{
		id: "2",
		values: [15.1, 19.2, 15.8, ...],
		metadata: { url: "/products/sku/10148191", streaming_platform: "hbo" },
	},
	{
		id: "3",
		values: [0.16, 1.2, 3.8, ...],
		metadata: { url: "/products/sku/97913813", streaming_platform: "amazon" },
	},
	{
		id: "4",
		values: [75.1, 67.1, 29.9, ...],
		metadata: { url: "/products/sku/418313", streaming_platform: "netflix" },
	},
	{
		id: "5",
		values: [58.8, 6.7, 3.4, ...],
		metadata: { url: "/products/sku/55519183", streaming_platform: "hbo" },
	},
];

// Upsert vectors with added metadata, returning a count of the vectors upserted and their vector IDs
let upserted = await env.YOUR_INDEX.upsert(newMetadataVectors);
```

### Query examples

Use the `query()` method:

```ts
let queryVector: Array<number> = [54.8, 5.5, 3.1, ...];
let originalMatches = await env.YOUR_INDEX.query(queryVector, {
	topK: 3,
	returnValues: true,
	returnMetadata: 'all',
});
```

Results without metadata filtering:

```json
{
	"count": 3,
	"matches": [
		{
			"id": "5",
			"score": 0.999909486,
			"values": [58.79999923706055, 6.699999809265137, 3.4000000953674316],
			"metadata": {
				"url": "/products/sku/55519183",
				"streaming_platform": "hbo"
			}
		},
		{
			"id": "4",
			"score": 0.789848214,
			"values": [75.0999984741211, 67.0999984741211, 29.899999618530273],
			"metadata": {
				"url": "/products/sku/418313",
				"streaming_platform": "netflix"
			}
		},
		{
			"id": "2",
			"score": 0.611976262,
			"values": [15.100000381469727, 19.200000762939453, 15.800000190734863],
			"metadata": {
				"url": "/products/sku/10148191",
				"streaming_platform": "hbo"
			}
		}
	]
}
```

The same `query()` method with a `filter` property supports metadata filtering.

```ts
let queryVector: Array<number> = [54.8, 5.5, 3.1, ...];
let metadataMatches = await env.YOUR_INDEX.query(queryVector, {
	topK: 3,
	filter: { streaming_platform: "netflix" },
	returnValues: true,
	returnMetadata: 'all',
});
```

Results with metadata filtering:

```json
{
	"count": 2,
	"matches": [
		{
			"id": "4",
			"score": 0.789848214,
			"values": [75.0999984741211, 67.0999984741211, 29.899999618530273],
			"metadata": {
				"url": "/products/sku/418313",
				"streaming_platform": "netflix"
			}
		},
		{
			"id": "1",
			"score": 0.491185264,
			"values": [32.400001525878906, 74.0999984741211, 3.200000047683716],
			"metadata": {
				"url": "/products/sku/13913913",
				"streaming_platform": "netflix"
			}
		}
	]
}
```

## Limitations

- As of now, metadata indexes need to be created for Vectorize indexes _before_ vectors can be inserted to support metadata filtering.
- Only indexes created on or after 2023-12-06 support metadata filtering. Previously created indexes cannot be migrated to support metadata filtering.

---

# Transition legacy Vectorize indexes

URL: https://developers.cloudflare.com/vectorize/reference/transition-vectorize-legacy/

Legacy Vectorize (V1) indexes are on a deprecation path as of Aug 15, 2024. Your Vectorize index may be a legacy index if it fulfills any of the follwing crieria:

1. Was created with a Wrangler version lower than `v3.71.0`.
2. Was created using the "--deprecated-v1" flag enabled.
3. Was created using the legacy REST API.

This document provides details around any transition steps that may be needed to move away from legacy Vectorize indexes.

## Why should I transition?

Legacy Vectorize (V1) indexes are on a deprecation path. Support for these indexes would be limited and their usage is not recommended for any production workloads.

Furthermore, you will no longer be able to create legacy Vectorize indexes by December 2024. Other operations will be unaffected and will remain functional.

Additionally, the new Vectorize (V2) indexes can operate at a significantly larger scale (with a capacity for multi-million vectors), and provide faster performance. Please review the [Limits](/vectorize/platform/limits/) page to understand the latest capabilities supported by Vectorize.

## Notable changes

In addition to supporting significantly larger indexes with multi-million vectors, and faster performance, these are some of the changes that need to be considered when transitioning away from legacy Vectorize indexes:

1. The new Vectorize (V2) indexes now support asynchronous mutations. Any vector inserts or deletes, and metadata index creation or deletes may take a few seconds to be reflected.

2. Vectorize (V2) support metadata and namespace filtering for much larger indexes with significantly lower latencies. However, the fields on which metadata filtering can be applied need to be specified before vectors are inserted. Refer to the [metadata index creation](/vectorize/reference/client-api/#create-metadata-index) page for more details.

3. Vectorize (V2) [query operation](/vectorize/reference/client-api/#query-vectors) now supports the ability to search for and return up to 100 most similar vectors.

4. Vectorize (V2) query operations provide a more granular control for querying metadata along with vectors. Refer to the [query operation](/vectorize/reference/client-api/#query-vectors) page for more details.

5. Vectorize (V2) expands the Vectorize capabilities that are available via Wrangler (with Wrangler version > `v3.71.0`).

## Transition

:::note[Automated Migration]

Watch this space for the upcoming capability to migrate legacy (V1) indexes to the new Vectorize (V2) indexes automatically.

:::

1. Wrangler now supports operations on the new version of Vectorize (V2) indexes by default. To use Wrangler commands for legacy (V1) indexes, the `--deprecated-v1` flag must be enabled. Please note that this flag is only supported to create, get, list and delete indexes and to insert vectors.

2. Refer to the [REST API](/api/resources/vectorize/subresources/indexes/methods/create/) page for details on the routes and payload types for the new Vectorize (V2) indexes.

3. To use the new version of Vectorize indexes in Workers, the environment binding must be defined as a `Vectorize` interface.

   ```typescript
   export interface Env {
   	// This makes your vector index methods available on env.VECTORIZE.*
   	// For example, env.VECTORIZE.insert() or query()
   	VECTORIZE: Vectorize;
   }
   ```

   The `Vectorize` interface includes the type changes and the capabilities supported by new Vectorize (V2) indexes.

   For legacy Vectorize (V1) indexes, use the `VectorizeIndex` interface.

   ```typescript
   export interface Env {
   	// This makes your vector index methods available on env.VECTORIZE.*
   	// For example, env.VECTORIZE.insert() or query()
   	VECTORIZE: VectorizeIndex;
   }
   ```

4. With the new Vectorize (V2) version, the `returnMetadata` option for the [query operation](/vectorize/reference/client-api/#query-vectors) now expects either `all`, `indexed` or `none` string values. For legacy Vectorize (V1), the `returnMetadata` option was a boolean field.

5. With the new Vectorize (V2) indexes, all index and vector mutations are asynchronous and return a `mutationId` in the response as a unique identifier for that mutation operation.

   These mutation operations are: [Vector Inserts](/vectorize/reference/client-api/#insert-vectors), [Vector Upserts](/vectorize/reference/client-api/#upsert-vectors), [Vector Deletes](/vectorize/reference/client-api/#delete-vectors-by-id), [Metadata Index Creation](/vectorize/reference/client-api/#create-metadata-index), [Metadata Index Deletion](/vectorize/reference/client-api/#delete-metadata-index).

   To check the identifier and the timestamp of the last mutation processed, use the Vectorize [Info command](/vectorize/reference/client-api/#get-index-info).

---

# Vector databases

URL: https://developers.cloudflare.com/vectorize/reference/what-is-a-vector-database/

Vector databases are a key part of building scalable AI-powered applications. Vector databases provide long term memory, on top of an existing machine learning model.

Without a vector database, you would need to train your model (or models) or re-run your dataset through a model before making a query, which would be slow and expensive.

## Why is a vector database useful?

A vector database determines what other data (represented as vectors) is near your input query. This allows you to build different use-cases on top of a vector database, including:

- Semantic search, used to return results similar to the input of the query.
- Classification, used to return the grouping (or groupings) closest to the input query.
- Recommendation engines, used to return content similar to the input based on different criteria (for example previous product sales, or user history).
- Anomaly detection, used to identify whether specific data points are similar to existing data, or different.

Vector databases can also power [Retrieval Augmented Generation](https://arxiv.org/abs/2005.11401) (RAG) tasks, which allow you to bring additional context to LLMs (Large Language Models) by using the context from a vector search to augment the user prompt.

### Vector search

In a traditional vector search use-case, queries are made against a vector database by passing it a query vector, and having the vector database return a configurable list of vectors with the shortest distance ("most similar") to the query vector.

The step-by-step workflow resembles the below:

1. A developer converts their existing dataset (documentation, images, logs stored in R2) into a set of vector embeddings (a one-way representation) by passing them through a machine learning model that is trained for that data type.
2. The output embeddings are inserted into a Vectorize database index.
3. A search query, classification request or anomaly detection query is also passed through the same ML model, returning a vector embedding representation of the query.
4. Vectorize is queried with this embedding, and returns a set of the most similar vector embeddings to the provided query.
5. The returned embeddings are used to retrieve the original source objects from dedicated storage (for example, R2, KV, and D1) and returned back to the user.

In a workflow without a vector database, you would need to pass your entire dataset alongside your query each time, which is neither practical (models have limits on input size) and would consume significant resources and time.

### Retrieval Augmented Generation

Retrieval Augmented Generation (RAG) is an approach used to improve the context provided to an LLM (Large Language Model) in generative AI use-cases, including chatbot and general question-answer applications. The vector database is used to enhance the prompt passed to the LLM by adding additional context alongside the query.

Instead of passing the prompt directly to the LLM, in the RAG approach you:

1. Generate vector embeddings from an existing dataset or corpus (for example, the dataset you want to use to add additional context to the LLMs response). An existing dataset or corpus could be a product documentation, research data, technical specifications, or your product catalog and descriptions.
2. Store the output embeddings in a Vectorize database index.

When a user initiates a prompt, instead of passing it (without additional context) to the LLM, you _augment_ it with additional context:

1. The user prompt is passed into the same ML model used for your dataset, returning a vector embedding representation of the query.
2. This embedding is used as the query (semantic search) against the vector database, which returns similar vectors.
3. These vectors are used to look up the content they relate to (if not embedded directly alongside the vectors as metadata).
4. This content is provided as context alongside the original user prompt, providing additional context to the LLM and allowing it to return an answer that is likely to be far more contextual than the standalone prompt.

[Create a RAG application today with AutoRAG](/autorag/) to deploy a fully managed RAG pipeline in just a few clicks. AutoRAG automatically sets up Vectorize, handles continuous indexing, and serves responses through a single API.

<sup>1</sup> You can learn more about the theory behind RAG by reading the [RAG
paper](https://arxiv.org/abs/2005.11401).
<sup>1</sup> You can learn more about the theory behind RAG by reading the [RAG
paper](https://arxiv.org/abs/2005.11401).

## Terminology

### Databases and indexes

In Vectorize, a database and an index are the same concept. Each index you create is separate from other indexes you create. Vectorize automatically manages optimizing and re-generating the index for you when you insert new data.

### Vector Embeddings

Vector embeddings represent the features of a machine learning model as a numerical vector (array of numbers). They are a one-way representation that encodes how a machine learning model understands the input(s) provided to it, based on how the model was originally trained and its' internal structure.

For example, a [text embedding model](/workers-ai/models/#text-embeddings) available in Workers AI is able to take text input and represent it as a 768-dimension vector. The text `This is a story about an orange cloud`, when represented as a vector embedding, resembles the following:

```json
[-0.019273685291409492,-0.01913292706012726,<764 dimensions here>,0.0007094172760844231,0.043409910053014755]
```

When a model considers the features of an input as "similar" (based on its understanding), the distance between the vector embeddings for those two inputs will be short.

### Dimensions

Vector dimensions describe the width of a vector embedding. The width of a vector embedding is the number of floating point elements that comprise a given vector.

The number of dimensions are defined by the machine learning model used to generate the vector embeddings, and how it represents input features based on its internal model and complexity. More dimensions ("wider" vectors) may provide more accuracy at the cost of compute and memory resources, as well as latency (speed) of vector search.

Refer to the [dimensions](/vectorize/best-practices/create-indexes/#dimensions) documentation to learn how to configure the accepted vector dimension size when creating a Vectorize index.

### Distance metrics

The distance metric is an index used for vector search. It defines how it determines how close your query vector is to other vectors within the index.

- Distance metrics determine how the vector search engine assesses similarity between vectors.
- Cosine, Euclidean (L2), and Dot Product are the most commonly used distance metrics in vector search.
- The machine learning model and type of embedding you use will determine which distance metric is best suited for your use-case.
- Different metrics determine different scoring characteristics. For example, the `cosine` distance metric is well suited to text, sentence similarity and/or document search use-cases. `euclidean` can be better suited for image or speech recognition use-cases.

Refer to the [distance metrics](/vectorize/best-practices/create-indexes/#distance-metrics) documentation to learn how to configure a distance metric when creating a Vectorize index.

---

# Tutorials

URL: https://developers.cloudflare.com/vectorize/tutorials/

import { GlossaryTooltip, ListTutorials, YouTubeVideos } from "~/components";

View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Vectorize.

## Docs

<ListTutorials />

## Videos

<YouTubeVideos products={["Vectorize"]} />

---

# Vercel AI SDK

URL: https://developers.cloudflare.com/workers-ai/configuration/ai-sdk/

import { PackageManagers } from "~/components";

Workers AI can be used with the [Vercel AI SDK](https://sdk.vercel.ai/) for JavaScript and TypeScript codebases.

## Setup

Install the [`workers-ai-provider` provider](https://sdk.vercel.ai/providers/community-providers/cloudflare-workers-ai):

<PackageManagers pkg="workers-ai-provider" />

Then, add an AI binding in your Workers project Wrangler file:

```toml
[ai]
binding = "AI"
```

## Models

The AI SDK can be configured to work with [any AI model](/workers-ai/models/).

```js
import { createWorkersAI } from "workers-ai-provider";

const workersai = createWorkersAI({ binding: env.AI });

// Choose any model: https://developers.cloudflare.com/workers-ai/models/
const model = workersai("@cf/meta/llama-3.1-8b-instruct", {});
```

## Generate Text

Once you have selected your model, you can generate text from a given prompt.

```js
import { createWorkersAI } from 'workers-ai-provider';
import { generateText } from 'ai';

type Env = {
  AI: Ai;
};

export default {
  async fetch(_: Request, env: Env) {
    const workersai = createWorkersAI({ binding: env.AI });
    const result = await generateText({
      model: workersai('@cf/meta/llama-2-7b-chat-int8'),
      prompt: 'Write a 50-word essay about hello world.',
    });

    return new Response(result.text);
  },
};
```

## Stream Text

For longer responses, consider streaming responses to provide as the generation completes.

```js
import { createWorkersAI } from 'workers-ai-provider';
import { streamText } from 'ai';

type Env = {
  AI: Ai;
};

export default {
  async fetch(_: Request, env: Env) {
    const workersai = createWorkersAI({ binding: env.AI });
    const result = streamText({
      model: workersai('@cf/meta/llama-2-7b-chat-int8'),
      prompt: 'Write a 50-word essay about hello world.',
    });

    return result.toTextStreamResponse({
      headers: {
        // add these headers to ensure that the
        // response is chunked and streamed
        'Content-Type': 'text/x-unknown',
        'content-encoding': 'identity',
        'transfer-encoding': 'chunked',
      },
    });
  },
};
```

## Generate Structured Objects

You can provide a Zod schema to generate a structured JSON response.

```js
import { createWorkersAI } from 'workers-ai-provider';
import { generateObject } from 'ai';
import { z } from 'zod';

type Env = {
  AI: Ai;
};

export default {
  async fetch(_: Request, env: Env) {
    const workersai = createWorkersAI({ binding: env.AI });
    const result = await generateObject({
      model: workersai('@cf/meta/llama-3.1-8b-instruct'),
      prompt: 'Generate a Lasagna recipe',
      schema: z.object({
        recipe: z.object({
          ingredients: z.array(z.string()),
          description: z.string(),
        }),
      }),
    });

    return Response.json(result.object);
  },
};
```

---

# Workers Bindings

URL: https://developers.cloudflare.com/workers-ai/configuration/bindings/

import { Type, MetaInfo, WranglerConfig } from "~/components";

## Workers

[Workers](/workers/) provides a serverless execution environment that allows you to create new applications or augment existing ones.

To use Workers AI with Workers, you must create a Workers AI [binding](/workers/runtime-apis/bindings/). Bindings allow your Workers to interact with resources, like Workers AI, on the Cloudflare Developer Platform. You create bindings on the Cloudflare dashboard or by updating your [Wrangler file](/workers/wrangler/configuration/).

To bind Workers AI to your Worker, add the following to the end of your Wrangler file:

<WranglerConfig>

```toml
[ai]
binding = "AI" # i.e. available in your Worker on env.AI
```

</WranglerConfig>

## Pages Functions

[Pages Functions](/pages/functions/) allow you to build full-stack applications with Cloudflare Pages by executing code on the Cloudflare network. Functions are Workers under the hood.

To configure a Workers AI binding in your Pages Function, you must use the Cloudflare dashboard. Refer to [Workers AI bindings](/pages/functions/bindings/#workers-ai) for instructions.

## Methods

### async env.AI.run()

`async env.AI.run()` runs a model. Takes a model as the first parameter, and an object as the second parameter.

```javascript
const answer = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
    prompt: "What is the origin of the phrase 'Hello, World'"
});
```

**Parameters**



* `model` <Type text="string" /> <MetaInfo text="required" />

  * The model to run.

  **Supported options**

  * `stream` <Type text="boolean" /> <MetaInfo text="optional" />
    * Returns a stream of results as they are available.



```javascript
const answer = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
    prompt: "What is the origin of the phrase 'Hello, World'",
    stream: true
});

return new Response(answer, {
    headers: { "content-type": "text/event-stream" }
});
```

---

# Hugging Face Chat UI

URL: https://developers.cloudflare.com/workers-ai/configuration/hugging-face-chat-ui/

Use Workers AI with [Chat UI](https://github.com/huggingface/chat-ui?tab=readme-ov-file#text-embedding-models), an open-source chat interface offered by Hugging Face.

## Prerequisites

You will need the following:

* A [Cloudflare account](https://dash.cloudflare.com)
* Your [Account ID](/fundamentals/account/find-account-and-zone-ids/)
* An [API token](/workers-ai/get-started/rest-api/#1-get-api-token-and-account-id) for Workers AI

## Setup

First, decide how to reference your Account ID and API token (either directly in your `.env.local` using the `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` variables or in the endpoint configuration).

Then, follow the rest of the setup instructions in the [Chat UI GitHub repository](https://github.com/huggingface/chat-ui?tab=readme-ov-file#text-embedding-models).

When setting up your models, specify the `cloudflare` endpoint.

```json
{
  "name" : "nousresearch/hermes-2-pro-mistral-7b",
  "tokenizer": "nousresearch/hermes-2-pro-mistral-7b",
  "parameters": {
    "stop": ["<|im_end|>"]
  },
  "endpoints" : [
    {
      "type": "cloudflare",
      // optionally specify these if not included in .env.local
      "accountId": "your-account-id",
      "apiToken": "your-api-token"
      //
    }
  ]
}
```

## Supported models

This template works with any [text generation models](/workers-ai/models/) that begin with the `@hf` parameter.

---

# Configuration

URL: https://developers.cloudflare.com/workers-ai/configuration/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# OpenAI compatible API endpoints

URL: https://developers.cloudflare.com/workers-ai/configuration/open-ai-compatibility/

import { Render } from "~/components"

<Render file="openai-compatibility" /> <br/>

## Usage

### Workers AI

Normally, Workers AI requires you to specify the model name in the cURL endpoint or within the `env.AI.run` function.

With OpenAI compatible endpoints,you can leverage the [openai-node sdk](https://github.com/openai/openai-node) to make calls to Workers AI. This allows you to use Workers AI by simply changing the base URL and the model name.

```js title="OpenAI SDK Example"
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: env.CLOUDFLARE_API_KEY,
  baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/ai/v1`
 });

const chatCompletion = await openai.chat.completions.create({
  messages: [{ role: "user", content: "Make some robot noises" }],
  model: "@cf/meta/llama-3.1-8b-instruct",
 });

const embeddings = await openai.embeddings.create({
    model: "@cf/baai/bge-large-en-v1.5",
    input: "I love matcha"
  });

```

```bash title="cURL example"
curl --request POST \
  --url https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1/chat/completions \
  --header "Authorization: Bearer {api_token}" \
  --header "Content-Type: application/json" \
  --data '
    {
      "model": "@cf/meta/llama-3.1-8b-instruct",
      "messages": [
        {
          "role": "user",
          "content": "how to build a wooden spoon in 3 short steps? give as short as answer as possible"
        }
      ]
    }
'
```

### AI Gateway

These endpoints are also compatible with [AI Gateway](/ai-gateway/providers/workersai/#openai-compatible-endpoints).

---

# Features

URL: https://developers.cloudflare.com/workers-ai/features/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# JSON Mode

URL: https://developers.cloudflare.com/workers-ai/features/json-mode/

import { Code } from "~/components";

export const jsonModeSchema = `{
  response_format: {
    title: "JSON Mode",
    type: "object",
    properties: {
      type: {
        type: "string",
        enum: ["json_object", "json_schema"],
      },
      json_schema: {},
    }
  }
}`;

export const jsonModeRequestExample = `{
  "messages": [
    {
      "role": "system",
      "content": "Extract data about a country."
    },
    {
      "role": "user",
      "content": "Tell me about India."
    }
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "capital": {
          "type": "string"
        },
        "languages": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "name",
        "capital",
        "languages"
      ]
    }
  }
}`;

export const jsonModeResponseExample = `{
  "response": {
    "name": "India",
    "capital": "New Delhi",
    "languages": [
      "Hindi",
      "English",
      "Bengali",
      "Telugu",
      "Marathi",
      "Tamil",
      "Gujarati",
      "Urdu",
      "Kannada",
      "Odia",
      "Malayalam",
      "Punjabi",
      "Sanskrit"
    ]
  }
}`;

When we want text-generation AI models to interact with databases, services, and external systems programmatically, typically when using tool calling or building AI agents, we must have structured response formats rather than natural language.

Workers AI supports JSON Mode, enabling applications to request a structured output response when interacting with AI models.

## Schema

JSON Mode is compatible with OpenAI’s implementation; to enable add the `response_format` property to the request object using the following convention:

<Code code={jsonModeSchema} lang="json" />

Where `json_schema` must be a valid [JSON Schema](https://json-schema.org/) declaration.

## JSON Mode example

When using JSON Format, pass the schema as in the example below as part of the request you send to the LLM.

<Code code={jsonModeRequestExample} lang="json" />

The LLM will follow the schema, and return a response such as below:

<Code code={jsonModeResponseExample} lang="json" />

As you can see, the model is complying with the JSON schema definition in the request and responding with a validated JSON object.

## Supported Models

This is the list of models that now support JSON Mode:

- [@cf/meta/llama-3.1-8b-instruct-fast](/workers-ai/models/llama-3.1-8b-instruct-fast/)
- [@cf/meta/llama-3.1-70b-instruct](/workers-ai/models/llama-3.1-70b-instruct/)
- [@cf/meta/llama-3.3-70b-instruct-fp8-fast](/workers-ai/models/llama-3.3-70b-instruct-fp8-fast/)
- [@cf/meta/llama-3-8b-instruct](/workers-ai/models/llama-3-8b-instruct/)
- [@cf/meta/llama-3.1-8b-instruct](/workers-ai/models/llama-3.1-8b-instruct/)
- [@cf/meta/llama-3.2-11b-vision-instruct](/workers-ai/models/llama-3.2-11b-vision-instruct/)
- [@hf/nousresearch/hermes-2-pro-mistral-7b](/workers-ai/models/hermes-2-pro-mistral-7b/)
- [@hf/thebloke/deepseek-coder-6.7b-instruct-awq](/workers-ai/models/deepseek-coder-6.7b-instruct-awq/)
- [@cf/deepseek-ai/deepseek-r1-distill-qwen-32b](/workers-ai/models/deepseek-r1-distill-qwen-32b/)

We will continue extending this list to keep up with new, and requested models.

Note that Workers AI can't guarantee that the model responds according to the requested JSON Schema. Depending on the complexity of the task and adequacy of the JSON Schema, the model may not be able to satisfy the request in extreme situations. If that's the case, then an error `JSON Mode couldn't be met` is returned and must be handled.

JSON Mode currently doesn't support streaming.

---

# Markdown Conversion

URL: https://developers.cloudflare.com/workers-ai/features/markdown-conversion/

import { Code, Type, MetaInfo, Details, Render } from "~/components";

[Markdown](https://en.wikipedia.org/wiki/Markdown) is essential for text generation and large language models (LLMs) in training and inference because it can provide structured, semantic, human, and machine-readable input. Likewise, Markdown facilitates chunking and structuring input data for better retrieval and synthesis in the context of RAGs, and its simplicity and ease of parsing and rendering make it ideal for AI Agents.

For these reasons, document conversion plays an important role when designing and developing AI applications. Workers AI provides the `toMarkdown` utility method that developers can use from the [`env.AI`](/workers-ai/configuration/bindings/) binding or the REST APIs for quick, easy, and convenient conversion and summary of documents in multiple formats to Markdown language.

## Methods and definitions

### async env.AI.toMarkdown()

Takes a list of documents in different formats and converts them to Markdown.

#### Parameter

- <code>documents</code>: <Type text="array" />- An array of
  `toMarkdownDocument`s.

#### Return values

- <code>results</code>: <Type text="array" />- An array of
  `toMarkdownDocumentResult`s.

### `toMarkdownDocument` definition

- `name` <Type text="string" />

  - Name of the document to convert.

- `blob` <Type text="Blob" />

  - A new [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob/Blob) object with the document content.

### `toMarkdownDocumentResult` definition

- `name` <Type text="string" />

  - Name of the converted document. Matches the input name.

- `mimetype` <Type text="string" />

  - The detected [mime type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) of the document.

- `tokens` <Type text="number" />

  - The estimated number of tokens of the converted document.

- `data` <Type text="string" />

  - The content of the converted document in Markdown format.

## Supported formats

This is the list of support formats. We are constantly adding new formats and updating this table.

<Render file="markdown-conversion-support" product="workers-ai" />

## Example

In this example, we fetch a PDF document and an image from R2 and feed them both to `env.AI.toMarkdown`. The result is a list of converted documents. Workers AI models are used automatically to detect and summarize the image.

```typescript
import { Env } from "./env";

export default {
	async fetch(request: Request, env: Env, ctx: ExecutionContext) {
		// https://pub-979cb28270cc461d94bc8a169d8f389d.r2.dev/somatosensory.pdf
		const pdf = await env.R2.get("somatosensory.pdf");

		// https://pub-979cb28270cc461d94bc8a169d8f389d.r2.dev/cat.jpeg
		const cat = await env.R2.get("cat.jpeg");

		return Response.json(
			await env.AI.toMarkdown([
				{
					name: "somatosensory.pdf",
					blob: new Blob([await pdf.arrayBuffer()], {
						type: "application/octet-stream",
					}),
				},
				{
					name: "cat.jpeg",
					blob: new Blob([await cat.arrayBuffer()], {
						type: "application/octet-stream",
					}),
				},
			]),
		);
	},
};
```

This is the result:

```json
[
	{
		"name": "somatosensory.pdf",
		"mimeType": "application/pdf",
		"format": "markdown",
		"tokens": 0,
		"data": "# somatosensory.pdf\n## Metadata\n- PDFFormatVersion=1.4\n- IsLinearized=false\n- IsAcroFormPresent=false\n- IsXFAPresent=false\n- IsCollectionPresent=false\n- IsSignaturesPresent=false\n- Producer=Prince 20150210 (www.princexml.com)\n- Title=Anatomy of the Somatosensory System\n\n## Contents\n### Page 1\nThis is a sample document to showcase..."
	},
	{
		"name": "cat.jpeg",
		"mimeType": "image/jpeg",
		"format": "markdown",
		"tokens": 0,
		"data": "The image is a close-up photograph of Grumpy Cat, a cat with a distinctive grumpy expression and piercing blue eyes. The cat has a brown face with a white stripe down its nose, and its ears are pointed upright. Its fur is light brown and darker around the face, with a pink nose and mouth. The cat's eyes are blue and slanted downward, giving it a perpetually grumpy appearance. The background is blurred, but it appears to be a dark brown color. Overall, the image is a humorous and iconic representation of the popular internet meme character, Grumpy Cat. The cat's facial expression and posture convey a sense of displeasure or annoyance, making it a relatable and entertaining image for many people."
	}
]
```

## REST API

In addition to the Workers AI [binding](/workers-ai/configuration/bindings/), you can use the [REST API](/workers-ai/get-started/rest-api/):

```bash
curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown \
  -H 'Authorization: Bearer {API_TOKEN}' \
	-F "files=@cat.jpeg" \
	-F "files=@somatosensory.pdf"
```

## Pricing

`toMarkdown` is free for most format conversions. In some cases, like image conversion, it can use Workers AI models for object detection and summarization, which may incur additional costs if it exceeds the Workers AI free allocation limits. See the [pricing page](/workers-ai/platform/pricing/) for more details.

---

# Prompting

URL: https://developers.cloudflare.com/workers-ai/features/prompting/

import { Code } from "~/components";

export const scopedExampleOne = `{
  messages: [
    { role: "system", content: "you are a very funny comedian and you like emojis" },
    { role: "user", content: "tell me a joke about cloudflare" },
  ],
};`;

export const scopedExampleTwo = `{
  messages: [
    { role: "system", content: "you are a professional computer science assistant" },
    { role: "user", content: "what is WASM?" },
    { role: "assistant", content: "WASM (WebAssembly) is a binary instruction format that is designed to be a platform-agnostic" },
    { role: "user", content: "does Python compile to WASM?" },
    { role: "assistant", content: "No, Python does not directly compile to WebAssembly" },
    { role: "user", content: "what about Rust?" },
  ],
};`;

export const unscopedExampleOne = `{
  prompt: "tell me a joke about cloudflare";
}`;

export const unscopedExampleTwo = `{
  prompt: "<s>[INST]comedian[/INST]</s>\n[INST]tell me a joke about cloudflare[/INST]",
  raw: true
};`;

Part of getting good results from text generation models is asking questions correctly. LLMs are usually trained with specific predefined templates, which should then be used with the model's tokenizer for better results when doing inference tasks.

There are two ways to prompt text generation models with Workers AI:

:::note[Important]
We recommend using unscoped prompts for inference with LoRA.
:::

### Scoped Prompts

This is the <strong>recommended</strong> method. With scoped prompts, Workers AI takes the burden of knowing and using different chat templates for different models and provides a unified interface to developers when building prompts and creating text generation tasks.

Scoped prompts are a list of messages. Each message defines two keys: the role and the content.

Typically, the role can be one of three options:

- <strong>system</strong> - System messages define the AI's personality. You can
  use them to set rules and how you expect the AI to behave.
- <strong>user</strong> - User messages are where you actually query the AI by
  providing a question or a conversation.
- <strong>assistant</strong> - Assistant messages hint to the AI about the
  desired output format. Not all models support this role.

OpenAI has a [good explanation](https://platform.openai.com/docs/guides/text-generation#messages-and-roles) of how they use these roles with their GPT models. Even though chat templates are flexible, other text generation models tend to follow the same conventions.

Here's an input example of a scoped prompt using system and user roles:

<Code code={scopedExampleOne} lang="js" />

Here's a better example of a chat session using multiple iterations between the user and the assistant.

<Code code={scopedExampleTwo} lang="js" />

Note that different LLMs are trained with different templates for different use cases. While Workers AI tries its best to abstract the specifics of each LLM template from the developer through a unified API, you should always refer to the model documentation for details (we provide links in the table above.) For example, instruct models like Codellama are fine-tuned to respond to a user-provided instruction, while chat models expect fragments of dialogs as input.

### Unscoped Prompts

You can use unscoped prompts to send a single question to the model without worrying about providing any context. Workers AI will automatically convert your `prompt` input to a reasonable default scoped prompt internally so that you get the best possible prediction.

<Code code={unscopedExampleOne} lang="js" />

You can also use unscoped prompts to construct the model chat template manually. In this case, you can use the raw parameter. Here's an input example of a [Mistral](https://docs.mistral.ai/models/#chat-template) chat template prompt:

<Code code={unscopedExampleTwo} lang="js" />

---

# Dashboard

URL: https://developers.cloudflare.com/workers-ai/get-started/dashboard/

import { Render } from "~/components"

Follow this guide to create a Workers AI application using the Cloudflare dashboard.

## Prerequisites

Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages) if you have not already.

## Setup

To create a Workers AI application:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Compute (Workers)** and **Workers & Pages**.
3. Select **Create**.
4. Under **Start from a template**, select **LLM App**. After you select your template, an [AI binding](/workers-ai/configuration/bindings/) will be created for you in the dashboard.
5. Review the provided code and select **Deploy**.
6. Preview your Worker at its provided [`workers.dev`](/workers/configuration/routing/workers-dev/) subdomain.

## Development

<Render file="dash-creation-next-steps" product="workers" />

---

# Getting started

URL: https://developers.cloudflare.com/workers-ai/get-started/

import { DirectoryListing } from "~/components"

There are several options to build your Workers AI projects on Cloudflare. To get started, choose your preferred method:

<DirectoryListing />

:::note


These examples are geared towards creating new Workers AI projects. For help adding Workers AI to an existing Worker, refer to [Workers Bindings](/workers-ai/configuration/bindings/).


:::

---

# REST API

URL: https://developers.cloudflare.com/workers-ai/get-started/rest-api/

This guide will instruct you through setting up and deploying your first Workers AI project. You will use the Workers AI REST API to experiment with a large language model (LLM).

## Prerequisites

Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages) if you have not already.

## 1. Get API token and Account ID

You need your API token and Account ID to use the REST API.

To get these values:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **AI** > **Workers AI**.
3. Select **Use REST API**.
4. Get your API token:
   1. Select **Create a Workers AI API Token**.
   2. Review the prefilled information.
   3. Select **Create API Token**.
   4. Select **Copy API Token**.
   5. Save that value for future use.
5. For **Get Account ID**, copy the value for **Account ID**. Save that value for future use.

:::note

If you choose to [create an API token](/fundamentals/api/get-started/create-token/) instead of using the template, that token will need permissions for both `Workers AI - Read` and `Workers AI - Edit`.

:::

## 2. Run a model via API

After creating your API token, authenticate and make requests to the API using your API token in the request.

You will use the [Execute AI model](/api/resources/ai/methods/run/) endpoint to run the [`@cf/meta/llama-3.1-8b-instruct`](/workers-ai/models/llama-3.1-8b-instruct/) model:

```bash
curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/@cf/meta/llama-3.1-8b-instruct \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -d '{ "prompt": "Where did the phrase Hello World come from" }'
```

Replace the values for `{ACCOUNT_ID}` and `{API_token}`.

The API response will look like the following:

```json
{
	"result": {
		"response": "Hello, World first appeared in 1974 at Bell Labs when Brian Kernighan included it in the C programming language example. It became widely used as a basic test program due to simplicity and clarity. It represents an inviting greeting from a program to the world."
	},
	"success": true,
	"errors": [],
	"messages": []
}
```

This example execution uses the `@cf/meta/llama-3.1-8b-instruct` model, but you can use any of the models in the [Workers AI models catalog](/workers-ai/models/). If using another model, you will need to replace `{model}` with your desired model name.

By completing this guide, you have created a Cloudflare account (if you did not have one already) and an API token that grants Workers AI read permissions to your account. You executed the [`@cf/meta/llama-3.1-8b-instruct`](/workers-ai/models/llama-3.1-8b-instruct/) model using a cURL command from the terminal and received an answer to your prompt in a JSON response.

## Related resources

- [Models](/workers-ai/models/) - Browse the Workers AI models catalog.
- [AI SDK](/workers-ai/configuration/ai-sdk) - Learn how to integrate with an AI model.

---

# Workers Bindings

URL: https://developers.cloudflare.com/workers-ai/get-started/workers-wrangler/

import { Render, PackageManagers, WranglerConfig, TypeScriptExample } from "~/components";

This guide will instruct you through setting up and deploying your first Workers AI project. You will use [Workers](/workers/), a Workers AI binding, and a large language model (LLM) to deploy your first AI-powered application on the Cloudflare global network.

<Render file="prereqs" product="workers" />

## 1. Create a Worker project

You will create a new Worker project using the `create-cloudflare` CLI (C3). [C3](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare) is a command-line tool designed to help you set up and deploy new applications to Cloudflare.

Create a new project named `hello-ai` by running:

<PackageManagers type="create" pkg="cloudflare@latest" args={"hello-ai"} />

Running `npm create cloudflare@latest` will prompt you to install the [`create-cloudflare` package](https://www.npmjs.com/package/create-cloudflare), and lead you through setup. C3 will also install [Wrangler](/workers/wrangler/), the Cloudflare Developer Platform CLI.

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

This will create a new `hello-ai` directory. Your new `hello-ai` directory will include:

- A `"Hello World"` [Worker](/workers/get-started/guide/#3-write-code) at `src/index.ts`.
- A [`wrangler.jsonc`](/workers/wrangler/configuration/) configuration file.

Go to your application directory:

```sh
cd hello-ai
```

## 2. Connect your Worker to Workers AI

You must create an AI binding for your Worker to connect to Workers AI. [Bindings](/workers/runtime-apis/bindings/) allow your Workers to interact with resources, like Workers AI, on the Cloudflare Developer Platform.

To bind Workers AI to your Worker, add the following to the end of your Wrangler file:

<WranglerConfig>

```toml
[ai]
binding = "AI"
```

</WranglerConfig>

Your binding is [available in your Worker code](/workers/reference/migrate-to-module-workers/#bindings-in-es-modules-format) on [`env.AI`](/workers/runtime-apis/handlers/fetch/).

{/* <!-- TODO update this once we know if we'll have it --> */}

You can also bind Workers AI to a Pages Function. For more information, refer to [Functions Bindings](/pages/functions/bindings/#workers-ai).

## 3. Run an inference task in your Worker

You are now ready to run an inference task in your Worker. In this case, you will use an LLM, [`llama-3.1-8b-instruct`](/workers-ai/models/llama-3.1-8b-instruct/), to answer a question.

Update the `index.ts` file in your `hello-ai` application directory with the following code:

<TypeScriptExample filename="index.ts">

```ts
export interface Env {
	// If you set another name in the Wrangler config file as the value for 'binding',
	// replace "AI" with the variable name you defined.
	AI: Ai;
}

export default {
	async fetch(request, env): Promise<Response> {
		const response = await env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
			prompt: "What is the origin of the phrase Hello, World",
		});

		return new Response(JSON.stringify(response));
	},
} satisfies ExportedHandler<Env>;
```
</TypeScriptExample>

Up to this point, you have created an AI binding for your Worker and configured your Worker to be able to execute the Llama 3.1 model. You can now test your project locally before you deploy globally.

## 4. Develop locally with Wrangler

While in your project directory, test Workers AI locally by running [`wrangler dev`](/workers/wrangler/commands/#dev):

```sh
npx wrangler dev
```

<Render file="ai-local-usage-charges" product="workers" />

You will be prompted to log in after you run the `wrangler dev`. When you run `npx wrangler dev`, Wrangler will give you a URL (most likely `localhost:8787`) to review your Worker. After you go to the URL Wrangler provides, a message will render that resembles the following example:

```json
{
	"response": "Ah, a most excellent question, my dear human friend! *adjusts glasses*\n\nThe origin of the phrase \"Hello, World\" is a fascinating tale that spans several decades and multiple disciplines. It all began in the early days of computer programming, when a young man named Brian Kernighan was tasked with writing a simple program to demonstrate the basics of a new programming language called C.\nKernighan, a renowned computer scientist and author, was working at Bell Labs in the late 1970s when he created the program. He wanted to showcase the language's simplicity and versatility, so he wrote a basic \"Hello, World!\" program that printed the familiar greeting to the console.\nThe program was included in Kernighan and Ritchie's influential book \"The C Programming Language,\" published in 1978. The book became a standard reference for C programmers, and the \"Hello, World!\" program became a sort of \"Hello, World!\" for the programming community.\nOver time, the phrase \"Hello, World!\" became a shorthand for any simple program that demonstrated the basics"
}
```

## 5. Deploy your AI Worker

Before deploying your AI Worker globally, log in with your Cloudflare account by running:

```sh
npx wrangler login
```

You will be directed to a web page asking you to log in to the Cloudflare dashboard. After you have logged in, you will be asked if Wrangler can make changes to your Cloudflare account. Scroll down and select **Allow** to continue.

Finally, deploy your Worker to make your project accessible on the Internet. To deploy your Worker, run:

```sh
npx wrangler deploy
```

```sh output
https://hello-ai.<YOUR_SUBDOMAIN>.workers.dev
```

Your Worker will be deployed to your custom [`workers.dev`](/workers/configuration/routing/workers-dev/) subdomain. You can now visit the URL to run your AI Worker.

By finishing this tutorial, you have created a Worker, connected it to Workers AI through an AI binding, and ran an inference task from the Llama 3 model.

## Related resources

- [Cloudflare Developers community on Discord](https://discord.cloudflare.com) - Submit feature requests, report bugs, and share your feedback directly with the Cloudflare team by joining the Cloudflare Discord server.
- [Models](/workers-ai/models/) - Browse the Workers AI models catalog.
- [AI SDK](/workers-ai/configuration/ai-sdk) - Learn how to integrate with an AI model.

---

# Demos and architectures

URL: https://developers.cloudflare.com/workers-ai/guides/demos-architectures/

import {
	ExternalResources,
	GlossaryTooltip,
	ResourcesBySelector,
} from "~/components";

Workers AI can be used to build dynamic and performant services. The following demo applications and reference architectures showcase how to use Workers AI optimally within your architecture.

## Demos

Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for Workers AI.

<ExternalResources type="apps" products={["Workers AI"]} />

## Reference architectures

Explore the following <GlossaryTooltip term="reference architecture">reference architectures</GlossaryTooltip> that use Workers AI:

<ResourcesBySelector
	types={[
		"reference-architecture",
		"design-guide",
		"reference-architecture-diagram",
	]}
	products={["Workers AI"]}
/>

---

# Guides

URL: https://developers.cloudflare.com/workers-ai/guides/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Data usage

URL: https://developers.cloudflare.com/workers-ai/platform/data-usage/

Cloudflare processes certain customer data in order to provide the Workers AI service, subject to our [Privacy Policy](https://www.cloudflare.com/privacypolicy/) and [Self-Serve Subscription Agreement](https://www.cloudflare.com/terms/) or [Enterprise Subscription Agreement](https://www.cloudflare.com/enterpriseterms/) (as applicable).

Cloudflare neither creates nor trains the AI models made available on Workers AI. The models constitute Third-Party Services and may be subject to open source or other license terms that apply between you and the model provider. Be sure to review the license terms applicable to each model (if any).

Your inputs (e.g., text prompts, image submissions, audio files, etc.), outputs (e.g., generated text/images, translations, etc.), embeddings, and training data constitute Customer Content.

For Workers AI:

* You own, and are responsible for, all of your Customer Content.
* Cloudflare does not make your Customer Content available to any other Cloudflare customer.
* Cloudflare does not use your Customer Content to (1) train any AI models made available on Workers AI or (2) improve any Cloudflare or third-party services, and would not do so unless we received your explicit consent.
* Your Customer Content for Workers AI may be stored by Cloudflare if you specifically use a storage service (e.g., R2, KV, DO, Vectorize, etc.) in conjunction with Workers AI.

---

# Models

URL: https://developers.cloudflare.com/workers-ai/models/

import ModelCatalog from "~/pages/workers-ai/models/index.astro";

<ModelCatalog />

---

# Errors

URL: https://developers.cloudflare.com/workers-ai/platform/errors/

Below is a list of Workers AI errors.

| **Name**                              | **Internal Code** | **HTTP Code** | **Description**                                                                                                                                      |
| ------------------------------------- | ----------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| No such model                         | `5007`            | `400`         | No such model `${model}` or task                                                                                                                     |
| Invalid data                          | `5004`            | `400`         | Invalid data type for base64 input: `${type}`                                                                                                        |
| Finetune missing required files       | `3039`            | `400`         | Finetune is missing required files `(model.safetensors and config.json) `                                                                            |
| Incomplete request                    | `3003`            | `400`         | Request is missing headers or body: `{what}`                                                                                                         |
| Account not allowed for private model | `5018`            | `403`         | The account is not allowed to access this model                                                                                                      |
| Model agreement                       | `5016`            | `403`         | User has not agreed to Llama3.2 model terms                                                                                                          |
| Account blocked                       | `3023`            | `403`         | Service unavailable for account                                                                                                                      |
| Account not allowed for private model | `3041`            | `403`         | The account is not allowed to access this model                                                                                                      |
| Deprecated SDK version                | `5019`            | `405`         | Request trying to use deprecated SDK version                                                                                                         |
| LoRa unsupported                      | `5005`            | `405`         | The model `${this.model}` does not support LoRa inference                                                                                            |
| Invalid model ID                      | `3042`            | `404`         | The model name is invalid                                                                                                                            |
| Request too large                     | `3006`            | `413`         | Request is too large                                                                                                                                 |
| Timeout                               | `3007`            | `408`         | Request timeout                                                                                                                                      |
| Aborted                               | `3008`            | `408`         | Request was aborted                                                                                                                                  |
| Account limited                       | `3036`            | `429`         | You have used up your daily free allocation of 10,000 neurons. Please upgrade to Cloudflare's Workers Paid plan if you would like to continue usage. |
| Out of capacity                       | `3040`            | `429`         | No more data centers to forward the request to                                                                                                       |

---

# Glossary

URL: https://developers.cloudflare.com/workers-ai/platform/glossary/

import { Glossary } from "~/components";

Review the definitions for terms used across Cloudflare's Workers AI documentation.

<Glossary product="workers-ai" />

---

# Platform

URL: https://developers.cloudflare.com/workers-ai/platform/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Limits

URL: https://developers.cloudflare.com/workers-ai/platform/limits/

import { Render } from "~/components"

Workers AI is now Generally Available. We've updated our rate limits to reflect this.

Note that model inferences in local mode using Wrangler will also count towards these limits. Beta models may have lower rate limits while we work on performance and scale.

<Render file="custom_requirements" />

Rate limits are default per task type, with some per-model limits defined as follows:

## Rate limits by task type

### [Automatic Speech Recognition](/workers-ai/models/)

* 720 requests per minute

### [Image Classification](/workers-ai/models/)

* 3000 requests per minute

### [Image-to-Text](/workers-ai/models/)

* 720 requests per minute

### [Object Detection](/workers-ai/models/)

* 3000 requests per minute

### [Summarization](/workers-ai/models/)

* 1500 requests per minute

### [Text Classification](/workers-ai/models/)

* 2000 requests per minute

### [Text Embeddings](/workers-ai/models/)

* 3000 requests per minute
* [@cf/baai/bge-large-en-v1.5](/workers-ai/models/bge-large-en-v1.5/) is 1500 requests per minute

### [Text Generation](/workers-ai/models/)

* 300 requests per minute
* [@hf/thebloke/mistral-7b-instruct-v0.1-awq](/workers-ai/models/mistral-7b-instruct-v0.1-awq/) is 400 requests per minute
* [@cf/microsoft/phi-2](/workers-ai/models/phi-2/) is 720 requests per minute
* [@cf/qwen/qwen1.5-0.5b-chat](/workers-ai/models/qwen1.5-0.5b-chat/) is 1500 requests per minute
* [@cf/qwen/qwen1.5-1.8b-chat](/workers-ai/models/qwen1.5-1.8b-chat/) is 720 requests per minute
* [@cf/qwen/qwen1.5-14b-chat-awq](/workers-ai/models/qwen1.5-14b-chat-awq/) is 150 requests per minute
* [@cf/tinyllama/tinyllama-1.1b-chat-v1.0](/workers-ai/models/tinyllama-1.1b-chat-v1.0/) is 720 requests per minute

### [Text-to-Image](/workers-ai/models/)

* 720 requests per minute
* [@cf/runwayml/stable-diffusion-v1-5-img2img](/workers-ai/models/stable-diffusion-v1-5-img2img/) is 1500 requests per minute

### [Translation](/workers-ai/models/)

* 720 requests per minute

---

# Pricing

URL: https://developers.cloudflare.com/workers-ai/platform/pricing/

:::note
Workers AI has updated pricing to be more granular, with per-model unit-based pricing presented, but still billing in neurons in the back end.
:::

Workers AI is included in both the [Free and Paid Workers plans](/workers/platform/pricing/) and is priced at **$0.011 per 1,000 Neurons**.

Our free allocation allows anyone to use a total of **10,000 Neurons per day at no charge**. To use more than 10,000 Neurons per day, you need to sign up for the [Workers Paid plan](/workers/platform/pricing/#workers). On Workers Paid, you will be charged at $0.011 / 1,000 Neurons for any usage above the free allocation of 10,000 Neurons per day.

You can monitor your Neuron usage in the [Cloudflare Workers AI dashboard](https://dash.cloudflare.com/?to=/:account/ai/workers-ai).

All limits reset daily at 00:00 UTC. If you exceed any one of the above limits, further operations will fail with an error.

|              | Free <br/> allocation  | Pricing                       |
| ------------ | ---------------------- | ----------------------------- |
| Workers Free | 10,000 Neurons per day | N/A - Upgrade to Workers Paid |
| Workers Paid | 10,000 Neurons per day | $0.011 / 1,000 Neurons        |

## What are Neurons?

Neurons are our way of measuring AI outputs across different models, representing the GPU compute needed to perform your request. Our serverless model allows you to pay only for what you use without having to worry about renting, managing, or scaling GPUs.

:::note
The Price in Tokens column is equivalent to the Price in Neurons column - the different units are displayed so you can easily compare and understand pricing.
:::

## LLM model pricing

| Model                                        | Price in Tokens                                            | Price in Neurons                                                          |
| -------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- |
| @cf/meta/llama-3.2-1b-instruct               | $0.027 per M input tokens <br/> $0.201 per M output tokens | 2457 neurons per M input tokens <br/> 18252 neurons per M output tokens   |
| @cf/meta/llama-3.2-3b-instruct               | $0.051 per M input tokens <br/> $0.335 per M output tokens | 4625 neurons per M input tokens <br/> 30475 neurons per M output tokens   |
| @cf/meta/llama-3.1-8b-instruct-fp8-fast      | $0.045 per M input tokens <br/> $0.384 per M output tokens | 4119 neurons per M input tokens <br/> 34868 neurons per M output tokens   |
| @cf/meta/llama-3.2-11b-vision-instruct       | $0.049 per M input tokens <br/> $0.676 per M output tokens | 4410 neurons per M input tokens <br/> 61493 neurons per M output tokens   |
| @cf/meta/llama-3.1-70b-instruct-fp8-fast     | $0.293 per M input tokens <br/> $2.253 per M output tokens | 26668 neurons per M input tokens <br/> 204805 neurons per M output tokens |
| @cf/meta/llama-3.3-70b-instruct-fp8-fast     | $0.293 per M input tokens <br/> $2.253 per M output tokens | 26668 neurons per M input tokens <br/> 204805 neurons per M output tokens |
| @cf/deepseek-ai/deepseek-r1-distill-qwen-32b | $0.497 per M input tokens <br/> $4.881 per M output tokens | 45170 neurons per M input tokens <br/> 443756 neurons per M output tokens |
| @cf/mistral/mistral-7b-instruct-v0.1         | $0.110 per M input tokens <br/> $0.190 per M output tokens | 10000 neurons per M input tokens <br/> 17300 neurons per M output tokens  |
| @cf/mistralai/mistral-small-3.1-24b-instruct | $0.351 per M input tokens <br/> $0.555 per M output tokens | 31876 neurons per M input tokens <br/> 50488 neurons per M output tokens  |
| @cf/meta/llama-3.1-8b-instruct               | $0.282 per M input tokens <br/> $0.827 per M output tokens | 25608 neurons per M input tokens <br/> 75147 neurons per M output tokens  |
| @cf/meta/llama-3.1-8b-instruct-fp8           | $0.152 per M input tokens <br/> $0.287 per M output tokens | 13778 neurons per M input tokens <br/> 26128 neurons per M output tokens  |
| @cf/meta/llama-3.1-8b-instruct-awq           | $0.123 per M input tokens <br/> $0.266 per M output tokens | 11161 neurons per M input tokens <br/> 24215 neurons per M output tokens  |
| @cf/meta/llama-3-8b-instruct                 | $0.282 per M input tokens <br/> $0.827 per M output tokens | 25608 neurons per M input tokens <br/> 75147 neurons per M output tokens  |
| @cf/meta/llama-3-8b-instruct-awq             | $0.123 per M input tokens <br/> $0.266 per M output tokens | 11161 neurons per M input tokens <br/> 24215 neurons per M output tokens  |
| @cf/meta/llama-2-7b-chat-fp16                | $0.556 per M input tokens <br/> $6.667 per M output tokens | 50505 neurons per M input tokens <br/> 606061 neurons per M output tokens |
| @cf/meta/llama-guard-3-8b                    | $0.484 per M input tokens <br/> $0.030 per M output tokens | 44003 neurons per M input tokens <br/> 2730 neurons per M output tokens   |
| @cf/meta/llama-4-scout-17b-16e-instruct      | $0.270 per M input tokens <br/> $0.850 per M output tokens | 24545 neurons per M input tokens <br/> 77273 neurons per M output tokens  |
| @cf/google/gemma-3-12b-it                    | $0.345 per M input tokens <br/> $0.556 per M output tokens | 31371 neurons per M input tokens <br/> 50560 neurons per M output tokens  |
| @cf/qwen/qwq-32b                             | $0.660 per M input tokens <br/> $1.000 per M output tokens | 60000 neurons per M input tokens <br/> 90909 neurons per M output tokens  |
| @cf/qwen/qwen2.5-coder-32b-instruct          | $0.660 per M input tokens <br/> $1.000 per M output tokens | 60000 neurons per M input tokens <br/> 90909 neurons per M output tokens  |

## Embeddings model pricing

| Model                      | Price in Tokens           | Price in Neurons                 |
| -------------------------- | ------------------------- | -------------------------------- |
| @cf/baai/bge-small-en-v1.5 | $0.020 per M input tokens | 1841 neurons per M input tokens  |
| @cf/baai/bge-base-en-v1.5  | $0.067 per M input tokens | 6058 neurons per M input tokens  |
| @cf/baai/bge-large-en-v1.5 | $0.204 per M input tokens | 18582 neurons per M input tokens |
| @cf/baai/bge-m3            | $0.012 per M input tokens | 1075 neurons per M input tokens  |

## Other model pricing

| Model                                 | Price in Tokens                                            | Price in Neurons                                                         |
| ------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------ |
| @cf/black-forest-labs/flux-1-schnell  | $0.0000528 per 512x512 tile <br/> $0.0001056 per step      | 4.80 neurons per 512x512 tile <br/> 9.60 neurons per step                |
| @cf/huggingface/distilbert-sst-2-int8 | $0.026 per M input tokens                                  | 2394 neurons per M input tokens                                          |
| @cf/baai/bge-reranker-base            | $0.003 per M input tokens                                  | 283 neurons per M input tokens                                           |
| @cf/meta/m2m100-1.2b                  | $0.342 per M input tokens <br/> $0.342 per M output tokens | 31050 neurons per M input tokens <br/> 31050 neurons per M output tokens |
| @cf/microsoft/resnet-50               | $2.51 per M images                                         | 228055 neurons per M images                                              |
| @cf/openai/whisper                    | $0.0005 per audio minute                                   | 41.14 neurons per audio minute                                           |
| @cf/openai/whisper-large-v3-turbo     | $0.0005 per audio minute                                   | 46.63 neurons per audio minute                                           |
| @cf/myshell-ai/melotts                | $0.0002 per audio minute                                   | 18.63 neurons per audio minute                                           |

---

# CI/CD

URL: https://developers.cloudflare.com/workers/ci-cd/

You can set up continuous integration and continuous deployment (CI/CD) for your Workers by using either the integrated build system, [Workers Builds](#workers-builds), or using [external providers](#external-cicd) to optimize your development workflow.

## Why use CI/CD?

Using a CI/CD pipeline to deploy your Workers is a best practice because it:

- Automates the build and deployment process, removing the need for manual `wrangler deploy` commands.
- Ensures consistent builds and deployments across your team by using the same source control management (SCM) system.
- Reduces variability and errors by deploying in a uniform environment.
- Simplifies managing access to production credentials.

## Which CI/CD should I use?

Choose [Workers Builds](/workers/ci-cd/builds) if you want a fully integrated solution within Cloudflare's ecosystem that requires minimal setup and configuration for GitHub or GitLab users.

We recommend using [external CI/CD providers](/workers/ci-cd/external-cicd) if:

- You have a self-hosted instance of GitHub or GitLabs, which is currently not supported in Workers Builds' [Git integration](/workers/ci-cd/builds/git-integration/)
- You are using a Git provider that is not GitHub or GitLab

## Workers Builds

[Workers Builds](/workers/ci-cd/builds) is Cloudflare's native CI/CD system that allows you to integrate with GitHub or GitLab to automatically deploy changes with each new push to a selected branch (e.g. `main`).

![Workers Builds Workflow Diagram](~/assets/images/workers/platform/ci-cd/workers-builds-workflow.png)

Ready to streamline your Workers deployments? Get started with [Workers Builds](/workers/ci-cd/builds/#get-started).

## External CI/CD

You can also choose to set up your CI/CD pipeline with an external provider.

- [GitHub Actions](/workers/ci-cd/external-cicd/github-actions/)
- [GitLab CI/CD](/workers/ci-cd/external-cicd/gitlab-cicd/)

---

# Compatibility dates

URL: https://developers.cloudflare.com/workers/configuration/compatibility-dates/

import { WranglerConfig } from "~/components";

Cloudflare regularly updates the Workers runtime. These updates apply to all Workers globally and should never cause a Worker that is already deployed to stop functioning. Sometimes, though, some changes may be backwards-incompatible. In particular, there might be bugs in the runtime API that existing Workers may inadvertently depend upon. Cloudflare implements bug fixes that new Workers can opt into while existing Workers will continue to see the buggy behavior to prevent breaking deployed Workers.

The compatibility date and flags are how you, as a developer, opt into these runtime changes. [Compatibility flags](/workers/configuration/compatibility-flags) will often have a date in which they are enabled by default, and so, by specifying a `compatibility_date` for your Worker, you can quickly enable all of these various compatibility flags up to, and including, that date.

## Setting compatibility date

When you start your project, you should always set `compatibility_date` to the current date. You should occasionally update the `compatibility_date` field. When updating, you should refer to the [compatibility flags](/workers/configuration/compatibility-flags) page to find out what has changed, and you should be careful to test your Worker to see if the changes affect you, updating your code as necessary. The new compatibility date takes effect when you next run the [`npx wrangler deploy`](/workers/wrangler/commands/#deploy) command.

There is no need to update your `compatibility_date` if you do not want to. The Workers runtime will support old compatibility dates forever. If, for some reason, Cloudflare finds it is necessary to make a change that will break live Workers, Cloudflare will actively contact affected developers. That said, Cloudflare aims to avoid this if at all possible.

However, even though you do not need to update the `compatibility_date` field, it is a good practice to do so for two reasons:

1. Sometimes, new features can only be made available to Workers that have a current `compatibility_date`. To access the latest features, you need to stay up-to-date.
2. Generally, other than the [compatibility flags](/workers/configuration/compatibility-flags) page, the Workers documentation may only describe the current `compatibility_date`, omitting information about historical behavior. If your Worker uses an old `compatibility_date`, you will need to continuously refer to the compatibility flags page in order to check if any of the APIs you are using have changed.

#### Via Wrangler

The compatibility date can be set in a Worker's [Wrangler configuration file](/workers/wrangler/configuration/).

<WranglerConfig>

```toml
# Opt into backwards-incompatible changes through April 5, 2022.
compatibility_date = "2022-04-05"
```

</WranglerConfig>

#### Via the Cloudflare Dashboard

When a Worker is created through the Cloudflare Dashboard, the compatibility date is automatically set to the current date.

The compatibility date can be updated in the Workers settings on the [Cloudflare dashboard](https://dash.cloudflare.com/).

#### Via the Cloudflare API

The compatibility date can be set when uploading a Worker using the [Workers Script API](/api/resources/workers/subresources/scripts/methods/update/) or [Workers Versions API](/api/resources/workers/subresources/scripts/subresources/versions/methods/create/) in the request body's `metadata` field.

If a compatibility date is not specified on upload via the API, it defaults to the oldest compatibility date, before any flags took effect (2021-11-02). When creating new Workers, it is highly recommended to set the compatibility date to the current date when uploading via the API.

---

# Compatibility flags

URL: https://developers.cloudflare.com/workers/configuration/compatibility-flags/

import { CompatibilityFlags, WranglerConfig, Render } from "~/components";

Compatibility flags enable specific features. They can be useful if you want to help the Workers team test upcoming changes that are not yet enabled by default, or if you need to hold back a change that your code depends on but still want to apply other compatibility changes.

Compatibility flags will often have a date in which they are enabled by default, and so, by specifying a [`compatibility_date`](/workers/configuration/compatibility-dates) for your Worker, you can quickly enable all of these various compatibility flags up to, and including, that date.

## Setting compatibility flags

You may provide a list of `compatibility_flags`, which enable or disable specific changes.

#### Via Wrangler

Compatibility flags can be set in a Worker's [Wrangler configuration file](/workers/wrangler/configuration/).

This example enables the specific flag `formdata_parser_supports_files`, which is described [below](/workers/configuration/compatibility-flags/#formdata-parsing-supports-file). As of the specified date, `2021-09-14`, this particular flag was not yet enabled by default, but, by specifying it in `compatibility_flags`, we can enable it anyway. `compatibility_flags` can also be used to disable changes that became the default in the past.

<WranglerConfig>

```toml
# Opt into backwards-incompatible changes through September 14, 2021.
compatibility_date = "2021-09-14"
# Also opt into an upcoming fix to the FormData API.
compatibility_flags = [ "formdata_parser_supports_files" ]
```

</WranglerConfig>

#### Via the Cloudflare Dashboard

Compatibility flags can be updated in the Workers settings on the [Cloudflare dashboard](https://dash.cloudflare.com/).

#### Via the Cloudflare API

Compatibility flags can be set when uploading a Worker using the [Workers Script API](/api/resources/workers/subresources/scripts/methods/update/) or [Workers Versions API](/api/resources/workers/subresources/scripts/subresources/versions/methods/create/) in the request body's `metadata` field.

## Node.js compatibility flag

:::note
[The `nodejs_compat` flag](/workers/runtime-apis/nodejs/) also enables `nodejs_compat_v2` as long as your compatibility date is 2024-09-23 or later. The v2 flag improves runtime Node.js compatibility by bundling additional polyfills and globals into your Worker. However, this improvement increases bundle size.

If your compatibility date is 2024-09-22 or before and you want to enable v2, add the `nodejs_compat_v2` in addition to the `nodejs_compat` flag.
If your compatibility date is after 2024-09-23, but you want to disable v2 to avoid increasing your bundle size, add the `no_nodejs_compat_v2` in addition to the `nodejs_compat flag`.
:::

A [growing subset](/workers/runtime-apis/nodejs/) of Node.js APIs are available directly as [Runtime APIs](/workers/runtime-apis/nodejs), with no need to add polyfills to your own code. To enable these APIs in your Worker, add the `nodejs_compat` compatibility flag to your [Wrangler configuration file](/workers/wrangler/configuration/):

<Render file="nodejs_compat" product="workers" />

A [growing subset](/workers/runtime-apis/nodejs/) of Node.js APIs are available directly as [Runtime APIs](/workers/runtime-apis/nodejs), with no need to add polyfills to your own code. To enable these APIs in your Worker, only the `nodejs_compat` compatibility flag is required:

<WranglerConfig>

```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_compat" ]
```

</WranglerConfig>

As additional Node.js APIs are added, they will be made available under the `nodejs_compat` compatibility flag. Unlike most other compatibility flags, we do not expect the `nodejs_compat` to become active by default at a future date.

The Node.js `AsyncLocalStorage` API is a particularly useful feature for Workers. To enable only the `AsyncLocalStorage` API, use the `nodejs_als` compatibility flag.

<WranglerConfig>

```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_als" ]
```

</WranglerConfig>

## Flags history

Newest flags are listed first.

<CompatibilityFlags />

## Experimental flags

These flags can be enabled via `compatibility_flags`, but are not yet scheduled to become default on any particular date.

<CompatibilityFlags experimental />

---

# Cron Triggers

URL: https://developers.cloudflare.com/workers/configuration/cron-triggers/

import { Render, WranglerConfig, TabItem, Tabs } from "~/components";

## Background

Cron Triggers allow users to map a cron expression to a Worker using a [`scheduled()` handler](/workers/runtime-apis/handlers/scheduled/) that enables Workers to be executed on a schedule.

Cron Triggers are ideal for running periodic jobs, such as for maintenance or calling third-party APIs to collect up-to-date data. Workers scheduled by Cron Triggers will run on underutilized machines to make the best use of Cloudflare's capacity and route traffic efficiently.

:::note

Cron Triggers can also be combined with [Workflows](/workflows/) to trigger multi-step, long-running tasks. You can [bind to a Workflow](/workflows/build/workers-api/) from directly from your Cron Trigger to execute a Workflow on a schedule.

:::

Cron Triggers execute on UTC time.

## Add a Cron Trigger

### 1. Define a scheduled event listener

To respond to a Cron Trigger, you must add a [`"scheduled"` handler](/workers/runtime-apis/handlers/scheduled/) to your Worker.

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async scheduled(controller, env, ctx) {
		console.log("cron processed");
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Env {}
export default {
	async scheduled(
		controller: ScheduledController,
		env: Env,
		ctx: ExecutionContext,
	) {
		console.log("cron processed");
	},
};
```

</TabItem> <TabItem label="Python" icon="seti:python">

```python
from workers import handler

@handler
async def on_scheduled(controller, env, ctx):
  print("cron processed")
```

</TabItem></Tabs>

Refer to the following additional examples to write your code:

- [Setting Cron Triggers](/workers/examples/cron-trigger/)
- [Multiple Cron Triggers](/workers/examples/multiple-cron-triggers/)

### 2. Update configuration

:::note[Cron Trigger changes take time to propagate.]

Changes such as adding a new Cron Trigger, updating an old Cron Trigger, or deleting a Cron Trigger may take several minutes (up to 15 minutes) to propagate to the Cloudflare global network.

:::

After you have updated your Worker code to include a `"scheduled"` event, you must update your Worker project configuration.

#### Via the [Wrangler configuration file](/workers/wrangler/configuration/)

If a Worker is managed with Wrangler, Cron Triggers should be exclusively managed through the [Wrangler configuration file](/workers/wrangler/configuration/).

Refer to the example below for a Cron Triggers configuration:

<WranglerConfig>

```toml
[triggers]
# Schedule cron triggers:
# - At every 3rd minute
# - At 15:00 (UTC) on first day of the month
# - At 23:59 (UTC) on the last weekday of the month
crons = [ "*/3 * * * *", "0 15 1 * *", "59 23 LW * *" ]
```

</WranglerConfig>

You also can set a different Cron Trigger for each [environment](/workers/wrangler/environments/) in your [Wrangler configuration file](/workers/wrangler/configuration/). You need to put the `triggers` array under your chosen environment. For example:

<WranglerConfig>

```toml
[env.dev.triggers]
crons = ["0 * * * *"]
```

</WranglerConfig>

#### Via the dashboard

To add Cron Triggers in the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In Account Home, select **Workers & Pages**.
3. In **Overview**, select your Worker > **Settings** > **Triggers** > **Cron Triggers**.

## Supported cron expressions

Cloudflare supports cron expressions with five fields, along with most [Quartz scheduler](http://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html#introduction)-like cron syntax extensions:

| Field         | Values                                                             | Characters   |
| ------------- | ------------------------------------------------------------------ | ------------ |
| Minute        | 0-59                                                               | \* , - /     |
| Hours         | 0-23                                                               | \* , - /     |
| Days of Month | 1-31                                                               | \* , - / L W |
| Months        | 1-12, case-insensitive 3-letter abbreviations ("JAN", "aug", etc.) | \* , - /     |
| Weekdays      | 1-7, case-insensitive 3-letter abbreviations ("MON", "fri", etc.)  | \* , - / L # |

:::note

Days of the week go from 1 = Sunday to 7 = Saturday, which is different on some other cron systems (where 0 = Sunday and 6 = Saturday).
To avoid ambiguity you may prefer to use the three-letter abbreviations (e.g. `SUN` rather than 1).

:::

### Examples

Some common time intervals that may be useful for setting up your Cron Trigger:

- `* * * * *`

  - At every minute

- `*/30 * * * *`

  - At every 30th minute

- `45 * * * *`

  - On the 45th minute of every hour

- `0 17 * * sun` or `0 17 * * 1`

  - 17:00 (UTC) on Sunday

- `10 7 * * mon-fri` or `10 7 * * 2-6`

  - 07:10 (UTC) on weekdays

- `0 15 1 * *`

  - 15:00 (UTC) on first day of the month

- `0 18 * * 6L` or `0 18 * * friL`

  - 18:00 (UTC) on the last Friday of the month

- `59 23 LW * *`
  - 23:59 (UTC) on the last weekday of the month

## Test Cron Triggers locally

Test Cron Triggers using Wrangler with [`wrangler dev`](/workers/wrangler/commands/#dev). This will expose a `/cdn-cgi/handler/scheduled` route which can be used to test using a HTTP request.

```sh
curl "http://localhost:8787/cdn-cgi/handler/scheduled"
```

To simulate different cron patterns, a `cron` query parameter can be passed in.

```sh
curl "http://localhost:8787/cdn-cgi/handler/scheduled?cron=*+*+*+*+*"
```

Optionally, you can also pass a `time` query parameter to override `controller.scheduledTime` in your scheduled event listener.

```sh
curl "http://localhost:8787/cdn-cgi/handler/scheduled?cron=*+*+*+*+*&time=1745856238"
```

## View past events

To view the execution history of Cron Triggers, view **Cron Events**:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In Account Home, go to **Workers & Pages**.
3. In **Overview**, select your **Worker**.
4. Select **Settings**.
5. Under **Trigger Events**, select **View events**.

Cron Events stores the 100 most recent invocations of the Cron scheduled event. [Workers Logs](/workers/observability/logs/workers-logs) also records invocation logs for the Cron Trigger with a longer retention period and a filter & query interface. If you are interested in an API to access Cron Events, use Cloudflare's [GraphQL Analytics API](/analytics/graphql-api).

:::note

It can take up to 30 minutes before events are displayed in **Past Cron Events** when creating a new Worker or changing a Worker's name.

:::

Refer to [Metrics and Analytics](/workers/observability/metrics-and-analytics/) for more information.

## Remove a Cron Trigger

### Via the dashboard

To delete a Cron Trigger on a deployed Worker via the dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Workers & Pages**, and select your Worker.
3. Go to **Triggers** > select the three dot icon next to the Cron Trigger you want to remove > **Delete**.

#### Via the [Wrangler configuration file](/workers/wrangler/configuration/)

If a Worker is managed with Wrangler, Cron Triggers should be exclusively managed through the [Wrangler configuration file](/workers/wrangler/configuration/).

When deploying a Worker with Wrangler any previous Cron Triggers are replaced with those specified in the `triggers` array.

- If the `crons` property is an empty array then all the Cron Triggers are removed.
- If the `triggers` or `crons` property are `undefined` then the currently deploy Cron Triggers are left in-place.

<WranglerConfig>

```toml
[triggers]
# Remove all cron triggers:
crons = [ ]
```

</WranglerConfig>

## Limits

Refer to [Limits](/workers/platform/limits/) to track the maximum number of Cron Triggers per Worker.

## Green Compute

With Green Compute enabled, your Cron Triggers will only run on Cloudflare points of presence that are located in data centers that are powered purely by renewable energy. Organizations may claim that they are powered by 100 percent renewable energy if they have procured sufficient renewable energy to account for their overall energy use.

Renewable energy can be purchased in a number of ways, including through on-site generation (wind turbines, solar panels), directly from renewable energy producers through contractual agreements called Power Purchase Agreements (PPA), or in the form of Renewable Energy Credits (REC, IRECs, GoOs) from an energy credit market.

Green Compute can be configured at the account level:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In Account Home, select **Workers & Pages**.
3. In the **Account details** section, find **Compute Setting**.
4. Select **Change**.
5. Select **Green Compute**.
6. Select **Confirm**.

## Related resources

- [Triggers](/workers/wrangler/configuration/#triggers) - Review Wrangler configuration file syntax for Cron Triggers.
- Learn how to access Cron Triggers in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.

---

# Environment variables

URL: https://developers.cloudflare.com/workers/configuration/environment-variables/

import { Render, TabItem, Tabs, WranglerConfig } from "~/components";

## Background

You can add environment variables, which are a type of binding, to attach text strings or JSON values to your Worker. Environment variables are available on the [`env` parameter](/workers/runtime-apis/handlers/fetch/#parameters) passed to your Worker's [`fetch` event handler](/workers/runtime-apis/handlers/fetch/).

Text strings and JSON values are not encrypted and are useful for storing application configuration.

## Add environment variables via Wrangler

To add env variables using Wrangler, define text and JSON via the `[vars]` configuration in your Wrangler file. In the following example, `API_HOST` and `API_ACCOUNT_ID` are text values and `SERVICE_X_DATA` is a JSON value.

<Render file="envvar-example" />

Refer to the following example on how to access the `API_HOST` environment variable in your Worker code:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request, env, ctx) {
		return new Response(`API host: ${env.API_HOST}`);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export interface Env {
	API_HOST: string;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		return new Response(`API host: ${env.API_HOST}`);
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

### Configuring different environments in Wrangler

[Environments in Wrangler](/workers/wrangler/environments) let you specify different configurations for the same Worker, including different values for `vars` in each environment.
As `vars` is a [non-inheritable key](/workers/wrangler/configuration/#non-inheritable-keys), they are not inherited by environments and must be specified for each environment.

The example below sets up two environments, `staging` and `production`, with different values for `API_HOST`.

<WranglerConfig>

```toml
name = "my-worker-dev"

# top level environment
[vars]
API_HOST = "api.example.com"

[env.staging.vars]
API_HOST = "staging.example.com"

[env.production.vars]
API_HOST = "production.example.com"
```

</WranglerConfig>

To run Wrangler commands in specific environments, you can pass in the `--env` or `-e` flag. For example, you can develop the Worker in an environment called `staging` by running `npx wrangler dev --env staging`, and deploy it with `npx wrangler deploy --env staging`.

Learn about [environments in Wrangler](/workers/wrangler/environments).

## Add environment variables via the dashboard

To add environment variables via the dashboard:

1. Log in to [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Select **Workers & Pages**.
3. In **Overview**, select your Worker.
4. Select **Settings**.
5. Under **Variables and Secrets**, select **Add**.
6. Select a **Type**, input a **Variable name**, and input its **Value**. This variable will be made available to your Worker.
7. (Optional) To add multiple environment variables, select **Add variable**.
8. Select **Deploy** to implement your changes.

:::caution[Plaintext strings and secrets]
Select the **Secret** type if your environment variable is a [secret](/workers/configuration/secrets/). Alternatively, consider [Cloudflare Secrets Store](/secrets-store/), for account-level secrets.
:::

<Render file="env_and_secrets" />

<Render file="secrets-in-dev" />

## Related resources

- Migrating environment variables from [Service Worker format to ES modules syntax](/workers/reference/migrate-to-module-workers/#environment-variables).

---

# Configuration

URL: https://developers.cloudflare.com/workers/configuration/

import { DirectoryListing } from "~/components";

Configure your Worker project with various features and customizations.

<DirectoryListing />

---

# Multipart upload metadata

URL: https://developers.cloudflare.com/workers/configuration/multipart-upload-metadata/

import { Type, MetaInfo } from "~/components";

If you're using the [Workers Script Upload API](/api/resources/workers/subresources/scripts/methods/update/) or [Version Upload API](/api/resources/workers/subresources/scripts/subresources/versions/methods/create/) directly, `multipart/form-data` uploads require you to specify a `metadata` part. This metadata defines the Worker's configuration in JSON format, analogue to the [wrangler.toml file](/workers/wrangler/configuration/).

## Sample `metadata`

```json
{
	"main_module": "main.js",
	"bindings": [
		{
			"type": "plain_text",
			"name": "MESSAGE",
			"text": "Hello, world!"
		}
	],
	"compatibility_date": "2021-09-14"
}
```

:::note

See examples of metadata being used with the Workers Script Upload API [here](/workers/platform/infrastructure-as-code#cloudflare-rest-api).
:::

## Attributes

The following attributes are configurable at the top-level.

:::note

At a minimum, the `main_module` key is required to upload a Worker.
:::

- `main_module` <Type text="string" /> <MetaInfo text="required" />

  - The part name that contains the module entry point of the Worker that will be executed. For example, `main.js`.

- `assets` <Type text="object" /> <MetaInfo text="optional" />

  - [Asset](/workers/static-assets/) configuration for a Worker.
  - `config` <Type text="object" /> <MetaInfo text="optional" />
    - [html_handling](/workers/static-assets/routing/advanced/html-handling/) determines the redirects and rewrites of requests for HTML content.
    - [not_found_handling](/workers/static-assets/#routing-behavior) determines the response when a request does not match a static asset.
  - `jwt` field provides a token authorizing assets to be attached to a Worker.

- `keep_assets` <Type text="boolean" /> <MetaInfo text="optional" />

  - Specifies whether assets should be retained from a previously uploaded Worker version; used in lieu of providing a completion token.

- `bindings` array\[object] optional

  - [Bindings](#bindings) to expose in the Worker.

- `placement` <Type text="object" /> <MetaInfo text="optional" />

  - [Smart placement](/workers/configuration/smart-placement/) object for the Worker.
  - `mode` field only supports `smart` for automatic placement.

- `compatibility_date` <Type text="string" /> <MetaInfo text="optional" />

  - [Compatibility Date](/workers/configuration/compatibility-dates/#setting-compatibility-date) indicating targeted support in the Workers runtime. Backwards incompatible fixes to the runtime following this date will not affect this Worker. Highly recommended to set a `compatibility_date`, otherwise if on upload via the API, it defaults to the oldest compatibility date before any flags took effect (2021-11-02).

- `compatibility_flags` array\[string] optional

  - [Compatibility Flags](/workers/configuration/compatibility-flags/#setting-compatibility-flags) that enable or disable certain features in the Workers runtime. Used to enable upcoming features or opt in or out of specific changes not included in a `compatibility_date`.

## Additional attributes: [Workers Script Upload API](/api/resources/workers/subresources/scripts/methods/update/)

For [immediately deployed uploads](/workers/configuration/versions-and-deployments/#upload-a-new-version-and-deploy-it-immediately), the following **additional** attributes are configurable at the top-level.

:::note

These attributes are **not available** for version uploads.
:::

- `migrations` array\[object] optional

  - [Durable Objects migrations](/durable-objects/reference/durable-objects-migrations/) to apply.

- `logpush` <Type text="boolean" /> <MetaInfo text="optional" />

  - Whether [Logpush](/cloudflare-for-platforms/cloudflare-for-saas/hostname-analytics/#logpush) is turned on for the Worker.

- `tail_consumers` array\[object] optional

  - [Tail Workers](/workers/observability/logs/tail-workers/) that will consume logs from the attached Worker.

- `tags` array\[string] optional

  - List of strings to use as tags for this Worker.

## Additional attributes: [Version Upload API](/api/resources/workers/subresources/scripts/subresources/versions/methods/create/)

For [version uploads](/workers/configuration/versions-and-deployments/#upload-a-new-version-to-be-gradually-deployed-or-deployed-at-a-later-time), the following **additional** attributes are configurable at the top-level.

:::note

These attributes are **not available** for immediately deployed uploads.
:::

- `annotations` <Type text="object" /> <MetaInfo text="optional" />

  - Annotations object specific to the Worker version.
  - `workers/message` specifies a custom message for the version.
  - `workers/tag` specifies a custom identifier for the version.

## Bindings

Workers can interact with resources on the Cloudflare Developer Platform using [bindings](/workers/runtime-apis/bindings/). Refer to the JSON example below that shows how to add bindings in the `metadata` part.

```json
{
	"bindings": [
		{
			"type": "ai",
			"name": "<VARIABLE_NAME>"
		},
		{
			"type": "analytics_engine",
			"name": "<VARIABLE_NAME>",
			"dataset": "<DATASET>"
		},
		{
			"type": "assets",
			"name": "<VARIABLE_NAME>"
		},
		{
			"type": "browser_rendering",
			"name": "<VARIABLE_NAME>"
		},
		{
			"type": "d1",
			"name": "<VARIABLE_NAME>",
			"id": "<D1_ID>"
		},
		{
			"type": "durable_object_namespace",
			"name": "<VARIABLE_NAME>",
			"class_name": "<DO_CLASS_NAME>"
		},
		{
			"type": "hyperdrive",
			"name": "<VARIABLE_NAME>",
			"id": "<HYPERDRIVE_ID>"
		},
		{
			"type": "kv_namespace",
			"name": "<VARIABLE_NAME>",
			"namespace_id": "<KV_ID>"
		},
		{
			"type": "mtls_certificate",
			"name": "<VARIABLE_NAME>",
			"certificate_id": "<MTLS_CERTIFICATE_ID>"
		},
		{
			"type": "plain_text",
			"name": "<VARIABLE_NAME>",
			"text": "<VARIABLE_VALUE>"
		},
		{
			"type": "queue",
			"name": "<VARIABLE_NAME>",
			"queue_name": "<QUEUE_NAME>"
		},
		{
			"type": "r2_bucket",
			"name": "<VARIABLE_NAME>",
			"bucket_name": "<R2_BUCKET_NAME>"
		},
		{
			"type": "secret_text",
			"name": "<VARIABLE_NAME>",
			"text": "<SECRET_VALUE>"
		},
		{
			"type": "service",
			"name": "<VARIABLE_NAME>",
			"service": "<SERVICE_NAME>",
			"environment": "production"
		},
		{
			"type": "tail_consumer",
			"service": "<WORKER_NAME>"
		},
		{
			"type": "vectorize",
			"name": "<VARIABLE_NAME>",
			"index_name": "<INDEX_NAME>"
		},
		{
			"type": "version_metadata",
			"name": "<VARIABLE_NAME>"
		}
	]
}
```

---

# Secrets

URL: https://developers.cloudflare.com/workers/configuration/secrets/

import { Render } from "~/components";

## Background

Secrets are a type of binding that allow you to attach encrypted text values to your Worker. You cannot see secrets after you set them and can only access secrets via [Wrangler](/workers/wrangler/commands/#secret) or programmatically via the [`env` parameter](/workers/runtime-apis/handlers/fetch/#parameters). Secrets are used for storing sensitive information like API keys and auth tokens. Secrets are available on the [`env` parameter](/workers/runtime-apis/handlers/fetch/#parameters) passed to your Worker's [`fetch` event handler](/workers/runtime-apis/handlers/fetch/).

:::note[Secrets Store (beta)]
Secrets described on this page are defined and managed on a per-Worker level. If you want to use account-level secrets, refer to [Secrets Store](/secrets-store/). Account-level secrets are configured on your Worker as a [Secrets Store binding](/secrets-store/integrations/workers/).
:::

## Local Development with Secrets

<Render file="secrets-in-dev" />

## Secrets on deployed Workers

### Adding secrets to your project

#### Via Wrangler

Secrets can be added through [`wrangler secret put`](/workers/wrangler/commands/#secret) or [`wrangler versions secret put`](/workers/wrangler/commands/#secret-put) commands.

`wrangler secret put` creates a new version of the Worker and deploys it immediately.

```sh
npx wrangler secret put <KEY>
```

If using [gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/), instead use the `wrangler versions secret put` command. This will only create a new version of the Worker, that can then be deploying using [`wrangler versions deploy`](/workers/wrangler/commands/#deploy-2).

:::note
Wrangler versions before 3.73.0 require you to specify a `--x-versions` flag.
:::

```sh
npx wrangler versions secret put <KEY>
```

#### Via the dashboard

To add a secret via the dashboard:

1. Log in to [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Select **Workers & Pages**.
3. In **Overview**, select your Worker > **Settings**.
4. Under **Variables and Secrets**, select **Add**.
5. Select the type **Secret**, input a **Variable name**, and input its **Value**. This secret will be made available to your Worker but the value will be hidden in Wrangler and the dashboard.
6. (Optional) To add more secrets, select **Add variable**.
7. Select **Deploy** to implement your changes.

### Delete secrets from your project

#### Via Wrangler

Secrets can be deleted through [`wrangler secret delete`](/workers/wrangler/commands/#delete-1) or [`wrangler versions secret delete`](/workers/wrangler/commands/#secret-delete) commands.

`wrangler secret delete` creates a new version of the Worker and deploys it immediately.

```sh
npx wrangler secret delete <KEY>
```

If using [gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/), instead use the `wrangler versions secret delete` command. This will only create a new version of the Worker, that can then be deploying using [`wrangler versions deploy`](/workers/wrangler/commands/#deploy-2).

```sh
npx wrangler versions secret delete <KEY>
```

#### Via the dashboard

To delete a secret from your Worker project via the dashboard:

1. Log in to [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Select **Workers & Pages**.
3. In **Overview**, select your Worker > **Settings**.
4. Under **Variables and Secrets**, select **Edit**.
5. In the **Edit** drawer, select **X** next to the secret you want to delete.
6. Select **Deploy** to implement your changes.
7. (Optional) Instead of using the edit drawer, you can click the delete icon next to the secret.

<Render file="env_and_secrets" />

## Related resources

- [Wrangler secret commands](/workers/wrangler/commands/#secret) - Review the Wrangler commands to create, delete and list secrets.
- [Cloudflare Secrets Store](/secrets-store/) - Encrypt and store sensitive information as secrets that are securely reusable across your account.

---

# Preview URLs

URL: https://developers.cloudflare.com/workers/configuration/previews/

import { Render, WranglerConfig } from "~/components";

Preview URLs allow you to preview new versions of your Worker without deploying it to production.

Every time you create a new [version](/workers/configuration/versions-and-deployments/#versions) of your Worker a unique preview URL is generated. Preview URLs take the format: `<VERSION_PREFIX>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev`. New [versions](/workers/configuration/versions-and-deployments/#versions) of a Worker are created on [`wrangler deploy`](/workers/wrangler/commands/#deploy), [`wrangler versions upload`](/workers/wrangler/commands/#upload) or when you make edits on the Cloudflare dashboard. By default, preview URLs are enabled and available publicly.

Preview URLs can be:

- Integrated into CI/CD pipelines, allowing automatic generation of preview environments for every pull request.
- Used for collaboration between teams to test code changes in a live environment and verify updates.
- Used to test new API endpoints, validate data formats, and ensure backward compatibility with existing services.

When testing zone level performance or security features for a version, we recommend using [version overrides](/workers/configuration/versions-and-deployments/gradual-deployments/#version-overrides) so that your zone's performance and security settings apply.

:::note
Preview URLs are only available for Worker versions uploaded after 2024-09-25.

Minimum required Wrangler version: 3.74.0. Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/).
:::

## View preview URLs using wrangler

The [`wrangler versions upload`](/workers/wrangler/commands/#upload) command uploads a new [version](/workers/configuration/versions-and-deployments/#versions) of your Worker and returns a preview URL for each version uploaded.

## View preview URLs on the Workers dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers) and select your project.
2. Go to the **Deployments** tab, and find the version you would like to view.

## Manage access to Preview URLs

By default, preview URLs are enabled and available publicly. You can use [Cloudflare Access](/cloudflare-one/policies/access/) to require visitors to authenticate before accessing preview URLs. You can limit access to yourself, your teammates, your organization, or anyone else you specify in your [access policy](/cloudflare-one/policies/access).

To limit your preview URLs to authorized emails only:

1. Log in to the [Cloudflare Access dashboard](https://one.dash.cloudflare.com/?to=/:account/access/apps).
2. Select your account.
3. Add an application.
4. Select **Self Hosted**.
5. Name your application (for example, "my-worker") and add your `workers.dev` subdomain as the **Application domain**.

For example, if you want to secure preview URLs for a Worker running on `my-worker.my-subdomain.workers.dev`.

- Subdomain: `*-my-worker`
- Domain: `my-subdomain.workers.dev`

:::note
You must press enter after you input your Application domain for it to save. You will see a "Zone is not associated with the current account" warning that you may ignore.
:::

6. Go to the next page.
7. Add a name for your access policy (for example, "Allow employees access to preview URLs for my-worker").
8. In the **Configure rules** section create a new rule with the **Emails** selector, or any other attributes which you wish to gate access to previews with.
9. Enter the emails you want to authorize. View [access policies](/cloudflare-one/policies/access/#selectors) to learn about configuring alternate rules.
10. Go to the next page.
11. Add application.

## Disabling Preview URLs

### Disabling Preview URLs in the dashboard

To disable Preview URLs for a Worker:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Workers & Pages** and in **Overview**, select your Worker.
3. Go to **Settings** > **Domains & Routes**.
4. On "Preview URLs" click "Disable".
5. Confirm you want to disable.

### Disabling Preview URLs in the [Wrangler configuration file](/workers/wrangler/configuration/)

:::note
Wrangler 3.91.0 or higher is required to use this feature.
:::

To disable Preview URLs for a Worker, include the following in your Worker's Wrangler file:

<WranglerConfig>

```toml
preview_urls = false
```

</WranglerConfig>

When you redeploy your Worker with this change, Preview URLs will be disabled.

:::caution

If you disable Preview URLs in the Cloudflare dashboard but do not update your Worker's Wrangler file with `preview_urls = false`, then Preview URLs will be re-enabled the next time you deploy your Worker with Wrangler.
:::

## Limitations

- Preview URLs are not generated for Workers that implement a [Durable Object](/durable-objects/).
- Preview URLs are not currently generated for [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/) [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers). This is a temporary limitation, we are working to remove it.
- You cannot currently configure Preview URLs to run on a subdomain other than [`workers.dev`](/workers/configuration/routing/workers-dev/).
- You cannot view logs for Preview URLs today, this includes Workers Logs, Wrangler tail and Logpush.

---

# Smart Placement

URL: https://developers.cloudflare.com/workers/configuration/smart-placement/

import { WranglerConfig } from "~/components";

By default, [Workers](/workers/) and [Pages Functions](/pages/functions/) are invoked in a data center closest to where the request was received. If you are running back-end logic in a Worker, it may be more performant to run that Worker closer to your back-end infrastructure rather than the end user. Smart Placement automatically places your workloads in an optimal location that minimizes latency and speeds up your applications.

## Background

The following example demonstrates how moving your Worker close to your back-end services could decrease application latency:

You have a user in Sydney, Australia who is accessing an application running on Workers. This application makes multiple round trips to a database located in Frankfurt, Germany in order to serve the user’s request.

![A user located in Sydney, AU connecting to a Worker in the same region which then makes multiple round trips to a database located in Frankfurt, DE. ](~/assets/images/workers/platform/workers-smart-placement-disabled.png)

The issue is the time that it takes the Worker to perform multiple round trips to the database. Instead of the request being processed close to the user, the Cloudflare network, with Smart Placement enabled, would process the request in a data center closest to the database.

![A user located in Sydney, AU connecting to a Worker in Frankfurt, DE which then makes multiple round trips to a database also located in Frankfurt, DE. ](~/assets/images/workers/platform/workers-smart-placement-enabled.png)

## Understand how Smart Placement works

Smart Placement is enabled on a per-Worker basis. Once enabled, Smart Placement analyzes the [request duration](/workers/observability/metrics-and-analytics/#request-duration) of the Worker in different Cloudflare locations around the world on a regular basis. Smart Placement decides where to run the Worker by comparing the estimated request duration in the location closest to where the request was received (the default location where the Worker would run) to a set of candidate locations around the world. For each candidate location, Smart Placement considers the performance of the Worker in that location as well as the network latency added by forwarding the request to that location. If the estimated request duration in the best candidate location is significantly faster than the location where the request was received, the request will be forwarded to that candidate location. Otherwise, the Worker will run in the default location closest to where the request was received.

Smart Placement only considers candidate locations where the Worker has previously run, since the estimated request duration in each candidate location is based on historical data from the Worker running in that location. This means that Smart Placement cannot run the Worker in a location that it does not normally receive traffic from.

Smart Placement only affects the execution of [fetch event handlers](/workers/runtime-apis/handlers/fetch/). Smart Placement does not affect the execution of [RPC methods](/workers/runtime-apis/rpc/) or [named entrypoints](/workers/runtime-apis/bindings/service-bindings/rpc/#named-entrypoints). Workers without a fetch event handler will be ignored by Smart Placement. For Workers with both fetch and non-fetch event handlers, Smart Placement will only affect the execution of the fetch event handler.

Similarly, Smart Placement will not affect where [static assets](/workers/static-assets/) are served from. Static assets will continue to be served from the location nearest to the incoming request. If a Worker is invoked and your code retrieves assets via the [static assets binding](https://developers.cloudflare.com/workers/static-assets/binding/), then assets will be served from the location that your Worker runs in.

## Enable Smart Placement

Smart Placement is available to users on all Workers plans.

### Enable Smart Placement via Wrangler

To enable Smart Placement via Wrangler:

1. Make sure that you have `wrangler@2.20.0` or later [installed](/workers/wrangler/install-and-update/).

2. Add the following to your Worker project's Wrangler file:

   <WranglerConfig>

   ```toml
   [placement]
   mode = "smart"
   ```

   </WranglerConfig>

3. Wait for Smart Placement to analyze your Worker. This process may take up to 15 minutes.

4. View your Worker's [request duration analytics](/workers/observability/metrics-and-analytics/#request-duration).

### Enable Smart Placement via the dashboard

To enable Smart Placement via the dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. In **Overview**,select your Worker.
4. Select **Settings** > **General**.
5. Under **Placement**, choose **Smart**.
6. Wait for Smart Placement to analyze your Worker. Smart Placement requires consistent traffic to the Worker from multiple locations around the world to make a placement decision. The analysis process may take up to 15 minutes.
7. View your Worker's [request duration analytics](/workers/observability/metrics-and-analytics/#request-duration)

## Observability

### Placement Status

A Worker's metadata contains details about a Worker's placement status. Query your Worker's placement status through the following Workers API endpoint:

```bash
curl -X GET https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/workers/services/{WORKER_NAME} \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" | jq .
```

Possible placement states include:

- _(not present)_: The Worker has not been analyzed for Smart Placement yet. The Worker will always run in the default Cloudflare location closest to where the request was received.
- `SUCCESS`: The Worker was successfully analyzed and will be optimized by Smart Placement. The Worker will run in the Cloudflare location that minimizes expected request duration, which may be the default location closest to where the request was received or may be a faster location elsewhere in the world.
- `INSUFFICIENT_INVOCATIONS`: The Worker has not received enough requests to make a placement decision. Smart Placement requires consistent traffic to the Worker from multiple locations around the world. The Worker will always run in the default Cloudflare location closest to where the request was received.
- `UNSUPPORTED_APPLICATION`: Smart Placement began optimizing the Worker and measured the results, which showed that Smart Placement made the Worker slower. In response, Smart Placement reverted the placement decision. The Worker will always run in the default Cloudflare location closest to where the request was received, and Smart Placement will not analyze the Worker again until it's redeployed. This state is rare and accounts for less that 1% of Workers with Smart Placement enabled.

### Request Duration Analytics

Once Smart Placement is enabled, data about request duration gets collected. Request duration is measured at the data center closest to the end user.

By default, one percent (1%) of requests are not routed with Smart Placement. These requests serve as a baseline to compare to.

### `cf-placement` header

Once Smart Placement is enabled, Cloudflare adds a `cf-placement` header to all requests. This can be used to check whether a request has been routed with Smart Placement and where the Worker is processing the request (which is shown as the nearest airport code to the data center).

For example, the `cf-placement: remote-LHR` header's `remote` value indicates that the request was routed using Smart Placement to a Cloudflare data center near London. The `cf-placement: local-EWR` header's `local` value indicates that the request was not routed using Smart Placement and the Worker was invoked in a data center closest to where the request was received, close to Newark Liberty International Airport (EWR).

:::caution[Beta use only]

We may remove the `cf-placement` header before Smart Placement enters general availability.

:::

## Best practices

If you are building full-stack applications on Workers, we recommend splitting up the front-end and back-end logic into different Workers and using [Service Bindings](/workers/runtime-apis/bindings/service-bindings/) to connect your front-end logic and back-end logic Workers.

![Smart Placement and Service Bindings](~/assets/images/workers/platform/smart-placement-service-bindings.png)

Enabling Smart Placement on your back-end Worker will invoke it close to your back-end service, while the front-end Worker serves requests close to the user. This architecture maintains fast, reactive front-ends while also improving latency when the back-end Worker is called.

## Give feedback on Smart Placement

Smart Placement is in beta. To share your thoughts and experience with Smart Placement, join the [Cloudflare Developer Discord](https://discord.cloudflare.com).

---

# Page Rules

URL: https://developers.cloudflare.com/workers/configuration/workers-with-page-rules/

Page Rules trigger certain actions whenever a request matches one of the URL patterns you define. You can define a page rule to trigger one or more actions whenever a certain URL pattern is matched. Refer to [Page Rules](/rules/page-rules/) to learn more about configuring Page Rules.

## Page Rules with Workers

Cloudflare acts as a [reverse proxy](https://www.cloudflare.com/learning/what-is-cloudflare/) to provide services, like Page Rules, to Internet properties. Your application's traffic will pass through a Cloudflare data center that is closest to the visitor. There are hundreds of these around the world, each of which are capable of running services like Workers and Page Rules. If your application is built on Workers and/or Pages, the [Cloudflare global network](https://www.cloudflare.com/learning/serverless/glossary/what-is-edge-computing/) acts as your origin server and responds to requests directly from the Cloudflare global network.

When using Page Rules with Workers, the following workflow is applied.

1. Request arrives at Cloudflare data center.
2. Cloudflare decides if this request is a Worker route. Because this is a Worker route, Cloudflare evaluates and disabled a number of features, including some that would be set by Page Rules.
3. Page Rules run as part of normal request processing with some features now disabled.
4. Worker executes.
5. Worker makes a same-zone or other-zone subrequest. Because this is a Worker route, Cloudflare disables a number of features, including some that would be set by Page Rules.

Page Rules are evaluated both at the client-to-Worker request stage (step 2) and the Worker subrequest stage (step 5).

If you are experiencing Page Rule errors when running Workers, contact your Cloudflare account team or [Cloudflare Support](/support/contacting-cloudflare-support/).

## Affected Page Rules

The following Page Rules may not work as expected when an incoming request is matched to a Worker route:

* Always Online
* [Always Use HTTPS](/workers/configuration/workers-with-page-rules/#always-use-https)
* [Automatic HTTPS Rewrites](/workers/configuration/workers-with-page-rules/#automatic-https-rewrites)
* [Browser Cache TTL](/workers/configuration/workers-with-page-rules/#browser-cache-ttl)
* [Browser Integrity Check](/workers/configuration/workers-with-page-rules/#browser-integrity-check)
* [Cache Deception Armor](/workers/configuration/workers-with-page-rules/#cache-deception-armor)
* [Cache Level](/workers/configuration/workers-with-page-rules/#cache-level)
* Disable Apps
* [Disable Zaraz](/workers/configuration/workers-with-page-rules/#disable-zaraz)
* [Edge Cache TTL](/workers/configuration/workers-with-page-rules/#edge-cache-ttl)
* [Email Obfuscation](/workers/configuration/workers-with-page-rules/#email-obfuscation)
* [Forwarding URL](/workers/configuration/workers-with-page-rules/#forwarding-url)
* Host Header Override
* [IP Geolocation Header](/workers/configuration/workers-with-page-rules/#ip-geolocation-header)
* Mirage
* [Origin Cache Control](/workers/configuration/workers-with-page-rules/#origin-cache-control)
* [Rocket Loader](/workers/configuration/workers-with-page-rules/#rocket-loader)
* [Security Level](/workers/configuration/workers-with-page-rules/#security-level)
* [SSL](/workers/configuration/workers-with-page-rules/#ssl)

This is because the default setting of these Page Rules will be disabled when Cloudflare recognizes that the request is headed to a Worker.

:::caution[Testing]


Due to ongoing changes to the Workers runtime, detailed documentation on how these rules will be affected are updated following testing.


:::

To learn what these Page Rules do, refer to [Page Rules](/rules/page-rules/).

:::note[Same zone versus other zone]


A same zone subrequest is a request the Worker makes to an orange-clouded hostname in the same zone the Worker runs on. Depending on your DNS configuration, any request that falls outside that definition may be considered an other zone request by the Cloudflare network.


:::

### Always Use HTTPS

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Respected |
| Worker | Same Zone  | Rule Ignored   |
| Worker | Other Zone | Rule Ignored   |

### Automatic HTTPS Rewrites

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Ignored   |
| Worker | Same Zone  | Rule Respected |
| Worker | Other Zone | Rule Ignored   |

### Browser Cache TTL

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Ignored   |
| Worker | Same Zone  | Rule Respected |
| Worker | Other Zone | Rule Ignored   |

### Browser Integrity Check

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Respected |
| Worker | Same Zone  | Rule Ignored   |
| Worker | Other Zone | Rule Ignored   |

### Cache Deception Armor

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Respected |
| Worker | Same Zone  | Rule Respected |
| Worker | Other Zone | Rule Ignored   |

### Cache Level

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Respected |
| Worker | Same Zone  | Rule Respected |
| Worker | Other Zone | Rule Ignored   |

### Disable Zaraz

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Respected |
| Worker | Same Zone  | Rule Respected |
| Worker | Other Zone | Rule Ignored   |

### Edge Cache TTL

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Respected |
| Worker | Same Zone  | Rule Respected |
| Worker | Other Zone | Rule Ignored   |

### Email Obfuscation

| Source     | Target     | Behavior       |
| -------------------------|------------|------------|
| Client     | Worker     | Rule Ignored   |
| Worker     | Same Zone  | Rule Respected |
| Worker     | Other Zone | Rule Ignored   |

### Forwarding URL

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Ignored   |
| Worker | Same Zone  | Rule Respected |
| Worker | Other Zone | Rule Ignored   |

### IP Geolocation Header

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Respected |
| Worker | Same Zone  | Rule Respected |
| Worker | Other Zone | Rule Ignored   |

### Origin Cache Control

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Respected |
| Worker | Same Zone  | Rule Respected |
| Worker | Other Zone | Rule Ignored   |

### Rocket Loader

| Source | Target     | Behavior     |
| ------ | ---------- | ------------ |
| Client | Worker     | Rule Ignored |
| Worker | Same Zone  | Rule Ignored |
| Worker | Other Zone | Rule Ignored |

### Security Level

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Respected |
| Worker | Same Zone  | Rule Ignored   |
| Worker | Other Zone | Rule Ignored   |

### SSL

| Source | Target     | Behavior       |
| ------ | ---------- | -------------- |
| Client | Worker     | Rule Respected |
| Worker | Same Zone  | Rule Respected |
| Worker | Other Zone | Rule Ignored   |

---

# Connect to databases

URL: https://developers.cloudflare.com/workers/databases/connecting-to-databases/

Cloudflare Workers can connect to and query your data in both SQL and NoSQL databases, including:

- Cloudflare's own [D1](/d1/), a serverless SQL-based database.
- Traditional hosted relational databases, including Postgres and MySQL, using [Hyperdrive](/hyperdrive/) (recommended) to significantly speed up access.
- Serverless databases, including Supabase, MongoDB Atlas, PlanetScale, and Prisma.

### D1 SQL database

D1 is Cloudflare's own SQL-based, serverless database. It is optimized for global access from Workers, and can scale out with multiple, smaller (10GB) databases, such as per-user, per-tenant or per-entity databases. Similar to some serverless databases, D1 pricing is based on query and storage costs.

| Database   | Library or Driver                                                                                                                          | Connection Method                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| [D1](/d1/) | [Workers binding](/d1/worker-api/), integrates with [Prisma](https://www.prisma.io/), [Drizzle](https://orm.drizzle.team/), and other ORMs | [Workers binding](/d1/worker-api/), [REST API](/api/resources/d1/subresources/database/methods/create/) |

### Traditional SQL databases

Traditional databases use SQL drivers that use [TCP sockets](/workers/runtime-apis/tcp-sockets/) to connect to the database. TCP is the de-facto standard protocol that many databases, such as PostgreSQL and MySQL, use for client connectivity.
These drivers are also widely compatible with your preferred ORM libraries and query builders.

This also includes serverless databases that are PostgreSQL or MySQL-compatible like [Supabase](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/), [Neon](/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon/) or [PlanetScale](/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale/),
which can be connected to using both native [TCP sockets and Hyperdrive](/hyperdrive/) or [serverless HTTP-based drivers](/workers/databases/connecting-to-databases/#serverless-databases) (detailed below).

| Database                                 | Integration       | Library or Driver                                                                               | Connection Method                                                                                                                                      |
| ---------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Postgres](/workers/tutorials/postgres/) | Direct connection | [Postgres.js](https://github.com/porsager/postgres),[node-postgres](https://node-postgres.com/) | [TCP Socket](/workers/runtime-apis/tcp-sockets/) via database driver, using [Hyperdrive](/hyperdrive/) for optimal performance (optional, recommended) |
| [MySQL](/workers/tutorials/mysql/)       | Direct connection | [mysql2](https://github.com/sidorares/node-mysql2), [mysql](https://github.com/mysqljs/mysql)   | [TCP Socket](/workers/runtime-apis/tcp-sockets/) via database driver, using [Hyperdrive](/hyperdrive/) for optimal performance (optional, recommended) |

:::note[Speed up database connectivity with Hyperdrive]

Connecting to SQL databases with TCP sockets requires multiple roundtrips to establish a secure connection before a query to the database is made.
Since a connection must be re-established on every Worker invocation, this adds unnecessary latency.

[Hyperdrive](/hyperdrive/) solves this by pooling database connections globally to eliminate unnecessary roundtrips and speed up your database access. Learn more about [how Hyperdrive works](/hyperdrive/configuration/how-hyperdrive-works/).

:::

### Serverless databases

Serverless databases provide HTTP-based proxies and drivers, also known as serverless drivers. These address the lack of connection reuse between Worker invocation similarly to [Hyperdrive](/hyperdrive/) for traditional SQL databases.

By providing a way to query your database with HTTP, these serverless databases and drivers eliminate several roundtrips needed to establish a secure connection.

| Database                                                                                                  | Library or Driver                                                                  | Connection Method       |
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------- |
| [PlanetScale](https://planetscale.com/blog/introducing-the-planetscale-serverless-driver-for-javascript)  | [@planetscale/database](https://github.com/planetscale/database-js)                | API via client library  |
| [Supabase](https://github.com/supabase/supabase/tree/master/examples/with-cloudflare-workers)             | [@supabase/supabase-js](https://github.com/supabase/supabase-js)                   | API via client library  |
| [Prisma](https://www.prisma.io/docs/guides/deployment/deployment-guides/deploying-to-cloudflare-workers)  | [prisma](https://github.com/prisma/prisma)                                         | API via client library  |
| [Neon](https://blog.cloudflare.com/neon-postgres-database-from-workers/)                                  | [@neondatabase/serverless](https://neon.tech/blog/serverless-driver-for-postgres/) | API via client library  |
| [Hasura](https://hasura.io/blog/building-applications-with-cloudflare-workers-and-hasura-graphql-engine/) | API                                                                                | GraphQL API via fetch() |
| [Upstash Redis](https://blog.cloudflare.com/cloudflare-workers-database-integration-with-upstash/)        | [@upstash/redis](https://github.com/upstash/upstash-redis)                         | API via client library  |
| [TiDB Cloud](https://docs.pingcap.com/tidbcloud/integrate-tidbcloud-with-cloudflare)                      | [@tidbcloud/serverless](https://github.com/tidbcloud/serverless-js)                | API via client library  |


Once you have installed the necessary packages, use the APIs provided by these packages to connect to your database and perform operations on it. Refer to detailed links for service-specific instructions.

## Authentication

If your database requires authentication, use Wrangler secrets to securely store your credentials. To do this, create a secret in your Cloudflare Workers project using the following [`wrangler secret`](/workers/wrangler/commands/#secret) command:

```sh
wrangler secret put <SECRET_NAME>
```

Then, retrieve the secret value in your code using the following code snippet:

```js
const secretValue = env.<SECRET_NAME>;
```

Use the secret value to authenticate with the external service. For example, if the external service requires an API key or database username and password for authentication, include these in using the relevant service's library or API.

For services that require mTLS authentication, use [mTLS certificates](/workers/runtime-apis/bindings/mtls) to present a client certificate.

## Next steps

- Learn how to connect to [an existing PostgreSQL database](/hyperdrive/) with Hyperdrive.
- Discover [other storage options available](/workers/platform/storage-options/) for use with Workers.
- [Create your first database](/d1/get-started/) with Cloudflare D1.

---

# Databases

URL: https://developers.cloudflare.com/workers/databases/

import { DirectoryListing } from "~/components";

Explore database integrations for your Worker projects.

<DirectoryListing />

---

# Supported bindings per development mode

URL: https://developers.cloudflare.com/workers/development-testing/bindings-per-env/

import { Render } from "~/components";

<Render file="bindings_per_env" />

---

# Environment variables and secrets

URL: https://developers.cloudflare.com/workers/development-testing/environment-variables/

import { Aside, PackageManagers, Steps } from "~/components";

During local development, you may need to configure **environment variables** (such as API URLs, feature flags) and **secrets** (API tokens, private keys). You can use a `.dev.vars` file in the root of your project to override environment variables for local development, and both [Wrangler](/workers/configuration/environment-variables/#compare-secrets-and-environment-variables) and the [Vite plugin](/workers/vite-plugin/reference/secrets/) will respect this override.

<Aside type="caution">
	Be sure to add `.dev.vars` to your `.gitignore` so it never gets committed.
</Aside>

### Why use a `.dev.vars` file?

Use `.dev.vars` to set local overrides for environment variables that should not be checked into your repository.

If you want to manage environment-based configuration that you **want checked into your repository** (for example, non-sensitive or shared environment defaults), you can define [environment variables as `[vars]`](/workers/wrangler/environments/#_top) in your Wrangler configuration. Using a `.dev.vars` file is specifically for local-only secrets or configuration that you do not want in version control and only want to inject in local dev sessions.

## Basic setup

<Steps>

1.  Create a `.dev.vars` file in your project root.

2.  Add key-value pairs:

    ```ini title=".dev.vars"
    API_HOST="localhost:3000"
    DEBUG="true"
    SECRET_TOKEN="my-local-secret-token"
    ```

3.  Run your `dev` command

        **Wrangler**
        <PackageManagers type="exec" pkg="wrangler" args="dev" />


        **Vite plugin**
         <PackageManagers type="exec" pkg="vite" args="dev" />

</Steps>

## Multiple local environments with `.dev.vars`

To simulate different local environments, you can:

<Steps>

1.  Create a file named `.dev.vars.<environment-name>` . For example, we'll use `.dev.vars.staging`.

2.  Add key-value pairs:
    ```ini title=".dev.vars.staging"
    API_HOST="staging.localhost:3000"
    DEBUG="false"
    SECRET_TOKEN="staging-token"
    ```
3.  Specify the environment when running the `dev` command:

        **Wrangler**

        <PackageManagers type="exec" pkg="wrangler" args="dev --env staging" />

        **Vite plugin**

        <PackageManagers type="exec" pkg="vite" args="dev" prefix="CLOUDFLARE_ENV=staging" />

        Only the values from `.dev.vars.staging` will be applied instead of `.dev.vars`.

</Steps>

## Learn more

- To learn how to configure multiple environments in Wrangler configuration, [read the documentation](/workers/wrangler/environments/#_top).
- To learn how to use Wrangler environments and Vite environments together, [read the Vite plugin documentation](/workers/vite-plugin/reference/cloudflare-environments/)

---

# Development & testing

URL: https://developers.cloudflare.com/workers/development-testing/

import {
	Details,
	LinkCard,
	Render,
	PackageManagers,
	WranglerConfig,
	Aside,
	InlineBadge,
	CardGrid,
	Card,
	Type,
	TypeScriptExample,
} from "~/components";

You can build, run, and test your Worker code on your own local machine before deploying it to Cloudflare's network. This is made possible through [Miniflare](/workers/testing/miniflare/), a simulator that executes your Worker code using the same runtime used in production, [`workerd`](https://github.com/cloudflare/workerd).

[By default](/workers/development-testing/#defaults), your Worker's bindings [connect to locally simulated resources](/workers/development-testing/#bindings-during-local-development), but can be configured to interact with the real, production resource with [remote bindings](/workers/development-testing/#remote-bindings).

## Core concepts

### Worker execution vs Bindings

When developing Workers, it's important to understand two distinct concepts:

- **Worker execution**: Where your Worker code actually runs (on your local machine vs on Cloudflare's infrastructure).

- [**Bindings**](/workers/runtime-apis/bindings/): How your Worker interacts with Cloudflare resources (like [KV namespaces](/kv), [R2 buckets](/r2), [D1 databases](/d1), [Queues](/queues/), [Durable Objects](/durable-objects/), etc). In your Worker code, these are accessed via the `env` object (such as `env.MY_KV`).

## Local development

**You can start a local development server using:**

1. The Cloudflare Workers CLI [**Wrangler**](/workers/wrangler/), using the built-in [`wrangler dev`](/workers/wrangler/commands/#dev) command.

<PackageManagers type="exec" pkg="wrangler" args="dev" />

2. [**Vite**](https://vite.dev/), using the [**Cloudflare Vite plugin**](/workers/vite-plugin/).

<PackageManagers type="exec" pkg="vite" args="dev" />

Both Wrangler and the Cloudflare Vite plugin use [Miniflare](/workers/testing/miniflare/) under the hood, and are developed and maintained by the Cloudflare team. For guidance on choosing when to use Wrangler versus Vite, see our guide [Choosing between Wrangler & Vite](/workers/development-testing/wrangler-vs-vite/).

- [Get started with Wrangler](/workers/wrangler/install-and-update/)
- [Get started with the Cloudflare Vite plugin](/workers/vite-plugin/get-started/)

### Defaults

By default, running `wrangler dev` / `vite dev` (when using the [Vite plugin](/workers/vite-plugin/get-started/)) means that:

- Your Worker code runs on your local machine.
- All resources your Worker is bound to in your [Wrangler configuration](/workers/wrangler/configuration/) are simulated locally.

### Bindings during local development

[Bindings](/workers/runtime-apis/bindings/) are interfaces that allow your Worker to interact with various Cloudflare resources (like [KV namespaces](/kv), [R2 buckets](/r2), [D1 databases](/d1), [Queues](/queues/), [Durable Objects](/durable-objects/), etc). In your Worker code, these are accessed via the `env` object (such as `env.MY_KV`).

During local development, your Worker code interacts with these bindings using the exact same API calls (such as `env.MY_KV.put()`) as it would in a deployed environment. These local resources are initially empty, but you can populate them with data, as documented in [Adding local data](/workers/development-testing/local-data/).

- By default, bindings connect to **local resource simulations** (except for [AI bindings](/workers-ai/configuration/bindings/), as AI models always run remotely).
- You can override this default behavior and **connect to the remote resource**, on a per-binding basis. This lets you connect to real, production resources while still running your Worker code locally.

## Remote bindings <InlineBadge preset="beta"/>

**Remote bindings** are bindings that are configured to connect to the deployed, remote resource during local development _instead_ of the locally simulated resource. You can configure remote bindings by setting `experimental_remote: true` in the binding definition.

### Example configuration

<WranglerConfig>

```jsonc title="wrangler.jsonc"
{
	"name": "my-worker",
	"compatibility_date": "$today",

	"r2_buckets": [
		{
			"bucket_name": "screenshots-bucket",
			"binding": "screenshots_bucket",
			"experimental_remote": true,
		},
	],
}
```

</WranglerConfig>

When remote bindings are configured, your Worker still **executes locally**, only the underlying resources your bindings connect to change. For all bindings marked with `experimental_remote: true`, Miniflare will route its operations (such as `env.MY_KV.put()`) to the deployed resource. All other bindings not explicitly configured with `experimental_remote: true` continue to use their default local simulations.

### Using Wrangler with remote bindings

If you're using [Wrangler](/workers/wrangler/) for local development and have remote bindings configured, you'll need to use the following experimental command:

<PackageManagers type="exec" pkg="wrangler" args="dev --x-remote-bindings" />

### Using Vite with remote bindings

If you're using Vite via [the Cloudflare Vite plugin](/workers/vite-plugin/), you'll need to add support for remote bindings in your Vite configuration (`vite.config.ts`):

```ts title="vite.config.ts" {10}
import { cloudflare } from "@cloudflare/vite-plugin";
import { defineConfig } from "vite";

export default defineConfig({
	plugins: [
		cloudflare({
			configPath: "./entry-worker/wrangler.jsonc",
			experimental: { remoteBindings: true },
		}),
	],
});
```

### Using Vitest with remote bindings

You can also use Vitest with configured remote bindings by enabling support in your Vitest configuration file (`vitest.config.ts`):

```ts title="vitest.config.ts" {7}
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
	test: {
		poolOptions: {
			workers: {
				experimental_remoteBindings: true,
				wrangler: { configPath: "./wrangler.jsonc" },
			},
		},
	},
});
```

### Targeting preview resources

To protect production data, you can create and specify preview resources in your [Wrangler configuration](/workers/wrangler/configuration/), such as:

- [Preview namespaces for KV stores](/workers/wrangler/configuration/#kv-namespaces):`preview_id`.
- [Preview buckets for R2 storage](/workers/wrangler/configuration/#r2-buckets): `preview_bucket_name`.
- [Preview database IDs for D1](/workers/wrangler/configuration/#d1-databases): `preview_database_id`

If preview configuration is present for a binding, setting `experimental_remote: true` will ensure that remote bindings connect to that designated remote preview resource.

**For example:**

<WranglerConfig>

```jsonc title="wrangler.jsonc"
{
	"name": "my-worker",
	"compatibility_date": "$today",

	"r2_buckets": [
		{
			"bucket_name": "screenshots-bucket",
			"binding": "screenshots_bucket",
			"preview_bucket_name": "preview-screenshots-bucket",
			"experimental_remote": true,
		},
	],
}
```

</WranglerConfig>

Running `wrangler dev --x-remote-bindings` with the above configuration means that:

- Your Worker code runs locally
- All calls made to `env.screenshots_bucket` will use the `preview-screenshots-bucket` resource, rather than the production `screenshots-bucket`.

### Recommended remote bindings

We recommend configuring specific bindings to connect to their remote counterparts. These services often rely on Cloudflare's network infrastructure or have complex backends that are not fully simulated locally.

The following bindings are recommended to have `experimental_remote: true` in your Wrangler configuration:

#### [Browser Rendering](/workers/wrangler/configuration/#browser-rendering):

To interact with a real headless browser for rendering. There is no current local simulation for Browser Rendering.

<WranglerConfig>
```jsonc title="wrangler.jsonc"
{
	"browser": {
		"binding": "MY_BROWSER",
		"experimental_remote": true
	},
}
```
</WranglerConfig>

#### [Workers AI](/workers/wrangler/configuration/#workers-ai):

To utilize actual AI models deployed on Cloudflare's network for inference. There is no current local simulation for Workers AI.

<WranglerConfig>
```jsonc title="wrangler.jsonc"
{
	"ai": {
		"binding": "AI",
		"experimental_remote": true
	},
}
```
</WranglerConfig>

#### [Vectorize](/workers/wrangler/configuration/#vectorize-indexes):

To connect to your production Vectorize indexes for accurate vector search and similarity operations. There is no current local simulation for Vectorize.

<WranglerConfig>
```jsonc title="wrangler.jsonc"
{
	"vectorize": [
		{
			"binding": "MY_VECTORIZE_INDEX",
			"index_name": "my-prod-index",
			"experimental_remote": true
		}
	],
}
```
</WranglerConfig>

#### [mTLS](/workers/wrangler/configuration/#mtls-certificates):

To verify that the certificate exchange and validation process work as expected. There is no current local simulation for mTLS bindings.

<WranglerConfig>
```jsonc title="wrangler.jsonc"
{
	"mtls_certificates": [
		{
			"binding": "MY_CLIENT_CERT_FETCHER",
			"certificate_id": "<YOUR_UPLOADED_CERT_ID>",
			"experimental_remote": true

    	}
    ]

}

````
</WranglerConfig>

#### [Images](/workers/wrangler/configuration/#images):

To connect to a high-fidelity version of the Images API, and verify that all transformations work as expected. Local simulation for Cloudflare Images is [limited with only a subset of features](/images/transform-images/bindings/#interact-with-your-images-binding-locally).

<WranglerConfig>
```jsonc title="wrangler.jsonc"
{
  "images": {
    "binding": "IMAGES" ,
		"experimental_remote": true
  }
}
````

</WranglerConfig>

<Aside type="note">

If `experimental_remote: true` is not specified for Browser Rendering, Vectorize, mTLS, or Images, Cloudflare **will issue a warning**. This prompts you to consider enabling it for a more production-like testing experience.

If a Workers AI binding has `experimental_remote` set to `false`, Cloudflare will **produce an error**. If the property is omitted, Cloudflare will connect to the remote resource and issue a warning to add the property to configuration.

</Aside>

#### [Dispatch Namespaces](/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler/):

Workers for Platforms users can configure `experimental_remote: true` in dispatch namespace binding definitions:

<WranglerConfig>
```jsonc title="wrangler.jsonc"
{
  "dispatch_namespaces": [
    {
      "binding": "DISPATCH_NAMESPACE",
      "namespace": "testing",
      "experimental_remote":true
		}
  ]
}
```
</WranglerConfig>

This allows you to run your [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) locally, while connecting it to your remote dispatch namespace binding. This allows you to test changes to your core dispatching logic against real, deployed [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers).

### Unsupported remote bindings

Certain bindings are not supported for remote connections during local development (`experimental_remote: true`). These will always use local simulations or local values.

If `experimental_remote: true` is specified in Wrangler configuration for any of the following unsupported binding types, Cloudflare **will issue an error**. See [all supported and unsupported bindings for remote bindings](/workers/development-testing/bindings-per-env/).

- [**Durable Objects**](/workers/wrangler/configuration/#durable-objects): Enabling remote connections for Durable Objects may be supported in the future, but currently will always run locally.

- [**Environment Variables (`vars`)**](/workers/wrangler/configuration/#environment-variables): Environment variables are intended to be distinct between local development and deployed environments. They are easily configurable locally (such as in a `.dev.vars` file or directly in Wrangler configuration).

- [**Secrets**](/workers/wrangler/configuration/#secrets): Like environment variables, secrets are expected to have different values in local development versus deployed environments for security reasons. Use `.dev.vars` for local secret management.

- **[Static Assets](/workers/wrangler/configuration/#assets)**: Static assets are always served from your local disk during development for speed and direct feedback on changes.

- [**Version Metadata**](/workers/runtime-apis/bindings/version-metadata/): Since your Worker code is running locally, version metadata (like commit hash, version tags) associated with a specific deployed version is not applicable or accurate.

- [**Analytics Engine**](/analytics/analytics-engine/): Local development sessions typically don't contribute data directly to production Analytics Engine.

- [**Hyperdrive**](/workers/wrangler/configuration/#hyperdrive): This is being actively worked on, but is currently unsupported.
- [**Rate Limiting**](/workers/runtime-apis/bindings/rate-limit/#configuration): Local development sessions typically should not share or affect rate limits of your deployed Workers. Rate limiting logic should be tested against local simulations.

<Aside type="tip">

If you have use-cases for connecting to any of the remote resources above, please [open a feature request](https://github.com/cloudflare/workers-sdk/issues) in our [`workers-sdk` repository](https://github.com/cloudflare/workers-sdk).

</Aside>

### Important Considerations

- **Data modification**: Operations (writes, deletes, updates) on bindings connected remotely will affect your actual data in the targeted Cloudflare resource (be it preview or production).

- **Billing**: Interactions with remote Cloudflare services through these connections will incur standard operational costs for those services (such as KV operations, R2 storage/operations, AI requests, D1 usage).

- **Network latency**: Expect network latency for operations on these remotely connected bindings, as they involve communication over the internet.

### API

Wrangler provides programmatic utilities to help tooling authors support remote binding connections when running Workers code with [Miniflare](/workers/testing/miniflare/).

**Key APIs include:**

- [`experimental_startRemoteProxySession`](#experimental_startRemoteProxySession): Starts a proxy session that allows interaction with remote bindings.
- [`unstable_convertConfigBindingsToStartWorkerBindings`](#unstable_convertconfigbindingstostartworkerbindings): Utility for converting binding definitions.
- [`experimental_maybeStartOrUpdateProxySession`](#experimental_maybestartorupdatemixedmodesession): Convenience function to easily start or update a proxy session.

#### `experimental_startRemoteProxySession`

This function starts a proxy session for a given set of bindings. It accepts options to control session behavior, including an `auth` option with your Cloudflare account ID and API token for remote binding access.

It returns an object with:

- `ready` <Type text="Promise<void>" />: Resolves when the session is ready.
- `dispose` <Type text="() => Promise<void>" />: Stops the session.
- `updateBindings` <Type text="(bindings: StartDevWorkerInput['bindings']) => Promise<void>" />: Updates session bindings.
- `remoteProxyConnectionString` <Type text="remoteProxyConnectionString" />: String to pass to Miniflare for remote binding access.

#### `unstable_convertConfigBindingsToStartWorkerBindings`

The `unstable_readConfig` utility returns an `Unstable_Config` object which includes the definition of the bindings included in the configuration file. These bindings definitions
are however not directly compatible with `experimental_startRemoteProxySession`. It can be quite convenient to however read the binding declarations with `unstable_readConfig` and then
pass them to `experimental_startRemoteProxySession`, so for this wrangler exposes `unstable_convertConfigBindingsToStartWorkerBindings` which is a simple utility to convert
the bindings in an `Unstable_Config` object into a structure that can be passed to `experimental_startRemoteProxySession`.

<Aside type="note">
	This type conversion is temporary. In the future, the types will be unified so
	you can pass the config object directly to
	`experimental_startRemoteProxySession`.
</Aside>

#### `experimental_maybeStartOrUpdateRemoteProxySession`

This wrapper simplifies proxy session management. It takes:

- The path to your Wrangler config, or an object with remote bindings.
- The current proxy session details (this parameter can be set to `null` or not being provided if none).

It returns an object with the proxy session details if started or updated, or `null` if no proxy session is needed.

The function:

- Based on the first argument prepares the input arguments for the proxy session.
- If there are no remote bindings to be used (nor a pre-existing proxy session) it returns null, signaling that no proxy session is needed.
- If the details of an existing proxy session have been provided it updates the proxy session accordingly.
- Otherwise if starts a new proxy session.
- Returns the proxy session details (that can later be passed as the second argument to `experimental_maybeStartOrUpdateRemoteProxySession`).

#### Example

Here's a basic example of using Miniflare with `experimental_maybeStartOrUpdateRemoteProxySession` to provide a local dev session with remote bindings. This example uses a single hardcoded KV binding.

<TypeScriptExample>
```ts
import { Miniflare, MiniflareOptions } from "miniflare";
import { experimental_maybeStartOrUpdateRemoteProxySession } from "wrangler";

let mf: Miniflare | null;

let remoteProxySessionDetails: Awaited<
ReturnType<typeof experimental_maybeStartOrUpdateRemoteProxySession>

> | null = null;

async function startOrUpdateDevSession() {
remoteProxySessionDetails =
await experimental_maybeStartOrUpdateRemoteProxySession(
{
bindings: {
MY_KV: {
type: 'kv_namespace',
id: 'kv-id',
experimental_remote: true,
}
}
},
remoteProxySessionDetails
);

const miniflareOptions: MiniflareOptions = {
scriptPath: "./worker.js",
kvNamespaces: {
MY_KV: {
id: "kv-id",
remoteProxyConnectionString:
remoteProxySessionDetails?.session.remoteProxyConnectionString,
},
},
};

if (!mf) {
mf = new Miniflare(miniflareOptions);
} else {
mf.setOptions(miniflareOptions);
}
}

// ... tool logic that invokes `startOrUpdateDevSession()` ...

// ... once the dev session is no longer needed run
// `remoteProxySessionDetails?.session.dispose()`

```
</TypeScriptExample>


## `wrangler dev --remote` (Legacy)

Separate from Miniflare-powered local development, Wrangler also offers a fully remote development mode via [`wrangler dev --remote`](/workers/wrangler/commands/#dev). Remote development is [**not** supported in the Vite plugin](/workers/development-testing/wrangler-vs-vite/).

<PackageManagers type="exec" pkg="wrangler" args="dev --remote" />

During **remote development**, all of your Worker code is uploaded to a temporary preview environment on Cloudflare's infrastructure, and changes to your code are automatically uploaded as you save.

When using remote development, all bindings automatically connect to their remote resources. Unlike local development, you cannot configure bindings to use local simulations - they will always use the deployed resources on Cloudflare's network.

### When to use Remote development

- For most development tasks, the most efficient and productive experience will be local development along with [remote bindings](/workers/development-testing/#remote-bindings) when needed.
- You may want to use `wrangler dev --remote` for testing features or behaviors that are highly specific to Cloudflare's network and cannot be adequately simulated locally or tested via remote bindings.

### Considerations

- Iteration is significantly slower than local development due to the upload/deployment step for each change.

### Limitations

- When you run a remote development session using the `--remote` flag, a limit of 50 [routes](/workers/configuration/routing/routes/) per zone is enforced. Learn more in[ Workers platform limits](/workers/platform/limits/#number-of-routes-per-zone-when-using-wrangler-dev---remote).

---

# Adding local data

URL: https://developers.cloudflare.com/workers/development-testing/local-data/

import {
	Details,
	LinkCard,
	Render,
	PackageManagers,
	FileTree,
	Aside,
} from "~/components";

Whether you are using Wrangler or the [Cloudflare Vite plugin](https://developers.cloudflare.com/workers/vite-plugin/), your workflow for **accessing** data during local development remains the same. However, you can only [populate local resources with data](/workers/development-testing/local-data/#populating-local-resources-with-data) via the Wrangler CLI.

### How it works

When you run either `wrangler dev` or [`vite`](https://vite.dev/guide/cli#dev-server), [Miniflare](/workers/testing/miniflare/) automatically creates **local versions** of your resources (like [KV](/kv), [D1](/d1/), or [R2](/r2)). This means you **don’t** need to manually set up separate local instances for each service. However, newly created local resources **won’t** contain any data — you'll need to use Wrangler commands with the `--local` flag to populate them. Changes made to local resources won’t affect production data.

## Populating local resources with data

When you first start developing, your local resources will be empty. You'll need to populate them with data using the Wrangler CLI.

### KV namespaces

<Aside type="caution" title="Syntax note">

Since version 3.60.0, Wrangler supports the `kv ...` syntax. If you are using versions below 3.60.0, the command follows the `kv:...` syntax. Learn more in the [Wrangler commands for KV page](/kv/reference/kv-commands/).

</Aside>

#### [Add a single key-value pair](/workers/wrangler/commands/#kv-key)

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="kv key put <KEY> <VALUE> --binding=<BINDING> --local "
/>

#### [Bulk upload](/workers/wrangler/commands/#kv-bulk)

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="kv bulk put <FILENAME.json> --binding=<BINDING> --local"
/>

### R2 buckets

#### [Upload a file](/workers/wrangler/commands/#r2-object)

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="r2 object put <BUCKET>/<KEY> --file=<PATH_TO_FILE> --local"
/>

You may also include [other metadata](/workers/wrangler/commands/#r2-object-put).

### D1 databases

#### [Execute a SQL statement](/workers/wrangler/commands/#d1-execute)

<PackageManagers
	type="exec"
	pkg="wrangler"
	args='d1 execute <DATABASE_NAME> --command="<SQL_QUERY>" --local'
/>

#### [Execute a SQL file](/workers/wrangler/commands/#d1-execute)

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="d1 execute <DATABASE_NAME> --file=./schema.sql --local"
/>

### Durable Objects

For Durable Objects, unlike KV, D1, and R2, there are no CLI commands to populate them with local data. To add data to Durable Objects during local development, you must write application code that creates Durable Object instances and [calls methods on them that store state](/durable-objects/best-practices/access-durable-objects-storage/). This typically involves creating development endpoints or test routes that initialize your Durable Objects with the desired data.

## Where local data gets stored

By default, both Wrangler and the Vite plugin store local binding data in the same location: the `.wrangler/state` folder in your project directory. This folder stores data in subdirectories for all local bindings: KV namespaces, R2 buckets, D1 databases, Durable Objects, etc.

### Clearing local storage

You can delete the `.wrangler/state` folder at any time to reset your local environment, and Miniflare will recreate it the next time you run your `dev` command. You can also delete specific sub-folders within `.wrangler/state` for more targeted clean-up.

### Changing the local data directory

If you prefer to specify a different directory for local storage, you can do so through the Wranlger CLI or in the Vite plugin's configuration.

#### Using Wrangler

Use the [`--persist-to`](/workers/wrangler/commands/#dev) flag with `wrangler dev`. You need to specify this flag every time you run the `dev` command:

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="dev --persist-to <DIRECTORY>"
/>

:::note
The local persistence folder (like `.wrangler/state` or any custom folder you set) should be added to your `.gitignore` to avoid committing local development data to version control.
:::

<Details header="Using `--local` with `--persist-to`">
If you run `wrangler dev --persist-to <DIRECTORY>` to specify a custom location for local data, you must also include the same `--persist-to <DIRECTORY>` when running other Wrangler commands that modify local data (and be sure to include the `--local` flag).

For example, to create a KV key named `test` with a value of `12345` in a local KV namespace, run:

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="kv key put test 12345 --binding MY_KV_NAMESPACE --local --persist-to worker-local"
/>

This command:

- Sets the KV key `test` to `12345` in the binding `MY_KV_NAMESPACE` (defined in your [Wrangler configuration file](/workers/wrangler/configuration/)).
- Uses `--persist-to worker-local` to ensure the data is created in the **worker-local** directory instead of the default `.wrangler/state`.
- Adds the `--local` flag, indicating you want to modify local data.

If `--persist-to` is not specified, Wrangler defaults to using `.wrangler/state` for local data.

</Details>

#### Using the Cloudflare Vite plugin

To customize where the Vite plugin stores local data, configure the [`persistState` option](/workers/vite-plugin/reference/api/#interface-pluginconfig) in your Vite config file:

```js title="vite.config.js"
import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [
		cloudflare({
			persistState: "./my-custom-directory",
		}),
	],
});
```

#### Sharing state between tools

If you want Wrangler and the Vite plugin to share the same state, configure them to use the same persistence path.

---

# Choosing between Wrangler & Vite

URL: https://developers.cloudflare.com/workers/development-testing/wrangler-vs-vite/

# When to use Wrangler vs Vite

Deciding between Wrangler and the Cloudflare Vite plugin depends on your project's focus and development workflow. Here are some quick guidelines to help you choose:

## When to use Wrangler

- **Backend & Workers-focused:**
  If you're primarily building APIs, serverless functions, or background tasks, use Wrangler.

- **Remote development:**
  If your project needs the ability to develop and test using production resources and data on Cloudflare's network, use Wrangler's `--remote` flag.

- **Simple frontends:**
  If you have minimal frontend requirements and don’t need hot reloading or advanced bundling, Wrangler may be sufficient.

## When to use the Cloudflare Vite Plugin

Use the [Vite plugin](/workers/vite-plugin/) for:

- **Frontend-centric development:**
  If you already use Vite with modern frontend frameworks like React, Vue, Svelte, or Solid, the Vite plugin integrates into your development workflow.

- **React Router v7:**
  If you are using [React Router v7](https://reactrouter.com/) (the successor to Remix), it is officially supported by the Vite plugin as a full-stack SSR framework.

- **Rapid iteration (HMR):**
  If you need near-instant updates in the browser, the Vite plugin provides [Hot Module Replacement (HMR)](https://vite.dev/guide/features.html#hot-module-replacement) during local development.

- **Advanced optimizations:**
  If you require more advanced optimizations (code splitting, efficient bundling, CSS handling, build time transformations, etc.), Vite is a strong fit.

- **Greater flexibility:**
  Due to Vite's advanced configuration options and large ecosystem of plugins, there is more flexibility to customize your development experience and build output.

---

# Dashboard

URL: https://developers.cloudflare.com/workers/get-started/dashboard/

import { Render } from "~/components";

Follow this guide to create a Workers application using [the Cloudflare dashboard](https://dash.cloudflare.com).

<Render file="playground-callout" />

## Prerequisites

[Create a Cloudflare account](/fundamentals/account/create-account/), if you have not already.

## Setup

To get started with a new Workers application:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to the **Workers & Pages** section of the dashboard.
2. Select [Create](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create). From here, you can:
    * You can select from the gallery of production-ready templates
    * Import an existing Git repository on your own account
    * Let Cloudflare clone and bootstrap a public repository containing a Workers application.
3. Once you've connected to your chosen [Git provider](/workers/ci-cd/builds/git-integration/github-integration/), configure your project and click `Deploy`.
4. Cloudflare will kick off a new build and deployment. Once deployed, preview your Worker at its provided `workers.dev` subdomain.

## Continue development
Applications started in the dashboard are set up with Git to help kickstart your development workflow. To continue developing on your repository, you can run:

```bash
# clone you repository locally
git clone <git repo URL>

# be sure you are in the root directory
cd <directory>
```

Now, you can preview and test your changes by [running Wrangler in your local development environment](/workers/development-testing/). Once you are ready to deploy you can run:

```bash
# adds the files to git tracking
git add .

# commits the changes
git commit -m "your message"

# push the changes to your Git provider
git push origin main
```


To do more:
- Review our [Examples](/workers/examples/) and [Tutorials](/workers/tutorials/) for inspiration.
- Set up [bindings](/workers/runtime-apis/bindings/) to allow your Worker to interact with other resources and unlock new functionality.
- Learn how to [test and debug](/workers/testing/) your Workers.
- Read about [Workers limits and pricing](/workers/platform/).

---

# CLI

URL: https://developers.cloudflare.com/workers/get-started/guide/

import { Details, Render, PackageManagers } from "~/components";

Set up and deploy your first Worker with Wrangler, the Cloudflare Developer Platform CLI.

This guide will instruct you through setting up and deploying your first Worker.

## Prerequisites

<Render file="prereqs" product="workers" />

## 1. Create a new Worker project

Open a terminal window and run C3 to create your Worker project. [C3 (`create-cloudflare-cli`)](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare) is a command-line tool designed to help you set up and deploy new applications to Cloudflare.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"my-first-worker"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Now, you have a new project set up. Move into that project folder.

```sh
cd my-first-worker
```

<Details header="What files did C3 create?">

In your project directory, C3 will have generated the following:

* `wrangler.jsonc`: Your [Wrangler](/workers/wrangler/configuration/#sample-wrangler-configuration) configuration file.
* `index.js` (in `/src`): A minimal `'Hello World!'` Worker written in [ES module](/workers/reference/migrate-to-module-workers/) syntax.
* `package.json`: A minimal Node dependencies configuration file.
* `package-lock.json`: Refer to [`npm` documentation on `package-lock.json`](https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json).
* `node_modules`: Refer to [`npm` documentation `node_modules`](https://docs.npmjs.com/cli/v7/configuring-npm/folders#node-modules).

</Details>

<Details header="What if I already have a project in a git repository?">

In addition to creating new projects from C3 templates, C3 also supports creating new projects from existing Git repositories. To create a new project from an existing Git repository, open your terminal and run:

```sh
npm create cloudflare@latest -- --template <SOURCE>
```

`<SOURCE>` may be any of the following:

- `user/repo` (GitHub)
- `git@github.com:user/repo`
- `https://github.com/user/repo`
- `user/repo/some-template` (subdirectories)
- `user/repo#canary` (branches)
- `user/repo#1234abcd` (commit hash)
- `bitbucket:user/repo` (Bitbucket)
- `gitlab:user/repo` (GitLab)

Your existing template folder must contain the following files, at a minimum, to meet the requirements for Cloudflare Workers:

- `package.json`
- `wrangler.jsonc` [See sample Wrangler configuration](/workers/wrangler/configuration/#sample-wrangler-configuration)
- `src/` containing a worker script referenced from `wrangler.jsonc`

</Details>

## 2. Develop with Wrangler CLI

C3 installs [Wrangler](/workers/wrangler/install-and-update/), the Workers command-line interface, in Workers projects by default. Wrangler lets you to [create](/workers/wrangler/commands/#init), [test](/workers/wrangler/commands/#dev), and [deploy](/workers/wrangler/commands/#deploy) your Workers projects.

After you have created your first Worker, run the [`wrangler dev`](/workers/wrangler/commands/#dev) command in the project directory to start a local server for developing your Worker. This will allow you to preview your Worker locally during development.

```sh
npx wrangler dev
```

If you have never used Wrangler before, it will open your web browser so you can login to your Cloudflare account.

Go to [http://localhost:8787](http://localhost:8787) to view your Worker.

<Details header="Browser issues?">

If you have issues with this step or you do not have access to a browser interface, refer to the [`wrangler login`](/workers/wrangler/commands/#login) documentation.

</Details>

## 3. Write code

With your new project generated and running, you can begin to write and edit your code.

Find the `src/index.js` file. `index.js` will be populated with the code below:

```js title="Original index.js"
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello World!");
	},
};
```

<Details header="Code explanation">

This code block consists of a few different parts.

```js title="Updated index.js" {1}
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello World!");
	},
};
```

`export default` is JavaScript syntax required for defining [JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#default_exports_versus_named_exports). Your Worker has to have a default export of an object, with properties corresponding to the events your Worker should handle.

```js title="index.js" {2}
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello World!");
	},
};
```

This [`fetch()` handler](/workers/runtime-apis/handlers/fetch/) will be called when your Worker receives an HTTP request. You can define additional event handlers in the exported object to respond to different types of events. For example, add a [`scheduled()` handler](/workers/runtime-apis/handlers/scheduled/) to respond to Worker invocations via a [Cron Trigger](/workers/configuration/cron-triggers/).

Additionally, the `fetch` handler will always be passed three parameters: [`request`, `env` and `context`](/workers/runtime-apis/handlers/fetch/).

```js title="index.js" {3}
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello World!");
	},
};
```

The Workers runtime expects `fetch` handlers to return a `Response` object or a Promise which resolves with a `Response` object. In this example, you will return a new `Response` with the string `"Hello World!"`.

</Details>

Replace the content in your current `index.js` file with the content below, which changes the text output.

```js title="index.js" {3}
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello Worker!");
	},
};
```

Then, save the file and reload the page. Your Worker's output will have changed to the new text.

<Details header="No visible changes?">

If the output for your Worker does not change, make sure that:

1. You saved the changes to `index.js`.
2. You have `wrangler dev` running.
3. You reloaded your browser.

</Details>

## 4. Deploy your project

Deploy your Worker via Wrangler to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/).

```sh
npx wrangler deploy
```

If you have not configured any subdomain or domain, Wrangler will prompt you during the publish process to set one up.

Preview your Worker at `<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev`.

<Details header="Seeing 523 errors?">

If you see [`523` errors](/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/error-523/) when pushing your `*.workers.dev` subdomain for the first time, wait a minute or so and the errors will resolve themselves.

</Details>

## Next steps

To do more:

- Push your project to a GitHub or GitLab repository then [connect to builds](/workers/ci-cd/builds/#get-started) to enable automatic builds and deployments.
- Visit the [Cloudflare dashboard](https://dash.cloudflare.com/) for simpler editing.
- Review our [Examples](/workers/examples/) and [Tutorials](/workers/tutorials/) for inspiration.
- Set up [bindings](/workers/runtime-apis/bindings/) to allow your Worker to interact with other resources and unlock new functionality.
- Learn how to [test and debug](/workers/testing/) your Workers.
- Read about [Workers limits and pricing](/workers/platform/).

---

# Getting started

URL: https://developers.cloudflare.com/workers/get-started/

import { DirectoryListing, Render } from "~/components";

Build your first Worker.

<DirectoryListing />

---

# Prompting

URL: https://developers.cloudflare.com/workers/get-started/prompting/

import { Tabs, TabItem, GlossaryTooltip, Type, Badge, TypeScriptExample } from "~/components";
import { Code } from "@astrojs/starlight/components";
import BasePrompt from '~/content/partials/prompts/base-prompt.txt?raw';

One of the fastest ways to build an application is by using AI to assist with writing the boiler plate code. When building, iterating on or debugging applications using AI tools and Large Language Models (LLMs), a well-structured and extensive prompt helps provide the model with clearer guidelines & examples that can dramatically improve output.

Below is an extensive example prompt that can help you build applications using Cloudflare Workers and your preferred AI model.

### Build Workers using a prompt

To use the prompt:

1. Use the click-to-copy button at the top right of the code block below to copy the full prompt to your clipboard
2. Paste into your AI tool of choice (for example OpenAI's ChatGPT or Anthropic's Claude)
3. Make sure to enter your part of the prompt at the end between the `<user_prompt>` and `</user_prompt>` tags.

Base prompt:
<Code code={BasePrompt} collapse={"30-10000"} lang="md" />

The prompt above adopts several best practices, including:

* Using `<xml>` tags to structure the prompt
* API and usage examples for products and use-cases
* Guidance on how to generate configuration (e.g. `wrangler.jsonc`) as part of the models response.
* Recommendations on Cloudflare products to use for specific storage or state needs

### Additional uses

You can use the prompt in several ways:

* Within the user context window, with your own user prompt inserted between the `<user_prompt>` tags (**easiest**)
* As the `system` prompt for models that support system prompts
* Adding it to the prompt library and/or file context within your preferred IDE:
	* Cursor: add the prompt to [your Project Rules](https://docs.cursor.com/context/rules-for-ai)
	* Zed: use [the `/file` command](https://zed.dev/docs/assistant/assistant-panel) to add the prompt to the Assistant context.
	* Windsurf: use [the `@-mention` command](https://docs.codeium.com/chat/overview) to include a file containing the prompt to your Chat.
  * GitHub Copilot: create the [`.github/copilot-instructions.md`](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) file at the root of your project and add the prompt.

:::note

The prompt(s) here are examples and should be adapted to your specific use case. We'll continue to build out the prompts available here, including additional prompts for specific products.

Depending on the model and user prompt, it may generate invalid code, configuration or other errors, and we recommend reviewing and testing the generated code before deploying it.

:::

### Passing a system prompt

If you are building an AI application that will itself generate code, you can additionally use the prompt above as a "system prompt", which will give the LLM additional information on how to structure the output code. For example:

<TypeScriptExample filename="index.ts">

```ts
import workersPrompt from "./workersPrompt.md"

// Llama 3.3 from Workers AI
const PREFERRED_MODEL = "@cf/meta/llama-3.3-70b-instruct-fp8-fast"

export default {
	async fetch(req: Request, env: Env, ctx: ExecutionContext) {
		const openai = new OpenAI({
			apiKey: env.WORKERS_AI_API_KEY
		});

		const stream = await openai.chat.completions.create({
			messages: [
				{
					role: "system",
					content: workersPrompt,
				},
				{
					role: "user",
					// Imagine something big!
					content: "Build an AI Agent using Workflows. The Workflow should be triggered by a GitHub webhook on a pull request, and ..."
				}
			],
			model: PREFERRED_MODEL,
			stream: true,
		});

		// Stream the response so we're not buffering the entire response in memory,
		// since it could be very large.
		const transformStream = new TransformStream();
		const writer = transformStream.writable.getWriter();
		const encoder = new TextEncoder();

		(async () => {
			try {
				for await (const chunk of stream) {
					const content = chunk.choices[0]?.delta?.content || '';
					await writer.write(encoder.encode(content));
				}
			} finally {
				await writer.close();
			}
		})();

		return new Response(transformStream.readable, {
			headers: {
				'Content-Type': 'text/plain; charset=utf-8',
				'Transfer-Encoding': 'chunked'
			}
		});
	}
}

```

</TypeScriptExample>

## Use docs in your editor

AI-enabled editors, including Cursor and Windsurf, can index documentation. Cursor includes the Cloudflare Developer Docs by default: you can use the [`@Docs`](https://docs.cursor.com/context/@-symbols/@-docs) command.

In other editors, such as Zed or Windsurf, you can paste in URLs to add to your context. Use the _Copy Page_ button to paste in Cloudflare docs directly, or fetch docs for each product by appending `llms-full.txt` to the root URL - for example, `https://developers.cloudflare.com/agents/llms-full.txt` or `https://developers.cloudflare.com/workflows/llms-full.txt`.

You can combine these with the Workers system prompt on this page to improve your editor or agent's understanding of the Workers APIs.

## Additional resources

To get the most out of AI models and tools, we recommend reading the following guides on prompt engineering and structure:

* OpenAI's [prompt engineering](https://platform.openai.com/docs/guides/prompt-engineering) guide and [best practices](https://platform.openai.com/docs/guides/reasoning-best-practices) for using reasoning models.
* The [prompt engineering](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) guide from Anthropic
* Google's [quick start guide](https://services.google.com/fh/files/misc/gemini-for-google-workspace-prompting-guide-101.pdf) for writing effective prompts
* Meta's [prompting documentation](https://www.llama.com/docs/how-to-guides/prompting/) for their Llama model family.
* GitHub's guide for [prompt engineering](https://docs.github.com/en/copilot/using-github-copilot/copilot-chat/prompt-engineering-for-copilot-chat) when using Copilot Chat.

---

# Templates

URL: https://developers.cloudflare.com/workers/get-started/quickstarts/

import { LinkButton, WorkersTemplates } from "~/components";

Templates are GitHub repositories that are designed to be a starting point for building a new Cloudflare Workers project. To start any of the projects below, run:

<WorkersTemplates />

---

## Built with Workers

Get inspiration from other sites and projects out there that were built with Cloudflare Workers.

<LinkButton variant="primary" href="https://workers.cloudflare.com/built-with">
	Built with Workers
</LinkButton>

---

# A/B testing with same-URL direct access

URL: https://developers.cloudflare.com/workers/examples/ab-testing/

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
const NAME = "myExampleWorkersABTest";

export default {
	async fetch(req) {
		const url = new URL(req.url);

		// Enable Passthrough to allow direct access to control and test routes.
		if (url.pathname.startsWith("/control") || url.pathname.startsWith("/test"))
			return fetch(req);

		// Determine which group this requester is in.
		const cookie = req.headers.get("cookie");

		if (cookie && cookie.includes(`${NAME}=control`)) {
			url.pathname = "/control" + url.pathname;
		} else if (cookie && cookie.includes(`${NAME}=test`)) {
			url.pathname = "/test" + url.pathname;
		} else {
			// If there is no cookie, this is a new client. Choose a group and set the cookie.
			const group = Math.random() < 0.5 ? "test" : "control"; // 50/50 split
			if (group === "control") {
				url.pathname = "/control" + url.pathname;
			} else {
				url.pathname = "/test" + url.pathname;
			}
			// Reconstruct response to avoid immutability
			let res = await fetch(url);
			res = new Response(res.body, res);
			// Set cookie to enable persistent A/B sessions.
			res.headers.append("Set-Cookie", `${NAME}=${group}; path=/`);
			return res;
		}
		return fetch(url);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
const NAME = "myExampleWorkersABTest";

export default {
	async fetch(req): Promise<Response> {
		const url = new URL(req.url);
		// Enable Passthrough to allow direct access to control and test routes.
		if (url.pathname.startsWith("/control") || url.pathname.startsWith("/test"))
			return fetch(req);
		// Determine which group this requester is in.
		const cookie = req.headers.get("cookie");
		if (cookie && cookie.includes(`${NAME}=control`)) {
			url.pathname = "/control" + url.pathname;
		} else if (cookie && cookie.includes(`${NAME}=test`)) {
			url.pathname = "/test" + url.pathname;
		} else {
			// If there is no cookie, this is a new client. Choose a group and set the cookie.
			const group = Math.random() < 0.5 ? "test" : "control"; // 50/50 split
			if (group === "control") {
				url.pathname = "/control" + url.pathname;
			} else {
				url.pathname = "/test" + url.pathname;
			}
			// Reconstruct response to avoid immutability
			let res = await fetch(url);
			res = new Response(res.body, res);
			// Set cookie to enable persistent A/B sessions.
			res.headers.append("Set-Cookie", `${NAME}=${group}; path=/`);
			return res;
		}
		return fetch(url);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
import random
from urllib.parse import urlparse, urlunparse
from workers import Response, fetch

NAME = "myExampleWorkersABTest"

async def on_fetch(request):
    url = urlparse(request.url)
    # Uncomment below when testing locally
    # url = url._replace(netloc="example.com") if "localhost" in url.netloc else url

    # Enable Passthrough to allow direct access to control and test routes.
    if url.path.startswith("/control") or url.path.startswith("/test"):
        return fetch(urlunparse(url))

    # Determine which group this requester is in.
    cookie = request.headers.get("cookie")

    if cookie and f'{NAME}=control' in cookie:
        url = url._replace(path="/control" + url.path)
    elif cookie and f'{NAME}=test' in cookie:
        url = url._replace(path="/test" + url.path)
    else:
        # If there is no cookie, this is a new client. Choose a group and set the cookie.
        group = "test" if random.random() < 0.5 else "control"
        if group == "control":
            url = url._replace(path="/control" + url.path)
        else:
            url = url._replace(path="/test" + url.path)

        # Reconstruct response to avoid immutability
        res = await fetch(urlunparse(url))
        headers = dict(res.headers)
        headers["Set-Cookie"] = f'{NAME}={group}; path=/'
        return Response(res.body, headers=headers)

    return fetch(urlunparse(url))
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";
import { getCookie, setCookie } from "hono/cookie";

const app = new Hono();

const NAME = "myExampleWorkersABTest";

// Enable passthrough to allow direct access to control and test routes
app.all("/control/*", (c) => fetch(c.req.raw));
app.all("/test/*", (c) => fetch(c.req.raw));

// Middleware to handle A/B testing logic
app.use("*", async (c) => {
	const url = new URL(c.req.url);

	// Determine which group this requester is in
	const abTestCookie = getCookie(c, NAME);

	if (abTestCookie === "control") {
		// User is in control group
		url.pathname = "/control" + c.req.path;
	} else if (abTestCookie === "test") {
		// User is in test group
		url.pathname = "/test" + c.req.path;
	} else {
		// If there is no cookie, this is a new client
		// Choose a group and set the cookie (50/50 split)
		const group = Math.random() < 0.5 ? "test" : "control";

		// Update URL path based on assigned group
		if (group === "control") {
			url.pathname = "/control" + c.req.path;
		} else {
			url.pathname = "/test" + c.req.path;
		}

		// Set cookie to enable persistent A/B sessions
		setCookie(c, NAME, group, {
			path: "/",
		});
	}

	const res = await fetch(url);

	return c.body(res.body, res);
});

export default app;
```

</TabItem> </Tabs>

---

# 103 Early Hints

URL: https://developers.cloudflare.com/workers/examples/103-early-hints/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/103-early-hints)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

`103` Early Hints is an HTTP status code designed to speed up content delivery. When enabled, Cloudflare can cache the `Link` headers marked with preload and/or preconnect from HTML pages and serve them in a `103` Early Hints response before reaching the origin server. Browsers can use these hints to fetch linked assets while waiting for the origin’s final response, dramatically improving page load speeds.

To ensure Early Hints are enabled on your zone:

1. Log in to the [Cloudflare Dashboard](https://dash.cloudflare.com) and select your account and website.
2. Go to **Speed** > **Optimization** > **Content Optimization**.
3. Enable the **Early Hints** toggle to on.

You can return `Link` headers from a Worker running on your zone to speed up your page load times.

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
const CSS = "body { color: red; }";
const HTML = `
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Early Hints test</title>
    <link rel="stylesheet" href="/test.css">
</head>
<body>
    <h1>Early Hints test page</h1>
</body>
</html>
`;

export default {
	async fetch(req) {
		// If request is for test.css, serve the raw CSS
		if (/test\.css$/.test(req.url)) {
			return new Response(CSS, {
				headers: {
					"content-type": "text/css",
				},
			});
		} else {
			// Serve raw HTML using Early Hints for the CSS file
			return new Response(HTML, {
				headers: {
					"content-type": "text/html",
					link: "</test.css>; rel=preload; as=style",
				},
			});
		}
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```js
const CSS = "body { color: red; }";
const HTML = `
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Early Hints test</title>
    <link rel="stylesheet" href="/test.css">
</head>
<body>
    <h1>Early Hints test page</h1>
</body>
</html>
`;

export default {
  async fetch(req): Promise<Response> {
    // If request is for test.css, serve the raw CSS
    if (/test\.css$/.test(req.url)) {
      return new Response(CSS, {
        headers: {
          "content-type": "text/css",
        },
      });
    } else {
      // Serve raw HTML using Early Hints for the CSS file
      return new Response(HTML, {
        headers: {
          "content-type": "text/html",
          link: "</test.css>; rel=preload; as=style",
        },
      });
    }
  },
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
import re
from workers import Response

CSS = "body { color: red; }"
HTML = """
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Early Hints test</title>
    <link rel="stylesheet" href="/test.css">
</head>
<body>
    <h1>Early Hints test page</h1>
</body>
</html>
"""
def on_fetch(request):
    if re.search("test.css", request.url):
        headers = {"content-type": "text/css"}
        return Response(CSS, headers=headers)
    else:
        headers = {"content-type": "text/html","link": "</test.css>; rel=preload; as=style"}
        return Response(HTML, headers=headers)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";

const app = new Hono();

const CSS = "body { color: red; }";
const HTML = `
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Early Hints test</title>
    <link rel="stylesheet" href="/test.css">
</head>
<body>
    <h1>Early Hints test page</h1>
</body>
</html>
`;

// Serve CSS file
app.get("/test.css", (c) => {
	return c.body(CSS, {
		headers: {
			"content-type": "text/css",
		},
	});
});

// Serve HTML with early hints
app.get("*", (c) => {
	return c.html(HTML, {
		headers: {
			link: "</test.css>; rel=preload; as=style",
		},
	});
});

export default app;
```

</TabItem> </Tabs>

---

# Accessing the Cloudflare Object

URL: https://developers.cloudflare.com/workers/examples/accessing-the-cloudflare-object/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/accessing-the-cloudflare-object)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(req) {
		const data =
			req.cf !== undefined
				? req.cf
				: { error: "The `cf` object is not available inside the preview." };

		return new Response(JSON.stringify(data, null, 2), {
			headers: {
				"content-type": "application/json;charset=UTF-8",
			},
		});
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(req): Promise<Response> {
		const data =
			req.cf !== undefined
				? req.cf
				: { error: "The `cf` object is not available inside the preview." };

		return new Response(JSON.stringify(data, null, 2), {
			headers: {
				"content-type": "application/json;charset=UTF-8",
			},
		});
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";

const app = new Hono();

app.get("*", async (c) => {
	// Access the raw request to get the cf object
	const req = c.req.raw;

	// Check if the cf object is available
	const data =
		req.cf !== undefined
			? req.cf
			: { error: "The `cf` object is not available inside the preview." };

	// Return the data formatted with 2-space indentation
	return c.json(data);
});

export default app;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
import json
from workers import Response
from js import JSON

def on_fetch(request):
    error = json.dumps({ "error": "The `cf` object is not available inside the preview." })
    data = request.cf if request.cf is not None else error
    headers = {"content-type":"application/json"}
    return Response(JSON.stringify(data, None, 2), headers=headers)
```

</TabItem> </Tabs>

---

# Aggregate requests

URL: https://developers.cloudflare.com/workers/examples/aggregate-requests/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/aggregate-requests)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		// someHost is set up to return JSON responses
		const someHost = "https://jsonplaceholder.typicode.com";
		const url1 = someHost + "/todos/1";
		const url2 = someHost + "/todos/2";

		const responses = await Promise.all([fetch(url1), fetch(url2)]);
		const results = await Promise.all(responses.map((r) => r.json()));

		const options = {
			headers: { "content-type": "application/json;charset=UTF-8" },
		};
		return new Response(JSON.stringify(results), options);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request) {
		// someHost is set up to return JSON responses
		const someHost = "https://jsonplaceholder.typicode.com";
		const url1 = someHost + "/todos/1";
		const url2 = someHost + "/todos/2";

		const responses = await Promise.all([fetch(url1), fetch(url2)]);
		const results = await Promise.all(responses.map((r) => r.json()));

		const options = {
			headers: { "content-type": "application/json;charset=UTF-8" },
		};
		return new Response(JSON.stringify(results), options);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";

const app = new Hono();

app.get("*", async (c) => {
	// someHost is set up to return JSON responses
	const someHost = "https://jsonplaceholder.typicode.com";
	const url1 = someHost + "/todos/1";
	const url2 = someHost + "/todos/2";

	// Fetch both URLs concurrently
	const responses = await Promise.all([fetch(url1), fetch(url2)]);

	// Parse JSON responses concurrently
	const results = await Promise.all(responses.map((r) => r.json()));

	// Return aggregated results
	return c.json(results);
});

export default app;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch
import asyncio
import json

async def on_fetch(request):
    # some_host is set up to return JSON responses
    some_host = "https://jsonplaceholder.typicode.com"
    url1 = some_host + "/todos/1"
    url2 = some_host + "/todos/2"

    responses = await asyncio.gather(fetch(url1), fetch(url2))
    results = await asyncio.gather(*(r.json() for r in responses))

    headers = {"content-type": "application/json;charset=UTF-8"}
    return Response.json(results, headers=headers)
```

</TabItem> </Tabs>

---

# Alter headers

URL: https://developers.cloudflare.com/workers/examples/alter-headers/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/alter-headers)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		const response = await fetch("https://example.com");

		// Clone the response so that it's no longer immutable
		const newResponse = new Response(response.body, response);

		// Add a custom header with a value
		newResponse.headers.append(
			"x-workers-hello",
			"Hello from Cloudflare Workers",
		);

		// Delete headers
		newResponse.headers.delete("x-header-to-delete");
		newResponse.headers.delete("x-header2-to-delete");

		// Adjust the value for an existing header
		newResponse.headers.set("x-header-to-change", "NewValue");

		return newResponse;
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const response = await fetch(request);

		// Clone the response so that it's no longer immutable
		const newResponse = new Response(response.body, response);

		// Add a custom header with a value
		newResponse.headers.append(
			"x-workers-hello",
			"Hello from Cloudflare Workers",
		);

		// Delete headers
		newResponse.headers.delete("x-header-to-delete");
		newResponse.headers.delete("x-header2-to-delete");

		// Adjust the value for an existing header
		newResponse.headers.set("x-header-to-change", "NewValue");

		return newResponse;
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch

async def on_fetch(request):
    response = await fetch("https://example.com")

    # Grab the response headers so they can be modified
    new_headers = response.headers

    # Add a custom header with a value
    new_headers["x-workers-hello"] = "Hello from Cloudflare Workers"

    # Delete headers
    if "x-header-to-delete" in new_headers:
        del new_headers["x-header-to-delete"]
    if "x-header2-to-delete" in new_headers:
        del new_headers["x-header2-to-delete"]

    # Adjust the value for an existing header
    new_headers["x-header-to-change"] = "NewValue"

    return Response(response.body, headers=new_headers)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

const app = new Hono();

app.use('*', async (c, next) => {
  // Process the request with the next middleware/handler
  await next();

  // After the response is generated, we can modify its headers

  // Add a custom header with a value
  c.res.headers.append(
    "x-workers-hello",
    "Hello from Cloudflare Workers with Hono"
  );

  // Delete headers
  c.res.headers.delete("x-header-to-delete");
  c.res.headers.delete("x-header2-to-delete");

  // Adjust the value for an existing header
  c.res.headers.set("x-header-to-change", "NewValue");
});

app.get('*', async (c) => {
  // Fetch content from example.com
  const response = await fetch("https://example.com");

  // Return the response body with original headers
  // (our middleware will modify the headers before sending)
  return new Response(response.body, {
    headers: response.headers
  });
});

export default app;
```

</TabItem> </Tabs>

You can also use the [`custom-headers-example` template](https://github.com/kristianfreeman/custom-headers-example) to deploy this code to your custom domain.

---

# Auth with headers

URL: https://developers.cloudflare.com/workers/examples/auth-with-headers/

import { TabItem, Tabs } from "~/components";

:::caution[Caution when using in production]

The example code contains a generic header key and value of `X-Custom-PSK` and `mypresharedkey`. To best protect your resources, change the header key and value in the Workers editor before saving your code.
:::

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		/**
		 * @param {string} PRESHARED_AUTH_HEADER_KEY Custom header to check for key
		 * @param {string} PRESHARED_AUTH_HEADER_VALUE Hard coded key value
		 */
		const PRESHARED_AUTH_HEADER_KEY = "X-Custom-PSK";
		const PRESHARED_AUTH_HEADER_VALUE = "mypresharedkey";
		const psk = request.headers.get(PRESHARED_AUTH_HEADER_KEY);

		if (psk === PRESHARED_AUTH_HEADER_VALUE) {
			// Correct preshared header key supplied. Fetch request from origin.
			return fetch(request);
		}

		// Incorrect key supplied. Reject the request.
		return new Response("Sorry, you have supplied an invalid key.", {
			status: 403,
		});
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		/**
		 * @param {string} PRESHARED_AUTH_HEADER_KEY Custom header to check for key
		 * @param {string} PRESHARED_AUTH_HEADER_VALUE Hard coded key value
		 */
		const PRESHARED_AUTH_HEADER_KEY = "X-Custom-PSK";
		const PRESHARED_AUTH_HEADER_VALUE = "mypresharedkey";
		const psk = request.headers.get(PRESHARED_AUTH_HEADER_KEY);

		if (psk === PRESHARED_AUTH_HEADER_VALUE) {
			// Correct preshared header key supplied. Fetch request from origin.
			return fetch(request);
		}

		// Incorrect key supplied. Reject the request.
		return new Response("Sorry, you have supplied an invalid key.", {
			status: 403,
		});
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch

async def on_fetch(request):
    PRESHARED_AUTH_HEADER_KEY = "X-Custom-PSK"
    PRESHARED_AUTH_HEADER_VALUE = "mypresharedkey"

    psk = request.headers[PRESHARED_AUTH_HEADER_KEY]

    if psk == PRESHARED_AUTH_HEADER_VALUE:
      # Correct preshared header key supplied. Fetch request from origin.
      return fetch(request)

    # Incorrect key supplied. Reject the request.
    return Response("Sorry, you have supplied an invalid key.", status=403)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

const app = new Hono();

// Add authentication middleware
app.use('*', async (c, next) => {
  /**
   * Define authentication constants
   */
  const PRESHARED_AUTH_HEADER_KEY = "X-Custom-PSK";
  const PRESHARED_AUTH_HEADER_VALUE = "mypresharedkey";

  // Get the pre-shared key from the request header
  const psk = c.req.header(PRESHARED_AUTH_HEADER_KEY);

  if (psk === PRESHARED_AUTH_HEADER_VALUE) {
    // Correct preshared header key supplied. Continue to the next handler.
    await next();
  } else {
    // Incorrect key supplied. Reject the request.
    return c.text("Sorry, you have supplied an invalid key.", 403);
  }
});

// Handle all authenticated requests by passing through to origin
app.all('*', async (c) => {
  return fetch(c.req.raw);
});

export default app;
```

</TabItem> </Tabs>

---

# HTTP Basic Authentication

URL: https://developers.cloudflare.com/workers/examples/basic-auth/

import { TabItem, Tabs } from "~/components";

:::note

This example Worker makes use of the [Node.js Buffer API](/workers/runtime-apis/nodejs/buffer/), which is available as part of the Worker's runtime [Node.js compatibility mode](/workers/runtime-apis/nodejs/). To run this Worker, you will need to [enable the `nodejs_compat` compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag).
:::

:::caution[Caution when using in production]

This code is provided as a sample, and is not suitable for production use. Basic Authentication sends credentials unencrypted, and must be used with an HTTPS connection to be considered secure. For a production-ready authentication system, consider using [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/applications/configure-apps/self-hosted-public-app/).

:::

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
/**
 * Shows how to restrict access using the HTTP Basic schema.
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication
 * @see https://tools.ietf.org/html/rfc7617
 *
 */

import { Buffer } from "node:buffer";

const encoder = new TextEncoder();

/**
 * Protect against timing attacks by safely comparing values using `timingSafeEqual`.
 * Refer to https://developers.cloudflare.com/workers/runtime-apis/web-crypto/#timingsafeequal for more details
 * @param {string} a
 * @param {string} b
 * @returns {boolean}
 */
function timingSafeEqual(a, b) {
	const aBytes = encoder.encode(a);
	const bBytes = encoder.encode(b);

	if (aBytes.byteLength !== bBytes.byteLength) {
		// Strings must be the same length in order to compare
		// with crypto.subtle.timingSafeEqual
		return false;
	}

	return crypto.subtle.timingSafeEqual(aBytes, bBytes);
}

export default {
	/**
	 *
	 * @param {Request} request
	 * @param {{PASSWORD: string}} env
	 * @returns
	 */
	async fetch(request, env) {
		const BASIC_USER = "admin";

		// You will need an admin password. This should be
		// attached to your Worker as an encrypted secret.
		// Refer to https://developers.cloudflare.com/workers/configuration/secrets/
		const BASIC_PASS = env.PASSWORD ?? "password";

		const url = new URL(request.url);

		switch (url.pathname) {
			case "/":
				return new Response("Anyone can access the homepage.");

			case "/logout":
				// Invalidate the "Authorization" header by returning a HTTP 401.
				// We do not send a "WWW-Authenticate" header, as this would trigger
				// a popup in the browser, immediately asking for credentials again.
				return new Response("Logged out.", { status: 401 });

			case "/admin": {
				// The "Authorization" header is sent when authenticated.
				const authorization = request.headers.get("Authorization");
				if (!authorization) {
					return new Response("You need to login.", {
						status: 401,
						headers: {
							// Prompts the user for credentials.
							"WWW-Authenticate": 'Basic realm="my scope", charset="UTF-8"',
						},
					});
				}
				const [scheme, encoded] = authorization.split(" ");

				// The Authorization header must start with Basic, followed by a space.
				if (!encoded || scheme !== "Basic") {
					return new Response("Malformed authorization header.", {
						status: 400,
					});
				}

				const credentials = Buffer.from(encoded, "base64").toString();

				// The username & password are split by the first colon.
				//=> example: "username:password"
				const index = credentials.indexOf(":");
				const user = credentials.substring(0, index);
				const pass = credentials.substring(index + 1);

				if (
					!timingSafeEqual(BASIC_USER, user) ||
					!timingSafeEqual(BASIC_PASS, pass)
				) {
					return new Response("You need to login.", {
						status: 401,
						headers: {
							// Prompts the user for credentials.
							"WWW-Authenticate": 'Basic realm="my scope", charset="UTF-8"',
						},
					});
				}

				return new Response("🎉 You have private access!", {
					status: 200,
					headers: {
						"Cache-Control": "no-store",
					},
				});
			}
		}

		return new Response("Not Found.", { status: 404 });
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
/**
 * Shows how to restrict access using the HTTP Basic schema.
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication
 * @see https://tools.ietf.org/html/rfc7617
 *
 */

import { Buffer } from "node:buffer";

const encoder = new TextEncoder();

/**
 * Protect against timing attacks by safely comparing values using `timingSafeEqual`.
 * Refer to https://developers.cloudflare.com/workers/runtime-apis/web-crypto/#timingsafeequal for more details
 */
function timingSafeEqual(a: string, b: string) {
	const aBytes = encoder.encode(a);
	const bBytes = encoder.encode(b);

	if (aBytes.byteLength !== bBytes.byteLength) {
		// Strings must be the same length in order to compare
		// with crypto.subtle.timingSafeEqual
		return false;
	}

	return crypto.subtle.timingSafeEqual(aBytes, bBytes);
}

interface Env {
	PASSWORD: string;
}
export default {
	async fetch(request, env): Promise<Response> {
		const BASIC_USER = "admin";

		// You will need an admin password. This should be
		// attached to your Worker as an encrypted secret.
		// Refer to https://developers.cloudflare.com/workers/configuration/secrets/
		const BASIC_PASS = env.PASSWORD ?? "password";

		const url = new URL(request.url);

		switch (url.pathname) {
			case "/":
				return new Response("Anyone can access the homepage.");

			case "/logout":
				// Invalidate the "Authorization" header by returning a HTTP 401.
				// We do not send a "WWW-Authenticate" header, as this would trigger
				// a popup in the browser, immediately asking for credentials again.
				return new Response("Logged out.", { status: 401 });

			case "/admin": {
				// The "Authorization" header is sent when authenticated.
				const authorization = request.headers.get("Authorization");
				if (!authorization) {
					return new Response("You need to login.", {
						status: 401,
						headers: {
							// Prompts the user for credentials.
							"WWW-Authenticate": 'Basic realm="my scope", charset="UTF-8"',
						},
					});
				}
				const [scheme, encoded] = authorization.split(" ");

				// The Authorization header must start with Basic, followed by a space.
				if (!encoded || scheme !== "Basic") {
					return new Response("Malformed authorization header.", {
						status: 400,
					});
				}

				const credentials = Buffer.from(encoded, "base64").toString();

				// The username and password are split by the first colon.
				//=> example: "username:password"
				const index = credentials.indexOf(":");
				const user = credentials.substring(0, index);
				const pass = credentials.substring(index + 1);

				if (
					!timingSafeEqual(BASIC_USER, user) ||
					!timingSafeEqual(BASIC_PASS, pass)
				) {
					return new Response("You need to login.", {
						status: 401,
						headers: {
							// Prompts the user for credentials.
							"WWW-Authenticate": 'Basic realm="my scope", charset="UTF-8"',
						},
					});
				}

				return new Response("🎉 You have private access!", {
					status: 200,
					headers: {
						"Cache-Control": "no-store",
					},
				});
			}
		}

		return new Response("Not Found.", { status: 404 });
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> <TabItem label="Rust" icon="seti:rust">
```rs
use base64::prelude::*;
use worker::*;

#[event(fetch)]
async fn fetch(req: Request, env: Env, _ctx: Context) -> Result<Response> {
let basic_user = "admin";
// You will need an admin password. This should be
// attached to your Worker as an encrypted secret.
// Refer to https://developers.cloudflare.com/workers/configuration/secrets/
let basic_pass = match env.secret("PASSWORD") {
Ok(s) => s.to_string(),
Err(_) => "password".to_string(),
};
let url = req.url()?;

    match url.path() {
        "/" => Response::ok("Anyone can access the homepage."),
        // Invalidate the "Authorization" header by returning a HTTP 401.
        // We do not send a "WWW-Authenticate" header, as this would trigger
        // a popup in the browser, immediately asking for credentials again.
        "/logout" => Response::error("Logged out.", 401),
        "/admin" => {
            // The "Authorization" header is sent when authenticated.
            let authorization = req.headers().get("Authorization")?;
            if authorization == None {
                let mut headers = Headers::new();
                // Prompts the user for credentials.
                headers.set(
                    "WWW-Authenticate",
                    "Basic realm='my scope', charset='UTF-8'",
                )?;
                return Ok(Response::error("You need to login.", 401)?.with_headers(headers));
            }
            let authorization = authorization.unwrap();
            let auth: Vec<&str> = authorization.split(" ").collect();
            let scheme = auth[0];
            let encoded = auth[1];

            // The Authorization header must start with Basic, followed by a space.
            if encoded == "" || scheme != "Basic" {
                return Response::error("Malformed authorization header.", 400);
            }

            let buff = BASE64_STANDARD.decode(encoded).unwrap();
            let credentials = String::from_utf8_lossy(&buff);
            // The username & password are split by the first colon.
            //=> example: "username:password"
            let credentials: Vec<&str> = credentials.split(':').collect();
            let user = credentials[0];
            let pass = credentials[1];

            if user != basic_user || pass != basic_pass {
                let mut headers = Headers::new();
                // Prompts the user for credentials.
                headers.set(
                    "WWW-Authenticate",
                    "Basic realm='my scope', charset='UTF-8'",
                )?;
                return Ok(Response::error("You need to login.", 401)?.with_headers(headers));
            }

            let mut headers = Headers::new();
            headers.set("Cache-Control", "no-store")?;
            Ok(Response::ok("🎉 You have private access!")?.with_headers(headers))
        }
        _ => Response::error("Not Found.", 404),
    }

}

````
</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
/**
 * Shows how to restrict access using the HTTP Basic schema with Hono.
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication
 * @see https://tools.ietf.org/html/rfc7617
 */

import { Hono } from "hono";
import { basicAuth } from "hono/basic-auth";

// Define environment interface
interface Env {
  Bindings: {
		USERNAME: string;
    PASSWORD: string;
  };
}

const app = new Hono<Env>();

// Public homepage - accessible to everyone
app.get("/", (c) => {
  return c.text("Anyone can access the homepage.");
});

// Admin route - protected with Basic Auth
app.get(
	"/admin",
	async (c, next) => {
		const auth = basicAuth({
			username: c.env.USERNAME,
			password: c.env.PASSWORD
		})

		return await auth(c, next);
	},
	(c) => {
		return c.text("🎉 You have private access!", 200, {
			"Cache-Control": "no-store",
		});
	}
);

export default app;
````

</TabItem> </Tabs>

---

# Block on TLS

URL: https://developers.cloudflare.com/workers/examples/block-on-tls/

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		try {
			const tlsVersion = request.cf.tlsVersion;
			// Allow only TLS versions 1.2 and 1.3
			if (tlsVersion !== "TLSv1.2" && tlsVersion !== "TLSv1.3") {
				return new Response("Please use TLS version 1.2 or higher.", {
					status: 403,
				});
			}
			return fetch(request);
		} catch (err) {
			console.error(
				"request.cf does not exist in the previewer, only in production",
			);
			return new Response(`Error in workers script ${err.message}`, {
				status: 500,
			});
		}
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		try {
			const tlsVersion = request.cf.tlsVersion;
			// Allow only TLS versions 1.2 and 1.3
			if (tlsVersion !== "TLSv1.2" && tlsVersion !== "TLSv1.3") {
				return new Response("Please use TLS version 1.2 or higher.", {
					status: 403,
				});
			}
			return fetch(request);
		} catch (err) {
			console.error(
				"request.cf does not exist in the previewer, only in production",
			);
			return new Response(`Error in workers script ${err.message}`, {
				status: 500,
			});
		}
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";

const app = new Hono();

// Middleware to check TLS version
app.use("*", async (c, next) => {
	// Access the raw request to get the cf object with TLS info
	const request = c.req.raw;
	const tlsVersion = request.cf?.tlsVersion;

	// Allow only TLS versions 1.2 and 1.3
	if (tlsVersion !== "TLSv1.2" && tlsVersion !== "TLSv1.3") {
		return c.text("Please use TLS version 1.2 or higher.", 403);
	}

	await next();

});

app.onError((err, c) => {
		console.error(
			"request.cf does not exist in the previewer, only in production",
		);
		return c.text(`Error in workers script: ${err.message}`, 500);
});

app.get("/", async (c) => {
	return c.text(`TLS Version: ${c.req.raw.cf.tlsVersion}`);
});

export default app;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch

async def on_fetch(request):
    tls_version = request.cf.tlsVersion
    if tls_version not in ("TLSv1.2", "TLSv1.3"):
        return Response("Please use TLS version 1.2 or higher.", status=403)
    return fetch(request)
```

</TabItem> </Tabs>

---

# Bulk origin override

URL: https://developers.cloudflare.com/workers/examples/bulk-origin-proxy/

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		/**
		 * An object with different URLs to fetch
		 * @param {Object} ORIGINS
		 */
		const ORIGINS = {
			"starwarsapi.yourdomain.com": "swapi.dev",
			"google.yourdomain.com": "www.google.com",
		};

		const url = new URL(request.url);

		// Check if incoming hostname is a key in the ORIGINS object
		if (url.hostname in ORIGINS) {
			const target = ORIGINS[url.hostname];
			url.hostname = target;
			// If it is, proxy request to that third party origin
			return fetch(url.toString(), request);
		}
		// Otherwise, process request as normal
		return fetch(request);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		/**
		 * An object with different URLs to fetch
		 * @param {Object} ORIGINS
		 */
		const ORIGINS = {
			"starwarsapi.yourdomain.com": "swapi.dev",
			"google.yourdomain.com": "www.google.com",
		};

		const url = new URL(request.url);

		// Check if incoming hostname is a key in the ORIGINS object
		if (url.hostname in ORIGINS) {
			const target = ORIGINS[url.hostname];
			url.hostname = target;
			// If it is, proxy request to that third party origin
			return fetch(url.toString(), request);
		}
		// Otherwise, process request as normal
		return fetch(request);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";
import { proxy } from "hono/proxy";

// An object with different URLs to fetch
const ORIGINS: Record<string, string> = {
	"starwarsapi.yourdomain.com": "swapi.dev",
	"google.yourdomain.com": "www.google.com",
};

const app = new Hono();

app.all("*", async (c) => {
	const url = new URL(c.req.url);

	// Check if incoming hostname is a key in the ORIGINS object
	if (url.hostname in ORIGINS) {
		const target = ORIGINS[url.hostname];
		url.hostname = target;

		// If it is, proxy request to that third party origin
		return proxy(url, c.req.raw);
	}

	// Otherwise, process request as normal
	return proxy(c.req.raw);
});

export default app;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from js import fetch, URL

async def on_fetch(request):
    # A dict with different URLs to fetch
    ORIGINS = {
      "starwarsapi.yourdomain.com": "swapi.dev",
      "google.yourdomain.com": "www.google.com",
    }

    url = URL.new(request.url)

    # Check if incoming hostname is a key in the ORIGINS object
    if url.hostname in ORIGINS:
        url.hostname = ORIGINS[url.hostname]
        # If it is, proxy request to that third party origin
        return fetch(url.toString(), request)

    # Otherwise, process request as normal
    return fetch(request)
```

</TabItem> </Tabs>

---

# Bulk redirects

URL: https://developers.cloudflare.com/workers/examples/bulk-redirects/

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		const externalHostname = "examples.cloudflareworkers.com";

		const redirectMap = new Map([
			["/bulk1", "https://" + externalHostname + "/redirect2"],
			["/bulk2", "https://" + externalHostname + "/redirect3"],
			["/bulk3", "https://" + externalHostname + "/redirect4"],
			["/bulk4", "https://google.com"],
		]);

		const requestURL = new URL(request.url);
		const path = requestURL.pathname;
		const location = redirectMap.get(path);

		if (location) {
			return Response.redirect(location, 301);
		}
		// If request not in map, return the original request
		return fetch(request);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const externalHostname = "examples.cloudflareworkers.com";

		const redirectMap = new Map([
			["/bulk1", "https://" + externalHostname + "/redirect2"],
			["/bulk2", "https://" + externalHostname + "/redirect3"],
			["/bulk3", "https://" + externalHostname + "/redirect4"],
			["/bulk4", "https://google.com"],
		]);

		const requestURL = new URL(request.url);
		const path = requestURL.pathname;
		const location = redirectMap.get(path);

		if (location) {
			return Response.redirect(location, 301);
		}
		// If request not in map, return the original request
		return fetch(request);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch
from urllib.parse import urlparse

async def on_fetch(request):
    external_hostname = "examples.cloudflareworkers.com"

    redirect_map = {
      "/bulk1": "https://" + external_hostname + "/redirect2",
      "/bulk2": "https://" + external_hostname + "/redirect3",
      "/bulk3": "https://" + external_hostname + "/redirect4",
      "/bulk4": "https://google.com",
      }

    url = urlparse(request.url)
    location = redirect_map.get(url.path, None)

    if location:
        return Response.redirect(location, 301)

    # If request not in map, return the original request
    return fetch(request)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";

const app = new Hono();

// Configure your redirects
const externalHostname = "examples.cloudflareworkers.com";

const redirectMap = new Map([
	["/bulk1", `https://${externalHostname}/redirect2`],
	["/bulk2", `https://${externalHostname}/redirect3`],
	["/bulk3", `https://${externalHostname}/redirect4`],
	["/bulk4", "https://google.com"],
]);

// Middleware to handle redirects
app.use("*", async (c, next) => {
	const path = c.req.path;
	const location = redirectMap.get(path);

	if (location) {
		// If path is in our redirect map, perform the redirect
		return c.redirect(location, 301);
	}

	// Otherwise, continue to the next handler
	await next();
});

// Default handler for requests that don't match any redirects
app.all("*", async (c) => {
	// Pass through to origin
	return fetch(c.req.raw);
});

export default app;
```

</TabItem> </Tabs>

---

# Using the Cache API

URL: https://developers.cloudflare.com/workers/examples/cache-api/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/cache-api)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request, env, ctx) {
		const cacheUrl = new URL(request.url);

		// Construct the cache key from the cache URL
		const cacheKey = new Request(cacheUrl.toString(), request);
		const cache = caches.default;

		// Check whether the value is already available in the cache
		// if not, you will need to fetch it from origin, and store it in the cache
		let response = await cache.match(cacheKey);

		if (!response) {
			console.log(
				`Response for request url: ${request.url} not present in cache. Fetching and caching request.`,
			);
			// If not in cache, get it from origin
			response = await fetch(request);

			// Must use Response constructor to inherit all of response's fields
			response = new Response(response.body, response);

			// Cache API respects Cache-Control headers. Setting s-max-age to 10
			// will limit the response to be in cache for 10 seconds max

			// Any changes made to the response here will be reflected in the cached value
			response.headers.append("Cache-Control", "s-maxage=10");

			ctx.waitUntil(cache.put(cacheKey, response.clone()));
		} else {
			console.log(`Cache hit for: ${request.url}.`);
		}
		return response;
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Env {}
export default {
	async fetch(request, env, ctx): Promise<Response> {
		const cacheUrl = new URL(request.url);

		// Construct the cache key from the cache URL
		const cacheKey = new Request(cacheUrl.toString(), request);
		const cache = caches.default;

		// Check whether the value is already available in the cache
		// if not, you will need to fetch it from origin, and store it in the cache
		let response = await cache.match(cacheKey);

		if (!response) {
			console.log(
				`Response for request url: ${request.url} not present in cache. Fetching and caching request.`,
			);
			// If not in cache, get it from origin
			response = await fetch(request);

			// Must use Response constructor to inherit all of response's fields
			response = new Response(response.body, response);

			// Cache API respects Cache-Control headers. Setting s-max-age to 10
			// will limit the response to be in cache for 10 seconds max

			// Any changes made to the response here will be reflected in the cached value
			response.headers.append("Cache-Control", "s-maxage=10");

			ctx.waitUntil(cache.put(cacheKey, response.clone()));
		} else {
			console.log(`Cache hit for: ${request.url}.`);
		}
		return response;
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from pyodide.ffi import create_proxy
from js import Response, Request, URL, caches, fetch

async def on_fetch(request, _env, ctx):
    cache_url = request.url

    # Construct the cache key from the cache URL
    cache_key = Request.new(cache_url, request)
    cache = caches.default

    # Check whether the value is already available in the cache
    # if not, you will need to fetch it from origin, and store it in the cache
    response = await cache.match(cache_key)

    if response is None:
        print(f"Response for request url: {request.url} not present in cache. Fetching and caching request.")
        # If not in cache, get it from origin
        response = await fetch(request)
        # Must use Response constructor to inherit all of response's fields
        response = Response.new(response.body, response)

        # Cache API respects Cache-Control headers. Setting s-max-age to 10
        # will limit the response to be in cache for 10 seconds s-maxage
        # Any changes made to the response here will be reflected in the cached value
        response.headers.append("Cache-Control", "s-maxage=10")
        ctx.waitUntil(create_proxy(cache.put(cache_key, response.clone())))
    else:
        print(f"Cache hit for: {request.url}.")
    return response
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";
import { cache } from "hono/cache";

const app = new Hono();

// We leverage hono built-in cache helper here
app.get(
	"*",
	cache({
		cacheName: "my-cache",
		cacheControl: "max-age=3600", // 1 hour
	}),
);

// Add a route to handle the request if it's not in cache
app.get("*", (c) => {
	return c.text("Hello from Hono!");
});

export default app;
```

</TabItem> </Tabs>

---

# Cache POST requests

URL: https://developers.cloudflare.com/workers/examples/cache-post-request/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/cache-post-request)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request, env, ctx) {
		async function sha256(message) {
			// encode as UTF-8
			const msgBuffer = await new TextEncoder().encode(message);
			// hash the message
			const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer);
			// convert bytes to hex string
			return [...new Uint8Array(hashBuffer)]
				.map((b) => b.toString(16).padStart(2, "0"))
				.join("");
		}
		try {
			if (request.method.toUpperCase() === "POST") {
				const body = await request.clone().text();
				// Hash the request body to use it as a part of the cache key
				const hash = await sha256(body);
				const cacheUrl = new URL(request.url);
				// Store the URL in cache by prepending the body's hash
				cacheUrl.pathname = "/posts" + cacheUrl.pathname + hash;
				// Convert to a GET to be able to cache
				const cacheKey = new Request(cacheUrl.toString(), {
					headers: request.headers,
					method: "GET",
				});

				const cache = caches.default;
				// Find the cache key in the cache
				let response = await cache.match(cacheKey);
				// Otherwise, fetch response to POST request from origin
				if (!response) {
					response = await fetch(request);
					ctx.waitUntil(cache.put(cacheKey, response.clone()));
				}
				return response;
			}
			return fetch(request);
		} catch (e) {
			return new Response("Error thrown " + e.message);
		}
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Env {}
export default {
	async fetch(request, env, ctx): Promise<Response> {
		async function sha256(message) {
			// encode as UTF-8
			const msgBuffer = await new TextEncoder().encode(message);
			// hash the message
			const hashBuffer = await crypto.subtle.digest("SHA-256", msgBuffer);
			// convert bytes to hex string
			return [...new Uint8Array(hashBuffer)]
				.map((b) => b.toString(16).padStart(2, "0"))
				.join("");
		}
		try {
			if (request.method.toUpperCase() === "POST") {
				const body = await request.clone().text();
				// Hash the request body to use it as a part of the cache key
				const hash = await sha256(body);
				const cacheUrl = new URL(request.url);
				// Store the URL in cache by prepending the body's hash
				cacheUrl.pathname = "/posts" + cacheUrl.pathname + hash;
				// Convert to a GET to be able to cache
				const cacheKey = new Request(cacheUrl.toString(), {
					headers: request.headers,
					method: "GET",
				});

				const cache = caches.default;
				// Find the cache key in the cache
				let response = await cache.match(cacheKey);
				// Otherwise, fetch response to POST request from origin
				if (!response) {
					response = await fetch(request);
					ctx.waitUntil(cache.put(cacheKey, response.clone()));
				}
				return response;
			}
			return fetch(request);
		} catch (e) {
			return new Response("Error thrown " + e.message);
		}
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
import hashlib
from pyodide.ffi import create_proxy
from js import fetch, URL, Headers, Request, caches

async def on_fetch(request, _, ctx):
    if 'POST' in request.method:
        # Hash the request body to use it as a part of the cache key
        body = await request.clone().text()
        body_hash = hashlib.sha256(body.encode('UTF-8')).hexdigest()

        # Store the URL in cache by prepending the body's hash
        cache_url = URL.new(request.url)
        cache_url.pathname = "/posts" + cache_url.pathname + body_hash

        # Convert to a GET to be able to cache
        headers = Headers.new(dict(request.headers).items())
        cache_key = Request.new(cache_url.toString(), method='GET', headers=headers)

        # Find the cache key in the cache
        cache = caches.default
        response = await cache.match(cache_key)

        # Otherwise, fetch response to POST request from origin
        if response is None:
            response = await fetch(request)
            ctx.waitUntil(create_proxy(cache.put(cache_key, response.clone())))

        return response

    return fetch(request)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";
import { sha256 } from "hono/utils/crypto";

const app = new Hono();

// Middleware for caching POST requests
app.post("*", async (c) => {
	try {
		// Get the request body
		const body = await c.req.raw.clone().text();

		// Hash the request body to use it as part of the cache key
		const hash = await sha256(body);

		// Create the cache URL
		const cacheUrl = new URL(c.req.url);

		// Store the URL in cache by prepending the body's hash
		cacheUrl.pathname = "/posts" + cacheUrl.pathname + hash;

		// Convert to a GET to be able to cache
		const cacheKey = new Request(cacheUrl.toString(), {
			headers: c.req.raw.headers,
			method: "GET",
		});

		const cache = caches.default;

		// Find the cache key in the cache
		let response = await cache.match(cacheKey);

		// If not in cache, fetch response to POST request from origin
		if (!response) {
			response = await fetch(c.req.raw);
			c.executionCtx.waitUntil(cache.put(cacheKey, response.clone()));
		}

		return response;
	} catch (e) {
		return c.text("Error thrown " + e.message, 500);
	}
});

// Handle all other HTTP methods
app.all("*", (c) => {
	return fetch(c.req.raw);
});

export default app;
```

</TabItem> </Tabs>

---

# Cache Tags using Workers

URL: https://developers.cloudflare.com/workers/examples/cache-tags/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/cache-tags)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		const requestUrl = new URL(request.url);
		const params = requestUrl.searchParams;
		const tags =
			params && params.has("tags") ? params.get("tags").split(",") : [];
		const url = params && params.has("uri") ? params.get("uri") : "";
		if (!url) {
			const errorObject = {
				error: "URL cannot be empty",
			};
			return new Response(JSON.stringify(errorObject), { status: 400 });
		}
		const init = {
			cf: {
				cacheTags: tags,
			},
		};
		return fetch(url, init)
			.then((result) => {
				const cacheStatus = result.headers.get("cf-cache-status");
				const lastModified = result.headers.get("last-modified");
				const response = {
					cache: cacheStatus,
					lastModified: lastModified,
				};
				return new Response(JSON.stringify(response), {
					status: result.status,
				});
			})
			.catch((err) => {
				const errorObject = {
					error: err.message,
				};
				return new Response(JSON.stringify(errorObject), { status: 500 });
			});
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const requestUrl = new URL(request.url);
		const params = requestUrl.searchParams;
		const tags =
			params && params.has("tags") ? params.get("tags").split(",") : [];
		const url = params && params.has("uri") ? params.get("uri") : "";
		if (!url) {
			const errorObject = {
				error: "URL cannot be empty",
			};
			return new Response(JSON.stringify(errorObject), { status: 400 });
		}
		const init = {
			cf: {
				cacheTags: tags,
			},
		};
		return fetch(url, init)
			.then((result) => {
				const cacheStatus = result.headers.get("cf-cache-status");
				const lastModified = result.headers.get("last-modified");
				const response = {
					cache: cacheStatus,
					lastModified: lastModified,
				};
				return new Response(JSON.stringify(response), {
					status: result.status,
				});
			})
			.catch((err) => {
				const errorObject = {
					error: err.message,
				};
				return new Response(JSON.stringify(errorObject), { status: 500 });
			});
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";

const app = new Hono();

app.all("*", async (c) => {
	const tags = c.req.query("tags") ? c.req.query("tags").split(",") : [];
	const uri = c.req.query("uri") ? c.req.query("uri") : "";

	if (!uri) {
		return c.json({ error: "URL cannot be empty" }, 400);
	}

	const init = {
		cf: {
			cacheTags: tags,
		},
	};

	const result = await fetch(uri, init);
	const cacheStatus = result.headers.get("cf-cache-status");
	const lastModified = result.headers.get("last-modified");

	const response = {
		cache: cacheStatus,
		lastModified: lastModified,
	};

	return c.json(response, result.status);
});

app.onError((err, c) => {
	return c.json({ error: err.message }, 500);
});

export default app;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from pyodide.ffi import to_js as _to_js
from js import Response, URL, Object, fetch

def to_js(x):
    return _to_js(x, dict_converter=Object.fromEntries)

async def on_fetch(request):
    request_url = URL.new(request.url)
    params = request_url.searchParams
    tags = params["tags"].split(",") if "tags" in params else []
    url = params["uri"] or None

    if url is None:
        error = {"error": "URL cannot be empty"}
        return Response.json(to_js(error), status=400)

    options = {"cf": {"cacheTags": tags}}
    result = await fetch(url, to_js(options))

    cache_status = result.headers["cf-cache-status"]
    last_modified = result.headers["last-modified"]
    response = {"cache": cache_status, "lastModified": last_modified}

    return Response.json(to_js(response), status=result.status)
```

</TabItem> </Tabs>

---

# Conditional response

URL: https://developers.cloudflare.com/workers/examples/conditional-response/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/conditional-response)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		const BLOCKED_HOSTNAMES = ["nope.mywebsite.com", "bye.website.com"];
		// Return a new Response based on a URL's hostname
		const url = new URL(request.url);
		if (BLOCKED_HOSTNAMES.includes(url.hostname)) {
			return new Response("Blocked Host", { status: 403 });
		}
		// Block paths ending in .doc or .xml based on the URL's file extension
		const forbiddenExtRegExp = new RegExp(/\.(doc|xml)$/);
		if (forbiddenExtRegExp.test(url.pathname)) {
			return new Response("Blocked Extension", { status: 403 });
		}
		// On HTTP method
		if (request.method === "POST") {
			return new Response("Response for POST");
		}
		// On User Agent
		const userAgent = request.headers.get("User-Agent") || "";
		if (userAgent.includes("bot")) {
			return new Response("Block User Agent containing bot", { status: 403 });
		}
		// On Client's IP address
		const clientIP = request.headers.get("CF-Connecting-IP");
		if (clientIP === "1.2.3.4") {
			return new Response("Block the IP 1.2.3.4", { status: 403 });
		}
		// On ASN
		if (request.cf && request.cf.asn == 64512) {
			return new Response("Block the ASN 64512 response");
		}
		// On Device Type
		// Requires Enterprise "CF-Device-Type Header" zone setting or
		// Page Rule with "Cache By Device Type" setting applied.
		const device = request.headers.get("CF-Device-Type");
		if (device === "mobile") {
			return Response.redirect("https://mobile.example.com");
		}
		console.error(
			"Getting Client's IP address, device type, and ASN are not supported in playground. Must test on a live worker",
		);
		return fetch(request);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const BLOCKED_HOSTNAMES = ["nope.mywebsite.com", "bye.website.com"];
		// Return a new Response based on a URL's hostname
		const url = new URL(request.url);
		if (BLOCKED_HOSTNAMES.includes(url.hostname)) {
			return new Response("Blocked Host", { status: 403 });
		}
		// Block paths ending in .doc or .xml based on the URL's file extension
		const forbiddenExtRegExp = new RegExp(/\.(doc|xml)$/);
		if (forbiddenExtRegExp.test(url.pathname)) {
			return new Response("Blocked Extension", { status: 403 });
		}
		// On HTTP method
		if (request.method === "POST") {
			return new Response("Response for POST");
		}
		// On User Agent
		const userAgent = request.headers.get("User-Agent") || "";
		if (userAgent.includes("bot")) {
			return new Response("Block User Agent containing bot", { status: 403 });
		}
		// On Client's IP address
		const clientIP = request.headers.get("CF-Connecting-IP");
		if (clientIP === "1.2.3.4") {
			return new Response("Block the IP 1.2.3.4", { status: 403 });
		}
		// On ASN
		if (request.cf && request.cf.asn == 64512) {
			return new Response("Block the ASN 64512 response");
		}
		// On Device Type
		// Requires Enterprise "CF-Device-Type Header" zone setting or
		// Page Rule with "Cache By Device Type" setting applied.
		const device = request.headers.get("CF-Device-Type");
		if (device === "mobile") {
			return Response.redirect("https://mobile.example.com");
		}
		console.error(
			"Getting Client's IP address, device type, and ASN are not supported in playground. Must test on a live worker",
		);
		return fetch(request);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
import re
from workers import Response
from urllib.parse import urlparse

async def on_fetch(request):
    blocked_hostnames = ["nope.mywebsite.com", "bye.website.com"]
    url = urlparse(request.url)

    # Block on hostname
    if url.hostname in blocked_hostnames:
        return Response("Blocked Host", status=403)

    # On paths ending in .doc or .xml
    if re.search(r'\.(doc|xml)$', url.path):
        return Response("Blocked Extension", status=403)

    # On HTTP method
    if "POST" in request.method:
        return Response("Response for POST")

    # On User Agent
    user_agent = request.headers["User-Agent"] or ""
    if "bot" in user_agent:
        return Response("Block User Agent containing bot", status=403)

    # On Client's IP address
    client_ip = request.headers["CF-Connecting-IP"]
    if client_ip == "1.2.3.4":
        return Response("Block the IP 1.2.3.4", status=403)

    # On ASN
    if request.cf and request.cf.asn == 64512:
        return Response("Block the ASN 64512 response")

    # On Device Type
    # Requires Enterprise "CF-Device-Type Header" zone setting or
    # Page Rule with "Cache By Device Type" setting applied.
    device = request.headers["CF-Device-Type"]
    if device == "mobile":
        return Response.redirect("https://mobile.example.com")

    return fetch(request)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";
import { HTTPException } from "hono/http-exception";

const app = new Hono();

// Middleware to handle all conditions before reaching the main handler
app.use("*", async (c, next) => {
	const request = c.req.raw;
	const BLOCKED_HOSTNAMES = ["nope.mywebsite.com", "bye.website.com"];
	const hostname = new URL(c.req.url)?.hostname;

	// Return a new Response based on a URL's hostname
	if (BLOCKED_HOSTNAMES.includes(hostname)) {
		return c.text("Blocked Host", 403);
	}

	// Block paths ending in .doc or .xml based on the URL's file extension
	const forbiddenExtRegExp = new RegExp(/\.(doc|xml)$/);
	if (forbiddenExtRegExp.test(c.req.pathname)) {
		return c.text("Blocked Extension", 403);
	}

	// On User Agent
	const userAgent = c.req.header("User-Agent") || "";
	if (userAgent.includes("bot")) {
		return c.text("Block User Agent containing bot", 403);
	}

	// On Client's IP address
	const clientIP = c.req.header("CF-Connecting-IP");
	if (clientIP === "1.2.3.4") {
		return c.text("Block the IP 1.2.3.4", 403);
	}

	// On ASN
	if (request.cf && request.cf.asn === 64512) {
		return c.text("Block the ASN 64512 response");
	}

	// On Device Type
	// Requires Enterprise "CF-Device-Type Header" zone setting or
	// Page Rule with "Cache By Device Type" setting applied.
	const device = c.req.header("CF-Device-Type");
	if (device === "mobile") {
		return c.redirect("https://mobile.example.com");
	}

	// Continue to the next handler
	await next();
});

// Handle POST requests differently
app.post("*", (c) => {
	return c.text("Response for POST");
});

// Default handler for other methods
app.get("*", async (c) => {
	console.error(
		"Getting Client's IP address, device type, and ASN are not supported in playground. Must test on a live worker",
	);

	// Fetch the original request
	return fetch(c.req.raw);
});

export default app;
```

</TabItem> </Tabs>

---

# Cache using fetch

URL: https://developers.cloudflare.com/workers/examples/cache-using-fetch/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/cache-using-fetch)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		const url = new URL(request.url);
		// Only use the path for the cache key, removing query strings
		// and always store using HTTPS, for example, https://www.example.com/file-uri-here
		const someCustomKey = `https://${url.hostname}${url.pathname}`;
		let response = await fetch(request, {
			cf: {
				// Always cache this fetch regardless of content type
				// for a max of 5 seconds before revalidating the resource
				cacheTtl: 5,
				cacheEverything: true,
				//Enterprise only feature, see Cache API for other plans
				cacheKey: someCustomKey,
			},
		});
		// Reconstruct the Response object to make its headers mutable.
		response = new Response(response.body, response);
		// Set cache control headers to cache on browser for 25 minutes
		response.headers.set("Cache-Control", "max-age=1500");
		return response;
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const url = new URL(request.url);
		// Only use the path for the cache key, removing query strings
		// and always store using HTTPS, for example, https://www.example.com/file-uri-here
		const someCustomKey = `https://${url.hostname}${url.pathname}`;
		let response = await fetch(request, {
			cf: {
				// Always cache this fetch regardless of content type
				// for a max of 5 seconds before revalidating the resource
				cacheTtl: 5,
				cacheEverything: true,
				//Enterprise only feature, see Cache API for other plans
				cacheKey: someCustomKey,
			},
		});
		// Reconstruct the Response object to make its headers mutable.
		response = new Response(response.body, response);
		// Set cache control headers to cache on browser for 25 minutes
		response.headers.set("Cache-Control", "max-age=1500");
		return response;
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

type Bindings = {};

const app = new Hono<{ Bindings: Bindings }>();

app.all('*', async (c) => {
  const url = new URL(c.req.url);

  // Only use the path for the cache key, removing query strings
  // and always store using HTTPS, for example, https://www.example.com/file-uri-here
  const someCustomKey = `https://${url.hostname}${url.pathname}`;

  // Fetch the request with custom cache settings
  let response = await fetch(c.req.raw, {
    cf: {
      // Always cache this fetch regardless of content type
      // for a max of 5 seconds before revalidating the resource
      cacheTtl: 5,
      cacheEverything: true,
      // Enterprise only feature, see Cache API for other plans
      cacheKey: someCustomKey,
    },
  });

  // Reconstruct the Response object to make its headers mutable
  response = new Response(response.body, response);

  // Set cache control headers to cache on browser for 25 minutes
  response.headers.set("Cache-Control", "max-age=1500");

  return response;
});

export default app;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from pyodide.ffi import to_js as _to_js
from js import Response, URL, Object, fetch

def to_js(x):
    return _to_js(x, dict_converter=Object.fromEntries)

async def on_fetch(request):
    url = URL.new(request.url)

    # Only use the path for the cache key, removing query strings
    # and always store using HTTPS, for example, https://www.example.com/file-uri-here
    some_custom_key = f"https://{url.hostname}{url.pathname}"

    response = await fetch(
        request,
        cf=to_js({
            # Always cache this fetch regardless of content type
            # for a max of 5 seconds before revalidating the resource
            "cacheTtl": 5,
            "cacheEverything": True,
            # Enterprise only feature, see Cache API for other plans
            "cacheKey": some_custom_key,
        }),
    )

    # Reconstruct the Response object to make its headers mutable
    response = Response.new(response.body, response)

    # Set cache control headers to cache on browser for 25 minutes
    response.headers["Cache-Control"] = "max-age=1500"

    return response
```

</TabItem> <TabItem label="Rust" icon="seti:rust">

```rs
use worker::*;

#[event(fetch)]
async fn fetch(req: Request, _env: Env, _ctx: Context) -> Result<Response> {
    let url = req.url()?;

    // Only use the path for the cache key, removing query strings
    // and always store using HTTPS, for example, https://www.example.com/file-uri-here
    let custom_key = format!(
        "https://{host}{path}",
        host = url.host_str().unwrap(),
        path = url.path()
    );

    let request = Request::new_with_init(
        url.as_str(),
        &RequestInit {
            headers: req.headers().clone(),
            method: req.method(),
            cf: CfProperties {
                // Always cache this fetch regardless of content type
                // for a max of 5 seconds before revalidating the resource
                cache_ttl: Some(5),
                cache_everything: Some(true),
                // Enterprise only feature, see Cache API for other plans
                cache_key: Some(custom_key),
                ..CfProperties::default()
            },
            ..RequestInit::default()
        },
    )?;

    let mut response = Fetch::Request(request).send().await?;

    // Set cache control headers to cache on browser for 25 minutes
    let _ = response.headers_mut().set("Cache-Control", "max-age=1500");
    Ok(response)
}
```

</TabItem> </Tabs>

## Caching HTML resources

```js
// Force Cloudflare to cache an asset
fetch(event.request, { cf: { cacheEverything: true } });
```

Setting the cache level to **Cache Everything** will override the default cacheability of the asset. For time-to-live (TTL), Cloudflare will still rely on headers set by the origin.

## Custom cache keys

:::note

This feature is available only to Enterprise customers.

:::

A request's cache key is what determines if two requests are the same for caching purposes. If a request has the same cache key as some previous request, then Cloudflare can serve the same cached response for both. For more about cache keys, refer to the [Create custom cache keys](/cache/how-to/cache-keys/#create-custom-cache-keys) documentation.

```js
// Set cache key for this request to "some-string".
fetch(event.request, { cf: { cacheKey: "some-string" } });
```

Normally, Cloudflare computes the cache key for a request based on the request's URL. Sometimes, though, you may like different URLs to be treated as if they were the same for caching purposes. For example, if your website content is hosted from both Amazon S3 and Google Cloud Storage - you have the same content in both places, and you can use a Worker to randomly balance between the two. However, you do not want to end up caching two copies of your content. You could utilize custom cache keys to cache based on the original request URL rather than the subrequest URL:

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		let url = new URL(request.url);

		if (Math.random() < 0.5) {
			url.hostname = "example.s3.amazonaws.com";
		} else {
			url.hostname = "example.storage.googleapis.com";
		}

		let newRequest = new Request(url, request);
		return fetch(newRequest, {
			cf: { cacheKey: request.url },
		});
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		let url = new URL(request.url);

		if (Math.random() < 0.5) {
			url.hostname = "example.s3.amazonaws.com";
		} else {
			url.hostname = "example.storage.googleapis.com";
		}

		let newRequest = new Request(url, request);
		return fetch(newRequest, {
			cf: { cacheKey: request.url },
		});
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

type Bindings = {};

const app = new Hono<{ Bindings: Bindings }>();

app.all('*', async (c) => {
  const originalUrl = c.req.url;
  const url = new URL(originalUrl);

  // Randomly select a storage backend
  if (Math.random() < 0.5) {
    url.hostname = "example.s3.amazonaws.com";
  } else {
    url.hostname = "example.storage.googleapis.com";
  }

  // Create a new request to the selected backend
  const newRequest = new Request(url, c.req.raw);

  // Fetch using the original URL as the cache key
  return fetch(newRequest, {
    cf: { cacheKey: originalUrl },
  });
});

export default app;
```

</TabItem> </Tabs>

Workers operating on behalf of different zones cannot affect each other's cache. You can only override cache keys when making requests within your own zone (in the above example `event.request.url` was the key stored), or requests to hosts that are not on Cloudflare. When making a request to another Cloudflare zone (for example, belonging to a different Cloudflare customer), that zone fully controls how its own content is cached within Cloudflare; you cannot override it.

## Override based on origin response code

```js
// Force response to be cached for 86400 seconds for 200 status
// codes, 1 second for 404, and do not cache 500 errors.
fetch(request, {
	cf: { cacheTtlByStatus: { "200-299": 86400, 404: 1, "500-599": 0 } },
});
```

This option is a version of the `cacheTtl` feature which chooses a TTL based on the response's status code and does not automatically set `cacheEverything: true`. If the response to this request has a status code that matches, Cloudflare will cache for the instructed time, and override cache directives sent by the origin. You can review [details on the `cacheTtl` feature on the Request page](/workers/runtime-apis/request/#the-cf-property-requestinitcfproperties).

## Customize cache behavior based on request file type

Using custom cache keys and overrides based on response code, you can write a Worker that sets the TTL based on the response status code from origin, and request file type.

The following example demonstrates how you might use this to cache requests for streaming media assets:

<Tabs syncKey="workersExamples"> <TabItem label="Module Worker" icon="seti:javascript">

```js title="index.js"
export default {
	async fetch(request) {
		// Instantiate new URL to make it mutable
		const newRequest = new URL(request.url);

		const customCacheKey = `${newRequest.hostname}${newRequest.pathname}`;
		const queryCacheKey = `${newRequest.hostname}${newRequest.pathname}${newRequest.search}`;

		// Different asset types usually have different caching strategies. Most of the time media content such as audio, videos and images that are not user-generated content would not need to be updated often so a long TTL would be best. However, with HLS streaming, manifest files usually are set with short TTLs so that playback will not be affected, as this files contain the data that the player would need. By setting each caching strategy for categories of asset types in an object within an array, you can solve complex needs when it comes to media content for your application

		const cacheAssets = [
			{
				asset: "video",
				key: customCacheKey,
				regex:
					/(.*\/Video)|(.*\.(m4s|mp4|ts|avi|mpeg|mpg|mkv|bin|webm|vob|flv|m2ts|mts|3gp|m4v|wmv|qt))/,
				info: 0,
				ok: 31556952,
				redirects: 30,
				clientError: 10,
				serverError: 0,
			},
			{
				asset: "image",
				key: queryCacheKey,
				regex:
					/(.*\/Images)|(.*\.(jpg|jpeg|png|bmp|pict|tif|tiff|webp|gif|heif|exif|bat|bpg|ppm|pgn|pbm|pnm))/,
				info: 0,
				ok: 3600,
				redirects: 30,
				clientError: 10,
				serverError: 0,
			},
			{
				asset: "frontEnd",
				key: queryCacheKey,
				regex: /^.*\.(css|js)/,
				info: 0,
				ok: 3600,
				redirects: 30,
				clientError: 10,
				serverError: 0,
			},
			{
				asset: "audio",
				key: customCacheKey,
				regex:
					/(.*\/Audio)|(.*\.(flac|aac|mp3|alac|aiff|wav|ogg|aiff|opus|ape|wma|3gp))/,
				info: 0,
				ok: 31556952,
				redirects: 30,
				clientError: 10,
				serverError: 0,
			},
			{
				asset: "directPlay",
				key: customCacheKey,
				regex: /.*(\/Download)/,
				info: 0,
				ok: 31556952,
				redirects: 30,
				clientError: 10,
				serverError: 0,
			},
			{
				asset: "manifest",
				key: customCacheKey,
				regex: /^.*\.(m3u8|mpd)/,
				info: 0,
				ok: 3,
				redirects: 2,
				clientError: 1,
				serverError: 0,
			},
		];

		const { asset, regex, ...cache } =
			cacheAssets.find(({ regex }) => newRequest.pathname.match(regex)) ?? {};

		const newResponse = await fetch(request, {
			cf: {
				cacheKey: cache.key,
				polish: false,
				cacheEverything: true,
				cacheTtlByStatus: {
					"100-199": cache.info,
					"200-299": cache.ok,
					"300-399": cache.redirects,
					"400-499": cache.clientError,
					"500-599": cache.serverError,
				},
				cacheTags: ["static"],
			},
		});

		const response = new Response(newResponse.body, newResponse);

		// For debugging purposes
		response.headers.set("debug", JSON.stringify(cache));
		return response;
	},
};
```

</TabItem> <TabItem label="Service Worker" icon="seti:javascript">

:::caution[Service Workers are deprecated]

Service Workers are deprecated, but still supported. We recommend using [Module Workers](/workers/reference/migrate-to-module-workers/) instead. New features may not be supported for Service Workers.

:::

```js title="index.js"
addEventListener("fetch", (event) => {
	return event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
	// Instantiate new URL to make it mutable
	const newRequest = new URL(request.url);

	// Set `const` to be used in the array later on
	const customCacheKey = `${newRequest.hostname}${newRequest.pathname}`;
	const queryCacheKey = `${newRequest.hostname}${newRequest.pathname}${newRequest.search}`;

	// Set all variables needed to manipulate Cloudflare's cache using the fetch API in the `cf` object. You will be passing these variables in the objects down below.
	const cacheAssets = [
		{
			asset: "video",
			key: customCacheKey,
			regex:
				/(.*\/Video)|(.*\.(m4s|mp4|ts|avi|mpeg|mpg|mkv|bin|webm|vob|flv|m2ts|mts|3gp|m4v|wmv|qt))/,
			info: 0,
			ok: 31556952,
			redirects: 30,
			clientError: 10,
			serverError: 0,
		},
		{
			asset: "image",
			key: queryCacheKey,
			regex:
				/(.*\/Images)|(.*\.(jpg|jpeg|png|bmp|pict|tif|tiff|webp|gif|heif|exif|bat|bpg|ppm|pgn|pbm|pnm))/,
			info: 0,
			ok: 3600,
			redirects: 30,
			clientError: 10,
			serverError: 0,
		},
		{
			asset: "frontEnd",
			key: queryCacheKey,
			regex: /^.*\.(css|js)/,
			info: 0,
			ok: 3600,
			redirects: 30,
			clientError: 10,
			serverError: 0,
		},
		{
			asset: "audio",
			key: customCacheKey,
			regex:
				/(.*\/Audio)|(.*\.(flac|aac|mp3|alac|aiff|wav|ogg|aiff|opus|ape|wma|3gp))/,
			info: 0,
			ok: 31556952,
			redirects: 30,
			clientError: 10,
			serverError: 0,
		},
		{
			asset: "directPlay",
			key: customCacheKey,
			regex: /.*(\/Download)/,
			info: 0,
			ok: 31556952,
			redirects: 30,
			clientError: 10,
			serverError: 0,
		},
		{
			asset: "manifest",
			key: customCacheKey,
			regex: /^.*\.(m3u8|mpd)/,
			info: 0,
			ok: 3,
			redirects: 2,
			clientError: 1,
			serverError: 0,
		},
	];

	// the `.find` method is used to find elements in an array (`cacheAssets`), in this case, `regex`, which can passed to the .`match` method to match on file extensions to cache, since they are many media types in the array. If you want to add more types, update the array. Refer to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find for more information.
	const { asset, regex, ...cache } =
		cacheAssets.find(({ regex }) => newRequest.pathname.match(regex)) ?? {};

	const newResponse = await fetch(request, {
		cf: {
			cacheKey: cache.key,
			polish: false,
			cacheEverything: true,
			cacheTtlByStatus: {
				"100-199": cache.info,
				"200-299": cache.ok,
				"300-399": cache.redirects,
				"400-499": cache.clientError,
				"500-599": cache.serverError,
			},
			cacheTags: ["static"],
		},
	});

	const response = new Response(newResponse.body, newResponse);

	// For debugging purposes
	response.headers.set("debug", JSON.stringify(cache));
	return response;
}
```

</TabItem> </Tabs>

## Using the HTTP Cache API

The `cache` mode can be set in `fetch` options.
Currently Workers only support the `no-store` mode for controlling the cache.
When `no-store` is supplied the cache is bypassed on the way to the origin and the request is not cacheable.

```js
fetch(request, { cache: 'no-store'});
```

---

# CORS header proxy

URL: https://developers.cloudflare.com/workers/examples/cors-header-proxy/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/cors-header-proxy)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		const corsHeaders = {
			"Access-Control-Allow-Origin": "*",
			"Access-Control-Allow-Methods": "GET,HEAD,POST,OPTIONS",
			"Access-Control-Max-Age": "86400",
		};

		// The URL for the remote third party API you want to fetch from
		// but does not implement CORS
		const API_URL = "https://examples.cloudflareworkers.com/demos/demoapi";

		// The endpoint you want the CORS reverse proxy to be on
		const PROXY_ENDPOINT = "/corsproxy/";

		// The rest of this snippet for the demo page
		function rawHtmlResponse(html) {
			return new Response(html, {
				headers: {
					"content-type": "text/html;charset=UTF-8",
				},
			});
		}

		const DEMO_PAGE = `
      <!DOCTYPE html>
      <html>
      <body>
        <h1>API GET without CORS Proxy</h1>
        <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#Checking_that_the_fetch_was_successful">Shows TypeError: Failed to fetch since CORS is misconfigured</a>
        <p id="noproxy-status"/>
        <code id="noproxy">Waiting</code>
        <h1>API GET with CORS Proxy</h1>
        <p id="proxy-status"/>
        <code id="proxy">Waiting</code>
        <h1>API POST with CORS Proxy + Preflight</h1>
        <p id="proxypreflight-status"/>
        <code id="proxypreflight">Waiting</code>
        <script>
        let reqs = {};
        reqs.noproxy = () => {
          return fetch("${API_URL}").then(r => r.json())
        }
        reqs.proxy = async () => {
          let href = "${PROXY_ENDPOINT}?apiurl=${API_URL}"
          return fetch(window.location.origin + href).then(r => r.json())
        }
        reqs.proxypreflight = async () => {
          let href = "${PROXY_ENDPOINT}?apiurl=${API_URL}"
          let response = await fetch(window.location.origin + href, {
            method: "POST",
            headers: {
              "Content-Type": "application/json"
            },
            body: JSON.stringify({
              msg: "Hello world!"
            })
          })
          return response.json()
        }
        (async () => {
        for (const [reqName, req] of Object.entries(reqs)) {
          try {
            let data = await req()
            document.getElementById(reqName).innerHTML = JSON.stringify(data)
          } catch (e) {
            document.getElementById(reqName).innerHTML = e
          }
        }
      })()
        </script>
      </body>
      </html>
    `;

		async function handleRequest(request) {
			const url = new URL(request.url);
			let apiUrl = url.searchParams.get("apiurl");

			if (apiUrl == null) {
				apiUrl = API_URL;
			}

			// Rewrite request to point to API URL. This also makes the request mutable
			// so you can add the correct Origin header to make the API server think
			// that this request is not cross-site.
			request = new Request(apiUrl, request);
			request.headers.set("Origin", new URL(apiUrl).origin);
			let response = await fetch(request);
			// Recreate the response so you can modify the headers

			response = new Response(response.body, response);
			// Set CORS headers

			response.headers.set("Access-Control-Allow-Origin", url.origin);

			// Append to/Add Vary header so browser will cache response correctly
			response.headers.append("Vary", "Origin");

			return response;
		}

		async function handleOptions(request) {
			if (
				request.headers.get("Origin") !== null &&
				request.headers.get("Access-Control-Request-Method") !== null &&
				request.headers.get("Access-Control-Request-Headers") !== null
			) {
				// Handle CORS preflight requests.
				return new Response(null, {
					headers: {
						...corsHeaders,
						"Access-Control-Allow-Headers": request.headers.get(
							"Access-Control-Request-Headers",
						),
					},
				});
			} else {
				// Handle standard OPTIONS request.
				return new Response(null, {
					headers: {
						Allow: "GET, HEAD, POST, OPTIONS",
					},
				});
			}
		}

		const url = new URL(request.url);
		if (url.pathname.startsWith(PROXY_ENDPOINT)) {
			if (request.method === "OPTIONS") {
				// Handle CORS preflight requests
				return handleOptions(request);
			} else if (
				request.method === "GET" ||
				request.method === "HEAD" ||
				request.method === "POST"
			) {
				// Handle requests to the API server
				return handleRequest(request);
			} else {
				return new Response(null, {
					status: 405,
					statusText: "Method Not Allowed",
				});
			}
		} else {
			return rawHtmlResponse(DEMO_PAGE);
		}
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const corsHeaders = {
			"Access-Control-Allow-Origin": "*",
			"Access-Control-Allow-Methods": "GET,HEAD,POST,OPTIONS",
			"Access-Control-Max-Age": "86400",
		};

		// The URL for the remote third party API you want to fetch from
		// but does not implement CORS
		const API_URL = "https://examples.cloudflareworkers.com/demos/demoapi";

		// The endpoint you want the CORS reverse proxy to be on
		const PROXY_ENDPOINT = "/corsproxy/";

		// The rest of this snippet for the demo page
		function rawHtmlResponse(html) {
			return new Response(html, {
				headers: {
					"content-type": "text/html;charset=UTF-8",
				},
			});
		}

		const DEMO_PAGE = `
      <!DOCTYPE html>
      <html>
      <body>
        <h1>API GET without CORS Proxy</h1>
        <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#Checking_that_the_fetch_was_successful">Shows TypeError: Failed to fetch since CORS is misconfigured</a>
        <p id="noproxy-status"/>
        <code id="noproxy">Waiting</code>
        <h1>API GET with CORS Proxy</h1>
        <p id="proxy-status"/>
        <code id="proxy">Waiting</code>
        <h1>API POST with CORS Proxy + Preflight</h1>
        <p id="proxypreflight-status"/>
        <code id="proxypreflight">Waiting</code>
        <script>
        let reqs = {};
        reqs.noproxy = () => {
          return fetch("${API_URL}").then(r => r.json())
        }
        reqs.proxy = async () => {
          let href = "${PROXY_ENDPOINT}?apiurl=${API_URL}"
          return fetch(window.location.origin + href).then(r => r.json())
        }
        reqs.proxypreflight = async () => {
          let href = "${PROXY_ENDPOINT}?apiurl=${API_URL}"
          let response = await fetch(window.location.origin + href, {
            method: "POST",
            headers: {
              "Content-Type": "application/json"
            },
            body: JSON.stringify({
              msg: "Hello world!"
            })
          })
          return response.json()
        }
        (async () => {
        for (const [reqName, req] of Object.entries(reqs)) {
          try {
            let data = await req()
            document.getElementById(reqName).textContent = JSON.stringify(data)
          } catch (e) {
            document.getElementById(reqName).textContent = e
          }
        }
      })()
        </script>
      </body>
      </html>
    `;

		async function handleRequest(request) {
			const url = new URL(request.url);
			let apiUrl = url.searchParams.get("apiurl");

			if (apiUrl == null) {
				apiUrl = API_URL;
			}

			// Rewrite request to point to API URL. This also makes the request mutable
			// so you can add the correct Origin header to make the API server think
			// that this request is not cross-site.
			request = new Request(apiUrl, request);
			request.headers.set("Origin", new URL(apiUrl).origin);
			let response = await fetch(request);
			// Recreate the response so you can modify the headers

			response = new Response(response.body, response);
			// Set CORS headers

			response.headers.set("Access-Control-Allow-Origin", url.origin);

			// Append to/Add Vary header so browser will cache response correctly
			response.headers.append("Vary", "Origin");

			return response;
		}

		async function handleOptions(request) {
			if (
				request.headers.get("Origin") !== null &&
				request.headers.get("Access-Control-Request-Method") !== null &&
				request.headers.get("Access-Control-Request-Headers") !== null
			) {
				// Handle CORS preflight requests.
				return new Response(null, {
					headers: {
						...corsHeaders,
						"Access-Control-Allow-Headers": request.headers.get(
							"Access-Control-Request-Headers",
						),
					},
				});
			} else {
				// Handle standard OPTIONS request.
				return new Response(null, {
					headers: {
						Allow: "GET, HEAD, POST, OPTIONS",
					},
				});
			}
		}

		const url = new URL(request.url);
		if (url.pathname.startsWith(PROXY_ENDPOINT)) {
			if (request.method === "OPTIONS") {
				// Handle CORS preflight requests
				return handleOptions(request);
			} else if (
				request.method === "GET" ||
				request.method === "HEAD" ||
				request.method === "POST"
			) {
				// Handle requests to the API server
				return handleRequest(request);
			} else {
				return new Response(null, {
					status: 405,
					statusText: "Method Not Allowed",
				});
			}
		} else {
			return rawHtmlResponse(DEMO_PAGE);
		}
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";
import { cors } from "hono/cors";

// The URL for the remote third party API you want to fetch from
// but does not implement CORS
const API_URL = "https://examples.cloudflareworkers.com/demos/demoapi";

// The endpoint you want the CORS reverse proxy to be on
const PROXY_ENDPOINT = "/corsproxy/";

const app = new Hono();

// Demo page handler
app.get("*", async (c) => {
	// Only handle non-proxy requests with this handler
	if (c.req.path.startsWith(PROXY_ENDPOINT)) {
		return next();
	}

	// Create the demo page HTML
	const DEMO_PAGE = `
    <!DOCTYPE html>
    <html>
    <body>
      <h1>API GET without CORS Proxy</h1>
      <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#Checking_that_the_fetch_was_successful">Shows TypeError: Failed to fetch since CORS is misconfigured</a>
      <p id="noproxy-status"/>
      <code id="noproxy">Waiting</code>
      <h1>API GET with CORS Proxy</h1>
      <p id="proxy-status"/>
      <code id="proxy">Waiting</code>
      <h1>API POST with CORS Proxy + Preflight</h1>
      <p id="proxypreflight-status"/>
      <code id="proxypreflight">Waiting</code>
      <script>
      let reqs = {};
      reqs.noproxy = () => {
        return fetch("${API_URL}").then(r => r.json())
      }
      reqs.proxy = async () => {
        let href = "${PROXY_ENDPOINT}?apiurl=${API_URL}"
        return fetch(window.location.origin + href).then(r => r.json())
      }
      reqs.proxypreflight = async () => {
        let href = "${PROXY_ENDPOINT}?apiurl=${API_URL}"
        let response = await fetch(window.location.origin + href, {
          method: "POST",
          headers: {
            "Content-Type": "application/json"
          },
          body: JSON.stringify({
            msg: "Hello world!"
          })
        })
        return response.json()
      }
      (async () => {
      for (const [reqName, req] of Object.entries(reqs)) {
        try {
          let data = await req()
          document.getElementById(reqName).innerHTML = JSON.stringify(data)
        } catch (e) {
          document.getElementById(reqName).innerHTML = e
        }
      }
    })()
      </script>
    </body>
    </html>
  `;

	return c.html(DEMO_PAGE);
});

// CORS proxy routes
app.on(["GET", "HEAD", "POST", "OPTIONS"], PROXY_ENDPOINT + "*", async (c) => {
	const url = new URL(c.req.url);

	// Handle OPTIONS preflight requests
	if (c.req.method === "OPTIONS") {
		const origin = c.req.header("Origin");
		const requestMethod = c.req.header("Access-Control-Request-Method");
		const requestHeaders = c.req.header("Access-Control-Request-Headers");

		if (origin && requestMethod && requestHeaders) {
			// Handle CORS preflight requests
			return new Response(null, {
				headers: {
					"Access-Control-Allow-Origin": "*",
					"Access-Control-Allow-Methods": "GET,HEAD,POST,OPTIONS",
					"Access-Control-Max-Age": "86400",
					"Access-Control-Allow-Headers": requestHeaders,
				},
			});
		} else {
			// Handle standard OPTIONS request
			return new Response(null, {
				headers: {
					Allow: "GET, HEAD, POST, OPTIONS",
				},
			});
		}
	}

	// Handle actual requests
	let apiUrl = url.searchParams.get("apiurl") || API_URL;

	// Rewrite request to point to API URL
	const modifiedRequest = new Request(apiUrl, c.req.raw);
	modifiedRequest.headers.set("Origin", new URL(apiUrl).origin);

	let response = await fetch(modifiedRequest);

	// Recreate the response so we can modify the headers
	response = new Response(response.body, response);

	// Set CORS headers
	response.headers.set("Access-Control-Allow-Origin", url.origin);

	// Append to/Add Vary header so browser will cache response correctly
	response.headers.append("Vary", "Origin");

	return response;
});

// Handle method not allowed for proxy endpoint
app.all(PROXY_ENDPOINT + "*", (c) => {
	return new Response(null, {
		status: 405,
		statusText: "Method Not Allowed",
	});
});

export default app;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from pyodide.ffi import to_js as _to_js
from js import Response, URL, fetch, Object, Request

def to_js(x):
    return _to_js(x, dict_converter=Object.fromEntries)

async def on_fetch(request):
    cors_headers = {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "GET,HEAD,POST,OPTIONS",
      "Access-Control-Max-Age": "86400",
    }

    api_url = "https://examples.cloudflareworkers.com/demos/demoapi"

    proxy_endpoint = "/corsproxy/"

    def raw_html_response(html):
        return Response.new(html, headers=to_js({"content-type": "text/html;charset=UTF-8"}))

    demo_page = f'''
    <!DOCTYPE html>
    <html>
    <body>
    <h1>API GET without CORS Proxy</h1>
    <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#Checking_that_the_fetch_was_successful">Shows TypeError: Failed to fetch since CORS is misconfigured</a>
    <p id="noproxy-status"/>
    <code id="noproxy">Waiting</code>
    <h1>API GET with CORS Proxy</h1>
    <p id="proxy-status"/>
    <code id="proxy">Waiting</code>
    <h1>API POST with CORS Proxy + Preflight</h1>
    <p id="proxypreflight-status"/>
    <code id="proxypreflight">Waiting</code>
    <script>
    let reqs = {{}};
    reqs.noproxy = () => {{
        return fetch("{api_url}").then(r => r.json())
    }}
    reqs.proxy = async () => {{
        let href = "{proxy_endpoint}?apiurl={api_url}"
        return fetch(window.location.origin + href).then(r => r.json())
    }}
    reqs.proxypreflight = async () => {{
        let href = "{proxy_endpoint}?apiurl={api_url}"
        let response = await fetch(window.location.origin + href, {{
        method: "POST",
        headers: {{
            "Content-Type": "application/json"
        }},
        body: JSON.stringify({{
            msg: "Hello world!"
        }})
        }})
        return response.json()
    }}
    (async () => {{
    for (const [reqName, req] of Object.entries(reqs)) {{
        try {{
        let data = await req()
        document.getElementById(reqName).innerHTML = JSON.stringify(data)
        }} catch (e) {{
        document.getElementById(reqName).innerHTML = e
        }}
    }}
    }})()
    </script>
    </body>
    </html>
    '''

    async def handle_request(request):
        url = URL.new(request.url)
        api_url2 = url.searchParams["apiurl"]

        if not api_url2:
            api_url2 = api_url

        request = Request.new(api_url2, request)
        request.headers["Origin"] = (URL.new(api_url2)).origin
        print(request.headers)
        response = await fetch(request)
        response = Response.new(response.body, response)
        response.headers["Access-Control-Allow-Origin"] = url.origin
        response.headers["Vary"] = "Origin"
        return response

    async def handle_options(request):
        if "Origin" in request.headers and "Access-Control-Request-Method" in request.headers and "Access-Control-Request-Headers" in request.headers:
            return Response.new(None, headers=to_js({
            **cors_headers,
            "Access-Control-Allow-Headers": request.headers["Access-Control-Request-Headers"]
          }))
        return Response.new(None, headers=to_js({"Allow": "GET, HEAD, POST, OPTIONS"}))

    url = URL.new(request.url)

    if url.pathname.startswith(proxy_endpoint):
        if request.method == "OPTIONS":
            return handle_options(request)
        if request.method in ("GET", "HEAD", "POST"):
            return handle_request(request)
        return Response.new(None, status=405, statusText="Method Not Allowed")
    return raw_html_response(demo_page)
```

</TabItem> <TabItem label="Rust" icon="seti:rust">
```rs
use std::{borrow::Cow, collections::HashMap};
use worker::*;

fn raw*html_response(html: &str) -> Result<Response> {
Response::from_html(html)
}
async fn handle_request(req: Request, api_url: &str) -> Result<Response> {
let url = req.url().unwrap();
let mut api_url2 = url
.query_pairs()
.find(|x| x.0 == Cow::Borrowed("apiurl"))
.unwrap()
.1
.to_string();
if api_url2 == String::from("") {
api_url2 = api_url.to_string();
}
let mut request = req.clone_mut()?;
\*request.path_mut()? = api_url2.clone();
if let url::Origin::Tuple(origin, *, _) = Url::parse(&api_url2)?.origin() {
(\*request.headers_mut()?).set("Origin", &origin)?;
}
let mut response = Fetch::Request(request).send().await?.cloned()?;
let headers = response.headers_mut();
if let url::Origin::Tuple(origin, _, \_) = url.origin() {
headers.set("Access-Control-Allow-Origin", &origin)?;
headers.set("Vary", "Origin")?;
}

    Ok(response)

}

fn handle*options(req: Request, cors_headers: &HashMap<&str, &str>) -> Result<Response> {
let headers: Vec<*> = req.headers().keys().collect();
if [
"access-control-request-method",
"access-control-request-headers",
"origin",
]
.iter()
.all(|i| headers.contains(&i.to_string()))
{
let mut headers = Headers::new();
for (k, v) in cors_headers.iter() {
headers.set(k, v)?;
}
return Ok(Response::empty()?.with_headers(headers));
}
Response::empty()
} #[event(fetch)]
async fn fetch(req: Request, \_env: Env, \_ctx: Context) -> Result<Response> {
let cors_headers = HashMap::from([
("Access-Control-Allow-Origin", "*"),
("Access-Control-Allow-Methods", "GET,HEAD,POST,OPTIONS"),
("Access-Control-Max-Age", "86400"),
]);
let api_url = "https://examples.cloudflareworkers.com/demos/demoapi";
let proxy_endpoint = "/corsproxy/";
let demo_page = format!(
r#"

<!DOCTYPE html>

<html>
<body>
<h1>API GET without CORS Proxy</h1>
<a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#Checking_that_the_fetch_was_successful">Shows TypeError: Failed to fetch since CORS is misconfigured</a>
<p id="noproxy-status"/>
<code id="noproxy">Waiting</code>
<h1>API GET with CORS Proxy</h1>
<p id="proxy-status"/>
<code id="proxy">Waiting</code>
<h1>API POST with CORS Proxy + Preflight</h1>
<p id="proxypreflight-status"/>
<code id="proxypreflight">Waiting</code>
<script>
let reqs = {{}};
reqs.noproxy = () => {{
        return fetch("{api_url}").then(r => r.json())
    }}
reqs.proxy = async () => {{
        let href = "{proxy_endpoint}?apiurl={api_url}"
        return fetch(window.location.origin + href).then(r => r.json())
    }}
reqs.proxypreflight = async () => {{
        let href = "{proxy_endpoint}?apiurl={api_url}"
        let response = await fetch(window.location.origin + href, {{
        method: "POST",
        headers: {{
            "Content-Type": "application/json"
        }},
body: JSON.stringify({{
            msg: "Hello world!"
        }})
}})
return response.json()
}}
(async () => {{
    for (const [reqName, req] of Object.entries(reqs)) {{
        try {{
        let data = await req()
        document.getElementById(reqName).innerHTML = JSON.stringify(data)
        }} catch (e) {{
        document.getElementById(reqName).innerHTML = e
        }}
}}
}})()
</script>
</body>
</html>
"#
);

    if req.url()?.path().starts_with(proxy_endpoint) {
        match req.method() {
            Method::Options => return handle_options(req, &cors_headers),
            Method::Get | Method::Head | Method::Post => return handle_request(req, api_url).await,
            _ => return Response::error("Method Not Allowed", 405),
        }
    }
    raw_html_response(&demo_page)

}

```
</TabItem> </Tabs>
```

---

# Country code redirect

URL: https://developers.cloudflare.com/workers/examples/country-code-redirect/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/country-code-redirect)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		/**
		 * A map of the URLs to redirect to
		 * @param {Object} countryMap
		 */
		const countryMap = {
			US: "https://example.com/us",
			EU: "https://example.com/eu",
		};

		// Use the cf object to obtain the country of the request
		// more on the cf object: https://developers.cloudflare.com/workers/runtime-apis/request#incomingrequestcfproperties
		const country = request.cf.country;

		if (country != null && country in countryMap) {
			const url = countryMap[country];
			// Remove this logging statement from your final output.
			console.log(
				`Based on ${country}-based request, your user would go to ${url}.`,
			);
			return Response.redirect(url);
		} else {
			return fetch("https://example.com", request);
		}
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		/**
		 * A map of the URLs to redirect to
		 * @param {Object} countryMap
		 */
		const countryMap = {
			US: "https://example.com/us",
			EU: "https://example.com/eu",
		};

		// Use the cf object to obtain the country of the request
		// more on the cf object: https://developers.cloudflare.com/workers/runtime-apis/request#incomingrequestcfproperties
		const country = request.cf.country;

		if (country != null && country in countryMap) {
			const url = countryMap[country];
			return Response.redirect(url);
		} else {
			return fetch(request);
		}
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch

async def on_fetch(request):
    countries = {
        "US": "https://example.com/us",
        "EU": "https://example.com/eu",
    }

    # Use the cf object to obtain the country of the request
    # more on the cf object: https://developers.cloudflare.com/workers/runtime-apis/request#incomingrequestcfproperties
    country = request.cf.country

    if country and country in countries:
        url = countries[country]
        return Response.redirect(url)

    return fetch("https://example.com", request)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

// Define the RequestWithCf interface to add Cloudflare-specific properties
interface RequestWithCf extends Request {
  cf: {
    country: string;
    // Other CF properties can be added as needed
  };
}

const app = new Hono();

app.get('*', async (c) => {
  /**
   * A map of the URLs to redirect to
   */
  const countryMap: Record<string, string> = {
    US: "https://example.com/us",
    EU: "https://example.com/eu",
  };

  // Cast the raw request to include Cloudflare-specific properties
  const request = c.req.raw as RequestWithCf;

  // Use the cf object to obtain the country of the request
  // more on the cf object: https://developers.cloudflare.com/workers/runtime-apis/request#incomingrequestcfproperties
  const country = request.cf.country;

  if (country != null && country in countryMap) {
    const url = countryMap[country];
    // Redirect using Hono's redirect helper
    return c.redirect(url);
  } else {
    // Default fallback
    return fetch("https://example.com", request);
  }
});

export default app;
```

</TabItem> </Tabs>

---

# Setting Cron Triggers

URL: https://developers.cloudflare.com/workers/examples/cron-trigger/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/cron-trigger)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { Render, TabItem, Tabs, WranglerConfig } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async scheduled(controller, env, ctx) {
		console.log("cron processed");
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Env {}
export default {
  async scheduled(
    controller: ScheduledController,
    env: Env,
    ctx: ExecutionContext,
  ) {
    console.log("cron processed");
  },
};
```

</TabItem> <TabItem label="Python" icon="seti:python">

```python
from workers import handler

@handler
async def on_scheduled(controller, env, ctx):
  print("cron processed")
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

interface Env {}

// Create Hono app
const app = new Hono<{ Bindings: Env }>();

// Regular routes for normal HTTP requests
app.get('/', (c) => c.text('Hello World!'));

// Export both the app and a scheduled function
export default {
  // The Hono app handles regular HTTP requests
  fetch: app.fetch,

  // The scheduled function handles Cron triggers
  async scheduled(
    controller: ScheduledController,
    env: Env,
    ctx: ExecutionContext,
  ) {
    console.log("cron processed");

    // You could also perform actions like:
    // - Fetching data from external APIs
    // - Updating KV or Durable Object storage
    // - Running maintenance tasks
    // - Sending notifications
  },
};
```

</TabItem> </Tabs>

## Set Cron Triggers in Wrangler

Refer to [Cron Triggers](/workers/configuration/cron-triggers/) for more information on how to add a Cron Trigger.

If you are deploying with Wrangler, set the cron syntax (once per hour as shown below) by adding this to your Wrangler file:

<WranglerConfig>

```toml
name = "worker"

# ...

[triggers]
crons = ["0 * * * *"]
```

</WranglerConfig>

You also can set a different Cron Trigger for each [environment](/workers/wrangler/environments/) in your [Wrangler configuration file](/workers/wrangler/configuration/). You need to put the `[triggers]` table under your chosen environment. For example:

<WranglerConfig>

```toml
[env.dev.triggers]
crons = ["0 * * * *"]
```

</WranglerConfig>

## Test Cron Triggers using Wrangler

The recommended way of testing Cron Triggers is using Wrangler.

Cron Triggers can be tested using Wrangler by passing in the `--test-scheduled` flag to [`wrangler dev`](/workers/wrangler/commands/#dev). This will expose a `/__scheduled` (or `/cdn-cgi/handler/scheduled` for Python Workers) route which can be used to test using a HTTP request. To simulate different cron patterns, a `cron` query parameter can be passed in.

```sh
npx wrangler dev --test-scheduled

curl "http://localhost:8787/__scheduled?cron=0+*+*+*+*"

curl "http://localhost:8787/cdn-cgi/handler/scheduled?cron=*+*+*+*+*" # Python Workers
```

---

# Data loss prevention

URL: https://developers.cloudflare.com/workers/examples/data-loss-prevention/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/data-loss-prevention)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		const DEBUG = true;
		const SOME_HOOK_SERVER = "https://webhook.flow-wolf.io/hook";

		/**
		 * Alert a data breach by posting to a webhook server
		 */
		async function postDataBreach(request) {
			return await fetch(SOME_HOOK_SERVER, {
				method: "POST",
				headers: {
					"content-type": "application/json;charset=UTF-8",
				},
				body: JSON.stringify({
					ip: request.headers.get("cf-connecting-ip"),
					time: Date.now(),
					request: request,
				}),
			});
		}

		/**
		 * Define personal data with regular expressions.
		 * Respond with block if credit card data, and strip
		 * emails and phone numbers from the response.
		 * Execution will be limited to MIME type "text/*".
		 */
		const response = await fetch(request);

		// Return origin response, if response wasn’t text
		const contentType = response.headers.get("content-type") || "";
		if (!contentType.toLowerCase().includes("text/")) {
			return response;
		}

		let text = await response.text();

		// When debugging replace the response
		// from the origin with an email
		text = DEBUG
			? text.replace("You may use this", "me@example.com may use this")
			: text;
		const sensitiveRegexsMap = {
			creditCard: String.raw`\b(?:4[0-9]{12}(?:[0-9]{3})?|(?:5[1-5][0-9]{2}|222[1-9]|22[3-9][0-9]|2[3-6][0-9]{2}|27[01][0-9]|2720)[0-9]{12}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|6(?:011|5[0-9]{2})[0-9]{12}|(?:2131|1800|35\d{3})\d{11})\b`,
			email: String.raw`\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b`,
			phone: String.raw`\b07\d{9}\b`,
		};

		for (const kind in sensitiveRegexsMap) {
			const sensitiveRegex = new RegExp(sensitiveRegexsMap[kind], "ig");
			const match = await sensitiveRegex.test(text);
			if (match) {
				// Alert a data breach
				await postDataBreach(request);
				// Respond with a block if credit card,
				// otherwise replace sensitive text with `*`s
				return kind === "creditCard"
					? new Response(kind + " found\nForbidden\n", {
							status: 403,
							statusText: "Forbidden",
						})
					: new Response(text.replace(sensitiveRegex, "**********"), response);
			}
		}
		return new Response(text, response);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const DEBUG = true;
		const SOME_HOOK_SERVER = "https://webhook.flow-wolf.io/hook";

		/**
		 * Alert a data breach by posting to a webhook server
		 */
		async function postDataBreach(request) {
			return await fetch(SOME_HOOK_SERVER, {
				method: "POST",
				headers: {
					"content-type": "application/json;charset=UTF-8",
				},
				body: JSON.stringify({
					ip: request.headers.get("cf-connecting-ip"),
					time: Date.now(),
					request: request,
				}),
			});
		}

		/**
		 * Define personal data with regular expressions.
		 * Respond with block if credit card data, and strip
		 * emails and phone numbers from the response.
		 * Execution will be limited to MIME type "text/*".
		 */
		const response = await fetch(request);

		// Return origin response, if response wasn’t text
		const contentType = response.headers.get("content-type") || "";
		if (!contentType.toLowerCase().includes("text/")) {
			return response;
		}

		let text = await response.text();

		// When debugging replace the response
		// from the origin with an email
		text = DEBUG
			? text.replace("You may use this", "me@example.com may use this")
			: text;
		const sensitiveRegexsMap = {
			creditCard: String.raw`\b(?:4[0-9]{12}(?:[0-9]{3})?|(?:5[1-5][0-9]{2}|222[1-9]|22[3-9][0-9]|2[3-6][0-9]{2}|27[01][0-9]|2720)[0-9]{12}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|6(?:011|5[0-9]{2})[0-9]{12}|(?:2131|1800|35\d{3})\d{11})\b`,
			email: String.raw`\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b`,
			phone: String.raw`\b07\d{9}\b`,
		};

		for (const kind in sensitiveRegexsMap) {
			const sensitiveRegex = new RegExp(sensitiveRegexsMap[kind], "ig");
			const match = await sensitiveRegex.test(text);
			if (match) {
				// Alert a data breach
				await postDataBreach(request);
				// Respond with a block if credit card,
				// otherwise replace sensitive text with `*`s
				return kind === "creditCard"
					? new Response(kind + " found\nForbidden\n", {
							status: 403,
							statusText: "Forbidden",
						})
					: new Response(text.replace(sensitiveRegex, "**********"), response);
			}
		}
		return new Response(text, response);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
import re
from datetime import datetime
from js import Response, fetch, JSON, Headers

# Alert a data breach by posting to a webhook server
async def post_data_breach(request):
    some_hook_server = "https://webhook.flow-wolf.io/hook"
    headers = Headers.new({"content-type": "application/json"}.items())
    body = JSON.stringify({
      "ip": request.headers["cf-connecting-ip"],
      "time": datetime.now(),
      "request": request,
    })
    return await fetch(some_hook_server, method="POST", headers=headers, body=body)

async def on_fetch(request):
    debug = True

    # Define personal data with regular expressions.
    # Respond with block if credit card data, and strip
    # emails and phone numbers from the response.
    # Execution will be limited to MIME type "text/*".
    response = await fetch(request)

    # Return origin response, if response wasn’t text
    content_type = response.headers["content-type"] or ""
    if "text" not in content_type:
        return response

    text = await response.text()
    # When debugging replace the response from the origin with an email
    text = text.replace("You may use this", "me@example.com may use this") if debug else text

    sensitive_regex = [
      ("credit_card",
      r'\b(?:4[0-9]{12}(?:[0-9]{3})?|(?:5[1-5][0-9]{2}|222[1-9]|22[3-9][0-9]|2[3-6][0-9]{2}|27[01][0-9]|2720)[0-9]{12}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|6(?:011|5[0-9]{2})[0-9]{12}|(?:2131|1800|35\d{3})\d{11})\b'),
      ("email", r'\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b'),
      ("phone", r'\b07\d{9}\b'),
    ]
    for (kind, regex) in sensitive_regex:
        match = re.search(regex, text, flags=re.IGNORECASE)
        if match:
            # Alert a data breach
            await post_data_breach(request)
            # Respond with a block if credit card, otherwise replace sensitive text with `*`s
            card_resp = Response.new(kind + " found\nForbidden\n", status=403,statusText="Forbidden")
            sensitive_resp = Response.new(re.sub(regex, "*"*10, text, flags=re.IGNORECASE), response)
            return card_resp if kind == "credit_card" else  sensitive_resp

    return Response.new(text, response)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

const app = new Hono();

// Configuration
const DEBUG = true;
const SOME_HOOK_SERVER = "https://webhook.flow-wolf.io/hook";

// Define sensitive data patterns
const sensitiveRegexsMap = {
  creditCard: String.raw`\b(?:4[0-9]{12}(?:[0-9]{3})?|(?:5[1-5][0-9]{2}|222[1-9]|22[3-9][0-9]|2[3-6][0-9]{2}|27[01][0-9]|2720)[0-9]{12}|3[47][0-9]{13}|3(?:0[0-5]|[68][0-9])[0-9]{11}|6(?:011|5[0-9]{2})[0-9]{12}|(?:2131|1800|35\d{3})\d{11})\b`,
  email: String.raw`\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b`,
  phone: String.raw`\b07\d{9}\b`,
};

/**
 * Alert a data breach by posting to a webhook server
 */
async function postDataBreach(request: Request) {
  return await fetch(SOME_HOOK_SERVER, {
    method: "POST",
    headers: {
      "content-type": "application/json;charset=UTF-8",
    },
    body: JSON.stringify({
      ip: request.headers.get("cf-connecting-ip"),
      time: Date.now(),
      request: request,
    }),
  });
}

// Main middleware to handle data loss prevention
app.use('*', async (c) => {
  // Fetch the origin response
  const response = await fetch(c.req.raw);

  // Return origin response if response wasn't text
  const contentType = response.headers.get("content-type") || "";
  if (!contentType.toLowerCase().includes("text/")) {
    return response;
  }

  // Get the response text
  let text = await response.text();

  // When debugging, replace the response from the origin with an email
  text = DEBUG
    ? text.replace("You may use this", "me@example.com may use this")
    : text;

  // Check for sensitive data
  for (const kind in sensitiveRegexsMap) {
    const sensitiveRegex = new RegExp(sensitiveRegexsMap[kind], "ig");
    const match = sensitiveRegex.test(text);

    if (match) {
      // Alert a data breach
      await postDataBreach(c.req.raw);

      // Respond with a block if credit card, otherwise replace sensitive text with `*`s
      if (kind === "creditCard") {
        return c.text(`${kind} found\nForbidden\n`, 403);
      } else {
        return new Response(text.replace(sensitiveRegex, "**********"), {
          status: response.status,
          statusText: response.statusText,
          headers: response.headers,
        });
      }
    }
  }

  // Return the modified response
  return new Response(text, {
    status: response.status,
    statusText: response.statusText,
    headers: response.headers,
  });
});

export default app;
```

</TabItem> </Tabs>

---

# Debugging logs

URL: https://developers.cloudflare.com/workers/examples/debugging-logs/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/debugging-logs)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request, env, ctx) {
		// Service configured to receive logs
		const LOG_URL = "https://log-service.example.com/";

		async function postLog(data) {
			return await fetch(LOG_URL, {
				method: "POST",
				body: data,
			});
		}

		let response;

		try {
			response = await fetch(request);
			if (!response.ok && !response.redirected) {
				const body = await response.text();
				throw new Error(
					"Bad response at origin. Status: " +
						response.status +
						" Body: " +
						// Ensure the string is small enough to be a header
						body.trim().substring(0, 10),
				);
			}
		} catch (err) {
			// Without ctx.waitUntil(), your fetch() to Cloudflare's
			// logging service may or may not complete
			ctx.waitUntil(postLog(err.toString()));
			const stack = JSON.stringify(err.stack) || err;
			// Copy the response and initialize body to the stack trace
			response = new Response(stack, response);
			// Add the error stack into a header to find out what happened
			response.headers.set("X-Debug-stack", stack);
			response.headers.set("X-Debug-err", err);
		}
		return response;
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Env {}
export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Service configured to receive logs
		const LOG_URL = "https://log-service.example.com/";

		async function postLog(data) {
			return await fetch(LOG_URL, {
				method: "POST",
				body: data,
			});
		}

		let response;

		try {
			response = await fetch(request);
			if (!response.ok && !response.redirected) {
				const body = await response.text();
				throw new Error(
					"Bad response at origin. Status: " +
						response.status +
						" Body: " +
						// Ensure the string is small enough to be a header
						body.trim().substring(0, 10),
				);
			}
		} catch (err) {
			// Without ctx.waitUntil(), your fetch() to Cloudflare's
			// logging service may or may not complete
			ctx.waitUntil(postLog(err.toString()));
			const stack = JSON.stringify(err.stack) || err;
			// Copy the response and initialize body to the stack trace
			response = new Response(stack, response);
			// Add the error stack into a header to find out what happened
			response.headers.set("X-Debug-stack", stack);
			response.headers.set("X-Debug-err", err);
		}
		return response;
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
import json
import traceback
from pyodide.ffi import create_once_callable
from js import Response, fetch, Headers

async def on_fetch(request, _env, ctx):
    # Service configured to receive logs
    log_url = "https://log-service.example.com/"

    async def post_log(data):
        return await fetch(log_url, method="POST", body=data)

    response = await fetch(request)

    try:
        if not response.ok and not response.redirected:
            body = await response.text()
        # Simulating an error. Ensure the string is small enough to be a header
        raise Exception(f'Bad response at origin. Status:{response.status} Body:{body.strip()[:10]}')
    except Exception as e:
        # Without ctx.waitUntil(), your fetch() to Cloudflare's
        # logging service may or may not complete
        ctx.waitUntil(create_once_callable(post_log(e)))
        stack = json.dumps(traceback.format_exc()) or e
        # Copy the response and add to header
        response = Response.new(stack, response)
        response.headers["X-Debug-stack"] = stack
        response.headers["X-Debug-err"] = e

    return response
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

// Define the environment with appropriate types
interface Env {}

const app = new Hono<{ Bindings: Env }>();

// Service configured to receive logs
const LOG_URL = "https://log-service.example.com/";

// Function to post logs to an external service
async function postLog(data: string) {
  return await fetch(LOG_URL, {
    method: "POST",
    body: data,
  });
}

// Middleware to handle error logging
app.use('*', async (c, next) => {
  try {
    // Process the request with the next handler
    await next();

    // After processing, check if the response indicates an error
    if (c.res && (!c.res.ok && !c.res.redirected)) {
      const body = await c.res.clone().text();
      throw new Error(
        "Bad response at origin. Status: " +
        c.res.status +
        " Body: " +
        // Ensure the string is small enough to be a header
        body.trim().substring(0, 10)
      );
    }

  } catch (err) {
    // Without waitUntil, the fetch to the logging service may not complete
    c.executionCtx.waitUntil(
      postLog(err.toString())
    );

    // Get the error stack or error itself
    const stack = JSON.stringify(err.stack) || err.toString();

    // Create a new response with the error information
    const response = c.res ?
      new Response(stack, {
        status: c.res.status,
        headers: c.res.headers
      }) :
      new Response(stack, { status: 500 });

    // Add debug headers
    response.headers.set("X-Debug-stack", stack);
    response.headers.set("X-Debug-err", err.toString());

    // Set the modified response
    c.res = response;
  }
});

// Default route handler that passes requests through
app.all('*', async (c) => {
  return fetch(c.req.raw);
});

export default app;
```

</TabItem> </Tabs>

---

# Cookie parsing

URL: https://developers.cloudflare.com/workers/examples/extract-cookie-value/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/extract-cookie-value)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { parse } from "cookie";
export default {
	async fetch(request) {
		// The name of the cookie
		const COOKIE_NAME = "__uid";
		const cookie = parse(request.headers.get("Cookie") || "");
		if (cookie[COOKIE_NAME] != null) {
			// Respond with the cookie value
			return new Response(cookie[COOKIE_NAME]);
		}
		return new Response("No cookie with name: " + COOKIE_NAME);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { parse } from "cookie";
export default {
	async fetch(request): Promise<Response> {
		// The name of the cookie
		const COOKIE_NAME = "__uid";
		const cookie = parse(request.headers.get("Cookie") || "");
		if (cookie[COOKIE_NAME] != null) {
			// Respond with the cookie value
			return new Response(cookie[COOKIE_NAME]);
		}
		return new Response("No cookie with name: " + COOKIE_NAME);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from http.cookies import SimpleCookie
from workers import Response

async def on_fetch(request):
    # Name of the cookie
    cookie_name = "__uid"

    cookies = SimpleCookie(request.headers["Cookie"] or "")

    if cookie_name in cookies:
        # Respond with cookie value
        return Response(cookies[cookie_name].value)

    return Response("No cookie with name: " + cookie_name)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';
import { getCookie } from 'hono/cookie';

const app = new Hono();

app.get('*', (c) => {
  // The name of the cookie
  const COOKIE_NAME = "__uid";

  // Get the specific cookie value using Hono's cookie helper
  const cookieValue = getCookie(c, COOKIE_NAME);

  if (cookieValue) {
    // Respond with the cookie value
    return c.text(cookieValue);
  }

  return c.text("No cookie with name: " + COOKIE_NAME);
});

export default app;
```

</TabItem> </Tabs>

:::note[External dependencies]

This example requires the npm package [`cookie`](https://www.npmjs.com/package/cookie) to be installed in your JavaScript project.

The Hono example uses the built-in cookie utilities provided by Hono, so no external dependencies are needed for that implementation.

:::

---

# Fetch HTML

URL: https://developers.cloudflare.com/workers/examples/fetch-html/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/fetch-html)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { Render, TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

<Render file="fetch-html-example-js" />

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request: Request): Promise<Response> {
		/**
		 * Replace `remote` with the host you wish to send requests to
		 */
		const remote = "https://example.com";

		return await fetch(remote, request);
	},
};
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from js import fetch

async def on_fetch(request):
    # Replace `remote` with the host you wish to send requests to
    remote = "https://example.com"
    return await fetch(remote, request)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

const app = new Hono();

app.all('*', async (c) => {
  /**
   * Replace `remote` with the host you wish to send requests to
   */
  const remote = "https://example.com";

  // Forward the request to the remote server
  return await fetch(remote, c.req.raw);
});

export default app;
```

</TabItem> </Tabs>

---

# Fetch JSON

URL: https://developers.cloudflare.com/workers/examples/fetch-json/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/fetch-json)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request, env, ctx) {
		const url = "https://jsonplaceholder.typicode.com/todos/1";

		// gatherResponse returns both content-type & response body as a string
		async function gatherResponse(response) {
			const { headers } = response;
			const contentType = headers.get("content-type") || "";
			if (contentType.includes("application/json")) {
				return { contentType, result: JSON.stringify(await response.json()) };
			}
			return { contentType, result: await response.text() };
		}

		const response = await fetch(url);
		const { contentType, result } = await gatherResponse(response);

		const options = { headers: { "content-type": contentType } };
		return new Response(result, options);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Env {}
export default {
	async fetch(request, env, ctx): Promise<Response> {
		const url = "https://jsonplaceholder.typicode.com/todos/1";

		// gatherResponse returns both content-type & response body as a string
		async function gatherResponse(response) {
			const { headers } = response;
			const contentType = headers.get("content-type") || "";
			if (contentType.includes("application/json")) {
				return { contentType, result: JSON.stringify(await response.json()) };
			}
			return { contentType, result: await response.text() };
		}

		const response = await fetch(url);
		const { contentType, result } = await gatherResponse(response);

		const options = { headers: { "content-type": contentType } };
		return new Response(result, options);
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch
import json

async def on_fetch(request):
    url = "https://jsonplaceholder.typicode.com/todos/1"

    # gather_response returns both content-type & response body as a string
    async def gather_response(response):
        headers = response.headers
        content_type = headers["content-type"] or ""

        if "application/json" in content_type:
            return (content_type, json.dumps(await response.json()))
        return (content_type, await response.text())

    response = await fetch(url)
    content_type, result = await gather_response(response)


    headers = {"content-type": content_type}
    return Response(result, headers=headers)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

type Env = {};

const app = new Hono<{ Bindings: Env }>();

app.get('*', async (c) => {
  const url = "https://jsonplaceholder.typicode.com/todos/1";

  // gatherResponse returns both content-type & response body as a string
  async function gatherResponse(response: Response) {
    const { headers } = response;
    const contentType = headers.get("content-type") || "";

    if (contentType.includes("application/json")) {
      return { contentType, result: JSON.stringify(await response.json()) };
    }

    return { contentType, result: await response.text() };
  }

  const response = await fetch(url);
  const { contentType, result } = await gatherResponse(response);

  return new Response(result, {
    headers: { "content-type": contentType }
  });
});

export default app;
```

</TabItem> </Tabs>

---

# Geolocation: Weather application

URL: https://developers.cloudflare.com/workers/examples/geolocation-app-weather/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/geolocation-app-weather)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		let endpoint = "https://api.waqi.info/feed/geo:";
		const token = ""; //Use a token from https://aqicn.org/api/
		let html_style = `body{padding:6em; font-family: sans-serif;} h1{color:#f6821f}`;

		let html_content = "<h1>Weather 🌦</h1>";

		const latitude = request.cf.latitude;
		const longitude = request.cf.longitude;
		endpoint += `${latitude};${longitude}/?token=${token}`;
		const init = {
			headers: {
				"content-type": "application/json;charset=UTF-8",
			},
		};

		const response = await fetch(endpoint, init);
		const content = await response.json();

		html_content += `<p>This is a demo using Workers geolocation data. </p>`;
		html_content += `You are located at: ${latitude},${longitude}.</p>`;
		html_content += `<p>Based off sensor data from <a href="${content.data.city.url}">${content.data.city.name}</a>:</p>`;
		html_content += `<p>The AQI level is: ${content.data.aqi}.</p>`;
		html_content += `<p>The N02 level is: ${content.data.iaqi.no2?.v}.</p>`;
		html_content += `<p>The O3 level is: ${content.data.iaqi.o3?.v}.</p>`;
		html_content += `<p>The temperature is: ${content.data.iaqi.t?.v}°C.</p>`;

		let html = `
      <!DOCTYPE html>
      <head>
        <title>Geolocation: Weather</title>
      </head>
      <body>
        <style>${html_style}</style>
        <div id="container">
        ${html_content}
        </div>
      </body>`;

		return new Response(html, {
			headers: {
				"content-type": "text/html;charset=UTF-8",
			},
		});
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		let endpoint = "https://api.waqi.info/feed/geo:";
		const token = ""; //Use a token from https://aqicn.org/api/
		let html_style = `body{padding:6em; font-family: sans-serif;} h1{color:#f6821f}`;

		let html_content = "<h1>Weather 🌦</h1>";

		const latitude = request.cf.latitude;
		const longitude = request.cf.longitude;
		endpoint += `${latitude};${longitude}/?token=${token}`;
		const init = {
			headers: {
				"content-type": "application/json;charset=UTF-8",
			},
		};

		const response = await fetch(endpoint, init);
		const content = await response.json();

		html_content += `<p>This is a demo using Workers geolocation data. </p>`;
		html_content += `You are located at: ${latitude},${longitude}.</p>`;
		html_content += `<p>Based off sensor data from <a href="${content.data.city.url}">${content.data.city.name}</a>:</p>`;
		html_content += `<p>The AQI level is: ${content.data.aqi}.</p>`;
		html_content += `<p>The N02 level is: ${content.data.iaqi.no2?.v}.</p>`;
		html_content += `<p>The O3 level is: ${content.data.iaqi.o3?.v}.</p>`;
		html_content += `<p>The temperature is: ${content.data.iaqi.t?.v}°C.</p>`;

		let html = `
      <!DOCTYPE html>
      <head>
        <title>Geolocation: Weather</title>
      </head>
      <body>
        <style>${html_style}</style>
        <div id="container">
        ${html_content}
        </div>
      </body>`;

		return new Response(html, {
			headers: {
				"content-type": "text/html;charset=UTF-8",
			},
		});
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';
import { html } from 'hono/html';

type Bindings = {};

interface WeatherApiResponse {
  data: {
    aqi: number;
    city: {
      name: string;
      url: string;
    };
    iaqi: {
      no2?: { v: number };
      o3?: { v: number };
      t?: { v: number };
    };
  };
}

const app = new Hono<{ Bindings: Bindings }>();

app.get('*', async (c) => {
  // Get API endpoint
  let endpoint = "https://api.waqi.info/feed/geo:";
  const token = ""; // Use a token from https://aqicn.org/api/

  // Define styles
  const html_style = `body{padding:6em; font-family: sans-serif;} h1{color:#f6821f}`;

  // Get geolocation from Cloudflare request
  const req = c.req.raw;
  const latitude = req.cf?.latitude;
  const longitude = req.cf?.longitude;

  // Create complete API endpoint with coordinates
  endpoint += `${latitude};${longitude}/?token=${token}`;

  // Fetch weather data
  const init = {
    headers: {
      "content-type": "application/json;charset=UTF-8",
    },
  };
  const response = await fetch(endpoint, init);
  const content = await response.json() as WeatherApiResponse;

  // Build HTML content
  const weatherContent = html`
    <h1>Weather 🌦</h1>
    <p>This is a demo using Workers geolocation data.</p>
    <p>You are located at: ${latitude},${longitude}.</p>
    <p>Based off sensor data from <a href="${content.data.city.url}">${content.data.city.name}</a>:</p>
    <p>The AQI level is: ${content.data.aqi}.</p>
    <p>The N02 level is: ${content.data.iaqi.no2?.v}.</p>
    <p>The O3 level is: ${content.data.iaqi.o3?.v}.</p>
    <p>The temperature is: ${content.data.iaqi.t?.v}°C.</p>
  `;

  // Complete HTML document
  const htmlDocument = html`
    <!DOCTYPE html>
    <head>
      <title>Geolocation: Weather</title>
    </head>
    <body>
      <style>${html_style}</style>
      <div id="container">
        ${weatherContent}
      </div>
    </body>
  `;

  // Return HTML response
  return c.html(htmlDocument);
});

export default app;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch

async def on_fetch(request):
    endpoint = "https://api.waqi.info/feed/geo:"
    token = "" # Use a token from https://aqicn.org/api/
    html_style = "body{padding:6em; font-family: sans-serif;} h1{color:#f6821f}"
    html_content = "<h1>Weather 🌦</h1>"

    latitude = request.cf.latitude
    longitude = request.cf.longitude

    endpoint += f"{latitude};{longitude}/?token={token}"
    response = await fetch(endpoint)
    content = await response.json()

    html_content += "<p>This is a demo using Workers geolocation data. </p>"
    html_content += f"You are located at: {latitude},{longitude}.</p>"
    html_content += f"<p>Based off sensor data from <a href='{content['data']['city']['url']}'>{content['data']['city']['name']}</a>:</p>"
    html_content += f"<p>The AQI level is: {content['data']['aqi']}.</p>"
    html_content += f"<p>The N02 level is: {content['data']['iaqi']['no2']['v']}.</p>"
    html_content += f"<p>The O3 level is: {content['data']['iaqi']['o3']['v']}.</p>"
    html_content += f"<p>The temperature is: {content['data']['iaqi']['t']['v']}°C.</p>"

    html = f"""
    <!DOCTYPE html>
      <head>
        <title>Geolocation: Weather</title>
      </head>
      <body>
        <style>{html_style}</style>
        <div id="container">
        {html_content}
        </div>
      </body>
    """

    headers = {"content-type": "text/html;charset=UTF-8"}
    return Response(html, headers=headers)
```

</TabItem> </Tabs>

---

# Geolocation: Custom Styling

URL: https://developers.cloudflare.com/workers/examples/geolocation-custom-styling/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/geolocation-custom-styling)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		let grads = [
			[
				{ color: "00000c", position: 0 },
				{ color: "00000c", position: 0 },
			],
			[
				{ color: "020111", position: 85 },
				{ color: "191621", position: 100 },
			],
			[
				{ color: "020111", position: 60 },
				{ color: "20202c", position: 100 },
			],
			[
				{ color: "020111", position: 10 },
				{ color: "3a3a52", position: 100 },
			],
			[
				{ color: "20202c", position: 0 },
				{ color: "515175", position: 100 },
			],
			[
				{ color: "40405c", position: 0 },
				{ color: "6f71aa", position: 80 },
				{ color: "8a76ab", position: 100 },
			],
			[
				{ color: "4a4969", position: 0 },
				{ color: "7072ab", position: 50 },
				{ color: "cd82a0", position: 100 },
			],
			[
				{ color: "757abf", position: 0 },
				{ color: "8583be", position: 60 },
				{ color: "eab0d1", position: 100 },
			],
			[
				{ color: "82addb", position: 0 },
				{ color: "ebb2b1", position: 100 },
			],
			[
				{ color: "94c5f8", position: 1 },
				{ color: "a6e6ff", position: 70 },
				{ color: "b1b5ea", position: 100 },
			],
			[
				{ color: "b7eaff", position: 0 },
				{ color: "94dfff", position: 100 },
			],
			[
				{ color: "9be2fe", position: 0 },
				{ color: "67d1fb", position: 100 },
			],
			[
				{ color: "90dffe", position: 0 },
				{ color: "38a3d1", position: 100 },
			],
			[
				{ color: "57c1eb", position: 0 },
				{ color: "246fa8", position: 100 },
			],
			[
				{ color: "2d91c2", position: 0 },
				{ color: "1e528e", position: 100 },
			],
			[
				{ color: "2473ab", position: 0 },
				{ color: "1e528e", position: 70 },
				{ color: "5b7983", position: 100 },
			],
			[
				{ color: "1e528e", position: 0 },
				{ color: "265889", position: 50 },
				{ color: "9da671", position: 100 },
			],
			[
				{ color: "1e528e", position: 0 },
				{ color: "728a7c", position: 50 },
				{ color: "e9ce5d", position: 100 },
			],
			[
				{ color: "154277", position: 0 },
				{ color: "576e71", position: 30 },
				{ color: "e1c45e", position: 70 },
				{ color: "b26339", position: 100 },
			],
			[
				{ color: "163C52", position: 0 },
				{ color: "4F4F47", position: 30 },
				{ color: "C5752D", position: 60 },
				{ color: "B7490F", position: 80 },
				{ color: "2F1107", position: 100 },
			],
			[
				{ color: "071B26", position: 0 },
				{ color: "071B26", position: 30 },
				{ color: "8A3B12", position: 80 },
				{ color: "240E03", position: 100 },
			],
			[
				{ color: "010A10", position: 30 },
				{ color: "59230B", position: 80 },
				{ color: "2F1107", position: 100 },
			],
			[
				{ color: "090401", position: 50 },
				{ color: "4B1D06", position: 100 },
			],
			[
				{ color: "00000c", position: 80 },
				{ color: "150800", position: 100 },
			],
		];
		async function toCSSGradient(hour) {
			let css = "linear-gradient(to bottom,";
			const data = grads[hour];
			const len = data.length;
			for (let i = 0; i < len; i++) {
				const item = data[i];
				css += ` #${item.color} ${item.position}%`;
				if (i < len - 1) css += ",";
			}
			return css + ")";
		}
		let html_content = "";
		let html_style = `
			html{width:100vw; height:100vh;}
			body{padding:0; margin:0 !important;height:100%;}
			#container {
				display: flex;
				flex-direction:column;
				align-items: center;
				justify-content: center;
				height: 100%;
				color:white;
				font-family:sans-serif;
			}`;
		const timezone = request.cf.timezone;
		console.log(timezone);
		let localized_date = new Date(
			new Date().toLocaleString("en-US", { timeZone: timezone }),
		);
		let hour = localized_date.getHours();
		let minutes = localized_date.getMinutes();
		html_content += "<h1>" + hour + ":" + minutes + "</h1>";
		html_content += "<p>" + timezone + "<br/></p>";
		html_style += "body{background:" + (await toCSSGradient(hour)) + ";}";
		let html = `
			<!DOCTYPE html>
			<head>
				<title>Geolocation: Customized Design</title>
			</head>
			<body>
				<style> ${html_style}</style>
				<div id="container">
					${html_content}
				</div>
			</body>`;
		return new Response(html, {
			headers: { "content-type": "text/html;charset=UTF-8" },
		});
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		let grads = [
			[
				{ color: "00000c", position: 0 },
				{ color: "00000c", position: 0 },
			],
			[
				{ color: "020111", position: 85 },
				{ color: "191621", position: 100 },
			],
			[
				{ color: "020111", position: 60 },
				{ color: "20202c", position: 100 },
			],
			[
				{ color: "020111", position: 10 },
				{ color: "3a3a52", position: 100 },
			],
			[
				{ color: "20202c", position: 0 },
				{ color: "515175", position: 100 },
			],
			[
				{ color: "40405c", position: 0 },
				{ color: "6f71aa", position: 80 },
				{ color: "8a76ab", position: 100 },
			],
			[
				{ color: "4a4969", position: 0 },
				{ color: "7072ab", position: 50 },
				{ color: "cd82a0", position: 100 },
			],
			[
				{ color: "757abf", position: 0 },
				{ color: "8583be", position: 60 },
				{ color: "eab0d1", position: 100 },
			],
			[
				{ color: "82addb", position: 0 },
				{ color: "ebb2b1", position: 100 },
			],
			[
				{ color: "94c5f8", position: 1 },
				{ color: "a6e6ff", position: 70 },
				{ color: "b1b5ea", position: 100 },
			],
			[
				{ color: "b7eaff", position: 0 },
				{ color: "94dfff", position: 100 },
			],
			[
				{ color: "9be2fe", position: 0 },
				{ color: "67d1fb", position: 100 },
			],
			[
				{ color: "90dffe", position: 0 },
				{ color: "38a3d1", position: 100 },
			],
			[
				{ color: "57c1eb", position: 0 },
				{ color: "246fa8", position: 100 },
			],
			[
				{ color: "2d91c2", position: 0 },
				{ color: "1e528e", position: 100 },
			],
			[
				{ color: "2473ab", position: 0 },
				{ color: "1e528e", position: 70 },
				{ color: "5b7983", position: 100 },
			],
			[
				{ color: "1e528e", position: 0 },
				{ color: "265889", position: 50 },
				{ color: "9da671", position: 100 },
			],
			[
				{ color: "1e528e", position: 0 },
				{ color: "728a7c", position: 50 },
				{ color: "e9ce5d", position: 100 },
			],
			[
				{ color: "154277", position: 0 },
				{ color: "576e71", position: 30 },
				{ color: "e1c45e", position: 70 },
				{ color: "b26339", position: 100 },
			],
			[
				{ color: "163C52", position: 0 },
				{ color: "4F4F47", position: 30 },
				{ color: "C5752D", position: 60 },
				{ color: "B7490F", position: 80 },
				{ color: "2F1107", position: 100 },
			],
			[
				{ color: "071B26", position: 0 },
				{ color: "071B26", position: 30 },
				{ color: "8A3B12", position: 80 },
				{ color: "240E03", position: 100 },
			],
			[
				{ color: "010A10", position: 30 },
				{ color: "59230B", position: 80 },
				{ color: "2F1107", position: 100 },
			],
			[
				{ color: "090401", position: 50 },
				{ color: "4B1D06", position: 100 },
			],
			[
				{ color: "00000c", position: 80 },
				{ color: "150800", position: 100 },
			],
		];
		async function toCSSGradient(hour) {
			let css = "linear-gradient(to bottom,";
			const data = grads[hour];
			const len = data.length;
			for (let i = 0; i < len; i++) {
				const item = data[i];
				css += ` #${item.color} ${item.position}%`;
				if (i < len - 1) css += ",";
			}
			return css + ")";
		}
		let html_content = "";
		let html_style = `
			html{width:100vw; height:100vh;}
			body{padding:0; margin:0 !important;height:100%;}
			#container {
				display: flex;
				flex-direction:column;
				align-items: center;
				justify-content: center;
				height: 100%;
				color:white;
				font-family:sans-serif;
			}`;
		const timezone = request.cf.timezone;
		console.log(timezone);
		let localized_date = new Date(
			new Date().toLocaleString("en-US", { timeZone: timezone }),
		);
		let hour = localized_date.getHours();
		let minutes = localized_date.getMinutes();
		html_content += "<h1>" + hour + ":" + minutes + "</h1>";
		html_content += "<p>" + timezone + "<br/></p>";
		html_style += "body{background:" + (await toCSSGradient(hour)) + ";}";
		let html = `
			<!DOCTYPE html>
			<head>
				<title>Geolocation: Customized Design</title>
			</head>
			<body>
				<style> ${html_style}</style>
				<div id="container">
					${html_content}
				</div>
			</body>`;
		return new Response(html, {
			headers: { "content-type": "text/html;charset=UTF-8" },
		});
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

type Bindings = {};
type ColorStop = { color: string; position: number };

const app = new Hono<{ Bindings: Bindings }>();

// Gradient configurations for each hour of the day (0-23)
const grads: ColorStop[][] = [
  [
    { color: "00000c", position: 0 },
    { color: "00000c", position: 0 },
  ],
  [
    { color: "020111", position: 85 },
    { color: "191621", position: 100 },
  ],
  [
    { color: "020111", position: 60 },
    { color: "20202c", position: 100 },
  ],
  [
    { color: "020111", position: 10 },
    { color: "3a3a52", position: 100 },
  ],
  [
    { color: "20202c", position: 0 },
    { color: "515175", position: 100 },
  ],
  [
    { color: "40405c", position: 0 },
    { color: "6f71aa", position: 80 },
    { color: "8a76ab", position: 100 },
  ],
  [
    { color: "4a4969", position: 0 },
    { color: "7072ab", position: 50 },
    { color: "cd82a0", position: 100 },
  ],
  [
    { color: "757abf", position: 0 },
    { color: "8583be", position: 60 },
    { color: "eab0d1", position: 100 },
  ],
  [
    { color: "82addb", position: 0 },
    { color: "ebb2b1", position: 100 },
  ],
  [
    { color: "94c5f8", position: 1 },
    { color: "a6e6ff", position: 70 },
    { color: "b1b5ea", position: 100 },
  ],
  [
    { color: "b7eaff", position: 0 },
    { color: "94dfff", position: 100 },
  ],
  [
    { color: "9be2fe", position: 0 },
    { color: "67d1fb", position: 100 },
  ],
  [
    { color: "90dffe", position: 0 },
    { color: "38a3d1", position: 100 },
  ],
  [
    { color: "57c1eb", position: 0 },
    { color: "246fa8", position: 100 },
  ],
  [
    { color: "2d91c2", position: 0 },
    { color: "1e528e", position: 100 },
  ],
  [
    { color: "2473ab", position: 0 },
    { color: "1e528e", position: 70 },
    { color: "5b7983", position: 100 },
  ],
  [
    { color: "1e528e", position: 0 },
    { color: "265889", position: 50 },
    { color: "9da671", position: 100 },
  ],
  [
    { color: "1e528e", position: 0 },
    { color: "728a7c", position: 50 },
    { color: "e9ce5d", position: 100 },
  ],
  [
    { color: "154277", position: 0 },
    { color: "576e71", position: 30 },
    { color: "e1c45e", position: 70 },
    { color: "b26339", position: 100 },
  ],
  [
    { color: "163C52", position: 0 },
    { color: "4F4F47", position: 30 },
    { color: "C5752D", position: 60 },
    { color: "B7490F", position: 80 },
    { color: "2F1107", position: 100 },
  ],
  [
    { color: "071B26", position: 0 },
    { color: "071B26", position: 30 },
    { color: "8A3B12", position: 80 },
    { color: "240E03", position: 100 },
  ],
  [
    { color: "010A10", position: 30 },
    { color: "59230B", position: 80 },
    { color: "2F1107", position: 100 },
  ],
  [
    { color: "090401", position: 50 },
    { color: "4B1D06", position: 100 },
  ],
  [
    { color: "00000c", position: 80 },
    { color: "150800", position: 100 },
  ],
];

// Convert hour to CSS gradient
async function toCSSGradient(hour: number): Promise<string> {
  let css = "linear-gradient(to bottom,";
  const data = grads[hour];
  const len = data.length;

  for (let i = 0; i < len; i++) {
    const item = data[i];
    css += ` #${item.color} ${item.position}%`;
    if (i < len - 1) css += ",";
  }

  return css + ")";
}

app.get('*', async (c) => {
  const request = c.req.raw;

  // Base HTML style
  let html_style = `
    html{width:100vw; height:100vh;}
    body{padding:0; margin:0 !important;height:100%;}
    #container {
      display: flex;
      flex-direction:column;
      align-items: center;
      justify-content: center;
      height: 100%;
      color:white;
      font-family:sans-serif;
    }`;

  // Get timezone from Cloudflare request
  const timezone = request.cf?.timezone || 'UTC';
  console.log(timezone);

  // Get localized time
  let localized_date = new Date(
    new Date().toLocaleString("en-US", { timeZone: timezone })
  );

  let hour = localized_date.getHours();
  let minutes = localized_date.getMinutes();

  // Generate HTML content
  let html_content = `<h1>${hour}:${minutes}</h1>`;
  html_content += `<p>${timezone}<br/></p>`;

  // Add background gradient based on hour
  html_style += `body{background:${await toCSSGradient(hour)};}`;

  // Complete HTML document
  let html = `
    <!DOCTYPE html>
    <head>
      <title>Geolocation: Customized Design</title>
    </head>
    <body>
      <style>${html_style}</style>
      <div id="container">
        ${html_content}
      </div>
    </body>`;

  return c.html(html);
});

export default app;
```

</TabItem> </Tabs>

---

# Geolocation: Hello World

URL: https://developers.cloudflare.com/workers/examples/geolocation-hello-world/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/geolocation-hello-world)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		let html_content = "";
		let html_style =
			"body{padding:6em; font-family: sans-serif;} h1{color:#f6821f;}";

		html_content += "<p> Colo: " + request.cf.colo + "</p>";
		html_content += "<p> Country: " + request.cf.country + "</p>";
		html_content += "<p> City: " + request.cf.city + "</p>";
		html_content += "<p> Continent: " + request.cf.continent + "</p>";
		html_content += "<p> Latitude: " + request.cf.latitude + "</p>";
		html_content += "<p> Longitude: " + request.cf.longitude + "</p>";
		html_content += "<p> PostalCode: " + request.cf.postalCode + "</p>";
		html_content += "<p> MetroCode: " + request.cf.metroCode + "</p>";
		html_content += "<p> Region: " + request.cf.region + "</p>";
		html_content += "<p> RegionCode: " + request.cf.regionCode + "</p>";
		html_content += "<p> Timezone: " + request.cf.timezone + "</p>";

		let html = `<!DOCTYPE html>
      <head>
        <title> Geolocation: Hello World </title>
        <style> ${html_style} </style>
      </head>
      <body>
        <h1>Geolocation: Hello World!</h1>
        <p>You now have access to geolocation data about where your user is visiting from.</p>
        ${html_content}
      </body>`;

		return new Response(html, {
			headers: {
				"content-type": "text/html;charset=UTF-8",
			},
		});
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		let html_content = "";
		let html_style =
			"body{padding:6em; font-family: sans-serif;} h1{color:#f6821f;}";

		html_content += "<p> Colo: " + request.cf.colo + "</p>";
		html_content += "<p> Country: " + request.cf.country + "</p>";
		html_content += "<p> City: " + request.cf.city + "</p>";
		html_content += "<p> Continent: " + request.cf.continent + "</p>";
		html_content += "<p> Latitude: " + request.cf.latitude + "</p>";
		html_content += "<p> Longitude: " + request.cf.longitude + "</p>";
		html_content += "<p> PostalCode: " + request.cf.postalCode + "</p>";
		html_content += "<p> MetroCode: " + request.cf.metroCode + "</p>";
		html_content += "<p> Region: " + request.cf.region + "</p>";
		html_content += "<p> RegionCode: " + request.cf.regionCode + "</p>";
		html_content += "<p> Timezone: " + request.cf.timezone + "</p>";

		let html = `<!DOCTYPE html>
      <head>
        <title> Geolocation: Hello World </title>
        <style> ${html_style} </style>
      </head>
      <body>
        <h1>Geolocation: Hello World!</h1>
        <p>You now have access to geolocation data about where your user is visiting from.</p>
        ${html_content}
      </body>`;

		return new Response(html, {
			headers: {
				"content-type": "text/html;charset=UTF-8",
			},
		});
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response

async def on_fetch(request):
    html_content = ""
    html_style = "body{padding:6em font-family: sans-serif;} h1{color:#f6821f;}"

    html_content += "<p> Colo: " + request.cf.colo + "</p>"
    html_content += "<p> Country: " + request.cf.country + "</p>"
    html_content += "<p> City: " + request.cf.city + "</p>"
    html_content += "<p> Continent: " + request.cf.continent + "</p>"
    html_content += "<p> Latitude: " + request.cf.latitude + "</p>"
    html_content += "<p> Longitude: " + request.cf.longitude + "</p>"
    html_content += "<p> PostalCode: " + request.cf.postalCode + "</p>"
    html_content += "<p> Region: " + request.cf.region + "</p>"
    html_content += "<p> RegionCode: " + request.cf.regionCode + "</p>"
    html_content += "<p> Timezone: " + request.cf.timezone + "</p>"

    html = f"""
    <!DOCTYPE html>
      <head>
        <title> Geolocation: Hello World </title>
        <style> {html_style} </style>
      </head>
      <body>
        <h1>Geolocation: Hello World!</h1>
        <p>You now have access to geolocation data about where your user is visiting from.</p>
        {html_content}
      </body>
    """

    headers = {"content-type": "text/html;charset=UTF-8"}
    return Response(html, headers=headers)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";
import { html } from "hono/html";

// Define the RequestWithCf interface to add Cloudflare-specific properties
interface RequestWithCf extends Request {
	cf: {
		// Cloudflare-specific properties for geolocation
		colo: string;
		country: string;
		city: string;
		continent: string;
		latitude: string;
		longitude: string;
		postalCode: string;
		metroCode: string;
		region: string;
		regionCode: string;
		timezone: string;
		// Add other CF properties as needed
	};
}

const app = new Hono();

app.get("*", (c) => {
	// Cast the raw request to include Cloudflare-specific properties
	const request = c.req.raw;

	// Define styles
	const html_style =
		"body{padding:6em; font-family: sans-serif;} h1{color:#f6821f;}";

	// Create content with geolocation data
	let html_content = html` <p>Colo: ${request.cf.colo}</p>
		<p>Country: ${request.cf.country}</p>
		<p>City: ${request.cf.city}</p>
		<p>Continent: ${request.cf.continent}</p>
		<p>Latitude: ${request.cf.latitude}</p>
		<p>Longitude: ${request.cf.longitude}</p>
		<p>PostalCode: ${request.cf.postalCode}</p>
		<p>MetroCode: ${request.cf.metroCode}</p>
		<p>Region: ${request.cf.region}</p>
		<p>RegionCode: ${request.cf.regionCode}</p>
		<p>Timezone: ${request.cf.timezone}</p>`;

	// Compose the full HTML
	const htmlContent = html`<!DOCTYPE html>
		<head>
			<title>Geolocation: Hello World</title>
			<style>
				${html_style}
			</style>
		</head>
		<body>
			<h1>Geolocation: Hello World!</h1>
			<p>
				You now have access to geolocation data about where your user is
				visiting from.
			</p>
			${html_content}
		</body> `;

	// Return the HTML response
	return c.html(htmlContent);
});

export default app;
```

</TabItem> </Tabs>

---

# Hot-link protection

URL: https://developers.cloudflare.com/workers/examples/hot-link-protection/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/hot-link-protection)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		const HOMEPAGE_URL = "https://tutorial.cloudflareworkers.com/";
		const PROTECTED_TYPE = "image/";

		// Fetch the original request
		const response = await fetch(request);

		// If it's an image, engage hotlink protection based on the
		// Referer header.
		const referer = request.headers.get("Referer");
		const contentType = response.headers.get("Content-Type") || "";

		if (referer && contentType.startsWith(PROTECTED_TYPE)) {
			// If the hostnames don't match, it's a hotlink
			if (new URL(referer).hostname !== new URL(request.url).hostname) {
				// Redirect the user to your website
				return Response.redirect(HOMEPAGE_URL, 302);
			}
		}

		// Everything is fine, return the response normally.
		return response;
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const HOMEPAGE_URL = "https://tutorial.cloudflareworkers.com/";
		const PROTECTED_TYPE = "image/";

		// Fetch the original request
		const response = await fetch(request);

		// If it's an image, engage hotlink protection based on the
		// Referer header.
		const referer = request.headers.get("Referer");
		const contentType = response.headers.get("Content-Type") || "";

		if (referer && contentType.startsWith(PROTECTED_TYPE)) {
			// If the hostnames don't match, it's a hotlink
			if (new URL(referer).hostname !== new URL(request.url).hostname) {
				// Redirect the user to your website
				return Response.redirect(HOMEPAGE_URL, 302);
			}
		}

		// Everything is fine, return the response normally.
		return response;
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch
from urllib.parse import urlparse

async def on_fetch(request):
    homepage_url = "https://tutorial.cloudflareworkers.com/"
    protected_type = "image/"

    # Fetch the original request
    response = await fetch(request)

    # If it's an image, engage hotlink protection based on the referer header
    referer = request.headers["Referer"]
    content_type = response.headers["Content-Type"] or ""

    if referer and content_type.startswith(protected_type):
        # If the hostnames don't match, it's a hotlink
        if urlparse(referer).hostname != urlparse(request.url).hostname:
            # Redirect the user to your website
            return Response.redirect(homepage_url, 302)

    # Everything is fine, return the response normally
    return response
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

const app = new Hono();

// Middleware for hot-link protection
app.use('*', async (c, next) => {
  const HOMEPAGE_URL = "https://tutorial.cloudflareworkers.com/";
  const PROTECTED_TYPE = "image/";

  // Continue to the next handler to get the response
  await next();

  // If we have a response, check for hotlinking
  if (c.res) {
    // If it's an image, engage hotlink protection based on the Referer header
    const referer = c.req.header("Referer");
    const contentType = c.res.headers.get("Content-Type") || "";

    if (referer && contentType.startsWith(PROTECTED_TYPE)) {
      // If the hostnames don't match, it's a hotlink
      if (new URL(referer).hostname !== new URL(c.req.url).hostname) {
        // Redirect the user to your website
        c.res = c.redirect(HOMEPAGE_URL, 302);
      }
    }
  }
});

// Default route handler that passes through the request to the origin
app.all('*', async (c) => {
  // Fetch the original request
  return fetch(c.req.raw);
});

export default app;
```

</TabItem> </Tabs>

---

# Custom Domain with Images

URL: https://developers.cloudflare.com/workers/examples/images-workers/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/images-workers)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

To serve images from a custom domain:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com).
2. Select your account > select **Workers & Pages**.
3. Select **Create application** > **Workers** > **Create Worker** and create your Worker.
4. In your Worker, select **Quick edit** and paste the following code.

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		// You can find this in the dashboard, it should look something like this: ZWd9g1K7eljCn_KDTu_MWA
		const accountHash = "";

		const { pathname } = new URL(request.url);

		// A request to something like cdn.example.com/83eb7b2-5392-4565-b69e-aff66acddd00/public
		// will fetch "https://imagedelivery.net/<accountHash>/83eb7b2-5392-4565-b69e-aff66acddd00/public"

		return fetch(`https://imagedelivery.net/${accountHash}${pathname}`);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		// You can find this in the dashboard, it should look something like this: ZWd9g1K7eljCn_KDTu_MWA
		const accountHash = "";

		const { pathname } = new URL(request.url);

		// A request to something like cdn.example.com/83eb7b2-5392-4565-b69e-aff66acddd00/public
		// will fetch "https://imagedelivery.net/<accountHash>/83eb7b2-5392-4565-b69e-aff66acddd00/public"

		return fetch(`https://imagedelivery.net/${accountHash}${pathname}`);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

interface Env {
  // You can store your account hash as a binding variable
  ACCOUNT_HASH?: string;
}

const app = new Hono<{ Bindings: Env }>();

app.get('*', async (c) => {
  // You can find this in the dashboard, it should look something like this: ZWd9g1K7eljCn_KDTu_MWA
  // Either get it from environment or hardcode it here
  const accountHash = c.env.ACCOUNT_HASH || "";

  const url = new URL(c.req.url);

  // A request to something like cdn.example.com/83eb7b2-5392-4565-b69e-aff66acddd00/public
  // will fetch "https://imagedelivery.net/<accountHash>/83eb7b2-5392-4565-b69e-aff66acddd00/public"

  return fetch(`https://imagedelivery.net/${accountHash}${url.pathname}`);
});

export default app;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from js import URL, fetch

async def on_fetch(request):
    # You can find this in the dashboard, it should look something like this: ZWd9g1K7eljCn_KDTu_MWA
    account_hash = ""
    url = URL.new(request.url)

    # A request to something like cdn.example.com/83eb7b2-5392-4565-b69e-aff66acddd00/public
    # will fetch "https://imagedelivery.net/<accountHash>/83eb7b2-5392-4565-b69e-aff66acddd00/public"
    return fetch(f'https://imagedelivery.net/{account_hash}{url.pathname}')
```

</TabItem> </Tabs>

Another way you can serve images from a custom domain is by using the `cdn-cgi/imagedelivery` prefix path which is used as path to trigger `cdn-cgi` image proxy.

Below is an example showing the hostname as a Cloudflare proxied domain under the same account as the Image, followed with the prefix path and the image `<ACCOUNT_HASH>`, `<IMAGE_ID>` and `<VARIANT_NAME>` which can be found in the **Images** on the Cloudflare dashboard.

```js
https://example.com/cdn-cgi/imagedelivery/<ACCOUNT_HASH>/<IMAGE_ID>/<VARIANT_NAME>
```

---

# Examples

URL: https://developers.cloudflare.com/workers/examples/

import { GlossaryTooltip, ListExamples } from "~/components";

Explore the following <GlossaryTooltip term="code example">examples</GlossaryTooltip> for Workers.

<ListExamples directory="workers/examples/" filters={["languages", "tags"]} />

---

# Logging headers to console

URL: https://developers.cloudflare.com/workers/examples/logging-headers/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/logging-headers)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		console.log(new Map(request.headers));
		return new Response("Hello world");
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		console.log(new Map(request.headers));
		return new Response("Hello world");
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response

async def on_fetch(request):
    print(dict(request.headers))
    return Response('Hello world')
```

</TabItem> <TabItem label="Rust" icon="seti:rust">
```rs
use worker::*;

#[event(fetch)]
async fn fetch(req: HttpRequest, \_env: Env, \_ctx: Context) -> Result<Response> {
console_log!("{:?}", req.headers());
Response::ok("hello world")
}

````
</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

const app = new Hono();

app.get('*', (c) => {
  // Different ways to log headers in Hono:

  // 1. Using Map to display headers in console
  console.log('Headers as Map:', new Map(c.req.raw.headers));

  // 2. Using spread operator to log headers
  console.log('Headers spread:', [...c.req.raw.headers]);

  // 3. Using Object.fromEntries to convert to an object
  console.log('Headers as Object:', Object.fromEntries(c.req.raw.headers));

  // 4. Hono's built-in header accessor (for individual headers)
  console.log('User-Agent:', c.req.header('User-Agent'));

  // 5. Using c.req.headers to get all headers
  console.log('All headers from Hono context:', c.req.header());

  return c.text('Hello world');
});

export default app;
````

</TabItem> </Tabs>

---

## Console-logging headers

Use a `Map` if you need to log a `Headers` object to the console:

```js
console.log(new Map(request.headers));
```

Use the `spread` operator if you need to quickly stringify a `Headers` object:

```js
let requestHeaders = JSON.stringify([...request.headers]);
```

Use `Object.fromEntries` to convert the headers to an object:

```js
let requestHeaders = Object.fromEntries(request.headers);
```

### The problem

When debugging Workers, examine the headers on a request or response. A common mistake is to try to log headers to the developer console via code like this:

```js
console.log(request.headers);
```

Or this:

```js
console.log(`Request headers: ${JSON.stringify(request.headers)}`);
```

Both attempts result in what appears to be an empty object — the string `"{}"` — even though calling `request.headers.has("Your-Header-Name")` might return true. This is the same behavior that browsers implement.

The reason this happens is because [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) objects do not store headers in enumerable JavaScript properties, so the developer console and JSON stringifier do not know how to read the names and values of the headers. It is not actually an empty object, but rather an opaque object.

`Headers` objects are iterable, which you can take advantage of to develop a couple of quick one-liners for debug-printing headers.

### Pass headers through a Map

The first common idiom for making Headers `console.log()`-friendly is to construct a `Map` object from the `Headers` object and log the `Map` object.

```js
console.log(new Map(request.headers));
```

This works because:

- `Map` objects can be constructed from iterables, like `Headers`.

- The `Map` object does store its entries in enumerable JavaScript properties, so the developer console can see into it.

### Spread headers into an array

The `Map` approach works for calls to `console.log()`. If you need to stringify your headers, you will discover that stringifying a `Map` yields nothing more than `[object Map]`.

Even though a `Map` stores its data in enumerable properties, those properties are [Symbol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol)-keyed. Because of this, `JSON.stringify()` will [ignore Symbol-keyed properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol#symbols_and_json.stringify) and you will receive an empty `{}`.

Instead, you can take advantage of the iterability of the `Headers` object in a new way by applying the [spread operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) (`...`) to it.

```js
let requestHeaders = JSON.stringify([...request.headers], null, 2);
console.log(`Request headers: ${requestHeaders}`);
```

### Convert headers into an object with Object.fromEntries (ES2019)

ES2019 provides [`Object.fromEntries`](https://github.com/tc39/proposal-object-from-entries) which is a call to convert the headers into an object:

```js
let headersObject = Object.fromEntries(request.headers);
let requestHeaders = JSON.stringify(headersObject, null, 2);
console.log(`Request headers: ${requestHeaders}`);
```

This results in something like:

```js
Request headers: {
  "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
  "accept-encoding": "gzip",
  "accept-language": "en-US,en;q=0.9",
  "cf-ipcountry": "US",
  // ...
}"
```

---

# Modify request property

URL: https://developers.cloudflare.com/workers/examples/modify-request-property/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/modify-request-property)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		/**
		 * Example someHost is set up to return raw JSON
		 * @param {string} someUrl the URL to send the request to, since we are setting hostname too only path is applied
		 * @param {string} someHost the host the request will resolve too
		 */
		const someHost = "example.com";
		const someUrl = "https://foo.example.com/api.js";

		/**
		 * The best practice is to only assign new RequestInit properties
		 * on the request object using either a method or the constructor
		 */
		const newRequestInit = {
			// Change method
			method: "POST",
			// Change body
			body: JSON.stringify({ bar: "foo" }),
			// Change the redirect mode.
			redirect: "follow",
			// Change headers, note this method will erase existing headers
			headers: {
				"Content-Type": "application/json",
			},
			// Change a Cloudflare feature on the outbound response
			cf: { apps: false },
		};

		// Change just the host
		const url = new URL(someUrl);

		url.hostname = someHost;

		// Best practice is to always use the original request to construct the new request
		// to clone all the attributes. Applying the URL also requires a constructor
		// since once a Request has been constructed, its URL is immutable.
		const newRequest = new Request(
			url.toString(),
			new Request(request, newRequestInit),
		);

		// Set headers using method
		newRequest.headers.set("X-Example", "bar");
		newRequest.headers.set("Content-Type", "application/json");
		try {
			return await fetch(newRequest);
		} catch (e) {
			return new Response(JSON.stringify({ error: e.message }), {
				status: 500,
			});
		}
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		/**
		 * Example someHost is set up to return raw JSON
		 * @param {string} someUrl the URL to send the request to, since we are setting hostname too only path is applied
		 * @param {string} someHost the host the request will resolve too
		 */
		const someHost = "example.com";
		const someUrl = "https://foo.example.com/api.js";

		/**
		 * The best practice is to only assign new RequestInit properties
		 * on the request object using either a method or the constructor
		 */
		const newRequestInit = {
			// Change method
			method: "POST",
			// Change body
			body: JSON.stringify({ bar: "foo" }),
			// Change the redirect mode.
			redirect: "follow",
			// Change headers, note this method will erase existing headers
			headers: {
				"Content-Type": "application/json",
			},
			// Change a Cloudflare feature on the outbound response
			cf: { apps: false },
		};

		// Change just the host
		const url = new URL(someUrl);

		url.hostname = someHost;

		// Best practice is to always use the original request to construct the new request
		// to clone all the attributes. Applying the URL also requires a constructor
		// since once a Request has been constructed, its URL is immutable.
		const newRequest = new Request(
			url.toString(),
			new Request(request, newRequestInit),
		);

		// Set headers using method
		newRequest.headers.set("X-Example", "bar");
		newRequest.headers.set("Content-Type", "application/json");
		try {
			return await fetch(newRequest);
		} catch (e) {
			return new Response(JSON.stringify({ error: e.message }), {
				status: 500,
			});
		}
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
import json
from pyodide.ffi import to_js as _to_js
from js import Object, URL, Request, fetch, Response

def to_js(obj):
    return _to_js(obj, dict_converter=Object.fromEntries)

async def on_fetch(request):
    some_host = "example.com"
    some_url = "https://foo.example.com/api.js"

    # The best practice is to only assign new_request_init properties
    # on the request object using either a method or the constructor
    new_request_init = {
      "method": "POST", # Change method
      "body": json.dumps({ "bar": "foo" }), # Change body
      "redirect": "follow", # Change the redirect mode
      # Change headers, note this method will erase existing headers
      "headers": {
        "Content-Type": "application/json",
      },
      #  Change a Cloudflare feature on the outbound response
      "cf": { "apps": False },
    }

    # Change just the host
    url = URL.new(some_url)
    url.hostname = some_host

    # Best practice is to always use the original request to construct the new request
    # to clone all the attributes. Applying the URL also requires a constructor
    # since once a Request has been constructed, its URL is immutable.
    org_request = Request.new(request, new_request_init)
    new_request = Request.new(url.toString(),org_request)

    new_request.headers["X-Example"] =  "bar"
    new_request.headers["Content-Type"] = "application/json"

    try:
        return await fetch(new_request)
    except Exception as e:
        return Response.new({"error": str(e)}, status=500)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";

const app = new Hono();

app.all("*", async (c) => {
	/**
	 * Example someHost is set up to return raw JSON
	 */
	const someHost = "example.com";
	const someUrl = "https://foo.example.com/api.js";

	// Create a URL object to modify the hostname
	const url = new URL(someUrl);
	url.hostname = someHost;

	// Create a new request
	// First create a clone of the original request with the new properties
	const requestClone = new Request(c.req.raw, {
		// Change method
		method: "POST",
		// Change body
		body: JSON.stringify({ bar: "foo" }),
		// Change the redirect mode
		redirect: "follow" as RequestRedirect,
		// Change headers, note this method will erase existing headers
		headers: {
			"Content-Type": "application/json",
			"X-Example": "bar",
		},
		// Change a Cloudflare feature on the outbound response
		cf: { apps: false },
	});

	// Then create a new request with the modified URL
	const newRequest = new Request(url.toString(), requestClone);

	// Send the modified request
	const response = await fetch(newRequest);

	// Return the response
	return response;
});

// Handle errors
app.onError((err, c) => {
	return err.getResponse();
});

export default app;
```

</TabItem> </Tabs>

---

# Modify response

URL: https://developers.cloudflare.com/workers/examples/modify-response/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/modify-response)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		/**
		 * @param {string} headerNameSrc Header to get the new value from
		 * @param {string} headerNameDst Header to set based off of value in src
		 */
		const headerNameSrc = "foo"; //"Orig-Header"
		const headerNameDst = "Last-Modified";

		/**
		 * Response properties are immutable. To change them, construct a new
		 * Response and pass modified status or statusText in the ResponseInit
		 * object. Response headers can be modified through the headers `set` method.
		 */
		const originalResponse = await fetch(request);

		// Change status and statusText, but preserve body and headers
		let response = new Response(originalResponse.body, {
			status: 500,
			statusText: "some message",
			headers: originalResponse.headers,
		});

		// Change response body by adding the foo prop
		const originalBody = await originalResponse.json();
		const body = JSON.stringify({ foo: "bar", ...originalBody });
		response = new Response(body, response);

		// Add a header using set method
		response.headers.set("foo", "bar");

		// Set destination header to the value of the source header
		const src = response.headers.get(headerNameSrc);

		if (src != null) {
			response.headers.set(headerNameDst, src);
			console.log(
				`Response header "${headerNameDst}" was set to "${response.headers.get(
					headerNameDst,
				)}"`,
			);
		}
		return response;
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		/**
		 * @param {string} headerNameSrc Header to get the new value from
		 * @param {string} headerNameDst Header to set based off of value in src
		 */
		const headerNameSrc = "foo"; //"Orig-Header"
		const headerNameDst = "Last-Modified";

		/**
		 * Response properties are immutable. To change them, construct a new
		 * Response and pass modified status or statusText in the ResponseInit
		 * object. Response headers can be modified through the headers `set` method.
		 */
		const originalResponse = await fetch(request);

		// Change status and statusText, but preserve body and headers
		let response = new Response(originalResponse.body, {
			status: 500,
			statusText: "some message",
			headers: originalResponse.headers,
		});

		// Change response body by adding the foo prop
		const originalBody = await originalResponse.json();
		const body = JSON.stringify({ foo: "bar", ...originalBody });
		response = new Response(body, response);

		// Add a header using set method
		response.headers.set("foo", "bar");

		// Set destination header to the value of the source header
		const src = response.headers.get(headerNameSrc);

		if (src != null) {
			response.headers.set(headerNameDst, src);
			console.log(
				`Response header "${headerNameDst}" was set to "${response.headers.get(
					headerNameDst,
				)}"`,
			);
		}
		return response;
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch
import json

async def on_fetch(request):
    header_name_src = "foo" # Header to get the new value from
    header_name_dst = "Last-Modified" # Header to set based off of value in src

    # Response properties are immutable. To change them, construct a new response
    original_response = await fetch(request)

    # Change status and statusText, but preserve body and headers
    response = Response(original_response.body, status=500, status_text="some message", headers=original_response.headers)

    # Change response body by adding the foo prop
    new_body = await original_response.json()
    new_body["foo"] = "bar"
    response.replace_body(json.dumps(new_body))

    # Add a new header
    response.headers["foo"] = "bar"

    # Set destination header to the value of the source header
    src = response.headers[header_name_src]

    if src is not None:
        response.headers[header_name_dst] = src
        print(f'Response header {header_name_dst} was set to {response.headers[header_name_dst]}')

    return response
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

const app = new Hono();

app.get('*', async (c) => {
  /**
   * Header configuration
   */
  const headerNameSrc = "foo"; // Header to get the new value from
  const headerNameDst = "Last-Modified"; // Header to set based off of value in src

  /**
   * Response properties are immutable. With Hono, we can modify the response
   * by creating custom response objects.
   */
  const originalResponse = await fetch(c.req.raw);

  // Get the JSON body from the original response
  const originalBody = await originalResponse.json();

  // Modify the body by adding a new property
  const modifiedBody = {
    foo: "bar",
    ...originalBody
  };

  // Create a new custom response with modified status, headers, and body
  const response = new Response(JSON.stringify(modifiedBody), {
    status: 500,
    statusText: "some message",
    headers: originalResponse.headers,
  });

  // Add a header using set method
  response.headers.set("foo", "bar");

  // Set destination header to the value of the source header
  const src = response.headers.get(headerNameSrc);
  if (src != null) {
    response.headers.set(headerNameDst, src);
    console.log(
      `Response header "${headerNameDst}" was set to "${response.headers.get(headerNameDst)}"`
    );
  }

  return response;
});

export default app;
```

</TabItem> </Tabs>

---

# Multiple Cron Triggers

URL: https://developers.cloudflare.com/workers/examples/multiple-cron-triggers/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/multiple-cron-triggers)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async scheduled(event, env, ctx) {
		// Write code for updating your API
		switch (event.cron) {
			case "*/3 * * * *":
				// Every three minutes
				await updateAPI();
				break;
			case "*/10 * * * *":
				// Every ten minutes
				await updateAPI2();
				break;
			case "*/45 * * * *":
				// Every forty-five minutes
				await updateAPI3();
				break;
		}
		console.log("cron processed");
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Env {}
export default {
	async scheduled(
		controller: ScheduledController,
		env: Env,
		ctx: ExecutionContext,
	) {
		// Write code for updating your API
		switch (controller.cron) {
			case "*/3 * * * *":
				// Every three minutes
				await updateAPI();
				break;
			case "*/10 * * * *":
				// Every ten minutes
				await updateAPI2();
				break;
			case "*/45 * * * *":
				// Every forty-five minutes
				await updateAPI3();
				break;
		}
		console.log("cron processed");
	},
};
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";

interface Env {}

// Create Hono app
const app = new Hono<{ Bindings: Env }>();

// Regular routes for normal HTTP requests
app.get("/", (c) => c.text("Multiple Cron Trigger Example"));

// Export both the app and a scheduled function
export default {
	// The Hono app handles regular HTTP requests
	fetch: app.fetch,

	// The scheduled function handles Cron triggers
	async scheduled(
		controller: ScheduledController,
		env: Env,
		ctx: ExecutionContext,
	) {
		// Check which cron schedule triggered this execution
		switch (controller.cron) {
			case "*/3 * * * *":
				// Every three minutes
				await updateAPI();
				break;
			case "*/10 * * * *":
				// Every ten minutes
				await updateAPI2();
				break;
			case "*/45 * * * *":
				// Every forty-five minutes
				await updateAPI3();
				break;
		}
		console.log("cron processed");
	},
};
```

</TabItem> </Tabs>

## Test Cron Triggers using Wrangler

The recommended way of testing Cron Triggers is using Wrangler.

Cron Triggers can be tested using Wrangler by passing in the `--test-scheduled` flag to [`wrangler dev`](/workers/wrangler/commands/#dev). This will expose a `/__scheduled` (or `/cdn-cgi/handler/scheduled` for Python Workers) route which can be used to test using a HTTP request. To simulate different cron patterns, a `cron` query parameter can be passed in.

```sh
npx wrangler dev --test-scheduled

curl "http://localhost:8787/__scheduled?cron=*%2F3+*+*+*+*"

curl "http://localhost:8787/cdn-cgi/handler/scheduled?cron=*+*+*+*+*" # Python Workers
```

---

# Post JSON

URL: https://developers.cloudflare.com/workers/examples/post-json/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/post-json)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		/**
		 * Example someHost is set up to take in a JSON request
		 * Replace url with the host you wish to send requests to
		 * @param {string} url the URL to send the request to
		 * @param {BodyInit} body the JSON data to send in the request
		 */
		const someHost = "https://examples.cloudflareworkers.com/demos";
		const url = someHost + "/requests/json";
		const body = {
			results: ["default data to send"],
			errors: null,
			msg: "I sent this to the fetch",
		};

		/**
		 * gatherResponse awaits and returns a response body as a string.
		 * Use await gatherResponse(..) in an async function to get the response body
		 * @param {Response} response
		 */
		async function gatherResponse(response) {
			const { headers } = response;
			const contentType = headers.get("content-type") || "";
			if (contentType.includes("application/json")) {
				return JSON.stringify(await response.json());
			} else if (contentType.includes("application/text")) {
				return response.text();
			} else if (contentType.includes("text/html")) {
				return response.text();
			} else {
				return response.text();
			}
		}

		const init = {
			body: JSON.stringify(body),
			method: "POST",
			headers: {
				"content-type": "application/json;charset=UTF-8",
			},
		};
		const response = await fetch(url, init);
		const results = await gatherResponse(response);
		return new Response(results, init);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		/**
		 * Example someHost is set up to take in a JSON request
		 * Replace url with the host you wish to send requests to
		 * @param {string} url the URL to send the request to
		 * @param {BodyInit} body the JSON data to send in the request
		 */
		const someHost = "https://examples.cloudflareworkers.com/demos";
		const url = someHost + "/requests/json";
		const body = {
			results: ["default data to send"],
			errors: null,
			msg: "I sent this to the fetch",
		};

		/**
		 * gatherResponse awaits and returns a response body as a string.
		 * Use await gatherResponse(..) in an async function to get the response body
		 * @param {Response} response
		 */
		async function gatherResponse(response) {
			const { headers } = response;
			const contentType = headers.get("content-type") || "";
			if (contentType.includes("application/json")) {
				return JSON.stringify(await response.json());
			} else if (contentType.includes("application/text")) {
				return response.text();
			} else if (contentType.includes("text/html")) {
				return response.text();
			} else {
				return response.text();
			}
		}

		const init = {
			body: JSON.stringify(body),
			method: "POST",
			headers: {
				"content-type": "application/json;charset=UTF-8",
			},
		};
		const response = await fetch(url, init);
		const results = await gatherResponse(response);
		return new Response(results, init);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
import json
from pyodide.ffi import to_js as _to_js
from js import Object, fetch, Response, Headers

def to_js(obj):
    return _to_js(obj, dict_converter=Object.fromEntries)

# gather_response returns both content-type & response body as a string
async def gather_response(response):
    headers = response.headers
    content_type = headers["content-type"] or ""

    if "application/json" in content_type:
        return (content_type, json.dumps(dict(await response.json())))
    return (content_type, await response.text())

async def on_fetch(_request):
    url = "https://jsonplaceholder.typicode.com/todos/1"

    body = {
      "results": ["default data to send"],
      "errors": None,
      "msg": "I sent this to the fetch",
    }

    options = {
      "body": json.dumps(body),
      "method": "POST",
      "headers": {
        "content-type": "application/json;charset=UTF-8",
      },
    }

    response = await fetch(url, to_js(options))
    content_type, result = await gather_response(response)

    headers = Headers.new({"content-type": content_type}.items())
    return Response.new(result, headers=headers)
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

const app = new Hono();

app.get('*', async (c) => {
  /**
   * Example someHost is set up to take in a JSON request
   * Replace url with the host you wish to send requests to
   */
  const someHost = "https://examples.cloudflareworkers.com/demos";
  const url = someHost + "/requests/json";
  const body = {
    results: ["default data to send"],
    errors: null,
    msg: "I sent this to the fetch",
  };

  /**
   * gatherResponse awaits and returns a response body as a string.
   * Use await gatherResponse(..) in an async function to get the response body
   */
  async function gatherResponse(response: Response) {
    const { headers } = response;
    const contentType = headers.get("content-type") || "";

    if (contentType.includes("application/json")) {
      return { contentType, result: JSON.stringify(await response.json()) };
    } else if (contentType.includes("application/text")) {
      return { contentType, result: await response.text() };
    } else if (contentType.includes("text/html")) {
      return { contentType, result: await response.text() };
    } else {
      return { contentType, result: await response.text() };
    }
  }

  const init = {
    body: JSON.stringify(body),
    method: "POST",
    headers: {
      "content-type": "application/json;charset=UTF-8",
    },
  };

  const response = await fetch(url, init);
  const { contentType, result } = await gatherResponse(response);

  return new Response(result, {
    headers: {
      "content-type": contentType,
    },
  });
});

export default app;
```

</TabItem> </Tabs>

---

# Stream OpenAI API Responses

URL: https://developers.cloudflare.com/workers/examples/openai-sdk-streaming/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/openai-sdk-streaming)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

In order to run this code, you must install the OpenAI SDK by running `npm i openai`.

:::note

For analytics, caching, rate limiting, and more, you can also send requests like this through Cloudflare's [AI Gateway](/ai-gateway/providers/openai/).

:::

<Tabs syncKey="workersExamples"> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import OpenAI from "openai";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const openai = new OpenAI({
			apiKey: env.OPENAI_API_KEY,
		});

		// Create a TransformStream to handle streaming data
		let { readable, writable } = new TransformStream();
		let writer = writable.getWriter();
		const textEncoder = new TextEncoder();

		ctx.waitUntil(
			(async () => {
				const stream = await openai.chat.completions.create({
					model: "gpt-4o-mini",
					messages: [{ role: "user", content: "Tell me a story" }],
					stream: true,
				});

				// loop over the data as it is streamed and write to the writeable
				for await (const part of stream) {
					writer.write(
						textEncoder.encode(part.choices[0]?.delta?.content || ""),
					);
				}
				writer.close();
			})(),
		);

		// Send the readable back to the browser
		return new Response(readable);
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";
import { streamText } from "hono/streaming";
import OpenAI from "openai";

interface Env {
	OPENAI_API_KEY: string;
}

const app = new Hono<{ Bindings: Env }>();

app.get("*", async (c) => {
	const openai = new OpenAI({
		apiKey: c.env.OPENAI_API_KEY,
	});

	const chatStream = await openai.chat.completions.create({
		model: "gpt-4o-mini",
		messages: [{ role: "user", content: "Tell me a story" }],
		stream: true,
	});

	return streamText(c, async (stream) => {
		for await (const message of chatStream) {
			await stream.write(message.choices[0].delta.content || "");
		}
		stream.close();
	});
});

export default app;
```

</TabItem> </Tabs>

---

# Using timingSafeEqual

URL: https://developers.cloudflare.com/workers/examples/protect-against-timing-attacks/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/protect-against-timing-attacks)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

The [`crypto.subtle.timingSafeEqual`](/workers/runtime-apis/web-crypto/#timingsafeequal) function compares two values using a constant-time algorithm. The time taken is independent of the contents of the values.

When strings are compared using the equality operator (`==` or `===`), the comparison will end at the first mismatched character. By using `timingSafeEqual`, an attacker would not be able to use timing to find where at which point in the two strings there is a difference.

The `timingSafeEqual` function takes two `ArrayBuffer` or `TypedArray` values to compare. These buffers must be of equal length, otherwise an exception is thrown.
Note that this function is not constant time with respect to the length of the parameters and also does not guarantee constant time for the surrounding code.
Handling of secrets should be taken with care to not introduce timing side channels.

In order to compare two strings, you must use the [`TextEncoder`](/workers/runtime-apis/encoding/#textencoder) API.

<Tabs syncKey="workersExamples"> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Environment {
	MY_SECRET_VALUE?: string;
}

export default {
	async fetch(req: Request, env: Environment) {
		if (!env.MY_SECRET_VALUE) {
			return new Response("Missing secret binding", { status: 500 });
		}

		const authToken = req.headers.get("Authorization") || "";

		if (authToken.length !== env.MY_SECRET_VALUE.length) {
			return new Response("Unauthorized", { status: 401 });
		}

		const encoder = new TextEncoder();

		const a = encoder.encode(authToken);
		const b = encoder.encode(env.MY_SECRET_VALUE);

		if (a.byteLength !== b.byteLength) {
			return new Response("Unauthorized", { status: 401 });
		}

		if (!crypto.subtle.timingSafeEqual(a, b)) {
			return new Response("Unauthorized", { status: 401 });
		}

		return new Response("Welcome!");
	},
};
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response
from js import TextEncoder, crypto

async def on_fetch(request, env):
    auth_token = request.headers["Authorization"] or ""
    secret = env.MY_SECRET_VALUE

    if secret is None:
        return Response("Missing secret binding", status=500)

    if len(auth_token) != len(secret):
        return Response("Unauthorized", status=401)

    encoder = TextEncoder.new()
    a = encoder.encode(auth_token)
    b = encoder.encode(secret)

    if a.byteLength != b.byteLength:
        return Response("Unauthorized", status=401)

    if not crypto.subtle.timingSafeEqual(a, b):
        return Response("Unauthorized", status=401)

    return Response("Welcome!")
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

interface Environment {
  Bindings: {
    MY_SECRET_VALUE?: string;
  }
}

const app = new Hono<Environment>();

// Middleware to handle authentication with timing-safe comparison
app.use('*', async (c, next) => {
  const secret = c.env.MY_SECRET_VALUE;

  if (!secret) {
    return c.text("Missing secret binding", 500);
  }

  const authToken = c.req.header("Authorization") || "";

  // Early length check to avoid unnecessary processing
  if (authToken.length !== secret.length) {
    return c.text("Unauthorized", 401);
  }

  const encoder = new TextEncoder();

  const a = encoder.encode(authToken);
  const b = encoder.encode(secret);

  if (a.byteLength !== b.byteLength) {
    return c.text("Unauthorized", 401);
  }

  // Perform timing-safe comparison
  if (!crypto.subtle.timingSafeEqual(a, b)) {
    return c.text("Unauthorized", 401);
  }

  // If we got here, the auth token is valid
  await next();
});

// Protected route
app.get('*', (c) => {
  return c.text("Welcome!");
});

export default app;
```

</TabItem> </Tabs>

---

# Read POST

URL: https://developers.cloudflare.com/workers/examples/read-post/

import { TabItem, Tabs, Render } from "~/components";

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/read-post)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		/**
		 * rawHtmlResponse returns HTML inputted directly
		 * into the worker script
		 * @param {string} html
		 */
		function rawHtmlResponse(html) {
			return new Response(html, {
				headers: {
					"content-type": "text/html;charset=UTF-8",
				},
			});
		}

		/**
		 * readRequestBody reads in the incoming request body
		 * Use await readRequestBody(..) in an async function to get the string
		 * @param {Request} request the incoming request to read from
		 */
		async function readRequestBody(request) {
			const contentType = request.headers.get("content-type");
			if (contentType.includes("application/json")) {
				return JSON.stringify(await request.json());
			} else if (contentType.includes("application/text")) {
				return request.text();
			} else if (contentType.includes("text/html")) {
				return request.text();
			} else if (contentType.includes("form")) {
				const formData = await request.formData();
				const body = {};
				for (const entry of formData.entries()) {
					body[entry[0]] = entry[1];
				}
				return JSON.stringify(body);
			} else {
				// Perhaps some other type of data was submitted in the form
				// like an image, or some other binary data.
				return "a file";
			}
		}

		const { url } = request;
		if (url.includes("form")) {
			return rawHtmlResponse(someForm);
		}
		if (request.method === "POST") {
			const reqBody = await readRequestBody(request);
			const retBody = `The request body sent in was ${reqBody}`;
			return new Response(retBody);
		} else if (request.method === "GET") {
			return new Response("The request was a GET");
		}
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		/**
		 * rawHtmlResponse returns HTML inputted directly
		 * into the worker script
		 * @param {string} html
		 */
		function rawHtmlResponse(html) {
			return new Response(html, {
				headers: {
					"content-type": "text/html;charset=UTF-8",
				},
			});
		}

		/**
		 * readRequestBody reads in the incoming request body
		 * Use await readRequestBody(..) in an async function to get the string
		 * @param {Request} request the incoming request to read from
		 */
		async function readRequestBody(request: Request) {
			const contentType = request.headers.get("content-type");
			if (contentType.includes("application/json")) {
				return JSON.stringify(await request.json());
			} else if (contentType.includes("application/text")) {
				return request.text();
			} else if (contentType.includes("text/html")) {
				return request.text();
			} else if (contentType.includes("form")) {
				const formData = await request.formData();
				const body = {};
				for (const entry of formData.entries()) {
					body[entry[0]] = entry[1];
				}
				return JSON.stringify(body);
			} else {
				// Perhaps some other type of data was submitted in the form
				// like an image, or some other binary data.
				return "a file";
			}
		}

		const { url } = request;
		if (url.includes("form")) {
			return rawHtmlResponse(someForm);
		}
		if (request.method === "POST") {
			const reqBody = await readRequestBody(request);
			const retBody = `The request body sent in was ${reqBody}`;
			return new Response(retBody);
		} else if (request.method === "GET") {
			return new Response("The request was a GET");
		}
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py

from js import Object, Response, Headers, JSON

async def read_request_body(request):
    headers = request.headers
    content_type = headers["content-type"] or ""

    if "application/json" in content_type:
        return JSON.stringify(await request.json())
    if "form" in content_type:
        form = await request.formData()
        data = Object.fromEntries(form.entries())
        return JSON.stringify(data)
    return await request.text()

async def on_fetch(request):
    def raw_html_response(html):
        headers = Headers.new({"content-type": "text/html;charset=UTF-8"}.items())
        return Response.new(html, headers=headers)

    if "form" in request.url:
        return raw_html_response("")

    if "POST" in request.method:
        req_body = await read_request_body(request)
        ret_body = f"The request body sent in was {req_body}"
        return Response.new(ret_body)

    return Response.new("The request was not POST")
```

</TabItem> <TabItem label="Rust" icon="seti:rust">

```rs
use serde::{Deserialize, Serialize};
use worker::*;

fn raw_html_response(html: &str) -> Result<Response> {
    Response::from_html(html)
}

#[derive(Deserialize, Serialize, Debug)]
struct Payload {
    msg: String,
}

async fn read_request_body(mut req: Request) -> String {
    let ctype = req.headers().get("content-type").unwrap().unwrap();
    match ctype.as_str() {
        "application/json" => format!("{:?}", req.json::<Payload>().await.unwrap()),
        "text/html" => req.text().await.unwrap(),
        "multipart/form-data" => format!("{:?}", req.form_data().await.unwrap()),
        _ => String::from("a file"),
    }
}

#[event(fetch)]
async fn fetch(req: Request, _env: Env, _ctx: Context) -> Result<Response> {
    if String::from(req.url()?).contains("form") {
        return raw_html_response("some html form");
    }

    match req.method() {
        Method::Post => {
            let req_body = read_request_body(req).await;
            Response::ok(format!("The request body sent in was {}", req_body))
        }
        _ => Response::ok(format!("The result was a {:?}", req.method())),
    }
}
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";
import { html } from "hono/html";

const app = new Hono();

/**
 * readRequestBody reads in the incoming request body
 * @param {Request} request the incoming request to read from
 */
async function readRequestBody(request: Request): Promise<string> {
	const contentType = request.headers.get("content-type") || "";

	if (contentType.includes("application/json")) {
		const body = await request.json();
		return JSON.stringify(body);
	} else if (contentType.includes("application/text")) {
		return request.text();
	} else if (contentType.includes("text/html")) {
		return request.text();
	} else if (contentType.includes("form")) {
		const formData = await request.formData();
		const body: Record<string, string> = {};
		for (const [key, value] of formData.entries()) {
			body[key] = value.toString();
		}
		return JSON.stringify(body);
	} else {
		// Perhaps some other type of data was submitted in the form
		// like an image, or some other binary data.
		return "a file";
	}
}

const someForm = html`<!DOCTYPE html>
	<html>
		<body>
			<form action="/" method="post">
				<div>
					<label for="message">Message:</label>
					<input id="message" name="message" type="text" />
				</div>
				<div>
					<button>Submit</button>
				</div>
			</form>
		</body>
	</html>`;

app.get("*", async (c) => {
	const url = c.req.url;

	if (url.includes("form")) {
		return c.html(someForm);
	}

	return c.text("The request was a GET");
});

app.post("*", async (c) => {
	const reqBody = await readRequestBody(c.req.raw);
	const retBody = `The request body sent in was ${reqBody}`;
	return c.text(retBody);
});

export default app;
```

</TabItem> </Tabs>

<Render file="request-dot-clone-warning" product="workers" />

---

# Redirect

URL: https://developers.cloudflare.com/workers/examples/redirect/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/redirect)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { Render, TabItem, Tabs } from "~/components";

## Redirect all requests to one URL

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

<Render file="redirect-example-js" />

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const destinationURL = "https://example.com";
		const statusCode = 301;
		return Response.redirect(destinationURL, statusCode);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response

def on_fetch(request):
    destinationURL = "https://example.com"
    statusCode = 301
    return Response.redirect(destinationURL, statusCode)
```

</TabItem> <TabItem label="Rust" icon="seti:rust">

```rs
use worker::*;

#[event(fetch)]
async fn fetch(_req: Request, _env: Env, _ctx: Context) -> Result<Response> {
    let destination_url = Url::parse("https://example.com")?;
    let status_code = 301;
    Response::redirect_with_status(destination_url, status_code)
}

```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

const app = new Hono();

app.all('*', (c) => {
  const destinationURL = "https://example.com";
  const statusCode = 301;
  return c.redirect(destinationURL, statusCode);
});

export default app;
```

</TabItem> </Tabs>

## Redirect requests from one domain to another

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		const base = "https://example.com";
		const statusCode = 301;

		const url = new URL(request.url);
		const { pathname, search } = url;

		const destinationURL = `${base}${pathname}${search}`;
		console.log(destinationURL);

		return Response.redirect(destinationURL, statusCode);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const base = "https://example.com";
		const statusCode = 301;

		const url = new URL(request.url);
		const { pathname, search } = url;

		const destinationURL = `${base}${pathname}${search}`;
		console.log(destinationURL);

		return Response.redirect(destinationURL, statusCode);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response
from urllib.parse import urlparse

async def on_fetch(request):
    base = "https://example.com"
    statusCode = 301

    url = urlparse(request.url)

    destinationURL = f'{base}{url.path}{url.query}'
    print(destinationURL)

    return Response.redirect(destinationURL, statusCode)
```

</TabItem> <TabItem label="Rust" icon="seti:rust">

```rs
use worker::*;

#[event(fetch)]
async fn fetch(req: Request, _env: Env, _ctx: Context) -> Result<Response> {
    let mut base = Url::parse("https://example.com")?;
    let status_code = 301;

    let url = req.url()?;

    base.set_path(url.path());
    base.set_query(url.query());

    console_log!("{:?}", base.to_string());

    Response::redirect_with_status(base, status_code)
}

```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

const app = new Hono();

app.all('*', (c) => {
  const base = "https://example.com";
  const statusCode = 301;

  const { pathname, search } = new URL(c.req.url);

  const destinationURL = `${base}${pathname}${search}`;
  console.log(destinationURL);

  return c.redirect(destinationURL, statusCode);
});

export default app;
```

</TabItem> </Tabs>

---

# Respond with another site

URL: https://developers.cloudflare.com/workers/examples/respond-with-another-site/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/respond-with-another-site)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { Render, TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

<Render file="respond-another-site-example-js" />

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		async function MethodNotAllowed(request) {
			return new Response(`Method ${request.method} not allowed.`, {
				status: 405,
				headers: {
					Allow: "GET",
				},
			});
		}
		// Only GET requests work with this proxy.
		if (request.method !== "GET") return MethodNotAllowed(request);
		return fetch(`https://example.com`);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch

def on_fetch(request):
    def method_not_allowed(request):
        msg = f'Method {request.method} not allowed.'
        headers = {"Allow": "GET"}
        return Response(msg, headers=headers, status=405)

    # Only GET requests work with this proxy.
    if request.method != "GET":
        return method_not_allowed(request)

    return fetch("https://example.com")
```

</TabItem></Tabs>

---

# Return small HTML page

URL: https://developers.cloudflare.com/workers/examples/return-html/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/return-html)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { Render, TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

<Render file="return-html-example-js" />

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const html = `<!DOCTYPE html>
		<body>
		  <h1>Hello World</h1>
		  <p>This markup was generated by a Cloudflare Worker.</p>
		</body>`;

		return new Response(html, {
			headers: {
				"content-type": "text/html;charset=UTF-8",
			},
		});
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response

def on_fetch(request):
    html = """<!DOCTYPE html>
    <body>
      <h1>Hello World</h1>
      <p>This markup was generated by a Cloudflare Worker.</p>
    </body>"""

    headers = {"content-type": "text/html;charset=UTF-8"}
    return Response(html, headers=headers)
```

</TabItem> <TabItem label="Rust" icon="seti:rust">

```rs
use worker::*;

#[event(fetch)]
async fn fetch(_req: Request, _env: Env, _ctx: Context) -> Result<Response> {
    let html = r#"<!DOCTYPE html>
		<body>
		  <h1>Hello World</h1>
		  <p>This markup was generated by a Cloudflare Worker.</p>
		</body>
    "#;
    Response::from_html(html)
}
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";
import { html } from "hono/html";

const app = new Hono();

app.get("*", (c) => {
	const doc = html`<!DOCTYPE html>
		<body>
			<h1>Hello World</h1>
			<p>This markup was generated by a Cloudflare Worker with Hono.</p>
		</body>`;

	return c.html(doc);
});

export default app;
```

</TabItem>

</Tabs>

---

# Return JSON

URL: https://developers.cloudflare.com/workers/examples/return-json/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/return-json)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { Render, TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

<Render file="return-json-example-js" />

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const data = {
			hello: "world",
		};

		return Response.json(data);
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response
import json

def on_fetch(request):
    data = json.dumps({"hello": "world"})
    headers = {"content-type": "application/json"}
    return Response(data, headers=headers)
```

</TabItem> <TabItem label="Rust" icon="seti:rust">

```rs
use serde::{Deserialize, Serialize};
use worker::*;

#[derive(Deserialize, Serialize, Debug)]
struct Json {
    hello: String,
}

#[event(fetch)]
async fn fetch(_req: Request, _env: Env, _ctx: Context) -> Result<Response> {
    let data = Json {
        hello: String::from("world"),
    };
    Response::from_json(&data)
}
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';

const app = new Hono();

app.get('*', (c) => {
  const data = {
    hello: "world",
  };

  return c.json(data);
});

export default app;
```

</TabItem> </Tabs>

---

# Rewrite links

URL: https://developers.cloudflare.com/workers/examples/rewrite-links/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/rewrite-links)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		const OLD_URL = "developer.mozilla.org";
		const NEW_URL = "mynewdomain.com";

		class AttributeRewriter {
			constructor(attributeName) {
				this.attributeName = attributeName;
			}
			element(element) {
				const attribute = element.getAttribute(this.attributeName);
				if (attribute) {
					element.setAttribute(
						this.attributeName,
						attribute.replace(OLD_URL, NEW_URL),
					);
				}
			}
		}

		const rewriter = new HTMLRewriter()
			.on("a", new AttributeRewriter("href"))
			.on("img", new AttributeRewriter("src"));

		const res = await fetch(request);
		const contentType = res.headers.get("Content-Type");

		// If the response is HTML, it can be transformed with
		// HTMLRewriter -- otherwise, it should pass through
		if (contentType.startsWith("text/html")) {
			return rewriter.transform(res);
		} else {
			return res;
		}
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const OLD_URL = "developer.mozilla.org";
		const NEW_URL = "mynewdomain.com";

		class AttributeRewriter {
			constructor(attributeName) {
				this.attributeName = attributeName;
			}
			element(element) {
				const attribute = element.getAttribute(this.attributeName);
				if (attribute) {
					element.setAttribute(
						this.attributeName,
						attribute.replace(OLD_URL, NEW_URL),
					);
				}
			}
		}

		const rewriter = new HTMLRewriter()
			.on("a", new AttributeRewriter("href"))
			.on("img", new AttributeRewriter("src"));

		const res = await fetch(request);
		const contentType = res.headers.get("Content-Type");

		// If the response is HTML, it can be transformed with
		// HTMLRewriter -- otherwise, it should pass through
		if (contentType.startsWith("text/html")) {
			return rewriter.transform(res);
		} else {
			return res;
		}
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from pyodide.ffi import create_proxy
from js import HTMLRewriter, fetch

async def on_fetch(request):
    old_url = "developer.mozilla.org"
    new_url = "mynewdomain.com"

    class AttributeRewriter:
        def __init__(self, attr_name):
            self.attr_name = attr_name
        def element(self, element):
            attr = element.getAttribute(self.attr_name)
            if attr:
                element.setAttribute(self.attr_name, attr.replace(old_url, new_url))

    href = create_proxy(AttributeRewriter("href"))
    src = create_proxy(AttributeRewriter("src"))
    rewriter = HTMLRewriter.new().on("a", href).on("img", src)
    res = await fetch(request)
    content_type = res.headers["Content-Type"]

    # If the response is HTML, it can be transformed with
    # HTMLRewriter -- otherwise, it should pass through
    if content_type.startswith("text/html"):
        return rewriter.transform(res)
    return res
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';
import { html } from 'hono/html';

const app = new Hono();

app.get('*', async (c) => {
  const OLD_URL = "developer.mozilla.org";
  const NEW_URL = "mynewdomain.com";

  class AttributeRewriter {
    attributeName: string;

    constructor(attributeName: string) {
      this.attributeName = attributeName;
    }

    element(element: Element) {
      const attribute = element.getAttribute(this.attributeName);
      if (attribute) {
        element.setAttribute(
          this.attributeName,
          attribute.replace(OLD_URL, NEW_URL)
        );
      }
    }
  }

  // Make a fetch request using the original request
  const res = await fetch(c.req.raw);
  const contentType = res.headers.get("Content-Type") || "";

  // If the response is HTML, transform it with HTMLRewriter
  if (contentType.startsWith("text/html")) {
    const rewriter = new HTMLRewriter()
      .on("a", new AttributeRewriter("href"))
      .on("img", new AttributeRewriter("src"));

    return new Response(rewriter.transform(res).body, {
      headers: res.headers
    });
  } else {
    // Pass through the response as is
    return res;
  }
});

export default app;
```

</TabItem> </Tabs>

---

# Sign requests

URL: https://developers.cloudflare.com/workers/examples/signing-requests/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/signing-requests)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

:::note

This example Worker makes use of the [Node.js Buffer API](/workers/runtime-apis/nodejs/buffer/), which is available as part of the Worker's runtime [Node.js compatibility mode](/workers/runtime-apis/nodejs/). To run this Worker, you will need to [enable the `nodejs_compat` compatibility flag](/workers/runtime-apis/nodejs/#get-started).
:::

You can both verify and generate signed requests from within a Worker using the [Web Crypto APIs](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/subtle).

The following Worker will:

- For request URLs beginning with `/generate/`, replace `/generate/` with `/`, sign the resulting path with its timestamp, and return the full, signed URL in the response body.

- For all other request URLs, verify the signed URL and allow the request through.

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { Buffer } from "node:buffer";

const encoder = new TextEncoder();

// How long an HMAC token should be valid for, in seconds
const EXPIRY = 60;

export default {
	/**
	 *
	 * @param {Request} request
	 * @param {{SECRET_DATA: string}} env
	 * @returns
	 */
	async fetch(request, env) {
		// You will need some secret data to use as a symmetric key. This should be
		// attached to your Worker as an encrypted secret.
		// Refer to https://developers.cloudflare.com/workers/configuration/secrets/
		const secretKeyData = encoder.encode(
			env.SECRET_DATA ?? "my secret symmetric key",
		);

		// Import your secret as a CryptoKey for both 'sign' and 'verify' operations
		const key = await crypto.subtle.importKey(
			"raw",
			secretKeyData,
			{ name: "HMAC", hash: "SHA-256" },
			false,
			["sign", "verify"],
		);

		const url = new URL(request.url);

		// This is a demonstration Worker that allows unauthenticated access to /generate
		// In a real application you would want to make sure that
		// users could only generate signed URLs when authenticated
		if (url.pathname.startsWith("/generate/")) {
			url.pathname = url.pathname.replace("/generate/", "/");

			const timestamp = Math.floor(Date.now() / 1000);

			// This contains all the data about the request that you want to be able to verify
			// Here we only sign the timestamp and the pathname, but often you will want to
			// include more data (for instance, the URL hostname or query parameters)
			const dataToAuthenticate = `${url.pathname}${timestamp}`;

			const mac = await crypto.subtle.sign(
				"HMAC",
				key,
				encoder.encode(dataToAuthenticate),
			);

			// Refer to https://developers.cloudflare.com/workers/runtime-apis/nodejs/
			// for more details on using Node.js APIs in Workers
			const base64Mac = Buffer.from(mac).toString("base64");

			url.searchParams.set("verify", `${timestamp}-${base64Mac}`);

			return new Response(`${url.pathname}${url.search}`);
			// Verify all non /generate requests
		} else {
			// Make sure you have the minimum necessary query parameters.
			if (!url.searchParams.has("verify")) {
				return new Response("Missing query parameter", { status: 403 });
			}

			const [timestamp, hmac] = url.searchParams.get("verify").split("-");

			const assertedTimestamp = Number(timestamp);

			const dataToAuthenticate = `${url.pathname}${assertedTimestamp}`;

			const receivedMac = Buffer.from(hmac, "base64");

			// Use crypto.subtle.verify() to guard against timing attacks. Since HMACs use
			// symmetric keys, you could implement this by calling crypto.subtle.sign() and
			// then doing a string comparison -- this is insecure, as string comparisons
			// bail out on the first mismatch, which leaks information to potential
			// attackers.
			const verified = await crypto.subtle.verify(
				"HMAC",
				key,
				receivedMac,
				encoder.encode(dataToAuthenticate),
			);

			if (!verified) {
				return new Response("Invalid MAC", { status: 403 });
			}

			// Signed requests expire after one minute. Note that this value should depend on your specific use case
			if (Date.now() / 1000 > assertedTimestamp + EXPIRY) {
				return new Response(
					`URL expired at ${new Date((assertedTimestamp + EXPIRY) * 1000)}`,
					{ status: 403 },
				);
			}
		}

		return fetch(new URL(url.pathname, "https://example.com"), request);
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { Buffer } from "node:buffer";

const encoder = new TextEncoder();

// How long an HMAC token should be valid for, in seconds
const EXPIRY = 60;

interface Env {
	SECRET_DATA: string;
}
export default {
	async fetch(request, env): Promise<Response> {
		// You will need some secret data to use as a symmetric key. This should be
		// attached to your Worker as an encrypted secret.
		// Refer to https://developers.cloudflare.com/workers/configuration/secrets/
		const secretKeyData = encoder.encode(
			env.SECRET_DATA ?? "my secret symmetric key",
		);

		// Import your secret as a CryptoKey for both 'sign' and 'verify' operations
		const key = await crypto.subtle.importKey(
			"raw",
			secretKeyData,
			{ name: "HMAC", hash: "SHA-256" },
			false,
			["sign", "verify"],
		);

		const url = new URL(request.url);

		// This is a demonstration Worker that allows unauthenticated access to /generate
		// In a real application you would want to make sure that
		// users could only generate signed URLs when authenticated
		if (url.pathname.startsWith("/generate/")) {
			url.pathname = url.pathname.replace("/generate/", "/");

			const timestamp = Math.floor(Date.now() / 1000);

			// This contains all the data about the request that you want to be able to verify
			// Here we only sign the timestamp and the pathname, but often you will want to
			// include more data (for instance, the URL hostname or query parameters)
			const dataToAuthenticate = `${url.pathname}${timestamp}`;

			const mac = await crypto.subtle.sign(
				"HMAC",
				key,
				encoder.encode(dataToAuthenticate),
			);

			// Refer to https://developers.cloudflare.com/workers/runtime-apis/nodejs/
			// for more details on using NodeJS APIs in Workers
			const base64Mac = Buffer.from(mac).toString("base64");

			url.searchParams.set("verify", `${timestamp}-${base64Mac}`);

			return new Response(`${url.pathname}${url.search}`);
			// Verify all non /generate requests
		} else {
			// Make sure you have the minimum necessary query parameters.
			if (!url.searchParams.has("verify")) {
				return new Response("Missing query parameter", { status: 403 });
			}

			const [timestamp, hmac] = url.searchParams.get("verify").split("-");

			const assertedTimestamp = Number(timestamp);

			const dataToAuthenticate = `${url.pathname}${assertedTimestamp}`;

			const receivedMac = Buffer.from(hmac, "base64");

			// Use crypto.subtle.verify() to guard against timing attacks. Since HMACs use
			// symmetric keys, you could implement this by calling crypto.subtle.sign() and
			// then doing a string comparison -- this is insecure, as string comparisons
			// bail out on the first mismatch, which leaks information to potential
			// attackers.
			const verified = await crypto.subtle.verify(
				"HMAC",
				key,
				receivedMac,
				encoder.encode(dataToAuthenticate),
			);

			if (!verified) {
				return new Response("Invalid MAC", { status: 403 });
			}

			// Signed requests expire after one minute. Note that this value should depend on your specific use case
			if (Date.now() / 1000 > assertedTimestamp + EXPIRY) {
				return new Response(
					`URL expired at ${new Date((assertedTimestamp + EXPIRY) * 1000)}`,
					{ status: 403 },
				);
			}
		}

		return fetch(new URL(url.pathname, "https://example.com"), request);
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Buffer } from "node:buffer";
import { Hono } from "hono";
import { proxy } from "hono/proxy";

const encoder = new TextEncoder();

// How long an HMAC token should be valid for, in seconds
const EXPIRY = 60;

interface Env {
	SECRET_DATA: string;
}

const app = new Hono();

// Handle URL generation requests
app.get("/generate/*", async (c) => {
	const env = c.env;

	// You will need some secret data to use as a symmetric key
	const secretKeyData = encoder.encode(
		env.SECRET_DATA ?? "my secret symmetric key",
	);

	// Import the secret as a CryptoKey for both 'sign' and 'verify' operations
	const key = await crypto.subtle.importKey(
		"raw",
		secretKeyData,
		{ name: "HMAC", hash: "SHA-256" },
		false,
		["sign", "verify"],
	);

	// Replace "/generate/" prefix with "/"
	let pathname = c.req.path.replace("/generate/", "/");

	const timestamp = Math.floor(Date.now() / 1000);

	// Data to authenticate: pathname + timestamp
	const dataToAuthenticate = `${pathname}${timestamp}`;

	// Sign the data
	const mac = await crypto.subtle.sign(
		"HMAC",
		key,
		encoder.encode(dataToAuthenticate),
	);

	// Convert the signature to base64
	const base64Mac = Buffer.from(mac).toString("base64");

	// Add verification parameter to URL
	url.searchParams.set("verify", `${timestamp}-${base64Mac}`);

	return c.text(`${pathname}${url.search}`);
});

// Handle verification for all other requests
app.all("*", async (c) => {
	const env = c.env;
	const url = c.req.url;

	// You will need some secret data to use as a symmetric key
	const secretKeyData = encoder.encode(
		env.SECRET_DATA ?? "my secret symmetric key",
	);

	// Import the secret as a CryptoKey for both 'sign' and 'verify' operations
	const key = await crypto.subtle.importKey(
		"raw",
		secretKeyData,
		{ name: "HMAC", hash: "SHA-256" },
		false,
		["sign", "verify"],
	);

	// Make sure the request has the verification parameter
	if (!c.req.query("verify")) {
		return c.text("Missing query parameter", 403);
	}

	// Extract timestamp and signature
	const [timestamp, hmac] = c.req.query("verify")!.split("-");
	const assertedTimestamp = Number(timestamp);

	// Recreate the data that should have been signed
	const dataToAuthenticate = `${c.req.path}${assertedTimestamp}`;

	// Convert base64 signature back to ArrayBuffer
	const receivedMac = Buffer.from(hmac, "base64");

	// Verify the signature
	const verified = await crypto.subtle.verify(
		"HMAC",
		key,
		receivedMac,
		encoder.encode(dataToAuthenticate),
	);

	// If verification fails, return 403
	if (!verified) {
		return c.text("Invalid MAC", 403);
	}

	// Check if the signature has expired
	if (Date.now() / 1000 > assertedTimestamp + EXPIRY) {
		return c.text(
			`URL expired at ${new Date((assertedTimestamp + EXPIRY) * 1000)}`,
			403,
		);
	}

	// If verification passes, proxy the request to example.com
	return proxy(`https://example.com/${c.req.path}`, ...c.req);
});

export default app;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from pyodide.ffi import to_js as _to_js
from js import Response, URL, TextEncoder, Buffer, fetch, Object, crypto

def to_js(x):
    return _to_js(x, dict_converter=Object.fromEntries)

encoder = TextEncoder.new()

# How long an HMAC token should be valid for, in seconds
EXPIRY = 60

async def on_fetch(request, env):
    # Get the secret key
    secret_key_data = encoder.encode(env.SECRET_DATA if hasattr(env, "SECRET_DATA") else "my secret symmetric key")

    # Import the secret as a CryptoKey for both 'sign' and 'verify' operations
    key = await crypto.subtle.importKey(
        "raw",
        secret_key_data,
        to_js({"name": "HMAC", "hash": "SHA-256"}),
        False,
        ["sign", "verify"]
    )

    url = URL.new(request.url)

    if url.pathname.startswith("/generate/"):
        url.pathname = url.pathname.replace("/generate/", "/", 1)

        timestamp = int(Date.now() / 1000)

        # Data to authenticate
        data_to_authenticate = f"{url.pathname}{timestamp}"

        # Sign the data
        mac = await crypto.subtle.sign(
            "HMAC",
            key,
            encoder.encode(data_to_authenticate)
        )

        # Convert to base64
        base64_mac = Buffer.from(mac).toString("base64")

        # Set the verification parameter
        url.searchParams.set("verify", f"{timestamp}-{base64_mac}")

        return Response.new(f"{url.pathname}{url.search}")
    else:
        # Verify the request
        if not "verify" in url.searchParams:
            return Response.new("Missing query parameter", status=403)

        verify_param = url.searchParams.get("verify")
        timestamp, hmac = verify_param.split("-")

        asserted_timestamp = int(timestamp)

        data_to_authenticate = f"{url.pathname}{asserted_timestamp}"

        received_mac = Buffer.from(hmac, "base64")

        # Verify the signature
        verified = await crypto.subtle.verify(
            "HMAC",
            key,
            received_mac,
            encoder.encode(data_to_authenticate)
        )

        if not verified:
            return Response.new("Invalid MAC", status=403)

        # Check expiration
        if Date.now() / 1000 > asserted_timestamp + EXPIRY:
            expiry_date = Date.new((asserted_timestamp + EXPIRY) * 1000)
            return Response.new(f"URL expired at {expiry_date}", status=403)

    # Proxy to example.com if verification passes
    return fetch(URL.new(f"https://example.com{url.pathname}"), request)
```

</TabItem> </Tabs>

## Validate signed requests using the WAF

The provided example code for signing requests is compatible with the [`is_timed_hmac_valid_v0()`](/ruleset-engine/rules-language/functions/#hmac-validation) Rules language function. This means that you can verify requests signed by the Worker script using a [WAF custom rule](/waf/custom-rules/use-cases/configure-token-authentication/#option-2-configure-using-waf-custom-rules).

---

# Set security headers

URL: https://developers.cloudflare.com/workers/examples/security-headers/

If you want to get started quickly, click on the button below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/main/workers/security-headers)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

import { TabItem, Tabs } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request) {
		const DEFAULT_SECURITY_HEADERS = {
			/*
    Secure your application with Content-Security-Policy headers.
    Enabling these headers will permit content from a trusted domain and all its subdomains.
    @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy
    "Content-Security-Policy": "default-src 'self' example.com *.example.com",
    */
			/*
    You can also set Strict-Transport-Security headers.
    These are not automatically set because your website might get added to Chrome's HSTS preload list.
    Here's the code if you want to apply it:
    "Strict-Transport-Security" : "max-age=63072000; includeSubDomains; preload",
    */
			/*
    Permissions-Policy header provides the ability to allow or deny the use of browser features, such as opting out of FLoC - which you can use below:
    "Permissions-Policy": "interest-cohort=()",
    */
			/*
    X-XSS-Protection header prevents a page from loading if an XSS attack is detected.
    @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-XSS-Protection
    */
			"X-XSS-Protection": "0",
			/*
    X-Frame-Options header prevents click-jacking attacks.
    @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options
    */
			"X-Frame-Options": "DENY",
			/*
    X-Content-Type-Options header prevents MIME-sniffing.
    @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Content-Type-Options
    */
			"X-Content-Type-Options": "nosniff",
			"Referrer-Policy": "strict-origin-when-cross-origin",
			"Cross-Origin-Embedder-Policy": 'require-corp; report-to="default";',
			"Cross-Origin-Opener-Policy": 'same-site; report-to="default";',
			"Cross-Origin-Resource-Policy": "same-site",
		};
		const BLOCKED_HEADERS = [
			"Public-Key-Pins",
			"X-Powered-By",
			"X-AspNet-Version",
		];

		let response = await fetch(request);
		let newHeaders = new Headers(response.headers);

		const tlsVersion = request.cf.tlsVersion;
		console.log(tlsVersion);
		// This sets the headers for HTML responses:
		if (
			newHeaders.has("Content-Type") &&
			!newHeaders.get("Content-Type").includes("text/html")
		) {
			return new Response(response.body, {
				status: response.status,
				statusText: response.statusText,
				headers: newHeaders,
			});
		}

		Object.keys(DEFAULT_SECURITY_HEADERS).map((name) => {
			newHeaders.set(name, DEFAULT_SECURITY_HEADERS[name]);
		});

		BLOCKED_HEADERS.forEach((name) => {
			newHeaders.delete(name);
		});

		if (tlsVersion !== "TLSv1.2" && tlsVersion !== "TLSv1.3") {
			return new Response("You need to use TLS version 1.2 or higher.", {
				status: 400,
			});
		} else {
			return new Response(response.body, {
				status: response.status,
				statusText: response.statusText,
				headers: newHeaders,
			});
		}
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request): Promise<Response> {
		const DEFAULT_SECURITY_HEADERS = {
			/*
    Secure your application with Content-Security-Policy headers.
    Enabling these headers will permit content from a trusted domain and all its subdomains.
    @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy
    "Content-Security-Policy": "default-src 'self' example.com *.example.com",
    */
			/*
    You can also set Strict-Transport-Security headers.
    These are not automatically set because your website might get added to Chrome's HSTS preload list.
    Here's the code if you want to apply it:
    "Strict-Transport-Security" : "max-age=63072000; includeSubDomains; preload",
    */
			/*
    Permissions-Policy header provides the ability to allow or deny the use of browser features, such as opting out of FLoC - which you can use below:
    "Permissions-Policy": "interest-cohort=()",
    */
			/*
    X-XSS-Protection header prevents a page from loading if an XSS attack is detected.
    @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-XSS-Protection
    */
			"X-XSS-Protection": "0",
			/*
    X-Frame-Options header prevents click-jacking attacks.
    @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options
    */
			"X-Frame-Options": "DENY",
			/*
    X-Content-Type-Options header prevents MIME-sniffing.
    @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Content-Type-Options
    */
			"X-Content-Type-Options": "nosniff",
			"Referrer-Policy": "strict-origin-when-cross-origin",
			"Cross-Origin-Embedder-Policy": 'require-corp; report-to="default";',
			"Cross-Origin-Opener-Policy": 'same-site; report-to="default";',
			"Cross-Origin-Resource-Policy": "same-site",
		};
		const BLOCKED_HEADERS = [
			"Public-Key-Pins",
			"X-Powered-By",
			"X-AspNet-Version",
		];

		let response = await fetch(request);
		let newHeaders = new Headers(response.headers);

		const tlsVersion = request.cf.tlsVersion;
		console.log(tlsVersion);
		// This sets the headers for HTML responses:
		if (
			newHeaders.has("Content-Type") &&
			!newHeaders.get("Content-Type").includes("text/html")
		) {
			return new Response(response.body, {
				status: response.status,
				statusText: response.statusText,
				headers: newHeaders,
			});
		}

		Object.keys(DEFAULT_SECURITY_HEADERS).map((name) => {
			newHeaders.set(name, DEFAULT_SECURITY_HEADERS[name]);
		});

		BLOCKED_HEADERS.forEach((name) => {
			newHeaders.delete(name);
		});

		if (tlsVersion !== "TLSv1.2" && tlsVersion !== "TLSv1.3") {
			return new Response("You need to use TLS version 1.2 or higher.", {
				status: 400,
			});
		} else {
			return new Response(response.body, {
				status: response.status,
				statusText: response.statusText,
				headers: newHeaders,
			});
		}
	},
} satisfies ExportedHandler;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from workers import Response, fetch

async def on_fetch(request):
    default_security_headers = {
        # Secure your application with Content-Security-Policy headers.
        #Enabling these headers will permit content from a trusted domain and all its subdomains.
        #@see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy
        "Content-Security-Policy": "default-src 'self' example.com *.example.com",
        #You can also set Strict-Transport-Security headers.
        #These are not automatically set because your website might get added to Chrome's HSTS preload list.
        #Here's the code if you want to apply it:
        "Strict-Transport-Security" : "max-age=63072000; includeSubDomains; preload",
        #Permissions-Policy header provides the ability to allow or deny the use of browser features, such as opting out of FLoC - which you can use below:
        "Permissions-Policy": "interest-cohort=()",
        #X-XSS-Protection header prevents a page from loading if an XSS attack is detected.
        #@see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-XSS-Protection
        "X-XSS-Protection": "0",
        #X-Frame-Options header prevents click-jacking attacks.
        #@see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options
        "X-Frame-Options": "DENY",
        #X-Content-Type-Options header prevents MIME-sniffing.
        #@see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Content-Type-Options
        "X-Content-Type-Options": "nosniff",
        "Referrer-Policy": "strict-origin-when-cross-origin",
        "Cross-Origin-Embedder-Policy": 'require-corp; report-to="default";',
        "Cross-Origin-Opener-Policy": 'same-site; report-to="default";',
        "Cross-Origin-Resource-Policy": "same-site",
    }
    blocked_headers = ["Public-Key-Pins", "X-Powered-By" ,"X-AspNet-Version"]

    res = await fetch(request)
    new_headers = res.headers

    # This sets the headers for HTML responses
    if "text/html" in new_headers["Content-Type"]:
        return Response(res.body, status=res.status, statusText=res.statusText, headers=new_headers)

    for name in default_security_headers:
        new_headers[name] = default_security_headers[name]

    for name in blocked_headers:
        del new_headers["name"]

    tls = request.cf.tlsVersion

    if not tls in ("TLSv1.2", "TLSv1.3"):
        return Response("You need to use TLS version 1.2 or higher.", status=400)
    return Response(res.body, status=res.status, statusText=res.statusText, headers=new_headers)
```

</TabItem> <TabItem label="Rust" icon="seti:rust">
```rs
use std::collections::HashMap;
use worker::*;

#[event(fetch)]
async fn fetch(req: Request, _env: Env, _ctx: Context) -> Result<Response> {
    let default_security_headers = HashMap::from([
        //Secure your application with Content-Security-Policy headers.
        //Enabling these headers will permit content from a trusted domain and all its subdomains.
        //@see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy
        (
            "Content-Security-Policy",
            "default-src 'self' example.com *.example.com",
        ),
        //You can also set Strict-Transport-Security headers.
        //These are not automatically set because your website might get added to Chrome's HSTS preload list.
        //Here's the code if you want to apply it:
        (
            "Strict-Transport-Security",
            "max-age=63072000; includeSubDomains; preload",
        ),
        //Permissions-Policy header provides the ability to allow or deny the use of browser features, such as opting out of FLoC - which you can use below:
        ("Permissions-Policy", "interest-cohort=()"),
        //X-XSS-Protection header prevents a page from loading if an XSS attack is detected.
        //@see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-XSS-Protection
        ("X-XSS-Protection", "0"),
        //X-Frame-Options header prevents click-jacking attacks.
        //@see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Frame-Options
        ("X-Frame-Options", "DENY"),
        //X-Content-Type-Options header prevents MIME-sniffing.
        //@see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Content-Type-Options
        ("X-Content-Type-Options", "nosniff"),
        ("Referrer-Policy", "strict-origin-when-cross-origin"),
        (
            "Cross-Origin-Embedder-Policy",
            "require-corp; report-to='default';",
        ),
        (
            "Cross-Origin-Opener-Policy",
            "same-site; report-to='default';",
        ),
        ("Cross-Origin-Resource-Policy", "same-site"),
    ]);
    let blocked_headers = ["Public-Key-Pins", "X-Powered-By", "X-AspNet-Version"];
    let tls = req.cf().unwrap().tls_version();
    let res = Fetch::Request(req).send().await?;
    let mut new_headers = res.headers().clone();

    // This sets the headers for HTML responses
    if Some(String::from("text/html")) == new_headers.get("Content-Type")? {
        return Ok(Response::from_body(res.body().clone())?
            .with_headers(new_headers)
            .with_status(res.status_code()));
    }
    for (k, v) in default_security_headers {
        new_headers.set(k, v)?;
    }

    for k in blocked_headers {
        new_headers.delete(k)?;
    }

    if !vec!["TLSv1.2", "TLSv1.3"].contains(&tls.as_str()) {
        return Response::error("You need to use TLS version 1.2 or higher.", 400);
    }
    Ok(Response::from_body(res.body().clone())?
        .with_headers(new_headers)
        .with_status(res.status_code()))

}

````
</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono';
import { secureHeaders } from 'hono/secure-headers';

const app = new Hono();
app.use(secureHeaders());

// Handle all other requests by passing through to origin
app.all('*', async (c) => {
  return fetch(c.req.raw);
});

export default app;
````

</TabItem> </Tabs>

---

# Turnstile with Workers

URL: https://developers.cloudflare.com/workers/examples/turnstile-html-rewriter/

import { TabItem, Tabs, Render } from "~/components";

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request, env) {
		const SITE_KEY = env.SITE_KEY; // The Turnstile Sitekey of your widget (pass as env or secret)
		const TURNSTILE_ATTR_NAME = "your_id_to_replace"; // The id of the element to put a Turnstile widget in
		let res = await fetch(request);

		// Instantiate the API to run on specific elements, for example, `head`, `div`
		let newRes = new HTMLRewriter()

			// `.on` attaches the element handler and this allows you to match on element/attributes or to use the specific methods per the API
			.on("head", {
				element(element) {
					// In this case, you are using `append` to add a new script to the `head` element
					element.append(
						`<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>`,
						{ html: true },
					);
				},
			})
			.on("div", {
				element(element) {
					// Add a turnstile widget element into if an element with the id of TURNSTILE_ATTR_NAME is found
					if (element.getAttribute("id") === TURNSTILE_ATTR_NAME) {
						element.append(
							`<div class="cf-turnstile" data-sitekey="${SITE_KEY}"></div>`,
							{ html: true },
						);
					}
				},
			})
			.transform(res);
		return newRes;
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
	async fetch(request, env): Promise<Response> {
		const SITE_KEY = env.SITE_KEY; // The Turnstile Sitekey of your widget (pass as env or secret)
		const TURNSTILE_ATTR_NAME = "your_id_to_replace"; // The id of the element to put a Turnstile widget in

		let res = await fetch(request);

		// Instantiate the API to run on specific elements, for example, `head`, `div`
		let newRes = new HTMLRewriter()

			// `.on` attaches the element handler and this allows you to match on element/attributes or to use the specific methods per the API
			.on("head", {
				element(element) {
					// In this case, you are using `append` to add a new script to the `head` element
					element.append(
						`<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>`,
						{ html: true },
					);
				},
			})
			.on("div", {
				element(element) {
					// Add a turnstile widget element into if an element with the id of TURNSTILE_ATTR_NAME is found
					if (element.getAttribute("id") === TURNSTILE_ATTR_NAME) {
						element.append(
							`<div class="cf-turnstile" data-sitekey="${SITE_KEY}" data-theme="light"></div>`,
							{ html: true },
						);
					}
				},
			})
			.transform(res);
		return newRes;
	},
} satisfies ExportedHandler<Env>;
```

</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from "hono";

interface Env {
	SITE_KEY: string;
	SECRET_KEY: string;
	TURNSTILE_ATTR_NAME?: string;
}

const app = new Hono<{ Bindings: Env }>();

// Middleware to inject Turnstile widget
app.use("*", async (c, next) => {
	const SITE_KEY = c.env.SITE_KEY; // The Turnstile Sitekey from environment
	const TURNSTILE_ATTR_NAME = c.env.TURNSTILE_ATTR_NAME || "your_id_to_replace"; // The target element ID

	// Process the request through the original endpoint
	await next();

	// Only process HTML responses
	const contentType = c.res.headers.get("content-type");
	if (!contentType || !contentType.includes("text/html")) {
		return;
	}

	// Clone the response to make it modifiable
	const originalResponse = c.res;
	const responseBody = await originalResponse.text();

	// Create an HTMLRewriter instance to modify the HTML
	const rewriter = new HTMLRewriter()
		// Add the Turnstile script to the head
		.on("head", {
			element(element) {
				element.append(
					`<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>`,
					{ html: true },
				);
			},
		})
		// Add the Turnstile widget to the target div
		.on("div", {
			element(element) {
				if (element.getAttribute("id") === TURNSTILE_ATTR_NAME) {
					element.append(
						`<div class="cf-turnstile" data-sitekey="${SITE_KEY}" data-theme="light"></div>`,
						{ html: true },
					);
				}
			},
		});

	// Create a new response with the same properties as the original
	const modifiedResponse = new Response(responseBody, {
		status: originalResponse.status,
		statusText: originalResponse.statusText,
		headers: originalResponse.headers,
	});

	// Transform the response using HTMLRewriter
	c.res = rewriter.transform(modifiedResponse);
});

// Handle POST requests for form submission with Turnstile validation
app.post("*", async (c) => {
	const formData = await c.req.formData();
	const token = formData.get("cf-turnstile-response");
	const ip = c.req.header("CF-Connecting-IP");

	// If no token, return an error
	if (!token) {
		return c.text("Missing Turnstile token", 400);
	}

	// Prepare verification data
	const verifyFormData = new FormData();
	verifyFormData.append("secret", c.env.SECRET_KEY || "");
	verifyFormData.append("response", token.toString());
	if (ip) verifyFormData.append("remoteip", ip);

	// Verify the token with Turnstile API
	const verifyResult = await fetch(
		"https://challenges.cloudflare.com/turnstile/v0/siteverify",
		{
			method: "POST",
			body: verifyFormData,
		},
	);

	const outcome = await verifyResult.json<{ success: boolean }>;

	// If verification fails, return an error
	if (!outcome.success) {
		return c.text("The provided Turnstile token was not valid!", 401);
	}

	// If verification succeeds, proceed with the original request
	// You would typically handle the form submission logic here

	// For this example, we'll just send a success response
	return c.text("Form submission successful!");
});

// Default handler for GET requests
app.get("*", async (c) => {
	// Fetch the original content (you'd replace this with your actual content source)
	return await fetch(c.req.raw);
});

export default app;
```

</TabItem> <TabItem label="Python" icon="seti:python">

```py
from pyodide.ffi import create_proxy
from js import HTMLRewriter, fetch

async def on_fetch(request, env):
    site_key = env.SITE_KEY
	attr_name = env.TURNSTILE_ATTR_NAME
    res = await fetch(request)

    class Append:
        def element(self, element):
            s = '<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>'
            element.append(s, {"html": True})

    class AppendOnID:
        def __init__(self, name):
            self.name = name
        def element(self, element):
            # You are using the `getAttribute` method here to retrieve the `id` or `class` of an element
            if element.getAttribute("id") == self.name:
                div = f'<div class="cf-turnstile" data-sitekey="{site_key}" data-theme="light"></div>'
                element.append(div, { "html": True })

    # Instantiate the API to run on specific elements, for example, `head`, `div`
    head = create_proxy(Append())
    div = create_proxy(AppendOnID(attr_name))
    new_res = HTMLRewriter.new().on("head", head).on("div", div).transform(res)

    return new_res
```

</TabItem> </Tabs>

:::note

This is only half the implementation for Turnstile. The corresponding token that is a result of a widget being rendered also needs to be verified using the [Siteverify API](/turnstile/get-started/server-side-validation/). Refer to the example below for one such implementation.
:::

<TabItem label="JavaScript" icon="seti:javascript">

```js
async function handlePost(request, env) {
    const body = await request.formData();
    // Turnstile injects a token in `cf-turnstile-response`.
    const token = body.get('cf-turnstile-response');
    const ip = request.headers.get('CF-Connecting-IP');

    // Validate the token by calling the `/siteverify` API.
    let formData = new FormData();

    // `secret_key` here is the Turnstile Secret key, which should be set using Wrangler secrets
    formData.append('secret', env.SECRET_KEY);
    formData.append('response', token);
    formData.append('remoteip', ip); //This is optional.

    const url = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
    const result = await fetch(url, {
        body: formData,
        method: 'POST',
    });

    const outcome = await result.json();

    if (!outcome.success) {
        return new Response('The provided Turnstile token was not valid!', { status: 401 });
    }
    // The Turnstile token was successfully validated. Proceed with your application logic.
    // Validate login, redirect user, etc.

	// Clone the original request with a new body
    const newRequest = new Request(request, {
        body: request.body, // Reuse the body
        method: request.method,
        headers: request.headers
    });

    return await fetch(newRequest);
}

export default {
	async fetch(request, env) {
		const SITE_KEY = env.SITE_KEY; // The Turnstile Sitekey of your widget (pass as env or secret)
		const TURNSTILE_ATTR_NAME = 'your_id_to_replace'; // The id of the element to put a Turnstile widget in

		let res = await fetch(request)

		if (request.method === 'POST') {
			return handlePost(request, env)
		}

		// Instantiate the API to run on specific elements, for example, `head`, `div`
		let newRes = new HTMLRewriter()
			// `.on` attaches the element handler and this allows you to match on element/attributes or to use the specific methods per the API
			.on('head', {
				element(element) {

					// In this case, you are using `append` to add a new script to the `head` element
					element.append(`<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>`, { html: true });
				},
			})
			.on('div', {
				element(element) {
					// You are using the `getAttribute` method here to retrieve the `id` or `class` of an element
					if (element.getAttribute('id') === <NAME_OF_ATTRIBUTE>) {
						element.append(`<div class="cf-turnstile" data-sitekey="${SITE_KEY}" data-theme="light"></div>`, { html: true });
					}
				},
			})
			.transform(res);
		return newRes
	}
}
```

</TabItem>

<Render file="request-dot-clone-warning" product="workers" />

---

# Using the WebSockets API

URL: https://developers.cloudflare.com/workers/examples/websockets/

import { TabItem, Tabs } from "~/components";

WebSockets allow you to communicate in real time with your Cloudflare Workers serverless functions. In this guide, you will learn the basics of WebSockets on Cloudflare Workers, both from the perspective of writing WebSocket servers in your Workers functions, as well as connecting to and working with those WebSocket servers as a client.

WebSockets are open connections sustained between the client and the origin server. Inside a WebSocket connection, the client and the origin can pass data back and forth without having to reestablish sessions. This makes exchanging data within a WebSocket connection fast. WebSockets are often used for real-time applications such as live chat and gaming.

:::note

WebSockets utilize an event-based system for receiving and sending messages, much like the Workers runtime model of responding to events.

:::

:::note

If your application needs to coordinate among multiple WebSocket connections, such as a chat room or game match, you will need clients to send messages to a single-point-of-coordination. Durable Objects provide a single-point-of-coordination for Cloudflare Workers, and are often used in parallel with WebSockets to persist state over multiple clients and connections. In this case, refer to [Durable Objects](/durable-objects/) to get started, and prefer using the Durable Objects' extended [WebSockets API](/durable-objects/best-practices/websockets/).

:::

## Write a WebSocket Server

WebSocket servers in Cloudflare Workers allow you to receive messages from a client in real time. This guide will show you how to set up a WebSocket server in Workers.

A client can make a WebSocket request in the browser by instantiating a new instance of `WebSocket`, passing in the URL for your Workers function:

```js
// In client-side JavaScript, connect to your Workers function using WebSockets:
const websocket = new WebSocket(
	"wss://example-websocket.signalnerve.workers.dev",
);
```

:::note

For more details about creating and working with WebSockets in the client, refer to [Writing a WebSocket client](#write-a-websocket-client).

:::

When an incoming WebSocket request reaches the Workers function, it will contain an `Upgrade` header, set to the string value `websocket`. Check for this header before continuing to instantiate a WebSocket:

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">
```js
async function handleRequest(request) {
  const upgradeHeader = request.headers.get('Upgrade');
  if (!upgradeHeader || upgradeHeader !== 'websocket') {
    return new Response('Expected Upgrade: websocket', { status: 426 });
  }
}
```
</TabItem> <TabItem label="Rust" icon="seti:rust">
```rs

use worker::\*;

#[event(fetch)]
async fn fetch(req: HttpRequest, \_env: Env, \_ctx: Context) -> Result<worker::Response> {
let upgrade_header = match req.headers().get("Upgrade") {
Some(h) => h.to_str().unwrap(),
None => "",
};
if upgrade_header != "websocket" {
return worker::Response::error("Expected Upgrade: websocket", 426);
}
}

````
</TabItem> </Tabs>
After you have appropriately checked for the `Upgrade` header, you can create a new instance of `WebSocketPair`, which contains server and client WebSockets. One of these WebSockets should be handled by the Workers function and the other should be returned as part of a `Response` with the [`101` status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/101), indicating the request is switching protocols:


<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">
```js
async function handleRequest(request) {
  const upgradeHeader = request.headers.get('Upgrade');
  if (!upgradeHeader || upgradeHeader !== 'websocket') {
    return new Response('Expected Upgrade: websocket', { status: 426 });
  }

  const webSocketPair = new WebSocketPair();
  const client = webSocketPair[0],
    server = webSocketPair[1];

  return new Response(null, {
    status: 101,
    webSocket: client,
  });
}
````

</TabItem> <TabItem label="Rust" icon="seti:rust">
```rs
use worker::*;

#[event(fetch)]
async fn fetch(req: HttpRequest, \_env: Env, \_ctx: Context) -> Result<worker::Response> {
let upgrade_header = match req.headers().get("Upgrade") {
Some(h) => h.to_str().unwrap(),
None => "",
};
if upgrade_header != "websocket" {
return worker::Response::error("Expected Upgrade: websocket", 426);
}

    let ws = WebSocketPair::new()?;
    let client = ws.client;
    let server = ws.server;
    server.accept()?;

    worker::Response::from_websocket(client)

}

````
</TabItem> </Tabs>

The `WebSocketPair` constructor returns an Object, with the `0` and `1` keys each holding a `WebSocket` instance as its value. It is common to grab the two WebSockets from this pair using [`Object.values`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_objects/Object/values) and [ES6 destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment), as seen in the below example.

In order to begin communicating with the `client` WebSocket in your Worker, call `accept` on the `server` WebSocket. This will tell the Workers runtime that it should listen for WebSocket data and keep the connection open with your `client` WebSocket:


<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">
```js
async function handleRequest(request) {
  const upgradeHeader = request.headers.get('Upgrade');
  if (!upgradeHeader || upgradeHeader !== 'websocket') {
    return new Response('Expected Upgrade: websocket', { status: 426 });
  }

  const webSocketPair = new WebSocketPair();
  const [client, server] = Object.values(webSocketPair);

  server.accept();

  return new Response(null, {
    status: 101,
    webSocket: client,
  });
}
````

</TabItem> <TabItem label="Rust" icon="seti:rust">
```rs
use worker::*;

#[event(fetch)]
async fn fetch(req: HttpRequest, \_env: Env, \_ctx: Context) -> Result<worker::Response> {
let upgrade_header = match req.headers().get("Upgrade") {
Some(h) => h.to_str().unwrap(),
None => "",
};
if upgrade_header != "websocket" {
return worker::Response::error("Expected Upgrade: websocket", 426);
}

    let ws = WebSocketPair::new()?;
    let client = ws.client;
    let server = ws.server;
    server.accept()?;

    worker::Response::from_websocket(client)

}

````
</TabItem> </Tabs>

WebSockets emit a number of [Events](/workers/runtime-apis/websockets/#events) that can be connected to using `addEventListener`. The below example hooks into the `message` event and emits a `console.log` with the data from it:

<Tabs syncKey="workersExamples"> <TabItem label="JavaScript" icon="seti:javascript">
```js
async function handleRequest(request) {
  const upgradeHeader = request.headers.get('Upgrade');
  if (!upgradeHeader || upgradeHeader !== 'websocket') {
    return new Response('Expected Upgrade: websocket', { status: 426 });
  }

  const webSocketPair = new WebSocketPair();
  const [client, server] = Object.values(webSocketPair);

  server.accept();
  server.addEventListener('message', event => {
    console.log(event.data);
  });

  return new Response(null, {
    status: 101,
    webSocket: client,
  });
}
````

</TabItem> <TabItem label="Rust" icon="seti:rust">
```rs
use futures::StreamExt;
use worker::*;

#[event(fetch)]
async fn fetch(req: HttpRequest, \_env: Env, \_ctx: Context) -> Result<worker::Response> {
let upgrade_header = match req.headers().get("Upgrade") {
Some(h) => h.to_str().unwrap(),
None => "",
};
if upgrade_header != "websocket" {
return worker::Response::error("Expected Upgrade: websocket", 426);
}

    let ws = WebSocketPair::new()?;
    let client = ws.client;
    let server = ws.server;
    server.accept()?;

    wasm_bindgen_futures::spawn_local(async move {
        let mut event_stream = server.events().expect("could not open stream");
        while let Some(event) = event_stream.next().await {
            match event.expect("received error in websocket") {
                WebsocketEvent::Message(msg) => server.send(&msg.text()).unwrap(),
                WebsocketEvent::Close(event) => console_log!("{:?}", event),
            }
        }
    });
    worker::Response::from_websocket(client)

}

````
</TabItem> <TabItem label="Hono" icon="seti:typescript">

```ts
import { Hono } from 'hono'
import { upgradeWebSocket } from 'hono/cloudflare-workers'

const app = new Hono()

app.get(
  '*',
  upgradeWebSocket((c) => {
    return {
      onMessage(event, ws) {
        console.log('Received message from client:', event.data)
        ws.send(`Echo: ${event.data}`)
      },
      onClose: () => {
        console.log('WebSocket closed:', event)
      },
      onError: () => {
        console.error('WebSocket error:', event)
      },
    }
  })
)

export default app;
````

</TabItem> </Tabs>

### Connect to the WebSocket server from a client

Writing WebSocket clients that communicate with your Workers function is a two-step process: first, create the WebSocket instance, and then attach event listeners to it:

```js
const websocket = new WebSocket(
	"wss://websocket-example.signalnerve.workers.dev",
);
websocket.addEventListener("message", (event) => {
	console.log("Message received from server");
	console.log(event.data);
});
```

WebSocket clients can send messages back to the server using the [`send`](/workers/runtime-apis/websockets/#send) function:

```js
websocket.send("MESSAGE");
```

When the WebSocket interaction is complete, the client can close the connection using [`close`](/workers/runtime-apis/websockets/#close):

```js
websocket.close();
```

For an example of this in practice, refer to the [`websocket-template`](https://github.com/cloudflare/websocket-template) to get started with WebSockets.

## Write a WebSocket client

Cloudflare Workers supports the `new WebSocket(url)` constructor. A Worker can establish a WebSocket connection to a remote server in the same manner as the client implementation described above.

Additionally, Cloudflare supports establishing WebSocket connections by making a fetch request to a URL with the `Upgrade` header set.

```js
async function websocket(url) {
	// Make a fetch request including `Upgrade: websocket` header.
	// The Workers Runtime will automatically handle other requirements
	// of the WebSocket protocol, like the Sec-WebSocket-Key header.
	let resp = await fetch(url, {
		headers: {
			Upgrade: "websocket",
		},
	});

	// If the WebSocket handshake completed successfully, then the
	// response has a `webSocket` property.
	let ws = resp.webSocket;
	if (!ws) {
		throw new Error("server didn't accept WebSocket");
	}

	// Call accept() to indicate that you'll be handling the socket here
	// in JavaScript, as opposed to returning it on to a client.
	ws.accept();

	// Now you can send and receive messages like before.
	ws.send("hello");
	ws.addEventListener("message", (msg) => {
		console.log(msg.data);
	});
}
```

## WebSocket compression

Cloudflare Workers supports WebSocket compression. Refer to [WebSocket Compression](/workers/configuration/compatibility-flags/#websocket-compression) for more information.

---

# Languages

URL: https://developers.cloudflare.com/workers/languages/

import { DirectoryListing } from "~/components";

Workers is a polyglot platform, and provides first-class support for the following programming languages:

<DirectoryListing />

Workers also supports [WebAssembly](/workers/runtime-apis/webassembly/) (abbreviated as "Wasm") — a binary format that many languages can be compiled to. This allows you to write Workers using programming language beyond the languages listed above, including C, C++, Kotlin, Go and more.

---

# Betas

URL: https://developers.cloudflare.com/workers/platform/betas/

These are the current alphas and betas relevant to the Cloudflare Workers platform.

* **Public alphas and betas are openly available**, but may have limitations and caveats due to their early stage of development.
* Private alphas and betas require explicit access to be granted. Refer to the documentation to join the relevant product waitlist.

| Product                                           | Private Beta | Public Beta | More Info                                                                   |
| ------------------------------------------------- | ------------ | ----------- | --------------------------------------------------------------------------- |
| Email Workers                                     |              | ✅           | [Docs](/email-routing/email-workers/)                                       |
| Green Compute                                     |              | ✅           | [Blog](https://blog.cloudflare.com/earth-day-2022-green-compute-open-beta/) |
| Pub/Sub                                           | ✅            |             | [Docs](/pub-sub)                                                            |
| [TCP Sockets](/workers/runtime-apis/tcp-sockets/) |              | ✅           | [Docs](/workers/runtime-apis/tcp-sockets)                                   |

---

# Deploy to Cloudflare buttons

URL: https://developers.cloudflare.com/workers/platform/deploy-buttons/

import { Tabs, TabItem } from "@astrojs/starlight/components";

If you're building a Workers application and would like to share it with other developers, you can embed a Deploy to Cloudflare button in your README, blog post, or documentation to enable others to quickly deploy your application on their own Cloudflare account. Deploy to Cloudflare buttons eliminate the need for complex setup, allowing developers to get started with your public GitHub or GitLab repository in just a few clicks.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/templates/tree/main/saas-admin-template)

## What are Deploy to Cloudflare buttons?
Deploy to Cloudflare buttons simplify the deployment of a Workers application by enabling Cloudflare to:
* **Clone a Git repository**: Cloudflare clones your source repository into the user's GitHub/GitLab account where they can continue development after deploying.
* **Configure a project**: Your users can customize key details such as repository name, Worker name, and required resource names in a single setup page with customizations reflected in the newly created Git repository.
* **Build & deploy**: Cloudflare builds the application using [Workers Builds](/workers/ci-cd/builds) and deploys it to the Cloudflare network. Any required resources are automatically provisioned and bound to the Worker without additional setup.

![Deploy to Cloudflare Flow](~/assets/images/workers/dtw-user-flow.png)

## How to Set Up Deploy to Cloudflare buttons
Deploy to Cloudflare buttons can be embedded anywhere developers might want to launch your project. To add a Deploy to Cloudflare button, copy the following snippet and replace the Git repository URL with your project's URL. You can also optionally specify a subdirectory.


<Tabs syncKey="DeployButtonSnippet">
<TabItem label="Markdown">
```md
[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=<your git repo URL>)
```

</TabItem>
<TabItem label="HTML">
```html
<a href="https://deploy.workers.cloudflare.com/?url=<YOUR_REPO_URL>"><img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare"/></a>
```

</TabItem>

<TabItem label="URL">
```
https://deploy.workers.cloudflare.com/?url=<YOUR_REPO_URL>
```
</TabItem>
</Tabs>

If you have already deployed your application using Workers Builds, you can generate a Deploy to Cloudflare button directly from the Cloudflare dashboard by selecting the share button (located within your Worker details) and copying the provided snippet.

![Share an application](~/assets/images/workers/dtw-share-project.png)

Once you have your snippet, you can paste this wherever you would like your button to be displayed.

## Automatic Resource provisioning
If your Worker application requires Cloudflare resources, they will be automatically provisioned as part of the deployment. Currently, supported resources include:
* **Storage**: [KV namespaces](/kv/), [D1 databases](/d1/), [R2 buckets](/r2/), [Hyperdrive](/hyperdrive/), and [Vectorize databases](/vectorize/)
* **Compute**: [Durable Objects](/durable-objects/), [Workers AI](/workers-ai/), and [Queues](/queues/)

Cloudflare will read the Wrangler configuration file of your source repo to determine resource requirements for your application. During deployment, Cloudflare will provision any necessary resources and update the Wrangler configuration where applicable for newly created resources (e.g. database IDs and namespace IDs). To ensure successful deployment, please make sure your source repository includes default values for resource names, resource IDs and any other properties for each binding.

## Best practices
**Configuring Build/Deploy commands**: If you are using custom  `build` and `deploy` scripts in your package.json (for example, if using a full stack framework or running D1 migrations), Cloudflare will automatically detect and pre-populate the build and deploy fields. Users can choose to modify or accept the custom commands during deployment configuration.

If no `deploy` script is specified, Cloudflare will preconfigure `npx wrangler deploy` by default. If no `build` script is specified, Cloudflare will leave this field blank.

**Running D1 Migrations**: If you would like to run migrations as part of your setup, you can specify this in your `package.json` by running your migrations as part of your `deploy` script. The migration command should reference the binding name rather than the database name to ensure migrations are successful when users specify a database name that is different from that of your source repository. The following is an example of how you can set up the scripts section of your `package.json`:

```json
{
  "scripts": {
    "build": "astro build",
    "deploy": "npm run db:migrations:apply && wrangler deploy",
    "db:migrations:apply": "wrangler d1 migrations apply DB_BINDING --remote"
  }
}
```

## Limitations

* **Monorepos**: Cloudflare does not fully support monorepos
  * If your repository URL contains a subdirectory, your application must be fully isolated within that subdirectory, including any dependencies. Otherwise, the build will fail. Cloudflare treats this subdirectory as the root of the new repository created as part of the deploy process.
  * Additionally, if you have a monorepo that contains multiple Workers applications, they will not be deployed together. You must configure a separate Deploy to Cloudflare button for each application. The user will manually create a distinct Workers application for each subdirectory.
* **Pages applications**: Deploy to Cloudflare buttons only support Workers applications.
* **Non-GitHub/GitLab repositories**: Source repositories from anything other than github.com and gitlab.com are not supported. Self-hosted versions of GitHub and GitLab are also not supported.
* **Private repositories**: Repositories must be public in order for others to successfully use your Deploy to Cloudflare button.

---

# Platform

URL: https://developers.cloudflare.com/workers/platform/

import { DirectoryListing } from "~/components";

Pricing, limits and other information about the Workers platform.

<DirectoryListing />

---

# Infrastructure as Code (IaC)

URL: https://developers.cloudflare.com/workers/platform/infrastructure-as-code/

import { GitHubCode } from "~/components";

Uploading and managing Workers is easy with [Wrangler](/workers/wrangler/configuration), but sometimes you need to do it more programmatically. You might do this with IaC ("Infrastructure as Code") tools or by calling the [Cloudflare API](/api) directly. Use cases for the API include build and deploy scripts, CI/CD pipelines, custom dev tools, and testing. We provide API SDK libraries for common languages that make interacting with the API easier, such as [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript) and [cloudflare-python](https://github.com/cloudflare/cloudflare-python). For IaC, a common tool is HashiCorp's Terraform. You can use the [Cloudflare Terraform Provider](/terraform) to create and manage Workers resources.

Here are examples of deploying a Worker with common tools and languages, and considerations for successfully managing Workers with IaC. In particular, the examples highlight how to upload script content and metadata which is different with each approach. Reference the Upload Worker Module API docs [here](/api/resources/workers/subresources/scripts/methods/update) for an exact definition of how script upload works.

All of these examples need an [account ID](/fundamentals/account/find-account-and-zone-ids) and [API token](/fundamentals/api/get-started/create-token) (not Global API key) to work.

## Workers Bundling

None of the examples below do [Workers Bundling](/workers/wrangler/bundling) which is usually the function of a tool like Wrangler or [esbuild](https://esbuild.github.io). Generally, you'd run this bundling step before applying your Terraform plan or using the API for script upload:

```bash
wrangler deploy --dry-run -outdir build
```

Then you'd reference the bundled script like `build/index.js`.

:::note

Depending on your Wrangler project and `-outdir`, the name and location of your bundled script might vary.
:::

Make sure to copy all of your config from `wrangler.json` into your Terraform config or API request. This is especially important for compatibility date or compatibility flags your script relies on.

## Terraform

In this example, you need a local file named `my-hello-world-script.mjs` with script content similar to the above examples. Replace `account_id` with your own. Learn more about the Cloudflare Terraform Provider [here](/terraform), and see an example with all the Workers script resource settings [here](https://github.com/cloudflare/terraform-provider-cloudflare/blob/main/examples/resources/cloudflare_workers_script/resource.tf).

```tf
terraform {
  required_providers {
    cloudflare = {
      source = "cloudflare/cloudflare"
      version = "~> 5"
    }
  }
}

resource "cloudflare_workers_script" "my-hello-world-script" {
  account_id = "<replace_me>"
  script_name = "my-hello-world-script"
  main_module = "my-hello-world-script.mjs"
  content = trimspace(file("my-hello-world-script.mjs"))
  compatibility_date = "$today"
  bindings = [{
    name = "MESSAGE"
    type = "plain_text"
    text = "Hello World!"
  }]
}
```

:::note

- `trimspace()` removes empty lines in the file
- The Workers Script resource does not have a `metadata` property like in the other examples. All of the properties found in `metadata` are instead at the top-level of the resource class, such as `bindings` or `compatibility_date`. Please see the [cloudflare_workers_script (Resource) docs](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/workers_script).
  :::

## Cloudflare API Libraries

### JavaScript/TypeScript

This example uses the [cloudflare-typescript](https://github.com/cloudflare/cloudflare-typescript) library which provides convenient access to the Cloudflare REST API from server-side JavaScript or TypeScript.

<GitHubCode
	repo="cloudflare/cloudflare-typescript"
	file="examples/workers/script-upload.ts"
	commit="3031b3c5a7091cebbff7b18d9780a11340ee21cd"
	lang="ts"
	useTypeScriptExample={true}
/>

### Python

This example uses the [cloudflare-python](https://github.com/cloudflare/cloudflare-python) library.

<GitHubCode
	repo="cloudflare/cloudflare-python"
	file="examples/workers/script_upload.py"
	commit="756dc87dde3a42c8d4c860ff2239c920c22014ec"
	lang="py"
/>

## Cloudflare REST API

Open a terminal or create a shell script to upload a Worker easily with curl. For this example, replace `<account_id>` and `<api_token>` with your own. What's notable about interacting with the Workers Script Upload API directly is that it uses [multipart/form-data](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/POST) for uploading metadata, multiple JavaScript modules, source maps, and more. This is abstracted away in Terraform and the API libraries.

```bash
curl https://api.cloudflare.com/client/v4/accounts/<account_id>/workers/scripts/my-hello-world-script \
  -X PUT \
  -H 'Authorization: Bearer <api_token>' \
  -F 'metadata={
        "main_module": "my-hello-world-script.mjs",
        "bindings": [
          {
            "type": "plain_text",
            "name": "MESSAGE",
            "text": "Hello World!"
          }
        ],
        "compatibility_date": "$today"
      };type=application/json' \
  -F 'my-hello-world-script.mjs=@-;filename=my-hello-world-script.mjs;type=application/javascript+module' <<EOF
export default {
  async fetch(request, env, ctx) {
    return new Response(env.MESSAGE, { status: 200 });
  }
};
EOF
```

:::note

Change `my-hello-world-script.mjs=@-;` to `my-hello-world-script.mjs=@./my-hello-world-script.mjs;` and remove everything after and including `<<EOF` to upload a local file named `my-hello-world-script.mjs` instead.
:::

### Workers for Platforms

With [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms), you can upload [User Workers](/cloudflare-for-platforms/workers-for-platforms/get-started/user-workers) in a [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace). You can use the exact same example. Simply change the url to:

```bash
curl https://api.cloudflare.com/client/v4/accounts/<account_id>/workers/dispatch/namespaces/<dispatch_namespace>/scripts/my-hello-world-script
```

For this to work, you first need to configure [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/get-started/configuration), create a dispatch namespace, and replace `<dispatch_namespace>` with your own.

### Python Workers

[Python Workers](/workers/languages/python/) (open beta) have their own special `text/x-python` content type and `python_workers` compatibility flag for uploading.

```bash
curl https://api.cloudflare.com/client/v4/accounts/<account_id>/workers/scripts/my-hello-world-script \
  -X PUT \
  -H 'Authorization: Bearer <api_token>' \
  -F 'metadata={
        "main_module": "my-hello-world-script.py",
        "bindings": [
          {
            "type": "plain_text",
            "name": "MESSAGE",
            "text": "Hello World!"
          }
        ],
        "compatibility_date": "$today",
        "compatibility_flags": [
          "python_workers"
        ]
      };type=application/json' \
  -F 'my-hello-world-script.py=@-;filename=my-hello-world-script.py;type=text/x-python' <<EOF
from workers import Response

def on_fetch(request, env):
    return Response(env.MESSAGE)
EOF
```

You can upload Python Workers in any of our language SDKs, even the non-Python ones. Just modify the above SDK examples with the `text/x-python` content type, change the script file extension from `.mjs` to `.py`, change the script content to a Python Worker format, and add the `python_workers` compatibility date.

---

# Known issues

URL: https://developers.cloudflare.com/workers/platform/known-issues/

Below are some known bugs and issues to be aware of when using Cloudflare Workers.

## Route specificity

* When defining route specificity, a trailing `/*` in your pattern may not act as expected.

Consider two different Workers, each deployed to the same zone. Worker A is assigned the `example.com/images/*` route and Worker B is given the `example.com/images*` route pattern. With these in place, here are how the following URLs will be resolved:

```
// (A) example.com/images/*
// (B) example.com/images*

"example.com/images"
// -> B
"example.com/images123"
// -> B
"example.com/images/hello"
// -> B
```

You will notice that all examples trigger Worker B. This includes the final example, which exemplifies the unexpected behavior.

When adding a wildcard on a subdomain, here are how the following URLs will be resolved:

```
// (A) *.example.com/a
// (B) a.example.com/*

"a.example.com/a"
// -> B
```

## wrangler dev

* When running `wrangler dev --remote`, all outgoing requests are given the `cf-workers-preview-token` header, which Cloudflare recognizes as a preview request. This applies to the entire Cloudflare network, so making HTTP requests to other Cloudflare zones is currently discarded for security reasons. To enable a workaround, insert the following code into your Worker script:

```js
const request = new Request(url, incomingRequest);
request.headers.delete('cf-workers-preview-token');
return await fetch(request);
```

## Fetch API in CNAME setup

When you make a subrequest using [`fetch()`](/workers/runtime-apis/fetch/) from a Worker, the Cloudflare DNS resolver is used. When a zone has a [Partial (CNAME) setup](/dns/zone-setups/partial-setup/), all hostnames that the Worker needs to be able to resolve require a dedicated DNS entry in Cloudflare's DNS setup. Otherwise the Fetch API call will fail with status code [530 (1016)](/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/error-1016/).

Setup with missing DNS records in Cloudflare DNS

```
// Zone in partial setup: example.com
// DNS records at Authoritative DNS: sub1.example.com, sub2.example.com, ...
// DNS records at Cloudflare DNS: sub1.example.com

"sub1.example.com/"
// -> Can be resolved by Fetch API
"sub2.example.com/"
// -> Cannot be resolved by Fetch API, will lead to 530 status code

```

After adding `sub2.example.com` to Cloudflare DNS

```
// Zone in partial setup: example.com
// DNS records at Authoritative DNS: sub1.example.com, sub2.example.com, ...
// DNS records at Cloudflare DNS: sub1.example.com, sub2.example.com

"sub1.example.com/"
// -> Can be resolved by Fetch API
"sub2.example.com/"
// -> Can be resolved by Fetch API
```

## Fetch to IP addresses

For Workers subrequests, requests can only be made to URLs, not to IP addresses directly. To overcome this limitation [add a A or AAAA name record to your zone](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/) and then fetch that resource.

For example, in the zone `example.com` create a record of type `A` with the name `server` and value `192.0.2.1`, and then use:

```js
await fetch('http://server.example.com')
```

Do not use:

```js
await fetch('http://192.0.2.1')
```

---

# Limits

URL: https://developers.cloudflare.com/workers/platform/limits/

import { Render, WranglerConfig } from "~/components";

## Account plan limits

| Feature                                                                          | Workers Free | Workers Paid |
| -------------------------------------------------------------------------------- | ------------ | ------------ |
| [Subrequests](#subrequests)                                                      | 50/request   | 1000/request |
| [Simultaneous outgoing<br/>connections/request](#simultaneous-open-connections)  | 6            | 6            |
| [Environment variables](#environment-variables)                                  | 64/Worker    | 128/Worker   |
| [Environment variable<br/>size](#environment-variables)                          | 5 KB         | 5 KB         |
| [Worker size](#worker-size)                                                      | 3 MB         | 10 MB        |
| [Worker startup time](#worker-startup-time)                                      | 400 ms       | 400 ms       |
| [Number of Workers](#number-of-workers)<sup>1</sup>                              | 100          | 500          |
| Number of [Cron Triggers](/workers/configuration/cron-triggers/)<br/>per account | 5            | 250          |
| Number of [Static Asset](#static-assets) files                                   | 20000        | 20000        |
| Individual [Static Asset](#static-assets) file size                              | 25 MiB       | 25 MiB       |

<sup>1</sup> If you are running into limits, your project may be a good fit for
[Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/).

<Render file="limits_increase" />

---

## Request limits

URLs have a limit of 16 KB.

Request headers observe a total limit of 32 KB, but each header is limited to 16 KB.

Cloudflare has network-wide limits on the request body size. This limit is tied to your Cloudflare account's plan, which is separate from your Workers plan. When the request body size of your `POST`/`PUT`/`PATCH` requests exceed your plan's limit, the request is rejected with a `(413) Request entity too large` error.

Cloudflare Enterprise customers may contact their account team or [Cloudflare Support](/support/contacting-cloudflare-support/) to have a request body limit beyond 500 MB.

| Cloudflare Plan | Maximum body size   |
| --------------- | ------------------- |
| Free            | 100 MB              |
| Pro             | 100 MB              |
| Business        | 200 MB              |
| Enterprise      | 500 MB (by default) |

---

## Response limits

Response headers observe a total limit of 32 KB, but each header is limited to 16 KB.

Cloudflare does not enforce response limits on response body sizes, but cache limits for [our CDN are observed](/cache/concepts/default-cache-behavior/). Maximum file size is 512 MB for Free, Pro, and Business customers and 5 GB for Enterprise customers.

---

## Worker limits

| Feature                  | Workers Free                               | Workers Paid                                                                                                                                                                                                                              |
| ------------------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Request](#request)      | 100,000 requests/day<br/>1000 requests/min | No limit                                                                                                                                                                                                                                  |
| [Worker memory](#memory) | 128 MB                                     | 128 MB                                                                                                                                                                                                                                    |
| [CPU time](#cpu-time)    | 10 ms                                      | 5 min HTTP request <br/> 15 min [Cron Trigger](/workers/configuration/cron-triggers/)                                                                                                                                                     |
| [Duration](#duration)    | No limit                                   | No limit for Workers. <br/>15 min duration limit for [Cron Triggers](/workers/configuration/cron-triggers/), [Durable Object Alarms](/durable-objects/api/alarms/) and [Queue Consumers](/queues/configuration/javascript-apis/#consumer) |

### Duration

Duration is a measurement of wall-clock time — the total amount of time from the start to end of an invocation of a Worker. There is no hard limit on the duration of a Worker. As long as the client that sent the request remains connected, the Worker can continue processing, making subrequests, and setting timeouts on behalf of that request. When the client disconnects, all tasks associated with that client request are canceled. Use [`event.waitUntil()`](/workers/runtime-apis/handlers/fetch/) to delay cancellation for another 30 seconds or until the promise passed to `waitUntil()` completes.

:::note

Cloudflare updates the Workers runtime a few times per week. When this happens, any in-flight requests are given a grace period of 30 seconds to finish. If a request does not finish within this time, it is terminated. While your application should follow the best practice of handling disconnects by retrying requests, this scenario is extremely improbable. To encounter it, you would need to have a request that takes longer than 30 seconds that also happens to intersect with the exact time an update to the runtime is happening.
:::

### CPU time

CPU time is the amount of time the CPU actually spends doing work during a given request.
If a Worker's request makes a sub-request and waits for that request to come back before
doing additional work, this time spent waiting **is not** counted towards CPU time.

**Most Workers requests consume less than 1-2 milliseconds of CPU time**, but you can increase the maximum CPU time from the default 30 seconds to 5 minutes (300,000 milliseconds) if you have CPU-bound tasks, such as large JSON payloads that need to be serialized, cryptographic key generation, or other data processing tasks.

<Render file="isolate-cpu-flexibility" />

To understand your CPU usage:

- CPU time and Wall time are surfaced in the [invocation log](/workers/observability/logs/workers-logs/#invocation-logs) within Workers Logs.
- For Tail Workers, CPU time and Wall time are surfaced at the top level of the [Workers Trace Events object](/logs/reference/log-fields/account/workers_trace_events/).
- DevTools locally can help identify CPU intensive portions of your code. See the [CPU profiling with DevTools documentation](/workers/observability/dev-tools/cpu-usage/).

You can also set a [custom limit](/workers/wrangler/configuration/#limits) on the amount of CPU time that can be used during each invocation of your Worker.

<WranglerConfig>

```jsonc
{
	// ...rest of your configuration...
	"limits": {
		"cpu_ms": 300000, // default is 30000 (30 seconds)
	},
	// ...rest of your configuration...
}
```

</WranglerConfig>

You can also customize this in the [Workers dashboard](https://dash.cloudflare.com/?to=/:account/workers). Select the specific Worker you wish to modify -> click on the "Settings" tab -> adjust the CPU time limit.

:::note

Scheduled Workers ([Cron Triggers](/workers/configuration/cron-triggers/)) have different limits on CPU time based on the schedule interval. When the schedule interval is less than 1 hour, a Scheduled Worker may run for up to 30 seconds. When the schedule interval is more than 1 hour, a scheduled Worker may run for up to 15 minutes.
:::

---

## Cache API limits

| Feature                                  | Workers Free | Workers Paid |
| ---------------------------------------- | ------------ | ------------ |
| [Maximum object size](#cache-api-limits) | 512 MB       | 512 MB       |
| [Calls/request](#cache-api-limits)       | 50           | 1,000        |

Calls/request means the number of calls to `put()`, `match()`, or `delete()` Cache API method per-request, using the same quota as subrequests (`fetch()`).

:::note

The size of chunked response bodies (`Transfer-Encoding: chunked`) is not known in advance. Then, `.put()`ing such responses will block subsequent `.put()`s from starting until the current `.put()` completes.

:::

---

## Request

Workers automatically scale onto thousands of Cloudflare global network servers around the world. There is no general limit to the number of requests per second Workers can handle.

Cloudflare’s abuse protection methods do not affect well-intentioned traffic. However, if you send many thousands of requests per second from a small number of client IP addresses, you can inadvertently trigger Cloudflare’s abuse protection. If you expect to receive `1015` errors in response to traffic or expect your application to incur these errors, [contact Cloudflare support](/support/contacting-cloudflare-support/) to increase your limit. Cloudflare's anti-abuse Workers Rate Limiting does not apply to Enterprise customers.

You can also confirm if you have been rate limited by anti-abuse Worker Rate Limiting by logging into the Cloudflare dashboard, selecting your account and zone, and going to **Security** > **Events**. Find the event and expand it. If the **Rule ID** is `worker`, this confirms that it is the anti-abuse Worker Rate Limiting.

The burst rate and daily request limits apply at the account level, meaning that requests on your `*.workers.dev` subdomain count toward the same limit as your zones. Upgrade to a [Workers Paid plan](https://dash.cloudflare.com/?account=workers/plans) to automatically lift these limits.

:::caution

If you are currently being rate limited, upgrade to a [Workers Paid plan](https://dash.cloudflare.com/?account=workers/plans) to lift burst rate and daily request limits.

:::

### Burst rate

Accounts using the Workers Free plan are subject to a burst rate limit of 1,000 requests per minute. Users visiting a rate limited site will receive a Cloudflare `1015` error page. However if you are calling your Worker programmatically, you can detect the rate limit page and handle it yourself by looking for HTTP status code `429`.

Workers being rate-limited by Anti-Abuse Protection are also visible from the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account and your website.
2. Select **Security** > **Events** > scroll to **Sampled logs**.
3. Review the log for a Web Application Firewall block event with a `ruleID` of `worker`.

### Daily request

Accounts using the Workers Free plan are subject to a daily request limit of 100,000 requests. Free plan daily requests counts reset at midnight UTC. A Worker that fails as a result of daily request limit errors can be configured by toggling its corresponding [route](/workers/configuration/routing/routes/) in two modes: 1) Fail open and 2) Fail closed.

#### Fail open

Routes in fail open mode will bypass the failing Worker and prevent it from operating on incoming traffic. Incoming requests will behave as if there was no Worker.

#### Fail closed

Routes in fail closed mode will display a Cloudflare `1027` error page to visitors, signifying the Worker has been temporarily disabled. Cloudflare recommends this option if your Worker is performing security related tasks.

---

## Memory

Only one Workers instance runs on each of the many global Cloudflare global network servers. Each Workers instance can consume up to 128 MB of memory. Use [global variables](/workers/runtime-apis/web-standards/) to persist data between requests on individual nodes. Note however, that nodes are occasionally evicted from memory.

If a Worker processes a request that pushes the Worker over the 128 MB limit, the Cloudflare Workers runtime may cancel one or more requests. To view these errors, as well as CPU limit overages:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages** and in **Overview**, select the Worker you would like to investigate.
3. Under **Metrics**, select **Errors** > **Invocation Statuses** and examine **Exceeded Memory**.

Use the [TransformStream API](/workers/runtime-apis/streams/transformstream/) to stream responses if you are concerned about memory usage. This avoids loading an entire response into memory.

Using DevTools locally can help identify memory leaks in your code. See the [memory profiling with DevTools documentation](/workers/observability/dev-tools/memory-usage/) to learn more.

---

## Subrequests

A subrequest is any request that a Worker makes to either Internet resources using the [Fetch API](/workers/runtime-apis/fetch/) or requests to other Cloudflare services like [R2](/r2/), [KV](/kv/), or [D1](/d1/).

### Worker-to-Worker subrequests

To make subrequests from your Worker to another Worker on your account, use [Service Bindings](/workers/runtime-apis/bindings/service-bindings/). Service bindings allow you to send HTTP requests to another Worker without those requests going over the Internet.

If you attempt to use global [`fetch()`](/workers/runtime-apis/fetch/) to make a subrequest to another Worker on your account that runs on the same [zone](/fundamentals/concepts/accounts-and-zones/#zones), without service bindings, the request will fail.

If you make a subrequest from your Worker to a target Worker that runs on a [Custom Domain](/workers/configuration/routing/custom-domains/#worker-to-worker-communication) rather than a route, the request will be allowed.

### How many subrequests can I make?

You can make 50 subrequests per request on Workers Free, and 1,000 subrequests per request on Workers Paid. Each subrequest in a redirect chain counts against this limit. This means that the number of subrequests a Worker makes could be greater than the number of `fetch(request)` calls in the Worker.

For subrequests to internal services like Workers KV and Durable Objects, the subrequest limit is 1,000 per request, regardless of the [usage model](/workers/platform/pricing/#workers) configured for the Worker.

### How long can a subrequest take?

There is no set limit on the amount of real time a Worker may use. As long as the client which sent a request remains connected, the Worker may continue processing, making subrequests, and setting timeouts on behalf of that request.

When the client disconnects, all tasks associated with that client’s request are proactively canceled. If the Worker passed a promise to [`event.waitUntil()`](/workers/runtime-apis/handlers/fetch/), cancellation will be delayed until the promise has completed or until an additional 30 seconds have elapsed, whichever happens first.

---

## Simultaneous open connections

You can open up to six connections simultaneously for each invocation of your Worker. The connections opened by the following API calls all count toward this limit:

- the `fetch()` method of the [Fetch API](/workers/runtime-apis/fetch/).
- `get()`, `put()`, `list()`, and `delete()` methods of [Workers KV namespace objects](/kv/api/).
- `put()`, `match()`, and `delete()` methods of [Cache objects](/workers/runtime-apis/cache/).
- `list()`, `get()`, `put()`, `delete()`, and `head()` methods of [R2](/r2/).
- `send()` and `sendBatch()`, methods of [Queues](/queues/).
- Opening a TCP socket using the [`connect()`](/workers/runtime-apis/tcp-sockets/) API.

Once an invocation has six connections open, it can still attempt to open additional connections.

- These attempts are put in a pending queue — the connections will not be initiated until one of the currently open connections has closed.
- Earlier connections can delay later ones, if a Worker tries to make many simultaneous subrequests, its later subrequests may appear to take longer to start.

If you have cases in your application that use `fetch()` but that do not require consuming the response body, you can avoid the unread response body from consuming a concurrent connection by using `response.body.cancel()`.

For example, if you want to check whether the HTTP response code is successful (2xx) before consuming the body, you should explicitly cancel the pending response body:

```ts
let resp = await fetch(url);

// Only read the response body for successful responses
if (resp.statusCode <= 299) {
	// Call resp.json(), resp.text() or otherwise process the body
} else {
	// Explicitly cancel it
	resp.body.cancel();
}
```

This will free up an open connection.

If the system detects that a Worker is deadlocked on open connections — for example, if the Worker has pending connection attempts but has no in-progress reads or writes on the connections that it already has open — then the least-recently-used open connection will be canceled to unblock the Worker.

If the Worker later attempts to use a canceled connection, an exception will be thrown. These exceptions should rarely occur in practice, though, since it is uncommon for a Worker to open a connection that it does not have an immediate use for.

:::note

Simultaneous Open Connections are measured from the top-level request, meaning any connections open from Workers sharing resources (for example, Workers triggered via [Service bindings](/workers/runtime-apis/bindings/service-bindings/)) will share the simultaneous open connection limit.

:::

---

## Environment variables

The maximum number of environment variables (secret and text combined) for a Worker is 128 variables on the Workers Paid plan, and 64 variables on the Workers Free plan.
There is no limit to the number of environment variables per account.

Each environment variable has a size limitation of 5 KB.

---

## Worker size

A Worker can be up to 10 MB in size _after compression_ on the Workers Paid plan, and up to 3 MB on the Workers Free plan. On either plan, a Worker can be up to 64 MB _before compression_.

You can assess the size of your Worker bundle after compression by performing a dry-run with `wrangler` and reviewing the final compressed (`gzip`) size output by `wrangler`:

```sh
wrangler deploy --outdir bundled/ --dry-run
```

```sh output
# Output will resemble the below:
Total Upload: 259.61 KiB / gzip: 47.23 KiB
```

Note that larger Worker bundles can impact the start-up time of the Worker, as the Worker needs to be loaded into memory.

To reduce the upload size of a Worker, consider some of the following strategies:

- Removing unnecessary dependencies and packages
- Storing configuration files, static assets, and binary data using [Workers KV](/kv/), [R2](/r2/), [D1](/d1/), or [Workers Static Assets](/workers/static-assets/) instead of bundling them within your Worker code.
- Splitng functionality across multiple Workers and connecting them using [Service bindings](/workers/runtime-apis/bindings/service-bindings/).

---

## Worker startup time

A Worker must be able to be parsed and execute its global scope (top-level code outside of any handlers) within 400 ms. Worker size can impact startup because there is more code to parse and evaluate. Avoiding expensive code in the global scope can keep startup efficient as well.

You can measure your Worker's startup time by deploying it to Cloudflare using [Wrangler](/workers/wrangler/). When you run `npx wrangler@latest deploy` or `npx wrangler@latest versions upload`, Wrangler will output the startup time of your Worker in the command-line output, using the `startup_time_ms` field in the [Workers Script API](/api/resources/workers/subresources/scripts/methods/update/) or [Workers Versions API](/api/resources/workers/subresources/scripts/subresources/versions/methods/create/).

If you are having trouble staying under this limit, consider [profiling using DevTools](/workers/observability/dev-tools/) locally to learn how to optimize your code.

When you attempt to deploy a Worker using the [Wrangler CLI](/workers/wrangler/), but your deployment is rejected because your Worker exceeds the maximum startup time, Wrangler will automatically generate a CPU profile that you can import into Chrome DevTools or open directly in VSCode. You can use this to learn what code in your Worker uses large amounts of CPU time at startup. Refer to [`wrangler check startup`](/workers/wrangler/commands/#startup) for more details.

<Render file="limits_increase" />

---

## Number of Workers

You can have up to 500 Workers on your account on the Workers Paid plan, and up to 100 Workers on the Workers Free plan.

If you need more than 500 Workers, consider using [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/).

---

## Routes and domains

### Number of routes per zone

Each zone has a limit of 1,000 [routes](/workers/configuration/routing/routes/). If you require more than 1,000 routes on your zone, consider using [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/) or request an increase to this limit.

### Number of routes per zone when using `wrangler dev --remote`

When you run a [remote development](/workers/development-testing/#remote-bindings) session using the `--remote` flag, a limit of 50 [routes](/workers/configuration/routing/routes/) per zone is enforced. The Quick Editor in the Cloudflare Dashboard also uses `wrangler dev --remote`, so any changes made there are subject to the same 50-route limit. If your zone has more than 50 routes, you **will not be able to run a remote session**. To fix this, you must remove routes until you are under the 50-route limit.

### Number of custom domains per zone

Each zone has a limit of 100 [custom domains](/workers/configuration/routing/custom-domains/). If you require more than 100 custom domains on your zone, consider using a wildcard [route](/workers/configuration/routing/routes/) or request an increase to this limit.

### Number of routed zones per Worker

When configuring [routing](/workers/configuration/routing/), the maximum number of zones that can be referenced by a Worker is 1,000. If you require more than 1,000 zones on your Worker, consider using [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/) or request an increase to this limit.

---

## Image Resizing with Workers

When using Image Resizing with Workers, refer to [Image Resizing documentation](/images/transform-images/) for more information on the applied limits.

---

## Log size

You can emit a maximum of 256 KB of data (across `console.log()` statements, exceptions, request metadata and headers) to the console for a single request. After you exceed this limit, further context associated with the request will not be recorded in logs, appear when tailing logs of your Worker, or within a [Tail Worker](/workers/observability/logs/tail-workers/).

Refer to the [Workers Trace Event Logpush documentation](/workers/observability/logs/logpush/#limits) for information on the maximum size of fields sent to logpush destinations.

---

## Unbound and Bundled plan limits

:::note
Unbound and Bundled plans have been deprecated and are no longer available for new accounts.
:::

If your Worker is on an Unbound plan, your limits are exactly the same as the Workers Paid plan.

If your Worker is on a Bundled plan, your limits are the same as the Workers Paid plan except for the following differences:

- Your limit for [subrequests](/workers/platform/limits/#subrequests) is 50/request
- Your limit for [CPU time](/workers/platform/limits/#cpu-time) is 50ms for HTTP requests and 50ms for [Cron Triggers](/workers/configuration/cron-triggers/)
- You have no [Duration](/workers/platform/limits/#duration) limits for [Cron Triggers](/workers/configuration/cron-triggers/), [Durable Object alarms](/durable-objects/api/alarms/), or [Queue consumers](/queues/configuration/javascript-apis/#consumer)
- Your Cache API limits for calls/requests is 50

---

## Static Assets

### Files

There is a 20,000 file count limit per [Worker version](/workers/configuration/versions-and-deployments/), and a 25 MiB individual file size limit. This matches the [limits in Cloudflare Pages](/pages/platform/limits/) today.

### Headers

A `_headers` file may contain up to 100 rules and each line may contain up to 2,000 characters. The entire line, including spacing, header name, and value, counts towards this limit.

### Redirects

A `_redirects` file may contain up to 2,000 static redirects and 100 dynamic redirects, for a combined total of 2,100 redirects. Each redirect declaration has a 1,000-character limit.

---

## Related resources

Review other developer platform resource limits.

- [KV limits](/kv/platform/limits/)
- [Durable Object limits](/durable-objects/platform/limits/)
- [Queues limits](/queues/platform/limits/)

---

# Pricing

URL: https://developers.cloudflare.com/workers/platform/pricing/

import { GlossaryTooltip, Render } from "~/components";

By default, users have access to the Workers Free plan. The Workers Free plan includes limited usage of Workers, Pages Functions, Workers KV and Hyperdrive. Read more about the [Free plan limits](/workers/platform/limits/#worker-limits).

The Workers Paid plan includes Workers, Pages Functions, Workers KV, Hyperdrive, and Durable Objects usage for a minimum charge of $5 USD per month for an account. The plan includes increased initial usage allotments, with clear charges for usage that exceeds the base plan. There are no additional charges for data transfer (egress) or throughput (bandwidth).

All included usage is on a monthly basis.

:::note[Pages Functions billing]

All [Pages Functions](/pages/functions/) are billed as Workers. All pricing and inclusions in this document apply to Pages Functions. Refer to [Functions Pricing](/pages/functions/pricing/) for more information on Pages Functions pricing.

:::

## Workers

Users on the Workers Paid plan have access to the Standard usage model. Workers Enterprise accounts are billed based on the usage model specified in their contract. To switch to the Standard usage model, reach out to your CSM.

|              | Requests<sup>1, 2</sup>                                            | Duration                        | CPU time                                                                                                                                                                                                                                                                                                                                   |
| ------------ | ------------------------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Free**     | 100,000 per day                                                    | No charge for duration          | 10 milliseconds of CPU time per invocation                                                                                                                                                                                                                                                                                                 |
| **Standard** | 10 million included per month <br /> +$0.30 per additional million | No charge or limit for duration | 30 million CPU milliseconds included per month<br /> +$0.02 per additional million CPU milliseconds<br /><br/> Max of [5 minutes of CPU time](/workers/platform/limits/#worker-limits) per invocation (default: 30 seconds)<br /> Max of 15 minutes of CPU time per [Cron Trigger](/workers/configuration/cron-triggers/) or [Queue Consumer](/queues/configuration/javascript-apis/#consumer) invocation |

<sup>1</sup> Inbound requests to your Worker. Cloudflare does not bill for
[subrequests](/workers/platform/limits/#subrequests) you make from your Worker.

<sup>2</sup> Requests to static assets are free and unlimited.

### Example pricing

#### Example 1

A Worker that serves 15 million requests per month, and uses an average of 7 milliseconds (ms) of CPU time per request, would have the following estimated costs:

|                  | Monthly Costs | Formula                                                                                                   |
| ---------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
| **Subscription** | $5.00         |                                                                                                           |
| **Requests**     | $1.50         | (15,000,000 requests - 10,000,000 included requests) / 1,000,000 \* $0.30                                 |
| **CPU time**     | $1.50         | ((7 ms of CPU time per request \* 15,000,000 requests) - 30,000,000 included CPU ms) / 1,000,000 \* $0.02 |
| **Total**        | $8.00         |                                                                                                           |

#### Example 2

A project that serves 15 million requests per month, with 80% (12 million) requests serving [static assets](/workers/static-assets/) and the remaining invoking dynamic Worker code. The Worker uses an average of 7 milliseconds (ms) of  time per request.

Requests to static assets are free and unlimited. This project would have the following estimated costs:

|                               | Monthly Costs | Formula |
| ----------------------------- | ------------- | ------- |
| **Subscription**              | $5.00         |         |
| **Requests to static assets** | $0            | -       |
| **Requests to Worker**        | $0            | -       |
| **CPU time**                  | $0            | -       |
| **Total**                     | $5.00         |
|                               |

#### Example 3

A Worker that runs on a [Cron Trigger](/workers/configuration/cron-triggers/) once an hour to collect data from multiple APIs, process the data and create a report.

- 720 requests/month
- 3 minutes (180,000ms) of CPU time per request

In this scenario, the estimated monthly cost would be calculated as:

|                  | Monthly Costs | Formula                                                                                                  |
| ---------------- | ------------- | -------------------------------------------------------------------------------------------------------- |
| **Subscription** | $5.00         |                                                                                                          |
| **Requests**     | $0.00         | -                                                                                                        |
| **CPU time**     | $1.99         | ((180,000 ms of CPU time per request \* 720 requests) - 30,000,000 included CPU ms) / 1,000,000 \* $0.02 |
| **Total**        | $6.99         |                                                                                                          |
|                  |               |                                                                                                          |

#### Example 4

A high traffic Worker that serves 100 million requests per month, and uses an average of 7 milliseconds (ms) of CPU time per request, would have the following estimated costs:

|                  | Monthly Costs | Formula                                                                                                    |
| ---------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
| **Subscription** | $5.00         |                                                                                                            |
| **Requests**     | $27.00        | (100,000,000 requests - 10,000,000 included requests) / 1,000,000 \* $0.30                                 |
| **CPU time**     | $13.40        | ((7 ms of CPU time per request \* 100,000,000 requests) - 30,000,000 included CPU ms) / 1,000,000 \* $0.02 |
| **Total**        | $45.40        |                                                                                                            |

:::note[Custom limits]

To prevent accidental runaway bills or denial-of-wallet attacks, configure the maximum amount of CPU time that can be used per invocation by [defining limits in your Worker's Wrangler file](/workers/wrangler/configuration/#limits), or via the Cloudflare dashboard (**Workers & Pages** > Select your Worker > **Settings** > **CPU Limits**).

If you had a Worker on the Bundled usage model prior to the migration to Standard pricing on March 1, 2024, Cloudflare has automatically added a 50 ms CPU limit on your Worker.

:::

### How to switch usage models

:::note

Some Workers Enterprise customers maintain the ability to change usage models.

:::

Users on the Workers Paid plan have access to the Standard usage model. However, some users may still have a legacy usage model configured.
Legacy usage models include Workers Unbound and Workers Bundled. Users are advised to move to the Workers Standard usage model.
Changing the usage model only affects billable usage, and has no technical implications.

To change your default account-wide usage model:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers-and-pages) and select your account.
2. In Account Home, select **Workers & Pages**.
3. Find **Usage Model** on the right-side menu > **Change**.

Usage models may be changed at the individual Worker level:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/services/view/:worker/production/settings) and select your account.
2. In Account Home, select **Workers & Pages**.
3. In **Overview**, select your Worker > **Settings** > **Usage Model**.

Existing Workers will not be impacted when changing the default usage model. You may change the usage model for individual Workers without affecting your account-wide default usage model.

:::

## Workers Logs

<Render file="workers_logs_pricing" />

:::note[Workers Logs documentation]

For more information and [examples of Workers Logs billing](/workers/observability/logs/workers-logs/#example-pricing), refer to the [Workers Logs documentation](/workers/observability/logs/workers-logs).

:::

## Workers Trace Events Logpush

Workers Logpush is only available on the Workers Paid plan.

|                       | Paid plan                          |
| --------------------- | ---------------------------------- |
| Requests <sup>1</sup> | 10 million / month, +$0.05/million |

<sup>1</sup> Workers Logpush charges for request logs that reach your end
destination after applying filtering or sampling.

## Workers KV

<Render file="kv_pricing" />

:::note[KV documentation]

To learn more about KV, refer to the [KV documentation](/kv/).

:::

## Hyperdrive

<Render file="hyperdrive_pricing" />

:::note[Hyperdrive documentation]

To learn more about Hyperdrive, refer to the [Hyperdrive documentation](/hyperdrive/).

:::

## Queues

<Render file="queues_pricing" />

:::note[Queues billing examples]

To learn more about Queues pricing and review billing examples, refer to [Queues Pricing](/queues/platform/pricing/).

:::

## D1

D1 is available on both the Workers Free and Workers Paid plans.

<Render file="d1-pricing" />

:::note[D1 billing]

Refer to [D1 Pricing](/d1/platform/pricing/) to learn more about how D1 is billed.

:::

## Durable Objects

<Render file="do-plans-note" product="durable-objects"/>

<Render file="durable-objects-pricing" product="durable-objects" params={{product:"workers"}} />

:::note[Durable Objects billing examples]

For more information and [examples of Durable Objects billing](/durable-objects/platform/pricing#compute-billing-examples), refer to [Durable Objects Pricing](/durable-objects/platform/pricing/).

:::

## Vectorize

Vectorize is currently only available on the Workers paid plan.

<Render file="vectorize-pricing" product="vectorize" />

## Service bindings

Requests made from your Worker to another worker via a [Service Binding](/workers/runtime-apis/bindings/service-bindings/) do not incur additional request fees. This allows you to split apart functionality into multiple Workers, without incurring additional costs.

For example, if Worker A makes a subrequest to Worker B via a Service Binding, or calls an RPC method provided by Worker B via a Service Binding, this is billed as:

- One request (for the initial invocation of Worker A)
- The total amount of CPU time used across both Worker A and Worker B

:::note[Only available on Workers Standard pricing]
If your Worker is on the deprecated Bundled or Unbound pricing plans, incoming requests from Service Bindings are charged the same as requests from the Internet. In the example above, you would be charged for two requests, one to Worker A, and one to Worker B.
:::

## Fine Print

Workers Paid plan is separate from any other Cloudflare plan (Free, Professional, Business) you may have. If you are an Enterprise customer, reach out to your account team to confirm pricing details.

Only requests that hit a Worker will count against your limits and your bill. Since Cloudflare Workers runs before the Cloudflare cache, the caching of a request still incurs costs. Refer to [Limits](/workers/platform/limits/) to review definitions and behavior after a limit is hit.

---

# Choose a data or storage product

URL: https://developers.cloudflare.com/workers/platform/storage-options/

import { Render, Details } from "~/components";

This guide describes the storage & database products available as part of Cloudflare Workers, including recommended use-cases and best practices.

## Choose a storage product

The following table maps our storage & database products to common industry terms as well as recommended use-cases:

<Render file="storage-products-table" product="workers" />

Applications can build on multiple storage & database products: for example, using Workers KV for session data; R2 for large file storage, media assets and user-uploaded files; and Hyperdrive to connect to a hosted Postgres or MySQL database.

:::note[Pages Functions]

Storage options can also be used by your front-end application built with Cloudflare Pages. For more information on available storage options for Pages applications, refer to the [Pages Functions bindings documentation](/pages/functions/bindings/).

:::

## SQL database options

There are three options for SQL-based databases available when building applications with Workers.

* **Hyperdrive** if you have an existing Postgres or MySQL database, require large (1TB, 100TB or more) single databases, and/or want to use your existing database tools. You can also connect Hyperdrive to database platforms like [PlanetScale](https://planetscale.com/) or [Neon](https://neon.tech/).
* **D1** for lightweight, serverless applications that are read-heavy, have global users that benefit from D1's [read replication](/d1/best-practices/read-replication/), and do not require you to manage and maintain a traditional RDBMS. You can connect to
* **Durable Objects** for stateful serverless workloads, per-user or per-customer SQL state, and building distributed systems (D1 and Queues are built on Durable Objects) where Durable Object's [strict serializability](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/) enables global ordering of requests and storage operations.

### Session storage

We recommend using [Workers KV](/kv/) for storing session data, credentials (API keys), and/or configuration data. These are typically read at high rates (thousands of RPS or more), are not typically modified (within KV's 1 write RPS per unique key limit), and do not need to be immediately consistent.

Frequently read keys benefit from KV's [internal cache](/kv/concepts/how-kv-works/), and repeated reads to these "hot" keys will typically see latencies in the 500µs to 10ms range.

Authentication frameworks like [OpenAuth](https://openauth.js.org/docs/storage/cloudflare/) use Workers KV as session storage when deployed to Cloudflare, and [Cloudflare Access](/cloudflare-one/policies/access/) uses KV to securely store and distribute user credentials so that they can be validated as close to the user as possible and reduce overall latency.

## Product overviews

### Workers KV

Workers KV is an eventually consistent key-value data store that caches on the Cloudflare global network.

It is ideal for projects that require:

- High volumes of reads and/or repeated reads to the same keys.
- Low-latency global reads (typically within 10ms for hot keys)
- Per-object time-to-live (TTL).
- Distributed configuration and/or session storage.

To get started with KV:

- Read how [KV works](/kv/concepts/how-kv-works/).
- Create a [KV namespace](/kv/concepts/kv-namespaces/).
- Review the [KV Runtime API](/kv/api/).
- Learn about KV [Limits](/kv/platform/limits/).

### R2

R2 is S3-compatible blob storage that allows developers to store large amounts of unstructured data without egress fees associated with typical cloud storage services.

It is ideal for projects that require:

- Storage for files which are infrequently accessed.
- Large object storage (for example, gigabytes or more per object).
- Strong consistency per object.
- Asset storage for websites (refer to [caching guide](/r2/buckets/public-buckets/#caching))

To get started with R2:

- Read the [Get started guide](/r2/get-started/).
- Learn about R2 [Limits](/r2/platform/limits/).
- Review the [R2 Workers API](/r2/api/workers/workers-api-reference/).

### Durable Objects

Durable Objects provide low-latency coordination and consistent storage for the Workers platform through global uniqueness and a transactional storage API.

- Global Uniqueness guarantees that there will be a single instance of a Durable Object class with a given ID running at once, across the world. Requests for a Durable Object ID are routed by the Workers runtime to the Cloudflare data center that owns the Durable Object.

- The transactional storage API provides strongly consistent key-value storage to the Durable Object. Each Object can only read and modify keys associated with that Object. Execution of a Durable Object is single-threaded, but multiple request events may still be processed out-of-order from how they arrived at the Object.

It is ideal for projects that require:

- Real-time collaboration (such as a chat application or a game server).
- Consistent storage.
- Data locality.

To get started with Durable Objects:

- Read the [introductory blog post](https://blog.cloudflare.com/introducing-workers-durable-objects/).
- Review the [Durable Objects documentation](/durable-objects/).
- Get started with [Durable Objects](/durable-objects/get-started/).
- Learn about Durable Objects [Limits](/durable-objects/platform/limits/).

### D1

[D1](/d1/) is Cloudflare’s native serverless database. With D1, you can create a database by importing data or defining your tables and writing your queries within a Worker or through the API.

D1 is ideal for:

- Persistent, relational storage for user data, account data, and other structured datasets.
- Use-cases that require querying across your data ad-hoc (using SQL).
- Workloads with a high ratio of reads to writes (most web applications).

To get started with D1:

- Read [the documentation](/d1)
- Follow the [Get started guide](/d1/get-started/) to provision your first D1 database.
- Review the [D1 Workers Binding API](/d1/worker-api/).

:::note
If your working data size exceeds 10 GB (the maximum size for a D1 database), consider splitting the database into multiple, smaller D1 databases.
:::

### Queues

Cloudflare Queues allows developers to send and receive messages with guaranteed delivery. It integrates with [Cloudflare Workers](/workers) and offers at-least once delivery, message batching, and does not charge for egress bandwidth.

Queues is ideal for:

- Offloading work from a request to schedule later.
- Send data from Worker to Worker (inter-Service communication).
- Buffering or batching data before writing to upstream systems, including third-party APIs or [Cloudflare R2](/queues/examples/send-errors-to-r2/).

To get started with Queues:

- [Set up your first queue](/queues/get-started/).
- Learn more [about how Queues works](/queues/reference/how-queues-works/).

### Hyperdrive

Hyperdrive is a service that accelerates queries you make to MySQL and Postgres databases, making it faster to access your data from across the globe, irrespective of your users’ location.

Hyperdrive allows you to:

- Connect to an existing database from Workers without connection overhead.
- Cache frequent queries across Cloudflare's global network to reduce response times on highly trafficked content.
- Reduce load on your origin database with connection pooling.

To get started with Hyperdrive:

- [Connect Hyperdrive](/hyperdrive/get-started/) to your existing database.
- Learn more [about how Hyperdrive speeds up your database queries](/hyperdrive/configuration/how-hyperdrive-works/).

## Pipelines

Pipelines is a streaming ingestion service that allows you to ingest high volumes of real time data, without managing any infrastructure.

Pipelines allows you to:

- Ingest data at extremely high throughput (tens of thousands of records per second or more)
- Batch and write data directly to object storage, ready for querying
- (Future) Transform and aggregate data during ingestion

To get started with Pipelines:

- [Create a Pipeline](/pipelines/getting-started/) that can batch and write records to R2.
- Learn more [about how Pipelines works](/pipelines/concepts/how-pipelines-work/).

### Analytics Engine

Analytics Engine is Cloudflare's time-series and metrics database that allows you to write unlimited-cardinality analytics at scale using a built-in API to write data points from Workers and query that data using SQL directly.

Analytics Engine allows you to:

- Expose custom analytics to your own customers
- Build usage-based billing systems
- Understand the health of your service on a per-customer or per-user basis
- Add instrumentation to frequently called code paths, without impacting performance or overwhelming external analytics systems with events

Cloudflare uses Analytics Engine internally to store and product per-product metrics for products like D1 and R2 at scale.

To get started with Analytics Engine:

- Learn how to [get started with Analytics Engine](/analytics/analytics-engine/get-started/)
- See [an example of writing time-series data to Analytics Engine](/analytics/analytics-engine/recipes/usage-based-billing-for-your-saas-product/)
- Understand the [SQL API](/analytics/analytics-engine/sql-api/) for reading data from your Analytics Engine datasets

### Vectorize

Vectorize is a globally distributed vector database that enables you to build full-stack, AI-powered applications with Cloudflare Workers and [Workers AI](/workers-ai/).

Vectorize allows you to:

- Store embeddings from any vector embeddings model (Bring Your Own embeddings) for semantic search and classification tasks.
- Add context to Large Language Model (LLM) queries by using vector search as part of a [Retrieval Augmented Generation](/workers-ai/guides/tutorials/build-a-retrieval-augmented-generation-ai/) (RAG) workflow.
- [Filter on vector metadata](/vectorize/reference/metadata-filtering/) to reduce the search space and return more relevant results.

To get started with Vectorize:

- [Create your first vector database](/vectorize/get-started/intro/).
- Combine [Workers AI and Vectorize](/vectorize/get-started/embeddings/) to generate, store and query text embeddings.
- Learn more about [how vector databases work](/vectorize/reference/what-is-a-vector-database/).

<Render file="durable-objects-vs-d1" product="durable-objects" />

---

# Workers for Platforms

URL: https://developers.cloudflare.com/workers/platform/workers-for-platforms/

Deploy custom code on behalf of your users or let your users directly deploy their own code to your platform, managing infrastructure.

---

# Errors and exceptions

URL: https://developers.cloudflare.com/workers/observability/errors/

import { TabItem, Tabs } from "~/components";

Review Workers errors and exceptions.

## Error pages generated by Workers

When a Worker running in production has an error that prevents it from returning a response, the client will receive an error page with an error code, defined as follows:

| Error code | Meaning                                                                                                                                         |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `1101`     | Worker threw a JavaScript exception.                                                                                                            |
| `1102`     | Worker exceeded [CPU time limit](/workers/platform/limits/#cpu-time).                                                                           |
| `1103`     | The owner of this worker needs to contact [Cloudflare Support](/support/contacting-cloudflare-support/)                                         |
| `1015`     | Worker hit the [burst rate limit](/workers/platform/limits/#burst-rate).                                                                        |
| `1019`     | Worker hit [loop limit](#loop-limit).                                                                                                           |
| `1021`     | Worker has requested a host it cannot access.                                                                                                   |
| `1022`     | Cloudflare has failed to route the request to the Worker.                                                                                       |
| `1024`     | Worker cannot make a subrequest to a Cloudflare-owned IP address.                                                                               |
| `1027`     | Worker exceeded free tier [daily request limit](/workers/platform/limits/#daily-request).                                                       |
| `1042`     | Worker tried to fetch from another Worker on the same zone, which is only [supported](/workers/runtime-apis/fetch/) when the [`global_fetch_strictly_public` compatibility flag](/workers/configuration/compatibility-flags/#global-fetch-strictly-public) is used. |

Other `11xx` errors generally indicate a problem with the Workers runtime itself. Refer to the [status page](https://www.cloudflarestatus.com) if you are experiencing an error.

### Loop limit

A Worker cannot call itself or another Worker more than 16 times. In order to prevent infinite loops between Workers, the [`CF-EW-Via`](/fundamentals/reference/http-headers/#cf-ew-via) header's value is an integer that indicates how many invocations are left. Every time a Worker is invoked, the integer will decrement by 1. If the count reaches zero, a [`1019`](#error-pages-generated-by-workers) error is returned.

### "The script will never generate a response" errors

Some requests may return a 1101 error with `The script will never generate a response` in the error message. This occurs when the Workers runtime detects that all the code associated with the request has executed and no events are left in the event loop, but a Response has not been returned.

#### Cause 1: Unresolved Promises

This is most commonly caused by relying on a Promise that is never resolved or rejected, which is required to return a Response. To debug, look for Promises within your code or dependencies' code that block a Response, and ensure they are resolved or rejected.

In browsers and other JavaScript runtimes, equivalent code will hang indefinitely, leading to both bugs and memory leaks. The Workers runtime throws an explicit error to help you debug.

In the example below, the Response relies on a Promise resolution that never happens. Uncommenting the `resolve` callback solves the issue.

```js null {9}
export default {
	fetch(req) {
		let response = new Response("Example response");
		let { promise, resolve } = Promise.withResolvers();

		// If the promise is not resolved, the Workers runtime will
		// recognize this and throw an error.

		// setTimeout(resolve, 0)

		return promise.then(() => response);
	},
};
```

You can prevent this by enforcing the [`no-floating-promises` eslint rule](https://typescript-eslint.io/rules/no-floating-promises/), which reports when a Promise is created and not properly handled.

#### Cause 2: WebSocket connections that are never closed

If a WebSocket is missing the proper code to close its server-side connection, the Workers runtime will throw a `script will never generate a response` error. In the example below, the `'close'` event from the client is not properly handled by calling `server.close()`, and the error is thrown. In order to avoid this, ensure that the WebSocket's server-side connection is properly closed via an event listener or other server-side logic.

```js null {10}
async function handleRequest(request) {
	let webSocketPair = new WebSocketPair();
	let [client, server] = Object.values(webSocketPair);
	server.accept();

	server.addEventListener("close", () => {
		// This missing line would keep a WebSocket connection open indefinitely
		// and results in "The script will never generate a response" errors
		// server.close();
	});

	return new Response(null, {
		status: 101,
		webSocket: client,
	});
}
```

### "Illegal invocation" errors

The error message `TypeError: Illegal invocation: function called with incorrect this reference` can be a source of confusion.

This is typically caused by calling a function that calls `this`, but the value of `this` has been lost.

For example, given an `obj` object with the `obj.foo()` method which logic relies on `this`, executing the method via `obj.foo();` will make sure that `this` properly references the `obj` object. However, assigning the method to a variable, e.g.`const func = obj.foo;` and calling such variable, e.g. `func();` would result in `this` being `undefined`. This is because `this` is lost when the method is called as a standalone function. This is standard behavior in JavaScript.

In practice, this is often seen when destructuring runtime provided Javascript objects that have functions that rely on the presence of `this`, such as `ctx`.

The following code will error:

```js
export default {
	async fetch(request, env, ctx) {
		// destructuring ctx makes waitUntil lose its 'this' reference
		const { waitUntil } = ctx;
		// waitUntil errors, as it has no 'this'
		waitUntil(somePromise);

		return fetch(request);
	},
};
```

Avoid destructuring or re-bind the function to the original context to avoid the error.

The following code will run properly:

```js
export default {
	async fetch(request, env, ctx) {
		// directly calling the method on ctx avoids the error
		ctx.waitUntil(somePromise);

		// alternatively re-binding to ctx via apply, call, or bind avoids the error
		const { waitUntil } = ctx;
		waitUntil.apply(ctx, [somePromise]);
		waitUntil.call(ctx, somePromise);
		const reboundWaitUntil = waitUntil.bind(ctx);
		reboundWaitUntil(somePromise);

		return fetch(request);
	},
};
```

### Cannot perform I/O on behalf of a different request

```
Uncaught (in promise) Error: Cannot perform I/O on behalf of a different request. I/O objects (such as streams, request/response bodies, and others) created in the context of one request handler cannot be accessed from a different request's handler.
```

This error occurs when you attempt to share input/output (I/O) objects (such as streams, requests, or responses) created by one invocation of your Worker in the context of a different invocation.

In Cloudflare Workers, each invocation is handled independently and has its own execution context. This design ensures optimal performance and security by isolating requests from one another. When you try to share I/O objects between different invocations, you break this isolation. Since these objects are tied to the specific request they were created in, accessing them from another request's handler is not allowed and leads to the error.

This error is most commonly caused by attempting to cache an I/O object, like a [Request](/workers/runtime-apis/request/) in global scope, and then access it in a subsequent request. For example, if you create a Worker and run the following code in local development, and make two requests to your Worker in quick succession, you can reproduce this error:

```js
let cachedResponse = null;

export default {
	async fetch(request, env, ctx) {
		if (cachedResponse) {
			return cachedResponse;
		}
		cachedResponse = new Response("Hello, world!");
		await new Promise((resolve) => setTimeout(resolve, 5000)); // Sleep for 5s to demonstrate this particular error case
		return cachedResponse;
	},
};
```

You can fix this by instead storing only the data in global scope, rather than the I/O object itself:

```js
let cachedData = null;

export default {
	async fetch(request, env, ctx) {
		if (cachedData) {
			return new Response(cachedData);
		}
		const response = new Response("Hello, world!");
		cachedData = await response.text();
		return new Response(cachedData, response);
	},
};
```

If you need to share state across requests, consider using [Durable Objects](/durable-objects/). If you need to cache data across requests, consider using [Workers KV](/kv/).

## Errors on Worker upload

These errors occur when a Worker is uploaded or modified.

| Error code | Meaning                                                                                                                         |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `10006`    | Could not parse your Worker's code.                                                                                             |
| `10007`    | Worker or [workers.dev subdomain](/workers/configuration/routing/workers-dev/) not found.                                       |
| `10015`    | Account is not entitled to use Workers.                                                                                         |
| `10016`    | Invalid Worker name.                                                                                                            |
| `10021`    | Validation Error. Refer to [Validation Errors](/workers/observability/errors/#validation-errors-10021) for details.             |
| `10026`    | Could not parse request body.                                                                                                   |
| `10027`    | The uploaded Worker exceeded the [Worker size limits](/workers/platform/limits/#worker-size). |
| `10035`    | Multiple attempts to modify a resource at the same time                                                                         |
| `10037`    | An account has exceeded the number of [Workers allowed](/workers/platform/limits/#number-of-workers).                           |
| `10052`    | A [binding](/workers/runtime-apis/bindings/) is uploaded without a name.                                                        |
| `10054`    | A environment variable or secret exceeds the [size limit](/workers/platform/limits/#environment-variables).                     |
| `10055`    | The number of environment variables or secrets exceeds the [limit/Worker](/workers/platform/limits/#environment-variables).     |
| `10056`    | [Binding](/workers/runtime-apis/bindings/) not found.                                                                           |
| `10068`    | The uploaded Worker has no registered [event handlers](/workers/runtime-apis/handlers/).                                        |
| `10069`    | The uploaded Worker contains [event handlers](/workers/runtime-apis/handlers/) unsupported by the Workers runtime.              |

### Validation Errors (10021)

The 10021 error code includes all errors that occur when you attempt to deploy a Worker, and Cloudflare then attempts to load and run the top-level scope (everything that happens before your Worker's [handler](/workers/runtime-apis/handlers/) is invoked). For example, if you attempt to deploy a broken Worker with invalid JavaScript that would throw a `SyntaxError` — Cloudflare will not deploy your Worker.

Specific error cases include but are not limited to:

#### Script startup exceeded CPU time limit

This means that you are doing work in the top-level scope of your Worker that takes [more than the startup time limit (400ms)](/workers/platform/limits/#worker-startup-time) of CPU time.

This is usually a sign of a bug and/or large performance problem with your code or a dependency you rely on. It's not typical to use more than 400ms of CPU time when your app starts. The more time your Worker's code spends parsing and executing top-level scope, the slower your Worker will be when you deploy a code change or a new [isolate](/workers/reference/how-workers-works/) is created.

This error is most commonly caused by attempting to perform expernsive initialization work directly in top level (global) scope, rather than either at build time or when your Worker's handler is invoked. For example, attempting to initialize an app by generating or consuming a large schema.

To analyze what is consuming so much CPU time, you should open Chrome DevTools for your Worker and look at the Profiling and/or Performance panels to understand where time is being spent. Is there something glaring that consumes tons of CPU time, especially the first time you make a request to your Worker?

## Runtime errors

Runtime errors will occur within the runtime, do not throw up an error page, and are not visible to the end user. Runtime errors are detected by the user with logs.

| Error message                                            | Meaning                                                                                                          |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `Network connection lost`                                | Connection failure. Catch a `fetch` or binding invocation and retry it.                                          |
| `Memory limit`<br/>`would be exceeded`<br/> `before EOF` | Trying to read a stream or buffer that would take you over the [memory limit](/workers/platform/limits/#memory). |
| `daemonDown`                                             | A temporary problem invoking the Worker.                                                                         |

## Identify errors: Workers Metrics

To review whether your application is experiencing any downtime or returning any errors:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. In **Overview**, select your Worker and review your Worker's metrics.

### Worker Errors

The **Errors by invocation status** chart shows the number of errors broken down into the following categories:

| Error                      | Meaning                                                         |
| -------------------------- | --------------------------------------------------------------- |
| `Uncaught Exception`       | Your Worker code threw a JavaScript exception during execution. |
| `Exceeded CPU Time Limits` | Worker exceeded CPU time limit or other resource constraints.   |
| `Exceeded Memory`          | Worker exceeded the memory limit during execution.              |
| `Internal`                 | An internal error occurred in the Workers runtime.              |

The **Client disconnected by type** chart shows the number of client disconnect errors broken down into the following categories:

| Client Disconnects             | Meaning                                                                                                                                                                                          |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Response Stream Disconnected` | Connection was terminated during the deferred proxying stage of a Worker request flow. It commonly appears for longer lived connections such as [WebSockets](/workers/runtime-apis/websockets/). |
| `Cancelled`                    | The Client disconnected before the Worker completed its response.                                                                                                                                |

## Debug exceptions with Workers Logs

[Workers Logs](/workers/observability/logs/workers-logs) is a powerful tool for debugging your Workers. It shows all the historic logs generated by your Worker, including any uncaught exceptions that occur during execution.

To find all your errors in Workers Logs, you can use the following filter: `$metadata.error EXISTS`. This will show all the logs that have an error associated with them. You can also filter by `$workers.outcome` to find the requests that resulted in an error. For example, you can filter by `$workers.outcome = "exception"` to find all the requests that resulted in an uncaught exception.

All the possible outcome values can be found in the [Workers Trace Event](/logs/reference/log-fields/account/workers_trace_events/#outcome) reference.

## Debug exceptions from `Wrangler`

To debug your worker via wrangler use `wrangler tail` to inspect and fix the exceptions.

Exceptions will show up under the `exceptions` field in the JSON returned by `wrangler tail`. After you have identified the exception that is causing errors, redeploy your code with a fix, and continue tailing the logs to confirm that it is fixed.

## Set up a 3rd party logging service

A Worker can make HTTP requests to any HTTP service on the public Internet. You can use a service like [Sentry](https://sentry.io) to collect error logs from your Worker, by making an HTTP request to the service to report the error. Refer to your service’s API documentation for details on what kind of request to make.

When using an external logging strategy, remember that outstanding asynchronous tasks are canceled as soon as a Worker finishes sending its main response body to the client. To ensure that a logging subrequest completes, pass the request promise to [`event.waitUntil()`](https://developer.mozilla.org/en-US/docs/Web/API/ExtendableEvent/waitUntil). For example:

<Tabs> <TabItem label="Module Worker" icon="seti:javascript">

```js
export default {
	async fetch(request, env, ctx) {
		function postLog(data) {
			return fetch("https://log-service.example.com/", {
				method: "POST",
				body: data,
			});
		}

		// Without ctx.waitUntil(), the `postLog` function may or may not complete.
		ctx.waitUntil(postLog(stack));
		return fetch(request);
	},
};
```

</TabItem> <TabItem label="Service Worker" icon="seti:javascript">

:::caution[Service Workers are deprecated]

Service Workers are deprecated, but still supported. We recommend using [Module Workers](/workers/reference/migrate-to-module-workers/) instead. New features may not be supported for Service Workers.

:::

```js
addEventListener("fetch", (event) => {
	event.respondWith(handleEvent(event));
});

async function handleEvent(event) {
	// ...

	// Without event.waitUntil(), the `postLog` function may or may not complete.
	event.waitUntil(postLog(stack));
	return fetch(event.request);
}

function postLog(data) {
	return fetch("https://log-service.example.com/", {
		method: "POST",
		body: data,
	});
}
```

</TabItem> </Tabs>

## Go to origin on error

By using [`event.passThroughOnException`](/workers/runtime-apis/context/#passthroughonexception), a Workers application will forward requests to your origin if an exception is thrown during the Worker's execution. This allows you to add logging, tracking, or other features with Workers, without degrading your application's functionality.

<Tabs> <TabItem label="Module Worker" icon="seti:javascript">

```js
export default {
	async fetch(request, env, ctx) {
		ctx.passThroughOnException();
		// an error here will return the origin response, as if the Worker wasn't present
		return fetch(request);
	},
};
```

</TabItem> <TabItem label="Service Worker" icon="seti:javascript">

:::caution[Service Workers are deprecated]

Service Workers are deprecated, but still supported. We recommend using [Module Workers](/workers/reference/migrate-to-module-workers/) instead. New features may not be supported for Service Workers.

:::

```js
addEventListener("fetch", (event) => {
	event.passThroughOnException();
	event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
	// An error here will return the origin response, as if the Worker wasn’t present.
	// ...
	return fetch(request);
}
```

</TabItem> </Tabs>

## Related resources

- [Log from Workers](/workers/observability/logs/) - Learn how to log your Workers.
- [Logpush](/workers/observability/logs/logpush/) - Learn how to push Workers Trace Event Logs to supported destinations.
- [RPC error handling](/workers/runtime-apis/rpc/error-handling/) - Learn how to handle errors from remote-procedure calls.

---

# Observability

URL: https://developers.cloudflare.com/workers/observability/

import { Badge, DirectoryListing } from "~/components";

Understand how your Worker projects are performing via logs, traces, and other data sources.

<DirectoryListing />

---

# Metrics and analytics

URL: https://developers.cloudflare.com/workers/observability/metrics-and-analytics/

import { GlossaryTooltip } from "~/components"

There are two graphical sources of information about your Workers traffic at a given time: Workers metrics and zone-based Workers analytics.

Workers metrics can help you diagnose issues and understand your Workers' workloads by showing performance and usage of your Workers. If your Worker runs on a route on a zone, or on a few zones, Workers metrics will show how much traffic your Worker is handling on a per-zone basis, and how many requests your site is getting.

Zone analytics show how much traffic all Workers assigned to a zone are handling.

## Workers metrics

Workers metrics aggregate request data for an individual Worker (if your Worker is running across multiple domains, and on `*.workers.dev`, metrics will aggregate requests across them). To view your Worker's metrics:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Compute (Workers)**.
3. In **Overview**, select your Worker to view its metrics.

There are two metrics that can help you understand the health of your Worker in a given moment: requests success and error metrics, and invocation statuses.

### Requests

The first graph shows historical request counts from the Workers runtime broken down into successful requests, errored requests, and subrequests.

* **Total**: All incoming requests registered by a Worker. Requests blocked by [WAF](https://www.cloudflare.com/waf/) or other security features will not count.
* **Success**: Requests that returned a Success or Client Disconnected invocation status.
* **Errors**: Requests that returned a Script Threw Exception, Exceeded Resources, or Internal Error invocation status — refer to [Invocation Statuses](/workers/observability/metrics-and-analytics/#invocation-statuses) for a breakdown of where your errors are coming from.

Request traffic data may display a drop off near the last few minutes displayed in the graph for time ranges less than six hours. This does not reflect a drop in traffic, but a slight delay in aggregation and metrics delivery.

### Subrequests

Subrequests are requests triggered by calling `fetch` from within a Worker. A subrequest that throws an uncaught error will not be counted.

* **Total**: All subrequests triggered by calling `fetch` from within a Worker.
* **Cached**: The number of cached responses returned.
* **Uncached**: The number of uncached responses returned.

### Wall time per execution

<GlossaryTooltip term="wall-clock time">Wall time</GlossaryTooltip> represents the elapsed time in milliseconds between the start of a Worker invocation, and when the Workers runtime determines that no more JavaScript needs to run. Specifically, wall time per execution chart measures the wall time that the JavaScript context remained open — including time spent waiting on I/O, and time spent executing in your Worker's [`waitUntil()`](/workers/runtime-apis/context/#waituntil) handler. Wall time is not the same as the time it takes your Worker to send the final byte of a response back to the client - wall time can be higher, if tasks within `waitUntil()` are still running after the response has been sent, or it can be lower. For example, when returning a response with a large body, the Workers runtime can, in some cases, determine that no more JavaScript needs to run, and closes the JavaScript context before all the bytes have passed through and been sent.

The Wall Time per execution chart shows historical wall time data broken down into relevant quantiles using [reservoir sampling](https://en.wikipedia.org/wiki/Reservoir_sampling). Learn more about [interpreting quantiles](https://www.statisticshowto.com/quantile-definition-find-easy-steps/).

### CPU Time per execution

The CPU Time per execution chart shows historical CPU time data broken down into relevant quantiles using [reservoir sampling](https://en.wikipedia.org/wiki/Reservoir_sampling). Learn more about [interpreting quantiles](https://www.statisticshowto.com/quantile-definition-find-easy-steps/). In some cases, higher quantiles may appear to exceed [CPU time limits](/workers/platform/limits/#cpu-time) without generating invocation errors because of a mechanism in the Workers runtime that allows rollover CPU time for requests below the CPU limit.

### Execution duration (GB-seconds)

The Duration per request chart shows historical [duration](/workers/platform/limits/#duration) per Worker invocation. The data is broken down into relevant quantiles, similar to the CPU time chart. Learn more about [interpreting quantiles](https://www.statisticshowto.com/quantile-definition-find-easy-steps/). Understanding duration on your Worker is especially useful when you are intending to do a significant amount of computation on the Worker itself.

### Invocation statuses

To review invocation statuses:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages**.
3. Select your Worker.
4. Find the **Summary** graph in **Metrics**.
5. Select **Errors**.

Worker invocation statuses indicate whether a Worker executed successfully or failed to generate a response in the Workers runtime. Invocation statuses differ from HTTP status codes. In some cases, a Worker invocation succeeds but does not generate a successful HTTP status because of another error encountered outside of the Workers runtime. Some invocation statuses result in a [Workers error code](/workers/observability/errors/#error-pages-generated-by-workers) being returned to the client.



| Invocation status      | Definition                                                                   | Workers error code | GraphQL field          |
| ---------------------- | ---------------------------------------------------------------------------- | ------------------ | ---------------------- |
| Success                | Worker executed successfully                                                 |                    | `success`              |
| Client disconnected    | HTTP client (that is, the browser) disconnected before the request completed |                    | `clientDisconnected`   |
| Worker threw exception | Worker threw an unhandled JavaScript exception                               | 1101               | `scriptThrewException` |
| Exceeded resources¹    | Worker exceeded runtime limits                                               | 1102, 1027         | `exceededResources`    |
| Internal error²        | Workers runtime encountered an error                                         |                    | `internalError`        |



¹ The Exceeded Resources status may appear when the Worker exceeds a [runtime limit](/workers/platform/limits/#request-limits). The most common cause is excessive CPU time, but is also caused by a Worker exceeding startup time or free tier limits.

² The Internal Error status may appear when the Workers runtime fails to process a request due to an internal failure in our system. These errors are not caused by any issue with the Worker code nor any resource limit. While requests with Internal Error status are rare, some may appear during normal operation. These requests are not counted towards usage for billing purposes. If you notice an elevated rate of requests with Internal Error status, review [www.cloudflarestatus.com](https://www.cloudflarestatus.com/).

To further investigate exceptions, use [`wrangler tail`](/workers/wrangler/commands/#tail).

### Request duration

The request duration chart shows how long it took your Worker to respond to requests, including code execution and time spent waiting on I/O. The request duration chart is currently only available when your Worker has [Smart Placement](/workers/configuration/smart-placement) enabled.

In contrast to [execution duration](/workers/observability/metrics-and-analytics/#execution-duration-gb-seconds), which measures only the time a Worker is active, request duration measures from the time a request comes into a data center until a response is delivered.

The data shows the duration for requests with Smart Placement enabled compared to those with Smart Placement disabled (by default, 1% of requests are routed with Smart Placement disabled). The chart shows a histogram with duration across the x-axis and the percentage of requests that fall into the corresponding duration on the y-axis.

### Metrics retention

Worker metrics can be inspected for up to three months in the past in maximum increments of one week.

## Zone analytics

Zone analytics aggregate request data for all Workers assigned to any [routes](/workers/configuration/routing/routes/) defined for a zone.

To review zone metrics:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select your site.
3. In **Analytics & Logs**, select **Workers**.

Zone data can be scoped by time range within the last 30 days. The dashboard includes charts and information described below.

### Subrequests

This chart shows subrequests — requests triggered by calling `fetch` from within a Worker — broken down by cache status.

* **Uncached**: Requests answered directly by your origin server or other servers responding to subrequests.
* **Cached**: Requests answered by Cloudflare’s [cache](https://www.cloudflare.com/learning/cdn/what-is-caching/). As Cloudflare caches more of your content, it accelerates content delivery and reduces load on your origin.

### Bandwidth

This chart shows historical bandwidth usage for all Workers on a zone broken down by cache status.

### Status codes

This chart shows historical requests for all Workers on a zone broken down by HTTP status code.

### Total requests

This chart shows historical data for all Workers on a zone broken down by successful requests, failed requests, and subrequests. These request types are categorized by HTTP status code where `200`-level requests are successful and `400` to `500`-level requests are failed.

## GraphQL

Worker metrics are powered by GraphQL. Learn more about querying our data sets in the [Querying Workers Metrics with GraphQL tutorial](/analytics/graphql-api/tutorials/querying-workers-metrics/).

---

# Query Builder

URL: https://developers.cloudflare.com/workers/observability/query-builder/

import { TabItem, Tabs, Steps, Render, WranglerConfig, YouTube, Markdown } from "~/components"

The Query Builder helps you write structured queries to investigate and visualize your telemetry data. The Query Builder searches the Workers Observability dataset, which currently includes all logs stored by [Workers Logs](/workers/observability/logs/workers-logs/).

The Query Builder can be found in the [Workers' Observability tab in the Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers-and-pages/observability/investigate/).

<YouTube id="nu4pTU8fR78" />

## Enable Query Builder

The Query Builder is available to all developers and requires no enablement. Queries search all Workers Logs stored by Cloudflare. If you have not yet enabled Workers Logs, you can do so by adding the following setting to your [Worker's Wrangler file](/workers/observability/logs/workers-logs/#enable-workers-logs) and redeploying your Worker.

<WranglerConfig>
	```toml
	[observability]
	enabled = true

	[observability.logs]
	invocation_logs = true
	head_sampling_rate = 1 # optional. default = 1.
	```
</WranglerConfig>

## Write a query in the Cloudflare dashboard

<Steps>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers-and-pages/observability/investigate/) and select your account.
2. In Account Home, go to **Workers & Pages**.
3. Select **Observability** in the left-hand navigation panel, and then the **Investigate** tab.
4. Select a **Visualization**.
5. Optional: Add fields to Filter, Group By, Order By, and Limit. For more information, see what [composes a query](/workers/observability/query-builder/#query-composition).
6. Optional: Select the appropriate time range.
7. Select **Run**. The query will automatically run whenever changes are made.
</Steps>

## Query composition

### Visualization

The Query Builder supports many visualization operators, including:

| Function                   | Arguments | Description |
| ---                        | --- | --- |
| **Count**                  | n/a           | The total number of rows matching the query conditions        |
| **Count Distinct**         | any field     | The number of occurrences of the unique values in the dataset |
| **Min**                    | numeric field | The smallest value for the field in the dataset               |
| **Max**                    | numeric field | The largest value for the field in the dataset                |
| **Sum**                    | numeric field | The total of all of the values for the field in the dataset   |
| **Average**                | numeric field | The average of the field in the dataset                       |
| **Standard Deviation**     | numeric field | The standard deviation of the field in the dataset            |
| **Variance**               | numeric field | The variance of the field in the dataset                      |
| **P001**                   | numeric field | The value of the field below which 0.1% of the data falls     |
| **P01**                    | numeric field | The value of the field below with 1% of the data falls        |
| **P05**                    | numeric field | The value of the field below with 5% of the data falls        |
| **P10**                    | numeric field | The value of the field below with 10% of the data falls       |
| **P25**                    | numeric field | The value of the field below with 25% of the data falls       |
| **Median (P50)**           | numeric field | The value of the field below with 50% of the data falls       |
| **P75**                    | numeric field | The value of the field below with 75% of the data falls       |
| **P90**                    | numeric field | The value of the field below with 90% of the data falls       |
| **P95**                    | numeric field | The value of the field below with 95% of the data falls       |
| **P99**                    | numeric field | The value of the field below with 99% of the data falls       |
| **P999**                   | numeric field | The value of the field below with 99.9% of the data falls     |

You can add multiple visualizations in a single query. Each visualization renders a graph. A single summary table is also returned, which shows the raw query results.

![Example of showing the Query Builder with multiple visualization](~/assets/images/workers-observability/query-builder-visualization.png)

All methods are aggregate functions. Most methods operate on a specific field in the log event. `Count` is an exception, and is an aggregate function that returns the number of log events matching the filter conditions.

### Filter

Filters help return the columns that match the specified conditions. Filters have three components: a key, an operator, and a value.

The key is any field in a log event. For example, you may choose `$workers.cpuTimeMs` or `$metadata.message`.

The operator is a logical condition that evaluates to true or false. See the table below for supported conditions:
| Data Type | Valid Conditions (Operators) |
| --- | --- |
| Numeric | Equals, Does not equal, Greater, Greater or equals, Less, Less or equals, Exists, Does not exist |
| String  | Equals, Does not equal, Includes, Does not include, Regex, Exists, Does not exist, Starts with   |

The value for a numeric field is an integer. The value for a string field is any string.

To add a filter:

<Steps>
1. Select **+** in the **Filter** section.
2. Select **Select key...** and input a key name. For example, `$workers.cpuTimeMs`.
3. Select the operator and change it to the operator best suited. For example, `Greater than`.
4. Select **Select value...** and input a value. For example, `100`.
</Steps>

When you run the query with the filter specified above, only log events where `$workers.cpuTimeMs > 100` will be returned.

Adding multiple filters combines them with an AND operator, meaning that only events matching all the filters will be returned.

### Search

Search is a text filter that returns only events containing the specified text. Search can be helpful as a quick filtering mechanism, or to search for unique identifiable values in your logs.

### Group By

Group By combines rows that have the same value into summary rows. For example, if a query adds `$workers.event.request.cf.country` as a Group By field, then the summary table will group by country.

### Order By

Order By affects how the results are sorted in the summary table. If `asc` is selected, the results are sorted in ascending order - from least to greatest. If `desc` is selected, the results are sorted in descending order - from greatest to least.

### Limit

Limit restricts the number of results returned. When paired with [Order By](/workers/observability/query-builder/#order-by), it can be used to return the "top" or "first" N results.

### Select time range

When you select a time range, you specify the time interval where you want to look for matching events. The retention period is dependent on your [plan type](/workers/observability/logs/workers-logs/#pricing).

## Viewing query results

There are three views for queries: Visualizations, Invocations, and Events.

### Visualizations tab

The **Visualizations** tab shows graphs and a summary table for the query.

![Visualization Overview](~/assets/images/workers-observability/query-builder-visualization.png)

### Invocations tab

The **Invocations** tab shows all logs, grouped by by the invocation, and ordered by timestamp. Only invocations matching the query criteria are returned.

![Invocations Overview](~/assets/images/workers-observability/query-builder-invocations-overview.png)

### Events tab

The **Events** tab shows all logs, ordered by timestamp. Only events matching the query criteria are returned. The Events tab can be customized to add additional fields in the view.

![Overview](~/assets/images/workers-observability/query-builder-events-overview.png)

## Save queries

It is recommended to save queries that may be reused for future investigations. You can save a query with a name, description, and custom tags by selecting **Save Query**. Queries are saved at the account-level and are accessible to all users in the account.

Saved queries can be re-run by selecting the relevant query from the **Queries** tab. You can edit the query and save edits.

Queries can be starred by users. Starred queries are unique to the user, and not to the account.

## Delete queries

Saved queries can be deleted from the **Queries** tab. If you delete a query, the query is deleted for all users in the account.

<Steps>
1. Select the [Queries](https://dash.cloudflare.com/?to=/:account/workers-and-pages/observability/queries) tab in the Observability dashboard.
2. On the right-hand side, select the three dots for additional actions.
3. Select **Delete Query** and follow the instructions.
</Steps>

## Share queries

Saved queries are assigned a unique URL and can be shared with any user in the account.

## Example: Composing a query

In this example, we will construct a query to find and debug all paths that respond with 5xx errors. First, we create a base query. In this base query, we want to visualize by
the raw event count. We can add a filter for `$workers.event.response.status` that is greater than 500.
Then, we group by `$workers.event.request.path` and `$workers.event.response.status` to identify the number of requests that were
affected by this behavior.

![Constructing a query](~/assets/images/workers-observability/query-builder-ex1-query.png)

The results show that the `/actuator/env` path has been experiencing 500s. Now, we can apply a filter for this path and investigate.

![Adding an additional field to the query](~/assets/images/workers-observability/query-builder-ex1-query-with-filter.png)

Now, we can investigate by selecting the **Invocations** tab. We can see that there were two logged invocations of this error.

![Examining the Invocations tab in the Query Builder](~/assets/images/workers-observability/query-builder-ex1-invocations.png)

We can expand a single invocation to view the relevant logs, and continue to debug.

![Viewing the logs for a single Invocation](~/assets/images/workers-observability/query-builder-ex1-invocation-logs.png)

---

# Source maps and stack traces

URL: https://developers.cloudflare.com/workers/observability/source-maps/

import { Render, WranglerConfig } from "~/components";
import { FileTree } from "@astrojs/starlight/components";

<Render file="source-maps" product="workers" />

## Source Maps

To enable source maps, add the following to your Worker's [Wrangler configuration](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
upload_source_maps = true
```

</WranglerConfig>

When `upload_source_maps` is set to `true`, Wrangler will automatically generate and upload source map files when you run [`wrangler deploy`](/workers/wrangler/commands/#deploy) or [`wrangler versions deploy`](/workers/wrangler/commands/#deploy-2).
​​

:::note

Miniflare can also [output source maps](https://miniflare.dev/developing/source-maps) for use in local development or [testing](/workers/testing/miniflare/writing-tests).

:::

## Stack traces

​​
When your Worker throws an uncaught exception, we fetch the source map and use it to map the stack trace of the exception back to lines of your Worker’s original source code.

You can then view the stack trace when streaming [real-time logs](/workers/observability/logs/real-time-logs/) or in [Tail Workers](/workers/observability/logs/tail-workers/).

:::note


The source map is retrieved after your Worker invocation completes — it's an asynchronous process that does not impact your Worker's CPU utilization or performance. Source maps are not accessible inside the Worker at runtime, if you `console.log()` the [stack property](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack) within a Worker, you will not get a deobfuscated stack trace.


:::

When Cloudflare attempts to remap a stack trace to the Worker's source map, it does so line-by-line, remapping as much as possible. If a line of the stack trace cannot be remapped for any reason, Cloudflare will leave that line of the stack trace unchanged, and continue to the next line of the stack trace.

## Limits

:::note[Wrangler version]
Minimum required Wrangler version for source maps: 3.46.0. Check your version by running `wrangler --version`.
:::


| Description                    | Limit         |
| ------------------------------ | ------------- |
| Maximum Source Map Size        | 15 MB gzipped |

## Example

Consider a simple project. `src/index.ts` serves as the entrypoint of the application and `src/calculator.ts` defines a ComplexCalculator class that supports basic arithmetic.

<FileTree>
- wrangler.jsonc
- tsconfig.json
- src
	- calculator.ts
	- index.ts
</FileTree>

Let's see how source maps can simplify debugging an error in the ComplexCalculator class.

![Stack Trace without Source Map remapping](~/assets/images/workers-observability/without-source-map.png)

With **no source maps uploaded**: notice how all the Javascript has been minified to one file, so the stack trace is missing information on file name, shows incorrect line numbers, and incorrectly references `js` instead of `ts`.

![Stack Trace with Source Map remapping](~/assets/images/workers-observability/with-source-map.png)

With **source maps uploaded**: all methods reference the correct files and line numbers.

## Related resources

* [Tail Workers](/workers/observability/logs/logpush/) - Learn how to attach Tail Workers to transform your logs and send them to HTTP endpoints.
* [Real-time logs](/workers/observability/logs/real-time-logs/) - Learn how to capture Workers logs in real-time.
* [RPC error handling](/workers/runtime-apis/rpc/error-handling/) - Learn how exceptions are handled over RPC (Remote Procedure Call).

---

# How Workers works

URL: https://developers.cloudflare.com/workers/reference/how-workers-works/

import { Render, NetworkMap, WorkersIsolateDiagram } from "~/components"

Though Cloudflare Workers behave similarly to [JavaScript](https://www.cloudflare.com/learning/serverless/serverless-javascript/) in the browser or in Node.js, there are a few differences in how you have to think about your code. Under the hood, the Workers runtime uses the [V8 engine](https://www.cloudflare.com/learning/serverless/glossary/what-is-chrome-v8/) — the same engine used by Chromium and Node.js. The Workers runtime also implements many of the standard [APIs](/workers/runtime-apis/) available in most modern browsers.

The differences between JavaScript written for the browser or Node.js happen at runtime. Rather than running on an individual's machine (for example, [a browser application or on a centralized server](https://www.cloudflare.com/learning/serverless/glossary/client-side-vs-server-side/)), Workers functions run on [Cloudflare's global network](https://www.cloudflare.com/network) - a growing global network of thousands of machines distributed across hundreds of locations.

<NetworkMap/>

Each of these machines hosts an instance of the Workers runtime, and each of those runtimes is capable of running thousands of user-defined applications. This guide will review some of those differences.

For more information, refer to the [Cloud Computing without Containers blog post](https://blog.cloudflare.com/cloud-computing-without-containers).

The three largest differences are: Isolates, Compute per Request, and Distributed Execution.

## Isolates

[V8](https://v8.dev) orchestrates isolates: lightweight contexts that provide your code with variables it can access and a safe environment to be executed within. You could even consider an isolate a sandbox for your function to run in.

<Render file="isolate-description" />

<WorkersIsolateDiagram/>

A given isolate has its own scope, but isolates are not necessarily long-lived. An isolate may be spun down and evicted for a number of reasons:

* Resource limitations on the machine.
* A suspicious script - anything seen as trying to break out of the isolate sandbox.
* Individual [resource limits](/workers/platform/limits/).

Because of this, it is generally advised that you not store mutable state in your global scope unless you have accounted for this contingency.

If you are interested in how Cloudflare handles security with the Workers runtime, you can [read more about how Isolates relate to Security and Spectre Threat Mitigation](/workers/reference/security-model/).

## Compute per request

<Render file="compute-per-request" />

## Distributed execution

Isolates are resilient and continuously available for the duration of a request, but in rare instances isolates may be evicted. When a Worker hits official [limits](/workers/platform/limits/) or when resources are exceptionally tight on the machine the request is running on, the runtime will selectively evict isolates after their events are properly resolved.

Like all other JavaScript platforms, a single Workers instance may handle multiple requests including concurrent requests in a single-threaded event loop. That means that other requests may (or may not) be processed during awaiting any `async` tasks (such as `fetch`) if other requests come in while processing a request.
Because there is no guarantee that any two user requests will be routed to the same or a different instance of your Worker, Cloudflare recommends you do not use or mutate global state.

## Related resources

* [`fetch()` handler](/workers/runtime-apis/handlers/fetch/) - Review how incoming HTTP requests to a Worker are passed to the `fetch()` handler.
* [Request](/workers/runtime-apis/request/) - Learn how incoming HTTP requests are passed to the `fetch()` handler.
* [Workers limits](/workers/platform/limits/) - Learn about Workers limits including Worker size, startup time, and more.

---

# How the Cache works

URL: https://developers.cloudflare.com/workers/reference/how-the-cache-works/

Workers was designed and built on top of Cloudflare's global network to allow developers to interact directly with the Cloudflare cache. The cache can provide ephemeral, data center-local storage, as a convenient way to frequently access static or dynamic content.

By allowing developers to write to the cache, Workers provide a way to customize cache behavior on Cloudflare’s CDN. To learn about the benefits of caching, refer to the Learning Center’s article on [What is Caching?](https://www.cloudflare.com/learning/cdn/what-is-caching/).

Cloudflare Workers run before the cache but can also be utilized to modify assets once they are returned from the cache. Modifying assets returned from cache allows for the ability to sign or personalize responses while also reducing load on an origin and reducing latency to the end user by serving assets from a nearby location.

## Interact with the Cloudflare Cache

Conceptually, there are two ways to interact with Cloudflare’s Cache using a Worker:

- Call to [`fetch()`](/workers/runtime-apis/fetch/) in a Workers script. Requests proxied through Cloudflare are cached even without Workers according to a zone’s default or configured behavior (for example, static assets like files ending in `.jpg` are cached by default). Workers can further customize this behavior by:

  - Setting Cloudflare cache rules (that is, operating on the `cf` object of a [request](/workers/runtime-apis/request/)).

- Store responses using the [Cache API](/workers/runtime-apis/cache/) from a Workers script. This allows caching responses that did not come from an origin and also provides finer control by:

  - Customizing cache behavior of any asset by setting headers such as `Cache-Control` on the response passed to `cache.put()`.

  - Caching responses generated by the Worker itself through `cache.put()`.

:::caution[Tiered caching]

The Cache API is not compatible with tiered caching. To take advantage of tiered caching, use the [fetch API](/workers/runtime-apis/fetch/).

:::

### Single file purge assets cached by a worker

When using single-file purge to purge assets cached by a Worker, make sure not to purge the end user URL. Instead, purge the URL that is in the `fetch` request. For example, you have a Worker that runs on `https://example.com/hello` and this Worker makes a `fetch` request to `https://notexample.com/hello`.

As far as cache is concerned, the asset in the `fetch` request (`https://notexample.com/hello`) is the asset that is cached. To purge it, you need to purge `https://notexample.com/hello`.

Purging the end user URL, `https://example.com/hello`, will not work because that is not the URL that cache sees. You need to confirm in your Worker which URL you are actually fetching, so you can purge the correct asset.

In the previous example, `https://notexample.com/hello` is not proxied through Cloudflare. If `https://notexample.com/hello` was proxied ([orange-clouded](/dns/proxy-status/)) through Cloudflare, then you must own `notexample.com` and purge `https://notexample.com/hello` from the `notexample.com` zone.

To better understand the example, review the following diagram:

```mermaid
flowchart TD
accTitle: Single file purge  assets cached by a worker
accDescr: This diagram is meant to help choose how to purge a file.
A("You have a Worker script that runs on <code>https://</code><code>example.com/hello</code> <br> and this Worker makes a <code>fetch</code> request to <code>https://</code><code>notexample.com/hello</code>.") --> B(Is <code>notexample.com</code> <br> an active zone on Cloudflare?)
    B -- Yes --> C(Is <code>https://</code><code>notexample.com/</code> <br> proxied through Cloudflare?)
    B -- No  --> D(Purge <code>https://</code><code>notexample.com/hello</code> <br> from the original <code>example.com</code> zone.)
    C -- Yes --> E(Do you own <br> <code>notexample.com</code>?)
    C -- No --> F(Purge <code>https://</code><code>notexample.com/hello</code> <br> from the original <code>example.com</code> zone.)
    E -- Yes --> G(Purge <code>https://</code><code>notexample.com/hello</code> <br> from the <code>notexample.com</code> zone.)
    E -- No --> H(Sorry, you can not purge the asset. <br> Only the owner of <code>notexample.com</code> can purge it.)
```

### Purge assets stored with the Cache API

Assets stored in the cache through [Cache API](/workers/runtime-apis/cache/) operations can be purged in a couple of ways:

- Call `cache.delete` within a Worker to invalidate the cache for the asset with a matching request variable.

  - Assets purged in this way are only purged locally to the data center the Worker runtime was executed.

- To purge an asset globally, use the standard [cache purge options](/cache/how-to/purge-cache/). Based on cache API implementation, not all cache purge endpoints function for purging assets stored by the Cache API.

  - All assets on a zone can be purged by using the [Purge Everything](/cache/how-to/purge-cache/purge-everything/) cache operation. This purge will remove all assets associated with a Cloudflare zone from cache in all data centers regardless of the method set.

  - [Cache Tags](/cache/how-to/purge-cache/purge-by-tags/#add-cache-tag-http-response-headers) can be added to requests dynamically in a Worker by calling `response.headers.append()` and appending `Cache-Tag` values dynamically to that request. Once set, those tags can be used to selectively purge assets from cache without invalidating all cached assets on a zone.

- Currently, it is not possible to purge a URL stored through Cache API that uses a custom cache key set by a Worker. Instead, use a [custom key created via Cache Rules](/cache/how-to/cache-rules/settings/#cache-key). Alternatively, purge your assets using purge everything, purge by tag, purge by host or purge by prefix.

## Edge versus browser caching

The browser cache is controlled through the `Cache-Control` header sent in the response to the client (the `Response` instance return from the handler). Workers can customize browser cache behavior by setting this header on the response.

Other means to control Cloudflare’s cache that are not mentioned in this documentation include: Page Rules and Cloudflare cache settings. Refer to the [How to customize Cloudflare’s cache](/cache/concepts/customize-cache/) if you wish to avoid writing JavaScript with still some granularity of control.

:::note[What should I use: the Cache API or fetch for caching objects on Cloudflare?]

For requests where Workers are behaving as middleware (that is, Workers are sending a subrequest via `fetch`) it is recommended to use `fetch`. This is because preexisting settings are in place that optimize caching while preventing unintended dynamic caching. For projects where there is no backend (that is, the entire project is on Workers as in [Workers Sites](/workers/configuration/sites/start-from-scratch)) the Cache API is the only option to customize caching.

The asset will be cached under the hostname specified within the Worker's subrequest — not the Worker's own hostname. Therefore, in order to purge the cached asset, the purge will have to be performed for the hostname included in the Worker subrequest.

:::

### `fetch`

In the context of Workers, a [`fetch`](/workers/runtime-apis/fetch/) provided by the runtime communicates with the Cloudflare cache. First, `fetch` checks to see if the URL matches a different zone. If it does, it reads through that zone’s cache (or Worker). Otherwise, it reads through its own zone’s cache, even if the URL is for a non-Cloudflare site. Cache settings on `fetch` automatically apply caching rules based on your Cloudflare settings. `fetch` does not allow you to modify or inspect objects before they reach the cache, but does allow you to modify how it will cache.

When a response fills the cache, the response header contains `CF-Cache-Status: HIT`. You can tell an object is attempting to cache if one sees the `CF-Cache-Status` at all.

This [template](/workers/examples/cache-using-fetch/) shows ways to customize Cloudflare cache behavior on a given request using fetch.

### Cache API

The [Cache API](/workers/runtime-apis/cache/) can be thought of as an ephemeral key-value store, whereby the `Request` object (or more specifically, the request URL) is the key, and the `Response` is the value.

There are two types of cache namespaces available to the Cloudflare Cache:

- **`caches.default`** – You can access the default cache (the same cache shared with `fetch` requests) by accessing `caches.default`. This is useful when needing to override content that is already cached, after receiving the response.
- **`caches.open()`** – You can access a namespaced cache (separate from the cache shared with `fetch` requests) using `let cache = await caches.open(CACHE_NAME)`. Note that [`caches.open`](https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage/open) is an async function, unlike `caches.default`.

When to use the Cache API:

- When you want to programmatically save and/or delete responses from a cache. For example, say an origin is responding with a `Cache-Control: max-age:0` header and cannot be changed. Instead, you can clone the `Response`, adjust the header to the `max-age=3600` value, and then use the Cache API to save the modified `Response` for an hour.

- When you want to programmatically access a Response from a cache without relying on a `fetch` request. For example, you can check to see if you have already cached a `Response` for the `https://example.com/slow-response` endpoint. If so, you can avoid the slow request.

This [template](/workers/examples/cache-api/) shows ways to use the cache API. For limits of the cache API, refer to [Limits](/workers/platform/limits/#cache-api-limits).

:::caution[Tiered caching and the Cache API]

Cache API within Workers does not support tiered caching. Tiered Cache concentrates connections to origin servers so they come from a small number of data centers rather than the full set of network locations. Cache API is local to a data center, this means that `cache.match` does a lookup, `cache.put` stores a response, and `cache.delete` removes a stored response only in the cache of the data center that the Worker handling the request is in. Because these methods apply only to local cache, they will not work with tiered cache.
:::

## Related resources

- [Cache API](/workers/runtime-apis/cache/)
- [Customize cache behavior with Workers](/cache/interaction-cloudflare-products/workers/)

---

# Reference

URL: https://developers.cloudflare.com/workers/reference/

import { DirectoryListing } from "~/components";

Conceptual knowledge about how Workers works.

<DirectoryListing />

---

# Migrate from Service Workers to ES Modules

URL: https://developers.cloudflare.com/workers/reference/migrate-to-module-workers/

import { WranglerConfig } from "~/components";

This guide will show you how to migrate your Workers from the [Service Worker](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API) format to the [ES modules](https://blog.cloudflare.com/workers-javascript-modules/) format.

## Advantages of migrating

There are several reasons to migrate your Workers to the ES modules format:

1. Your Worker will run faster. With service workers, bindings are exposed as globals. This means that for every request, the Workers runtime must create a new JavaScript execution context, which adds overhead and time. Workers written using ES modules can reuse the same execution context across multiple requests.
2. Implementing [Durable Objects](/durable-objects/) requires Workers that use ES modules.
3. Bindings for [D1](/d1/), [Workers AI](/workers-ai/), [Vectorize](/vectorize/), [Workflows](/workflows/), and [Images](/images/transform-images/bindings/) can only be used from Workers that use ES modules.
4. You can [gradually deploy changes to your Worker](/workers/configuration/versions-and-deployments/gradual-deployments/) when you use the ES modules format.
5. You can easily publish Workers using ES modules to `npm`, allowing you to import and reuse Workers within your codebase.

## Migrate a Worker

The following example demonstrates a Worker that redirects all incoming requests to a URL with a `301` status code.

:::caution[Service Workers are deprecated]

Service Workers are deprecated, but still supported. We recommend using [Module Workers](/workers/reference/migrate-to-module-workers/) instead. New features may not be supported for Service Workers.

:::

With the Service Worker syntax, the example Worker looks like:

```js
async function handler(request) {
  const base = 'https://example.com';
  const statusCode = 301;

  const destination = new URL(request.url, base);
  return Response.redirect(destination.toString(), statusCode);
}

// Initialize Worker
addEventListener('fetch', event => {
  event.respondWith(handler(event.request));
});
```

Workers using ES modules format replace the `addEventListener` syntax with an object definition, which must be the file's default export (via `export default`). The previous example code becomes:

```js
export default {
  fetch(request) {
    const base = "https://example.com";
    const statusCode = 301;

    const source = new URL(request.url);
    const destination = new URL(source.pathname, base);
    return Response.redirect(destination.toString(), statusCode);
  },
};
```

## Bindings

[Bindings](/workers/runtime-apis/bindings/) allow your Workers to interact with resources on the Cloudflare developer platform.

Workers using ES modules format do not rely on any global bindings. However, Service Worker syntax accesses bindings on the global scope.

To understand bindings, refer the following `TODO` KV namespace binding example. To create a `TODO` KV namespace binding, you will:

1. Create a KV namespace named `My Tasks` and receive an ID that you will use in your binding.
2. Create a Worker.
3. Find your Worker's [Wrangler configuration file](/workers/wrangler/configuration/) and add a KV namespace binding:

<WranglerConfig>

```toml
kv_namespaces = [
  { binding = "TODO", id = "<ID>" }
]
```

</WranglerConfig>

In the following sections, you will use your binding in Service Worker and ES modules format.

:::note[Reference KV from Durable Objects and Workers]


To learn more about how to reference KV from Workers, refer to the [KV bindings documentation](/kv/concepts/kv-bindings/).


:::

### Bindings in Service Worker format

In Service Worker syntax, your `TODO` KV namespace binding is defined in the global scope of your Worker. Your `TODO` KV namespace binding is available to use anywhere in your Worker application's code.

```js
addEventListener("fetch", async (event) => {
  return await getTodos()
});

async function getTodos() {
  // Get the value for the "to-do:123" key
  // NOTE: Relies on the TODO KV binding that maps to the "My Tasks" namespace.
  let value = await TODO.get("to-do:123");

  // Return the value, as is, for the Response
  event.respondWith(new Response(value));
}
```

### Bindings in ES modules format

In ES modules format, bindings are only available inside the `env` parameter that is provided at the entry point to your Worker.

To access the `TODO` KV namespace binding in your Worker code, the `env` parameter must be passed from the `fetch` handler in your Worker to the `getTodos` function.

```js
import { getTodos } from './todos'

export default {
  async fetch(request, env, ctx) {
    // Passing the env parameter so other functions
    // can reference the bindings available in the Workers application
    return await getTodos(env)
  },
};
```

The following code represents a `getTodos` function that calls the `get` function on the `TODO` KV binding.

```js
async function getTodos(env) {
  // NOTE: Relies on the TODO KV binding which has been provided inside of
  // the env parameter of the `getTodos` function
  let value = await env.TODO.get("to-do:123");
  return new Response(value);
}

export { getTodos }
```

## Environment variables

[Environment variables](/workers/configuration/environment-variables/) are accessed differently in code written in ES modules format versus Service Worker format.

Review the following example environment variable configuration in the [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
name = "my-worker-dev"

# Define top-level environment variables
# under the `[vars]` block using
# the `key = "value"` format
[vars]
API_ACCOUNT_ID = "<EXAMPLE-ACCOUNT-ID>"
```

</WranglerConfig>

### Environment variables in Service Worker format

In Service Worker format, the `API_ACCOUNT_ID` is defined in the global scope of your Worker application. Your `API_ACCOUNT_ID` environment variable is available to use anywhere in your Worker application's code.

```js
addEventListener("fetch", async (event) => {
  console.log(API_ACCOUNT_ID) // Logs "<EXAMPLE-ACCOUNT-ID>"
  return new Response("Hello, world!")
})
```

### Environment variables in ES modules format

In ES modules format, environment variables are only available inside the `env` parameter that is provided at the entrypoint to your Worker application.

```js
export default {
  async fetch(request, env, ctx) {
    console.log(env.API_ACCOUNT_ID) // Logs "<EXAMPLE-ACCOUNT-ID>"
    return new Response("Hello, world!")
  },
};
```

## Cron Triggers

To handle a [Cron Trigger](/workers/configuration/cron-triggers/) event in a Worker written with ES modules syntax, implement a [`scheduled()` event handler](/workers/runtime-apis/handlers/scheduled/#syntax), which is the equivalent of listening for a `scheduled` event in Service Worker syntax.

This example code:

```js
addEventListener("scheduled", (event) => {
  // ...
});
```

Then becomes:

```js
export default {
  async scheduled(event, env, ctx) {
    // ...
  },
};
```

## Access `event` or `context` data

Workers often need access to data not in the `request` object. For example, sometimes Workers use [`waitUntil`](/workers/runtime-apis/context/#waituntil) to delay execution. Workers using ES modules format can access `waitUntil` via the `context` parameter. Refer to [ES modules parameters](/workers/runtime-apis/handlers/fetch/#parameters) for  more information.

This example code:

```js
async function triggerEvent(event) {
  // Fetch some data
  console.log('cron processed', event.scheduledTime);
}

// Initialize Worker
addEventListener('scheduled', event => {
  event.waitUntil(triggerEvent(event));
});
```

Then becomes:

```js
async function triggerEvent(event) {
  // Fetch some data
  console.log('cron processed', event.scheduledTime);
}

export default {
  async scheduled(event, env, ctx) {
    ctx.waitUntil(triggerEvent(event));
  },
};
```

## Service Worker syntax

A Worker written in Service Worker syntax consists of two parts:

1. An event listener that listens for `FetchEvents`.
2. An event handler that returns a [Response](/workers/runtime-apis/response/) object which is passed to the event’s `.respondWith()` method.

When a request is received on one of Cloudflare’s global network servers for a URL matching a Worker, Cloudflare's server passes the request to the Workers runtime. This dispatches a `FetchEvent` in the [isolate](/workers/reference/how-workers-works/#isolates) where the Worker is running.

```js
addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  return new Response('Hello worker!', {
    headers: { 'content-type': 'text/plain' },
  });
}
```

Below is an example of the request response workflow:

1. An event listener for the `FetchEvent` tells the script to listen for any request coming to your Worker. The event handler is passed the `event` object, which includes `event.request`, a [`Request`](/workers/runtime-apis/request/) object which is a representation of the HTTP request that triggered the `FetchEvent`.

2. The call to `.respondWith()` lets the Workers runtime intercept the request in order to send back a custom response (in this example, the plain text `'Hello worker!'`).

   * The `FetchEvent` handler typically culminates in a call to the method `.respondWith()` with either a [`Response`](/workers/runtime-apis/response/) or `Promise<Response>` that determines the response.

   * The `FetchEvent` object also provides [two other methods](/workers/runtime-apis/handlers/fetch/) to handle unexpected exceptions and operations that may complete after a response is returned.

Learn more about [the lifecycle methods of the `fetch()` handler](/workers/runtime-apis/rpc/lifecycle/).

### Supported `FetchEvent` properties



* `event.type` string

  * The type of event. This will always return `"fetch"`.

* `event.request` Request

  * The incoming HTTP request.

* <code>event.respondWith(responseResponse|<span style="margin-left:-6px">Promise</span>)</code> : void

  * Refer to [`respondWith`](#respondwith).

* <code>event.waitUntil(promisePromise)</code> : void

  * Refer to [`waitUntil`](#waituntil).

* <code>event.passThroughOnException()</code> : void

  * Refer to [`passThroughOnException`](#passthroughonexception).



### `respondWith`

Intercepts the request and allows the Worker to send a custom response.

If a `fetch` event handler does not call `respondWith`, the runtime delivers the event to the next registered `fetch` event handler. In other words, while not recommended, this means it is possible to add multiple `fetch` event handlers within a Worker.

If no `fetch` event handler calls `respondWith`, then the runtime forwards the request to the origin as if the Worker did not. However, if there is no origin – or the Worker itself is your origin server, which is always true for `*.workers.dev` domains – then you must call `respondWith` for a valid response.

```js
// Format: Service Worker
addEventListener('fetch', event => {
  let { pathname } = new URL(event.request.url);

  // Allow "/ignore/*" URLs to hit origin
  if (pathname.startsWith('/ignore/')) return;

  // Otherwise, respond with something
  event.respondWith(handler(event));
});
```

### `waitUntil`

The `waitUntil` command extends the lifetime of the `"fetch"` event. It accepts a `Promise`-based task which the Workers runtime will execute before the handler terminates but without blocking the response. For example, this is ideal for [caching responses](/workers/runtime-apis/cache/#put) or handling logging.

With the Service Worker format, `waitUntil` is available within the `event` because it is a native `FetchEvent` property.

With the ES modules format, `waitUntil` is moved and available on the `context` parameter object.

```js
// Format: Service Worker
addEventListener('fetch', event => {
  event.respondWith(handler(event));
});

async function handler(event) {
  // Forward / Proxy original request
  let res = await fetch(event.request);

  // Add custom header(s)
  res = new Response(res.body, res);
  res.headers.set('x-foo', 'bar');

  // Cache the response
  // NOTE: Does NOT block / wait
  event.waitUntil(caches.default.put(event.request, res.clone()));

  // Done
  return res;
}
```

### `passThroughOnException`

The `passThroughOnException` method prevents a runtime error response when the Worker throws an unhandled exception. Instead, the script will [fail open](https://community.microfocus.com/cyberres/b/sws-22/posts/security-fundamentals-part-1-fail-open-vs-fail-closed), which will proxy the request to the origin server as though the Worker was never invoked.

To prevent JavaScript errors from causing entire requests to fail on uncaught exceptions, `passThroughOnException()` causes the Workers runtime to yield control to the origin server.

With the Service Worker format, `passThroughOnException` is added to the `FetchEvent` interface, making it available within the `event`.

With the ES modules format, `passThroughOnException` is available on the `context` parameter object.

```js
// Format: Service Worker
addEventListener('fetch', event => {
  // Proxy to origin on unhandled/uncaught exceptions
  event.passThroughOnException();
  throw new Error('Oops');
});
```

---

# Protocols

URL: https://developers.cloudflare.com/workers/reference/protocols/

Cloudflare Workers support the following protocols and interfaces:

| Protocol               | Inbound                                                                                                                                                                                                                                                                                                          | Outbound                                                                                                     |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **HTTP / HTTPS**       | Handle incoming HTTP requests using the [`fetch()` handler](/workers/runtime-apis/handlers/fetch/)                                                                                                                                                                                                               | Make HTTP subrequests using the [`fetch()` API](/workers/runtime-apis/fetch/)                                |
| **Direct TCP sockets** | Support for handling inbound TCP connections is [coming soon](https://blog.cloudflare.com/workers-tcp-socket-api-connect-databases/)                                                                                                                                                                             | Create outbound TCP connections using the [`connect()` API](/workers/runtime-apis/tcp-sockets/)              |
| **WebSockets**         | Accept incoming WebSocket connections using the [`WebSocket` API](/workers/runtime-apis/websockets/), or with [MQTT over WebSockets (Pub/Sub)](/pub-sub/learning/websockets-browsers/)                                                                                                                           | [MQTT over WebSockets (Pub/Sub)](/pub-sub/learning/websockets-browsers/)                                     |
| **MQTT**               | Handle incoming messages to an MQTT broker with [Pub Sub](/pub-sub/learning/integrate-workers/)                                                                                                                                                                                                                  | Support for publishing MQTT messages to an MQTT topic is [coming soon](/pub-sub/learning/integrate-workers/) |
| **HTTP/3 (QUIC)**      | Accept inbound requests over [HTTP/3](https://www.cloudflare.com/learning/performance/what-is-http3/) by enabling it on your [zone](/fundamentals/concepts/accounts-and-zones/#zones) in **Speed** > **Optimization** > **Protocol Optimization** area of the [Cloudflare dashboard](https://dash.cloudflare.com/). |                                                                                                              |
| **SMTP**               | Use [Email Workers](/email-routing/email-workers/) to process and forward email, without having to manage TCP connections to SMTP email servers                                                                                                                                                                  | [Email Workers](/email-routing/email-workers/)                                                               |

---

# Cache

URL: https://developers.cloudflare.com/workers/runtime-apis/cache/

## Background

The [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache) allows fine grained control of reading and writing from the [Cloudflare global network](https://www.cloudflare.com/network/) cache.

The Cache API is available globally but the contents of the cache do not replicate outside of the originating data center. A `GET /users` response can be cached in the originating data center, but will not exist in another data center unless it has been explicitly created.

:::caution[Tiered caching]

The `cache.put` method is not compatible with tiered caching. Refer to [Cache API](/workers/reference/how-the-cache-works/#cache-api) for more information. To perform tiered caching, use the [fetch API](/workers/reference/how-the-cache-works/#interact-with-the-cloudflare-cache).

:::

Workers deployed to custom domains have access to functional `cache` operations. So do [Pages functions](/pages/functions/), whether attached to custom domains or `*.pages.dev` domains.

However, any Cache API operations in the Cloudflare Workers dashboard editor and [Playground](/workers/playground/) previews will have no impact. For Workers fronted by [Cloudflare Access](https://www.cloudflare.com/teams/access/), the Cache API is not currently available.

:::note

This individualized zone cache object differs from Cloudflare’s Global CDN. For details, refer to [How the cache works](/workers/reference/how-the-cache-works/).

:::

***

## Accessing Cache

The `caches.default` API is strongly influenced by the web browsers’ Cache API, but there are some important differences. For instance, Cloudflare Workers runtime exposes a single global cache object.

```js
let cache = caches.default;
await cache.match(request);
```

You may create and manage additional Cache instances via the [`caches.open`](https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage/open) method.

```js
let myCache = await caches.open('custom:cache');
await myCache.match(request);
```

:::note

When using the cache API, avoid overriding the hostname in cache requests, as this can lead to unnecessary DNS lookups and cache inefficiencies. Always use the hostname that matches the domain associated with your Worker.

```js
// recommended approach: use your Worker hostname to ensure efficient caching
request.url = "https://your-Worker-hostname.com/";

let myCache = await caches.open('custom:cache');
let response = await myCache.match(request);
```

:::

***

## Headers

Our implementation of the Cache API respects the following HTTP headers on the response passed to `put()`:

* `Cache-Control`
  * Controls caching directives. This is consistent with [Cloudflare Cache-Control Directives](/cache/concepts/cache-control#cache-control-directives). Refer to [Edge TTL](/cache/how-to/configure-cache-status-code#edge-ttl) for a list of HTTP response codes and their TTL when `Cache-Control` directives are not present.
* `Cache-Tag`
  * Allows resource purging by tag(s) later.
* `ETag`
  * Allows `cache.match()` to evaluate conditional requests with `If-None-Match`.
* `Expires` string
  * A string that specifies when the resource becomes invalid.
* `Last-Modified`
  * Allows `cache.match()` to evaluate conditional requests with `If-Modified-Since`.

This differs from the web browser Cache API as they do not honor any headers on the request or response.

:::note

Responses with `Set-Cookie` headers are never cached, because this sometimes indicates that the response contains unique data. To store a response with a `Set-Cookie` header, either delete that header or set `Cache-Control: private=Set-Cookie` on the response before calling `cache.put()`.

Use the `Cache-Control` method to store the response without the `Set-Cookie` header.

:::

***

## Methods

### Put

```js
cache.put(request, response);
```

* <code>put(request, response)</code> : Promise

  * Attempts to add a response to the cache, using the given request as the key. Returns a promise that resolves to `undefined` regardless of whether the cache successfully stored the response.

:::note

The `stale-while-revalidate` and `stale-if-error` directives are not supported when using the `cache.put` or `cache.match` methods.

:::

#### Parameters

* `request` string | Request

  * Either a string or a [`Request`](/workers/runtime-apis/request/) object to serve as the key. If a string is passed, it is interpreted as the URL for a new Request object.

* `response` Response
  * A [`Response`](/workers/runtime-apis/response/) object to store under the given key.

#### Invalid parameters

`cache.put` will throw an error if:

* The `request` passed is a method other than `GET`.
* The `response` passed has a `status` of [`206 Partial Content`](https://www.webfx.com/web-development/glossary/http-status-codes/what-is-a-206-status-code/).
* The `response` passed contains the header `Vary: *`. The value of the `Vary` header is an asterisk (`*`). Refer to the [Cache API specification](https://w3c.github.io/ServiceWorker/#cache-put) for more information.

#### Errors

`cache.put` returns a `413` error if `Cache-Control` instructs not to cache or if the response is too large.

### `Match`

```js
cache.match(request, options);
```

* <code>match(request, options)</code> : Promise`<Response | undefined>`

  * Returns a promise wrapping the response object keyed to that request.

:::note

The `stale-while-revalidate` and `stale-if-error` directives are not supported when using the `cache.put` or `cache.match` methods.
:::


#### Parameters

* `request` string | Request

  * The string or [`Request`](/workers/runtime-apis/request/) object used as the lookup key. Strings are interpreted as the URL for a new `Request` object.

* `options`
  * Can contain one possible property: `ignoreMethod` (Boolean). When `true`, the request is considered to be a `GET` request regardless of its actual value.

Unlike the browser Cache API, Cloudflare Workers do not support the `ignoreSearch` or `ignoreVary` options on `match()`. You can accomplish this behavior by removing query strings or HTTP headers at `put()` time.

Our implementation of the Cache API respects the following HTTP headers on the request passed to `match()`:

* `Range`

  * Results in a `206` response if a matching response with a Content-Length header is found. Your Cloudflare cache always respects range requests, even if an `Accept-Ranges` header is on the response.

* `If-Modified-Since`

  * Results in a `304` response if a matching response is found with a `Last-Modified` header with a value after the time specified in `If-Modified-Since`.

* `If-None-Match`

  * Results in a `304` response if a matching response is found with an `ETag` header with a value that matches a value in `If-None-Match`.

* `cache.match()`
  * Never sends a subrequest to the origin. If no matching response is found in cache, the promise that `cache.match()` returns is fulfilled with `undefined`.


#### Errors

`cache.match` generates a `504` error response when the requested content is missing or expired. The Cache API does not expose this `504` directly to the Worker script, instead returning `undefined`. Nevertheless, the underlying `504` is still visible in Cloudflare Logs.

If you use Cloudflare Logs, you may see these `504` responses with the `RequestSource` of `edgeWorkerCacheAPI`. Again, these are expected if the cached asset was missing or expired. Note that `edgeWorkerCacheAPI` requests are already filtered out in other views, such as Cache Analytics. To filter out these requests or to filter requests by end users of your website only, refer to [Filter end users](/analytics/graphql-api/features/filtering/#filter-end-users).

### `Delete`

```js
cache.delete(request, options);
```

* <code>delete(request, options)</code> : Promise`<boolean>`

Deletes the `Response` object from the cache and returns a `Promise` for a Boolean response:

* `true`: The response was cached but is now deleted
* `false`: The response was not in the cache at the time of deletion.

:::caution[Global purges]

The `cache.delete` method only purges content of the cache in the data center that the Worker was invoked. For global purges, refer to [Purging assets stored with the Cache API](/workers/reference/how-the-cache-works/#purge-assets-stored-with-the-cache-api).

:::

#### Parameters

* `request` string | Request

  * The string or [`Request`](/workers/runtime-apis/request/) object used as the lookup key. Strings are interpreted as the URL for a new `Request` object.

* `options` object
  * Can contain one possible property: `ignoreMethod` (Boolean). Consider the request method a GET regardless of its actual value.

***

## Related resources

* [How the cache works](/workers/reference/how-the-cache-works/)
* [Example: Cache using `fetch()`](/workers/examples/cache-using-fetch/)
* [Example: using the Cache API](/workers/examples/cache-api/)
* [Example: caching POST requests](/workers/examples/cache-post-request/)

---

# Security model

URL: https://developers.cloudflare.com/workers/reference/security-model/

import { WorkersArchitectureDiagram } from "~/components"

This article includes an overview of Cloudflare security architecture, and then addresses two frequently asked about issues: V8 bugs and Spectre.

Since the very start of the Workers project, security has been a high priority — there was a concern early on that when hosting a large number of tenants on shared infrastructure, side channels of various kinds would pose a threat. The Cloudflare Workers runtime is carefully designed to defend against side channel attacks.

To this end, Workers is designed to make it impossible for code to measure its own execution time locally. For example, the value returned by `Date.now()` is locked in place while code is executing. No other timers are provided. Moreover, Cloudflare provides no access to concurrency (for example, multi-threading), as it could allow attackers to construct ad hoc timers. These design choices cannot be introduced retroactively into other platforms — such as web browsers — because they remove APIs that existing applications depend on. They were possible in Workers only because of runtime design choices from the start.

While these early design decisions have proven effective, Cloudflare is continuing to add defense-in-depth, including techniques to disrupt attacks by rescheduling Workers to create additional layers of isolation between suspicious Workers and high-value Workers.

The Workers approach is very different from the approach taken by most of the industry. It is resistant to the entire range of [Spectre-style attacks](https://www.cloudflare.com/learning/security/threats/meltdown-spectre/), without requiring special attention paid to each one and without needing to block speculation in general. However, because the Workers approach is different, it requires careful study. Cloudflare is currently working with researchers at Graz University of Technology (TU Graz) to study what has been done. These researchers include some of the people who originally discovered Spectre. Cloudflare will publish the results of this research as they becomes available.

For more details, refer to [this talk](https://www.infoq.com/presentations/cloudflare-v8/) by Kenton Varda, architect of Cloudflare Workers. Spectre is covered near the end.

## Architectural overview

Beginning with a quick overview of the Workers runtime architecture:

<WorkersArchitectureDiagram/>

There are two fundamental parts of designing a code sandbox: secure isolation and API design.

### Isolation

First, a secure execution environment needed to be created wherein code cannot access anything it is not supposed to.

For this, the primary tool is V8, the JavaScript engine developed by Google for use in Chrome. V8 executes code inside isolates, which prevent that code from accessing memory outside the isolate — even within the same process. Importantly, this means Cloudflare can run many isolates within a single process. This is essential for an edge compute platform like Workers where Cloudflare must host many thousands of guest applications on every machine and rapidly switch between these guests thousands of times per second with minimal overhead. If Cloudflare had to run a separate process for every guest, the number of tenants Cloudflare could support would be drastically reduced, and Cloudflare would have to limit edge compute to a small number of big Enterprise customers. With isolate technology, Cloudflare can make edge compute available to everyone.

Sometimes, though, Cloudflare does decide to schedule a Worker in its own private process. Cloudflare does this if the Worker uses certain features that needs an extra layer of isolation. For example, when a developer uses the devtools debugger to inspect their Worker, Cloudflare runs that Worker in a separate process. This is because historically, in the browser, the inspector protocol has only been usable by the browser’s trusted operator, and therefore has not received as much security scrutiny as the rest of V8. In order to hedge against the increased risk of bugs in the inspector protocol, Cloudflare moves inspected Workers into a separate process with a process-level sandbox. Cloudflare also uses process isolation as an extra defense against Spectre.

Additionally, even for isolates that run in a shared process with other isolates, Cloudflare runs multiple instances of the whole runtime on each machine, which is called cordons. Workers are distributed among cordons by assigning each Worker a level of trust and separating low-trusted Workers from those trusted more highly. As one example of this in operation: a customer who signs up for the Free plan will not be scheduled in the same process as an Enterprise customer. This provides some defense-in-depth in the case a zero-day security vulnerability is found in V8.

At the whole-process level, Cloudflare applies another layer of sandboxing for defense in depth. The layer 2 sandbox uses Linux namespaces and `seccomp` to prohibit all access to the filesystem and network. Namespaces and `seccomp` are commonly used to implement containers. However, Cloudflare's use of these technologies is much stricter than what is usually possible in container engines, because Cloudflare configures namespaces and `seccomp` after the process has started but before any isolates have been loaded. This means, for example, Cloudflare can (and does) use a totally empty filesystem (mount namespace) and uses `seccomp` to block absolutely all filesystem-related system calls. Container engines cannot normally prohibit all filesystem access because doing so would make it impossible to use `exec()` to start the guest program from disk. In the Workers case, Cloudflare's guest programs are not native binaries and the Workers runtime itself has already finished loading before Cloudflare blocks filesystem access.

The layer 2 sandbox also totally prohibits network access. Instead, the process is limited to communicating only over local UNIX domain sockets to talk to other processes on the same system. Any communication to the outside world must be mediated by some other local process outside the sandbox.

One such process in particular, which is called the supervisor, is responsible for fetching Worker code and configuration from disk or from other internal services. The supervisor ensures that the sandbox process cannot read any configuration except that which is relevant to the Workers that it should be running.

For example, when the sandbox process receives a request for a Worker it has not seen before, that request includes the encryption key for that Worker’s code, including attached secrets. The sandbox can then pass that key to the supervisor in order to request the code. The sandbox cannot request any Worker for which it has not received the appropriate key. It cannot enumerate known Workers. It also cannot request configuration it does not need; for example, it cannot request the TLS key used for HTTPS traffic to the Worker.

Aside from reading configuration, the other reason for the sandbox to talk to other processes on the system is to implement APIs exposed to Workers.

### API design

There is a saying: If a tree falls in the forest, but no one is there to hear it, does it make a sound? A Cloudflare saying: If a Worker executes in a fully-isolated environment in which it is totally prevented from communicating with the outside world, does it actually run?

Complete code isolation is, in fact, useless. In order for Workers to do anything useful, they have to be allowed to communicate with users. At the very least, a Worker needs to be able to receive requests and respond to them. For Workers to send requests to the world safely, APIs are needed.

In the context of sandboxing, API design takes on a new level of responsibility. Cloudflare APIs define exactly what a Worker can and cannot do. Cloudflare must be very careful to design each API so that it can only express allowed operations and no more. For example, Cloudflare wants to allow Workers to make and receive HTTP requests, while not allowing them to be able to access the local filesystem or internal network services.

Currently, Workers does not allow any access to the local filesystem. Therefore, Cloudflare does not expose a filesystem API at all. No API means no access.

But, imagine if Workers did want to support local filesystem access in the future. How can that be done? Workers should not see the whole filesystem. Imagine, though, if each Worker had its own private directory on the filesystem where it can store whatever it wants.

To do this, Workers would use a design based on [capability-based security](https://en.wikipedia.org/wiki/Capability-based_security). Capabilities are a big topic, but in this case, what it would mean is that Cloudflare would give the Worker an object of type `Directory`, representing a directory on the filesystem. This object would have an API that allows creating and opening files and subdirectories, but does not permit traversing up the parent directory. Effectively, each Worker would see its private `Directory` as if it were the root of their own filesystem.

How would such an API be implemented? As described above, the sandbox process cannot access the real filesystem. Instead, file access would be mediated by the supervisor process. The sandbox talks to the supervisor using [Cap’n Proto RPC](https://capnproto.org/rpc.html), a capability-based RPC protocol. (Cap’n Proto is an open source project currently maintained by the Cloudflare Workers team.) This protocol makes it very easy to implement capability-based APIs, so that Cloudflare can strictly limit the sandbox to accessing only the files that belong to the Workers it is running.

Now what about network access? Today, Workers are allowed to talk to the rest of the world only via HTTP — both incoming and outgoing. There is no API for other forms of network access, therefore it is prohibited; although, Cloudflare plans to support other protocols in the future.

As mentioned before, the sandbox process cannot connect directly to the network. Instead, all outbound HTTP requests are sent over a UNIX domain socket to a local proxy service. That service implements restrictions on the request. For example, it verifies that the request is either addressed to a public Internet service or to the Worker’s zone’s own origin server, not to internal services that might be visible on the local machine or network. It also adds a header to every request identifying the Worker from which it originates, so that abusive requests can be traced and blocked. Once everything is in order, the request is sent on to the Cloudflare network's HTTP caching layer and then out to the Internet.

Similarly, inbound HTTP requests do not go directly to the Workers runtime. They are first received by an inbound proxy service. That service is responsible for TLS termination (the Workers runtime never sees TLS keys), as well as identifying the correct Worker script to run for a particular request URL. Once everything is in order, the request is passed over a UNIX domain socket to the sandbox process.

## V8 bugs and the patch gap

Every non-trivial piece of software has bugs and sandboxing technologies are no exception. Virtual machines, containers, and isolates — which Workers use — also have bugs.

Workers rely heavily on isolation provided by V8, the JavaScript engine built by Google for use in Chrome. This has pros and cons. On one hand, V8 is an extraordinarily complicated piece of technology, creating a wider attack surface than virtual machines. More complexity means more opportunities for something to go wrong. However, an extraordinary amount of effort goes into finding and fixing V8 bugs, owing to its position as arguably the most popular sandboxing technology in the world. Google regularly pays out 5-figure bounties to anyone finding a V8 sandbox escape. Google also operates fuzzing infrastructure that automatically finds bugs faster than most humans can. Google’s investment does a lot to minimize the danger of V8 zero-days — bugs that are found by malicious actors and not known to Google.

But, what happens after a bug is found and reported? V8 is open source, so fixes for security bugs are developed in the open and released to everyone at the same time. It is important that any patch be rolled out to production as fast as possible, before malicious actors can develop an exploit.

The time between publishing the fix and deploying it is known as the patch gap. Google previously [announced that Chrome’s patch gap had been reduced from 33 days to 15 days](https://www.zdnet.com/article/google-cuts-chrome-patch-gap-in-half-from-33-to-15-days/).

Fortunately, Cloudflare directly controls the machines on which the Workers runtime operates. Nearly the entire build and release process has been automated, so the moment a V8 patch is published, Cloudflare systems automatically build a new release of the Workers runtime and, after one-click sign-off from the necessary (human) reviewers, automatically push that release out to production.

As a result, the Workers patch gap is now under 24 hours. A patch published by V8’s team in Munich during their work day will usually be in production before the end of the US work day.

## Spectre: Introduction

The V8 team at Google has stated that [V8 itself cannot defend against Spectre](https://arxiv.org/abs/1902.05178). Workers does not need to depend on V8 for this. The Workers environment presents many alternative approaches to mitigating Spectre.

### What is it?

Spectre is a class of attacks in which a malicious program can trick the CPU into speculatively performing computation using data that the program is not supposed to have access to. The CPU eventually realizes the problem and does not allow the program to see the results of the speculative computation. However, the program may be able to derive bits of the secret data by looking at subtle side effects of the computation, such as the effects on the cache.

For more information about Spectre, refer to the [Learning Center page on the topic](https://www.cloudflare.com/learning/security/threats/meltdown-spectre/).

### Why does it matter for Workers?

Spectre encompasses a wide variety of vulnerabilities present in modern CPUs. The specific vulnerabilities vary by architecture and model and it is likely that many vulnerabilities exist which have not yet been discovered.

These vulnerabilities are a problem for every cloud compute platform. Any time you have more than one tenant running code on the same machine, Spectre attacks are possible. However, the closer together the tenants are, the more difficult it can be to mitigate specific vulnerabilities. Many of the known issues can be mitigated at the kernel level (protecting processes from each other) or at the hypervisor level (protecting VMs), often with the help of CPU microcode updates and various defenses (many of which can come with serious performance impact).

In Cloudflare Workers, tenants are isolated from each other using V8 isolates — not processes nor VMs. This means that Workers cannot necessarily rely on OS or hypervisor patches to prevent Spectre. Workers need its own strategy.

### Why not use process isolation?

Cloudflare Workers is designed to run your code in every single Cloudflare location.

Workers is designed to be a platform accessible to everyone. It needs to handle a huge number of tenants, where many tenants get very little traffic.

Combine these two points and planning becomes difficult.

A typical, non-edge serverless provider could handle a low-traffic tenant by sending all of that tenant’s traffic to a single machine, so that only one copy of the application needs to be loaded. If the machine can handle, say, a dozen tenants, that is plenty. That machine can be hosted in a massive data center with millions of machines, achieving economies of scale. However, this centralization incurs latency and worldwide bandwidth costs when the users are not nearby.

With Workers, on the other hand, every tenant, regardless of traffic level, currently runs in every Cloudflare location. And in the quest to get as close to the end user as possible, Cloudflare sometimes chooses locations that only have space for a limited number of machines. The net result is that Cloudflare needs to be able to host thousands of active tenants per machine, with the ability to rapidly spin up inactive ones on-demand. That means that each guest cannot take more than a couple megabytes of memory — hardly enough space for a call stack, much less everything else that a process needs.

Moreover, Cloudflare need context switching to be computationally efficient. Many Workers resident in memory will only handle an event every now and then, and many Workers spend less than a fraction of a millisecond on any particular event. In this environment, a single core can easily find itself switching between thousands of different tenants every second. To handle one event, a significant amount of communication needs to happen between the guest application and its host, meaning still more switching and communications overhead. If each tenant lives in its own process, all this overhead is orders of magnitude larger than if many tenants live in a single process. When using strict process isolation in Workers, the CPU cost can easily be 10x what it is with a shared process.

In order to keep Workers inexpensive, fast, and accessible to everyone, Cloudflare needed to find a way to host multiple tenants in a single process.

### There is no fix for Spectre

Spectre does not have an official solution. Not even when using heavyweight virtual machines. Everyone is still vulnerable.

The industry encounters new Spectre attacks. Every couple months, researchers uncover a new Spectre vulnerability, CPU vendors release new microcode, and OS vendors release kernel patches. Everyone must continue updating.

But is it enough to merely deploy the latest patches?

More vulnerabilities exist but have not yet been publicized. To defend against Spectre, Cloudflare needed to take a different approach. It is not enough to block individual known vulnerabilities. Instead, entire classes of vulnerabilities must be addressed at once.

### Building a defense

It is unlikely that any all-encompassing fix for Spectre will be found. However, the following thought experiment raises points to consider:

Fundamentally, all Spectre vulnerabilities use side channels to detect hidden processor state. Side channels, by definition, involve observing some non-deterministic behavior of a system. Conveniently, most software execution environments try hard to eliminate non-determinism, because non-deterministic execution makes applications unreliable.

However, there are a few sorts of non-determinism that are still common. The most obvious among these is timing. The industry long ago gave up on the idea that a program should take the same amount of time every time it runs, because deterministic timing is fundamentally at odds with heuristic performance optimization. Most Spectre attacks focus on timing as a way to detect the hidden microarchitectural state of the CPU.

Some have proposed that this can be solved by making timers inaccurate or adding random noise. However, it turns out that this does not stop attacks; it only makes them slower. If the timer tracks real time at all, then anything you can do to make it inaccurate can be overcome by running an attack multiple times and using statistics to filter out inconsistencies.

Many security researchers see this as the end of the story. What good is slowing down an attack if the attack is still possible?

### Cascading slow-downs

However, measures that slow down an attack can be powerful.

The key insight is this: as an attack becomes slower, new techniques become practical to make it even slower still. The goal, then, is to chain together enough techniques that an attack becomes so slow as to be uninteresting.

Much of cryptography, after all, is technically vulnerable to brute force attacks — technically, with enough time, you can break it. But when the time required is thousands (or even billions) of years, this is a sufficient defense.

What can be done to slow down Spectre attacks to the point of meaninglessness?

## Freezing a Spectre attack

### Step 0: Do not allow native code

Workers does not allow our customers to upload native-code binaries to run on the Cloudflare network — only JavaScript and WebAssembly. Many other languages, like Python, Rust, or even Cobol, can be compiled or transpiled to one of these two formats. Both are passed through V8 to convert these formats into true native code.

This, in itself, does not necessarily make Spectre attacks harder. However, this is presented as step 0 because it is fundamental to enabling the following steps.

Accepting native code programs implies being beholden to an existing CPU architecture (typically, x86). In order to execute code with reasonable performance, it is usually necessary to run the code directly on real hardware, severely limiting the host’s control over how that execution plays out. For example, a kernel or hypervisor has no ability to prohibit applications from invoking the `CLFLUSH` instruction, an instruction [which is useful in side channel attacks](https://gruss.cc/files/flushflush.pdf) and almost nothing else.

Moreover, supporting native code typically implies supporting whole existing operating systems and software stacks, which bring with them decades of expectations about how the architecture works under them. For example, x86 CPUs allow a kernel or hypervisor to disable the RDTSC instruction, which reads a high-precision timer. Realistically, though, disabling it will break many programs because they are implemented to use RDTSC any time they want to know the current time.

Supporting native code would limit choice in future mitigation techniques. There is greater freedom in using an abstract intermediate format.

### Step 1: Disallow timers and multi-threading

In Workers, you can get the current time using the JavaScript Date API by calling `Date.now()`. However, the time value returned is not the current time. `Date.now()` returns the time of the last I/O. It does not advance during code execution. For example, if an attacker writes:

```js
let start = Date.now();
for (let i = 0; i < 1e6; i++) {
  doSpectreAttack();
}
let end = Date.now();
```

The values of `start` and `end` will always be exactly the same. The attacker cannot use `Date` to measure the execution time of their code, which they would need to do to carry out an attack.

:::note

This measure was implemented in mid-2017, before Spectre was announced. This measure was implemented because Cloudflare was already concerned about side channel timing attacks. The Workers team has designed the system with side channels in mind.
:::

Similarly, multi-threading and shared memory are not permitted in Workers. Everything related to the processing of one event happens on the same thread. Otherwise, one would be able to race threads in order to guess and check the underlying timer. Multiple Workers are not allowed to operate on the same request concurrently. For example, if you have installed a Cloudflare App on your zone which is implemented using Workers, and your zone itself also uses Workers, then a request to your zone may actually be processed by two Workers in sequence. These run in the same thread.

At this point, measuring code execution time locally is prevented. However, it can still be measured remotely. For example, the HTTP client that is sending a request to trigger the execution of the Worker can measure how long it takes for the Worker to respond. Such a measurement is likely to be very noisy, as it would have to traverse the Internet and incur general networking costs. Such noise can be overcome, in theory, by executing the attack many times and taking an average.

:::note

It has been suggested that if Workers reset its execution environment on every request, that Workers would be in a much safer position against timing attacks. Unfortunately, it is not so simple. The execution state could be stored in a client — not the Worker itself — allowing a Worker to resume its previous state on every new request.
:::

In adversarial testing and with help from leading Spectre experts, Cloudflare has not been able to develop a remote timing attack that works in production. However, the lack of a working attack does not mean that Workers should stop building defenses. Instead, the Workers team is currently testing some more advanced measures.

### Step 2: Dynamic process isolation

If an attack is possible at all, it would take a long time to run — hours at the very least, maybe as long as weeks. But once an attack has been running even for a second, there is a large amount of new data that can be used to trigger further measures.

Spectre attacks exhibit abnormal behavior that would not usually be seen in a normal program. These attacks intentionally try to create pathological performance scenarios in order to amplify microarchitectural effects. This is especially true when the attack has already been forced to run billions of times in a loop in order to overcome other mitigations, like those discussed above. This tends to show up in metrics like CPU performance counters.

Now, the usual problem with using performance metrics to detect Spectre attacks is that there are sometimes false positives. Sometimes, a legitimate program behaves poorly. The runtime cannot shut down every application that has poor performance.

Instead, the runtime chooses to reschedule any Worker with suspicious performance metrics into its own process. As described above, the runtime cannot do this with every Worker because the overhead would be too high. However, it is acceptable to isolate a few Worker processes as a defense mechanism. If the Worker is legitimate, it will keep operating, with a little more overhead. Fortunately, Cloudflare can relocate a Worker into its own process at basically any time.

In fact, elaborate performance-counter based triggering may not even be necessary here. If a Worker uses a large amount of CPU time per event, then the overhead of isolating it in its own process is relatively less because it switches context less often. So, the runtime might as well use process isolation for any Worker that is CPU-hungry.

Once a Worker is isolated, Cloudflare can rely on the operating system’s Spectre defenses, as most desktop web browsers do.

Cloudflare has been working with the experts at Graz Technical University to develop this approach. TU Graz’s team co-discovered Spectre itself and has been responsible for a huge number of the follow-on discoveries since then. Cloudflare has developed the ability to dynamically isolate Workers and has identified metrics which reliably detect attacks.

As mentioned previously, process isolation is not a complete defense. Over time, Spectre attacks tend to be slower to carry out which means Cloudflare has the ability to reasonably guess and identify malicious actors. Isolating the process further slows down the potential attack.

### Step 3: Periodic whole-memory shuffling

At this point, all known attacks have been prevented. This leaves Workers susceptible to unknown attacks in the future, as with all other CPU-based systems. However, all new attacks will generally be very slow, taking days or longer, leaving Cloudflare with time to prepare a defense.

For example, it is within reason to restart the entire Workers runtime on a daily basis. This will reset the locations of everything in memory, forcing attacks to restart the process of discovering the locations of secrets. Cloudflare can also reschedule Workers across physical machines or cordons, so that the window to attack any particular neighbor is limited.

In general, because Workers are fundamentally preemptible (unlike containers or VMs), Cloudflare has a lot of freedom to frustrate attacks.

Cloudflare sees this as an ongoing investment — not something that will ever be done.

---

# Console

URL: https://developers.cloudflare.com/workers/runtime-apis/console/

The `console` object provides a set of methods to help you emit logs, warnings, and debug code.

All standard [methods of the `console` API](https://developer.mozilla.org/en-US/docs/Web/API/console) are present on the `console` object in Workers.

However, some methods are no ops — they can be called, and do not emit an error, but do not do anything. This ensures compatibility with libraries which may use these APIs.

The table below enumerates each method, and the extent to which it is supported in Workers.

All methods noted as "✅ supported" have the following behavior:

* They will be written to the console in local dev (`npx wrangler@latest dev`)
* They will appear in live logs, when tailing logs in the dashboard or running [`wrangler tail`](https://developers.cloudflare.com/workers/observability/log-from-workers/#use-wrangler-tail)
* They will create entries in the `logs` field of [Tail Worker](https://developers.cloudflare.com/workers/observability/tail-workers/) events and [Workers Trace Events](https://developers.cloudflare.com/logs/reference/log-fields/account/workers_trace_events/), which can be pushed to a destination of your choice via [Logpush](https://developers.cloudflare.com/workers/observability/logpush/).

All methods noted as "🟡 partial support" have the following behavior:

* In both production and local development the method can be safely called, but will do nothing (no op)
* In the [Workers Playground](https://workers.cloudflare.com/playground), Quick Editor in the Workers dashboard, and remote preview mode (`wrangler dev --remote`) calling the method will behave as expected, print to the console, etc.

Refer to [Log from Workers](https://developers.cloudflare.com/workers/observability/log-from-workers/) for more on debugging and adding logs to Workers.

| Method                                                                                                         | Behavior                                                                                           |
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`console.debug()`](https://developer.mozilla.org/en-US/docs/Web/API/console/debug_static)                     | ✅ supported                                                                                        |
| [`console.error()`](https://developer.mozilla.org/en-US/docs/Web/API/console/error_static)                     | ✅ supported                                                                                        |
| [`console.info()`](https://developer.mozilla.org/en-US/docs/Web/API/console/info_static)                       | ✅ supported                                                                                        |
| [`console.log()`](https://developer.mozilla.org/en-US/docs/Web/API/console/log_static)                         | ✅ supported                                                                                        |
| [`console.warn()`](https://developer.mozilla.org/en-US/docs/Web/API/console/warn_static)                       | ✅ supported                                                                                        |
| [`console.clear()`](https://developer.mozilla.org/en-US/docs/Web/API/console/clear_static)                     | 🟡 partial support                                                                                 |
| [`console.count()`](https://developer.mozilla.org/en-US/docs/Web/API/console/count_static)                     | 🟡 partial support                                                                                 |
| [`console.group()`](https://developer.mozilla.org/en-US/docs/Web/API/console/group_static)                     | 🟡 partial support                                                                                 |
| [`console.table()`](https://developer.mozilla.org/en-US/docs/Web/API/console/table_static)                     | 🟡 partial support                                                                                 |
| [`console.trace()`](https://developer.mozilla.org/en-US/docs/Web/API/console/trace_static)                     | 🟡 partial support                                                                                 |
| [`console.assert()`](https://developer.mozilla.org/en-US/docs/Web/API/console/assert_static)                   | ⚪ no op                                                                                            |
| [`console.countReset()`](https://developer.mozilla.org/en-US/docs/Web/API/console/countreset_static)           | ⚪ no op                                                                                            |
| [`console.dir()`](https://developer.mozilla.org/en-US/docs/Web/API/console/dir_static)                         | ⚪ no op                                                                                            |
| [`console.dirxml()`](https://developer.mozilla.org/en-US/docs/Web/API/console/dirxml_static)                   | ⚪ no op                                                                                            |
| [`console.groupCollapsed()`](https://developer.mozilla.org/en-US/docs/Web/API/console/groupcollapsed_static)   | ⚪ no op                                                                                            |
| [`console.groupEnd`](https://developer.mozilla.org/en-US/docs/Web/API/console/groupend_static)                 | ⚪ no op                                                                                            |
| [`console.profile()`](https://developer.mozilla.org/en-US/docs/Web/API/console/profile_static)                 | ⚪ no op                                                                                            |
| [`console.profileEnd()`](https://developer.mozilla.org/en-US/docs/Web/API/console/profileend_static)           | ⚪ no op                                                                                            |
| [`console.time()`](https://developer.mozilla.org/en-US/docs/Web/API/console/time_static)                       | ⚪ no op                                                                                            |
| [`console.timeEnd()`](https://developer.mozilla.org/en-US/docs/Web/API/console/timeend_static)                 | ⚪ no op                                                                                            |
| [`console.timeLog()`](https://developer.mozilla.org/en-US/docs/Web/API/console/timelog_static)                 | ⚪ no op                                                                                            |
| [`console.timeStamp()`](https://developer.mozilla.org/en-US/docs/Web/API/console/timestamp_static)             | ⚪ no op                                                                                            |
| [`console.createTask()`](https://developer.chrome.com/blog/devtools-modern-web-debugging/#linked-stack-traces) | 🔴 Will throw an exception in production, but works in local dev, Quick Editor, and remote preview |

---

# Context (ctx)

URL: https://developers.cloudflare.com/workers/runtime-apis/context/

The Context API provides methods to manage the lifecycle of your Worker or Durable Object.

Context is exposed via the following places:

* As the third parameter in all [handlers](/workers/runtime-apis/handlers/), including the [`fetch()` handler](/workers/runtime-apis/handlers/fetch/). (`fetch(request, env, ctx)`)
* As a class property of the [`WorkerEntrypoint` class](/workers/runtime-apis/bindings/service-bindings/rpc)

## `waitUntil`

`ctx.waitUntil()` extends the lifetime of your Worker, allowing you to perform work without blocking returning a response, and that may continue after a response is returned. It accepts a `Promise`, which the Workers runtime will continue executing, even after a response has been returned by the Worker's [handler](/workers/runtime-apis/handlers/).

`waitUntil` is commonly used to:

* Fire off events to external analytics providers. (note that when you use [Workers Analytics Engine](/analytics/analytics-engine/), you do not need to use `waitUntil`)
* Put items into cache using the [Cache API](/workers/runtime-apis/cache/)

:::note[Alternatives to waitUntil]

If you are using `waitUntil()` to emit logs or exceptions, we recommend using [Tail Workers](/workers/observability/logs/tail-workers/) instead. Even if your Worker throws an uncaught exception, the Tail Worker will execute, ensuring that you can emit logs or exceptions regardless of the Worker's invocation status.

[Cloudflare Queues](/queues/) is purpose-built for performing work out-of-band, without blocking returning a response back to the client Worker.
:::

You can call `waitUntil()` multiple times. Similar to `Promise.allSettled`, even if a promise passed to one `waitUntil` call is rejected, promises passed to other `waitUntil()` calls will still continue to execute.

For example:

```js
export default {
  async fetch(request, env, ctx) {
    // Forward / proxy original request
    let res = await fetch(request);

    // Add custom header(s)
    res = new Response(res.body, res);
    res.headers.set('x-foo', 'bar');

    // Cache the response
    // NOTE: Does NOT block / wait
    ctx.waitUntil(caches.default.put(request, res.clone()));

    // Done
    return res;
  },
};
```

## `passThroughOnException`

:::caution[Reuse of body]

The Workers Runtime uses streaming for request and response bodies. It does not buffer the body. Hence, if an exception occurs after the body has been consumed, `passThroughOnException()` cannot send the body again.

If this causes issues, we recommend cloning the request body and handling exceptions in code. This will protect against uncaught code exceptions. However some exception times such as exceed CPU or memory limits will not be mitigated.
:::

The `passThroughOnException` method allows a Worker to [fail open](https://community.microfocus.com/cyberres/b/sws-22/posts/security-fundamentals-part-1-fail-open-vs-fail-closed), and pass a request through to an origin server when a Worker throws an unhandled exception. This can be useful when using Workers as a layer in front of an existing service, allowing the service behind the Worker to handle any unexpected error cases that arise in your Worker.

```js
export default {
  async fetch(request, env, ctx) {
    // Proxy to origin on unhandled/uncaught exceptions
    ctx.passThroughOnException();
    throw new Error('Oops');
  },
};
```

---

# EventSource

URL: https://developers.cloudflare.com/workers/runtime-apis/eventsource/

## Background

The [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) interface is a server-sent event API that allows a server to push events to a client. The `EventSource` object is used to receive server-sent events. It connects to a server over HTTP and receives events in a text-based format.

### Constructor

```js
let eventSource = new EventSource(url, options);
```



* `url` USVString - The URL to which to connect.
* `options` EventSourceInit - An optional dictionary containing any optional settings.



By default, the `EventSource` will use the global `fetch()` function under the
covers to make requests. If you need to use a different fetch implementation as
provided by a Cloudflare Workers binding, you can pass the `fetcher` option:

```js
export default {
  async fetch(req, env) {
    let eventSource = new EventSource(url, { fetcher: env.MYFETCHER });
    // ...
  }
};
```

Note that the `fetcher` option is a Cloudflare Workers specific extension.

### Properties



* `eventSource.url` USVString read-only
  * The URL of the event source.
* `eventSource.readyState` USVString read-only
  * The state of the connection.
* `eventSource.withCredentials` Boolean read-only
  * A Boolean indicating whether the `EventSource` object was instantiated with cross-origin (CORS) credentials set (`true`), or not (`false`).



### Methods



* `eventSource.close()`
  * Closes the connection.
* `eventSource.onopen`
  * An event handler called when a connection is opened.
* `eventSource.onmessage`
  * An event handler called when a message is received.
* `eventSource.onerror`
  * An event handler called when an error occurs.



### Events



* `message`
  * Fired when a message is received.
* `open`
  * Fired when the connection is opened.
* `error`
  * Fired when an error occurs.



### Class Methods



* <code>EventSource.from(readableStreamReadableStream) : EventSource</code>
  * This is a Cloudflare Workers specific extension that creates a new `EventSource` object from an existing `ReadableStream`. Such an instance does not initiate a new connection but instead attaches to the provided stream.

---

# Encoding

URL: https://developers.cloudflare.com/workers/runtime-apis/encoding/

## TextEncoder

### Background

The `TextEncoder` takes a stream of code points as input and emits a stream of bytes. Encoding types passed to the constructor are ignored and a UTF-8 `TextEncoder` is created.

[`TextEncoder()`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder/TextEncoder) returns a newly constructed `TextEncoder` that generates a byte stream with UTF-8 encoding. `TextEncoder` takes no parameters and throws no exceptions.

### Constructor

```js
let encoder = new TextEncoder();
```

### Properties



* `encoder.encoding` DOMString read-only
  * The name of the encoder as a string describing the method the `TextEncoder` uses (always `utf-8`).



### Methods



* <code>encode(inputUSVString)</code> : Uint8Array

  * Encodes a string input.



***

## TextDecoder

### Background

The `TextDecoder` interface represents a UTF-8 decoder. Decoders take a stream of bytes as input and emit a stream of code points.

[`TextDecoder()`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder/TextDecoder) returns a newly constructed `TextDecoder` that generates a code-point stream.

### Constructor

```js
let decoder = new TextDecoder();
```

### Properties



* `decoder.encoding` DOMString read-only

  * The name of the decoder that describes the method the `TextDecoder` uses.

* `decoder.fatal` boolean read-only

  * Indicates if the error mode is fatal.

* `decoder.ignoreBOM` boolean read-only
  * Indicates if the byte-order marker is ignored.



### Methods



* `decode()` : DOMString
  * Decodes using the method specified in the `TextDecoder` object. Learn more at [MDN’s `TextDecoder` documentation](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder/decode).

---

# Fetch

URL: https://developers.cloudflare.com/workers/runtime-apis/fetch/

import { TabItem, Tabs } from "~/components";

The [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) provides an interface for asynchronously fetching resources via HTTP requests inside of a Worker.

:::note

Asynchronous tasks such as `fetch` must be executed within a [handler](/workers/runtime-apis/handlers/). If you try to call `fetch()` within [global scope](https://developer.mozilla.org/en-US/docs/Glossary/Global_scope), your Worker will throw an error. Learn more about [the Request context](/workers/runtime-apis/request/#the-request-context).

:::

:::caution[Worker to Worker]

Worker-to-Worker `fetch` requests are possible with [Service bindings](/workers/runtime-apis/bindings/service-bindings/) or by enabling the [`global_fetch_strictly_public` compatibility flag](/workers/configuration/compatibility-flags/#global-fetch-strictly-public).

:::

## Syntax

<Tabs> <TabItem label="Module Worker" icon="seti:javascript">

```js null {3-7}
export default {
	async scheduled(controller, env, ctx) {
		return await fetch("https://example.com", {
			headers: {
				"X-Source": "Cloudflare-Workers",
			},
		});
	},
};
```

</TabItem> <TabItem label="Service Worker" icon="seti:javascript">

:::caution[Service Workers are deprecated]

Service Workers are deprecated, but still supported. We recommend using [Module Workers](/workers/reference/migrate-to-module-workers/) instead. New features may not be supported for Service Workers.

:::

```js null {8}
addEventListener("fetch", (event) => {
	// NOTE: can’t use fetch here, as we’re not in an async scope yet
	event.respondWith(eventHandler(event));
});

async function eventHandler(event) {
	// fetch can be awaited here since `event.respondWith()` waits for the Promise it receives to settle
	const resp = await fetch(event.request);
	return resp;
}
```

</TabItem> <TabItem label="Python Worker" icon="seti:python">

```python
from workers import fetch, handler

@handler
async def on_scheduled(controller, env, ctx):
  return await fetch("https://example.com", headers={"X-Source": "Cloudflare-Workers"})
```

</TabItem></Tabs>

- <code>fetch(resource, options optional)</code> : Promise`<Response>`

  - Fetch returns a promise to a Response.

### Parameters

- [`resource`](https://developer.mozilla.org/en-US/docs/Web/API/fetch#resource) Request | string | URL

- `options` options
  - `cache` `undefined | 'no-store'` optional
    - Standard HTTP `cache` header. Only `cache: 'no-store'` is supported.
      Any other `cache` header will result in a `TypeError` with the message `Unsupported cache mode: <attempted-cache-mode>`.
      _ For all requests this forwards the `Pragma: no-cache` and `Cache-Control: no-cache` headers to the origin.
      _ For requests to origins not hosted by Cloudflare, `no-store` bypasses the use of Cloudflare's caches.
  - An object that defines the content and behavior of the request.

---

## How the `Accept-Encoding` header is handled

When making a subrequest with the `fetch()` API, you can specify which forms of compression to prefer that the server will respond with (if the server supports it) by including the [`Accept-Encoding`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Accept-Encoding) header.

Workers supports both the gzip and brotli compression algorithms. Usually it is not necessary to specify `Accept-Encoding` or `Content-Encoding` headers in the Workers Runtime production environment – brotli or gzip compression is automatically requested when fetching from an origin and applied to the response when returning data to the client, depending on the capabilities of the client and origin server.

To support requesting brotli from the origin, you must enable the [`brotli_content_encoding`](/workers/configuration/compatibility-flags/#brotli-content-encoding-support) compatibility flag in your Worker. Soon, this compatibility flag will be enabled by default for all Workers past an upcoming compatibility date.

### Passthrough behavior

One scenario where the Accept-Encoding header is useful is for passing through compressed data from a server to the client, where the Accept-Encoding allows the worker to directly receive the compressed data stream from the server without it being decompressed beforehand. As long as you do not read the body of the compressed response prior to returning it to the client and keep the `Content-Encoding` header intact, it will "pass through" without being decompressed and then recompressed again. This can be helpful when using Workers in front of origin servers or when fetching compressed media assets, to ensure that the same compression used by the origin server is used in the response that your Worker returns.

In addition to a change in the content encoding, recompression is also needed when a response uses an encoding not supported by the client. As an example, when a Worker requests either brotli or gzip as the encoding but the client only supports gzip, recompression will still be needed if the server returns brotli-encoded data to the server (and will be applied automatically). Note that this behavior may also vary based on the [compression rules](/rules/compression-rules/), which can be used to configure what compression should be applied for different types of data on the server side.

```typescript
export default {
	async fetch(request) {
		// Accept brotli or gzip compression
		const headers = new Headers({
			"Accept-Encoding": "br, gzip",
		});
		let response = await fetch("https://developers.cloudflare.com", {
			method: "GET",
			headers,
		});

		// As long as the original response body is returned and the Content-Encoding header is
		// preserved, the same encoded data will be returned without needing to be compressed again.
		return new Response(response.body, {
			status: response.status,
			statusText: response.statusText,
			headers: response.headers,
		});
	},
};
```

## Related resources

- [Example: use `fetch` to respond with another site](/workers/examples/respond-with-another-site/)
- [Example: Fetch HTML](/workers/examples/fetch-html/)
- [Example: Fetch JSON](/workers/examples/fetch-json/)
- [Example: cache using Fetch](/workers/examples/cache-using-fetch/)
- Write your Worker code in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.

---

# Headers

URL: https://developers.cloudflare.com/workers/runtime-apis/headers/

## Background

All HTTP request and response headers are available through the [Headers API](https://developer.mozilla.org/en-US/docs/Web/API/Headers).

When a header name possesses multiple values, those values will be concatenated as a single, comma-delimited string value. This means that `Headers.get` will always return a string or a `null` value. This applies to all header names except for `Set-Cookie`, which requires `Headers.getAll`. This is documented below in [Differences](#differences).

```js
let headers = new Headers();

headers.get('x-foo'); //=> null

headers.set('x-foo', '123');
headers.get('x-foo'); //=> "123"

headers.set('x-foo', 'hello');
headers.get('x-foo'); //=> "hello"

headers.append('x-foo', 'world');
headers.get('x-foo'); //=> "hello, world"
```

## Differences

* Despite the fact that the `Headers.getAll` method has been made obsolete, Cloudflare still offers this method but only for use with the `Set-Cookie` header. This is because cookies will often contain date strings, which include commas. This can make parsing multiple values in a `Set-Cookie` header more difficult. Any attempts to use `Headers.getAll` with other header names will throw an error. A brief history `Headers.getAll` is available in this [GitHub issue](https://github.com/whatwg/fetch/issues/973).

* Due to [RFC 6265](https://www.rfc-editor.org/rfc/rfc6265) prohibiting folding multiple `Set-Cookie` headers into a single header, the `Headers.append` method will allow you to set multiple `Set-Cookie` response headers instead of appending the value onto the existing header.

```js
const headers = new Headers();

headers.append("Set-Cookie", "cookie1=value_for_cookie_1; Path=/; HttpOnly;");
headers.append("Set-Cookie", "cookie2=value_for_cookie_2; Path=/; HttpOnly;");

console.log(headers.getAll("Set-Cookie"));
// Array(2) [ cookie1=value_for_cookie_1; Path=/; HttpOnly;, cookie2=value_for_cookie_2; Path=/; HttpOnly; ]
```

* In Cloudflare Workers, the `Headers.get` method returns a [`USVString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) instead of a [`ByteString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), which is specified by the spec. For most scenarios, this should have no noticeable effect. To compare the differences between these two string classes, refer to this [Playground example](https://workers.cloudflare.com/playground#LYVwNgLglgDghgJwgegGYHsHALQBM4RwDcABAEbogB2+CAngLzbMutvvsCMALAJx-cAzAHZeANkG8AHAAZOU7t2EBWAEy9eqsXNWdOALg5HjbHv34jxk2fMUr1m7Z12cAsACgAwuioQApr7YACJQAM4w6KFQ0D76JBhYeATEJFRwwH4MAERQNH4AHgB0AFahWaSoUGAB6Zk5eUWlWR7evgEQ2AAqdDB+cXAwMGBQAMYEUD7IxXAAbnChIwiwEADUwOi44H4eHgURSCS4fqhw4BAkAN7uAJDzdFQj8X4QIwAWABQIfgCOIH6hEAAlJcbtdqucxucGCQsoBeDcAXHtZUHgkggCCoKSeAgkaFUPwAdxInQKEAAog8Nn4EO9AYUAiNKe9IYDkc8SPTKbgsVCSABlCBLKgAc0KqAQ6GAnleiG8R3ehQVaIx3JZoIZVFC6GqhTA6CF7yynVeYRIJrgJAAqryAGr8wVCkj46KvEjmyH6LIAGhIzLVPk12t1+sNxtCprD5oAQnR-Hbcg6nRAXW7sT5LZ0AGLYKQe70co5cgiq67XZDIEgACT8cCOCAjXxIoRAg0iflwJAg6EdmAA1iQfGA6I7nSRo7GBfHQt6yGj+yAEKCy6bgEM-BlfOM0yBQv9LTa48LQoUiaHUiSSMM8cOwGASDBBec4Ivy-jEFR466KLOk2FCqzzq81a1mGuIEpWQFUqE7wXDC+ZttgkJZHEcGFucAC+xbXF8EDzlQZ6EgASv8EQan4BpSn4Ix9pQ5xJn4JAAAatAGfgMa6NAdoBJBEeE-r0YBNaQR2XY7vRdFzhAMCzgyK6IGE-qFF6lwkAJwEkBhNxoe4aEeCYelGGYAiWBI0hyAoShqBoWg6HoLQ+P4gQhLxUQxFQcQJDg+CEKQaQZNkGSEF5cDlPEVQ1H5WRkLqZDNF49ntF0PR9K6gzDJCExUFMmpUDs7gXFkwBwLkAD66ybNUSH1EcjRlDp7j6Q1rCGRYogmTY5n2FZTguMwHhAA).

## Cloudflare headers

Cloudflare sets a number of its own custom headers on incoming requests and outgoing responses. While some may be used for its own tracking and bookkeeping, many of these can be useful to your own applications – or Workers – too.

For a list of documented Cloudflare request headers, refer to [Cloudflare HTTP headers](/fundamentals/reference/http-headers/).

## Related resources

* [Logging headers to console](/workers/examples/logging-headers/) - Review how to log headers in the console.
* [Cloudflare HTTP headers](/fundamentals/reference/http-headers/) - Contains a list of specific headers that Cloudflare adds.

---

# HTMLRewriter

URL: https://developers.cloudflare.com/workers/runtime-apis/html-rewriter/

import { Render } from "~/components";

## Background

The `HTMLRewriter` class allows developers to build comprehensive and expressive HTML parsers inside of a Cloudflare Workers application. It can be thought of as a jQuery-like experience directly inside of your Workers application. Leaning on a powerful JavaScript API to parse and transform HTML, `HTMLRewriter` allows developers to build deeply functional applications.

The `HTMLRewriter` class should be instantiated once in your Workers script, with a number of handlers attached using the `on` and `onDocument` functions.

---

## Constructor

```js
new HTMLRewriter()
	.on("*", new ElementHandler())
	.onDocument(new DocumentHandler());
```

---

## Global types

Throughout the `HTMLRewriter` API, there are a few consistent types that many properties and methods use:

- `Content` string | Response | ReadableStream

  - Content inserted in the output stream should be a string, [`Response`](/workers/runtime-apis/response/), or [`ReadableStream`](/workers/runtime-apis/streams/readablestream/).

- `ContentOptions` Object

  - `{ html: Boolean }` Controls the way the HTMLRewriter treats inserted content. If the `html` boolean is set to true, content is treated as raw HTML. If the `html` boolean is set to false or not provided, content will be treated as text and proper HTML escaping will be applied to it.

---

## Handlers

There are two handler types that can be used with `HTMLRewriter`: element handlers and document handlers.

### Element Handlers

An element handler responds to any incoming element, when attached using the `.on` function of an `HTMLRewriter` instance. The element handler should respond to `element`, `comments`, and `text`. The example processes `div` elements with an `ElementHandler` class.

```js
class ElementHandler {
	element(element) {
		// An incoming element, such as `div`
		console.log(`Incoming element: ${element.tagName}`);
	}

	comments(comment) {
		// An incoming comment
	}

	text(text) {
		// An incoming piece of text
	}
}

async function handleRequest(req) {
	const res = await fetch(req);

	return new HTMLRewriter().on("div", new ElementHandler()).transform(res);
}
```

### Document Handlers

A document handler represents the incoming HTML document. A number of functions can be defined on a document handler to query and manipulate a document’s `doctype`, `comments`, `text`, and `end`. Unlike an element handler, a document handler’s `doctype`, `comments`, `text`, and `end` functions are not scoped by a particular selector. A document handler's functions are called for all the content on the page including the content outside of the top-level HTML tag:

```js
class DocumentHandler {
	doctype(doctype) {
		// An incoming doctype, such as <!DOCTYPE html>
	}

	comments(comment) {
		// An incoming comment
	}

	text(text) {
		// An incoming piece of text
	}

	end(end) {
		// The end of the document
	}
}
```

#### Async Handlers

All functions defined on both element and document handlers can return either `void` or a `Promise<void>`. Making your handler function `async` allows you to access external resources such as an API via fetch, Workers KV, Durable Objects, or the cache.

```js
class UserElementHandler {
	async element(element) {
		let response = await fetch(new Request("/user"));

		// fill in user info using response
	}
}

async function handleRequest(req) {
	const res = await fetch(req);

	// run the user element handler via HTMLRewriter on a div with ID `user_info`
	return new HTMLRewriter()
		.on("div#user_info", new UserElementHandler())
		.transform(res);
}
```

### Element

The `element` argument, used only in element handlers, is a representation of a DOM element. A number of methods exist on an element to query and manipulate it:

#### Properties

- `tagName` string

  - The name of the tag, such as `"h1"` or `"div"`. This property can be assigned different values, to modify an element’s tag.

- `attributes` Iterator read-only

  - A `[name, value]` pair of the tag’s attributes.

- `removed` boolean

  - Indicates whether the element has been removed or replaced by one of the previous handlers.

- `namespaceURI` String
  - Represents the [namespace URI](https://infra.spec.whatwg.org/#namespaces) of an element.

#### Methods

- <code>getAttribute(namestring)</code> : string | null

  - Returns the value for a given attribute name on the element, or `null` if it is not found.

- <code>hasAttribute(namestring)</code> : boolean

  - Returns a boolean indicating whether an attribute exists on the element.

- <code>setAttribute(namestring, valuestring)</code> : Element

  - Sets an attribute to a provided value, creating the attribute if it does not exist.

- <code>removeAttribute(namestring)</code> : Element

  - Removes the attribute.

- <code>before(contentContent, contentOptionsContentOptionsoptional)</code> :
  Element

  - Inserts content before the element.

  <Render file="content_and_contentoptions" />

- <code>after(contentContent, contentOptionsContentOptionsoptional)</code> :
  Element

  - Inserts content right after the element.

- <code>prepend(contentContent, contentOptionsContentOptionsoptional)</code> :
  Element

  - Inserts content right after the start tag of the element.

- <code>append(contentContent, contentOptionsContentOptionsoptional)</code> :
  Element

  - Inserts content right before the end tag of the element.

- <code>replace(contentContent, contentOptionsContentOptionsoptional)</code> :
  Element

  - Removes the element and inserts content in place of it.

- <code>setInnerContent(contentContent, contentOptionsContentOptionsoptional)</code> :
	Element

  - Replaces content of the element.

- <code>remove()</code> : Element

  - Removes the element with all its content.

- <code>removeAndKeepContent()</code> : Element

  - Removes the start tag and end tag of the element but keeps its inner content intact.

- `onEndTag(handlerFunction<void>)` : void

  - Registers a handler that is invoked when the end tag of the element is reached.

### EndTag

The `endTag` argument, used only in handlers registered with `element.onEndTag`, is a limited representation of a DOM element.

#### Properties

- `name` string

  - The name of the tag, such as `"h1"` or `"div"`. This property can be assigned different values, to modify an element's tag.

#### Methods

- <code>before(contentContent, contentOptionsContentOptionsoptional)</code> :
  EndTag

  - Inserts content right before the end tag.

- <code>after(contentContent, contentOptionsContentOptionsoptional)</code> :
  EndTag

  - Inserts content right after the end tag.

  <Render file="content_and_contentoptions" />

- <code>remove()</code> : EndTag

  - Removes the element with all its content.

### Text chunks

Since Cloudflare performs zero-copy streaming parsing, text chunks are not the same thing as text nodes in the lexical tree. A lexical tree text node can be represented by multiple chunks, as they arrive over the wire from the origin.

Consider the following markup: `<div>Hey. How are you?</div>`. It is possible that the Workers script will not receive the entire text node from the origin at once; instead, the `text` element handler will be invoked for each received part of the text node. For example, the handler might be invoked with `“Hey. How ”,` then `“are you?”`. When the last chunk arrives, the text’s `lastInTextNode` property will be set to `true`. Developers should make sure to concatenate these chunks together.

#### Properties

- `removed` boolean

  - Indicates whether the element has been removed or replaced by one of the previous handlers.

- `text` string read-only

  - The text content of the chunk. Could be empty if the chunk is the last chunk of the text node.

- `lastInTextNode` boolean read-only
  - Specifies whether the chunk is the last chunk of the text node.

#### Methods

- <code>before(contentContent, contentOptionsContentOptionsoptional)</code> :
  Element

  - Inserts content before the element.

  <Render file="content_and_contentoptions" />

- <code>after(contentContent, contentOptionsContentOptionsoptional)</code> :
  Element

  - Inserts content right after the element.

- <code>replace(contentContent, contentOptionsContentOptionsoptional)</code> :
  Element

  - Removes the element and inserts content in place of it.

- <code>remove()</code> : Element

  - Removes the element with all its content.

### Comments

The `comments` function on an element handler allows developers to query and manipulate HTML comment tags.

```js
class ElementHandler {
	comments(comment) {
		// An incoming comment element, such as <!-- My comment -->
	}
}
```

#### Properties

- `comment.removed` boolean

  - Indicates whether the element has been removed or replaced by one of the previous handlers.

- `comment.text` string
  - The text of the comment. This property can be assigned different values, to modify comment’s text.

#### Methods

- <code>before(contentContent, contentOptionsContentOptionsoptional)</code> :
  Element

  - Inserts content before the element.

  <Render file="content_and_contentoptions" />

- <code>after(contentContent, contentOptionsContentOptionsoptional)</code> :
  Element

  - Inserts content right after the element.

- <code>replace(contentContent, contentOptionsContentOptionsoptional)</code> :
  Element

  - Removes the element and inserts content in place of it.

- <code>remove()</code> : Element

  - Removes the element with all its content.

### Doctype

The `doctype` function on a document handler allows developers to query a document’s [doctype](https://developer.mozilla.org/en-US/docs/Glossary/Doctype).

```js
class DocumentHandler {
	doctype(doctype) {
		// An incoming doctype element, such as
		// <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
	}
}
```

#### Properties

- `doctype.name` string | null read-only

  - The doctype name.

- `doctype.publicId` string | null read-only

  - The quoted string in the doctype after the PUBLIC atom.

- `doctype.systemId` string | null read-only
  - The quoted string in the doctype after the SYSTEM atom or immediately after the `publicId`.

### End

The `end` function on a document handler allows developers to append content to the end of a document.

```js
class DocumentHandler {
	end(end) {
		// The end of the document
	}
}
```

#### Methods

- <code>append(contentContent, contentOptionsContentOptionsoptional)</code> :
  DocumentEnd

  - Inserts content after the end of the document.

  <Render file="content_and_contentoptions" />

---

## Selectors

This is what selectors are and what they are used for.

- `*`

  - Any element.

- `E`

  - Any element of type E.

- `E:nth-child(n)`

  - An E element, the n-th child of its parent.

- `E:first-child`

  - An E element, first child of its parent.

- `E:nth-of-type(n)`

  - An E element, the n-th sibling of its type.

- `E:first-of-type`

  - An E element, first sibling of its type.

- `E:not(s)`

  - An E element that does not match either compound selectors.

- `E.warning`

  - An E element belonging to the class warning.

- `E#myid`

  - An E element with ID equal to myid.

- `E[foo]`

  - An E element with a foo attribute.

- `E[foo="bar"]`

  - An E element whose foo attribute value is exactly equal to bar.

- `E[foo="bar" i]`

  - An E element whose foo attribute value is exactly equal to any (ASCII-range) case-permutation of bar.

- `E[foo="bar" s]`

  - An E element whose foo attribute value is exactly and case-sensitively equal to bar.

- `E[foo~="bar"]`

  - An E element whose foo attribute value is a list of whitespace-separated values, one of which is exactly equal to bar.

- `E[foo^="bar"]`

  - An E element whose foo attribute value begins exactly with the string bar.

- `E[foo$="bar"]`

  - An E element whose foo attribute value ends exactly with the string bar.

- `E[foo*="bar"]`

  - An E element whose foo attribute value contains the substring bar.

- `E[foo|="en"]`

  - An E element whose foo attribute value is a hyphen-separated list of values beginning with en.

- `E F`

  - An F element descendant of an E element.

- `E > F`
  - An F element child of an E element.

---

## Errors

If a handler throws an exception, parsing is immediately halted, the transformed response body is errored with the thrown exception, and the untransformed response body is canceled (closed). If the transformed response body was already partially streamed back to the client, the client will see a truncated response.

```js
async function handle(request) {
	let oldResponse = await fetch(request);
	let newResponse = new HTMLRewriter()
		.on("*", {
			element(element) {
				throw new Error("A really bad error.");
			},
		})
		.transform(oldResponse);

	// At this point, an expression like `await newResponse.text()`
	// will throw `new Error("A really bad error.")`.
	// Thereafter, any use of `newResponse.body` will throw the same error,
	// and `oldResponse.body` will be closed.

	// Alternatively, this will produce a truncated response to the client:
	return newResponse;
}
```

---

## Related resources

- [Introducing `HTMLRewriter`](https://blog.cloudflare.com/introducing-htmlrewriter/)
- [Tutorial: Localize a Website](/pages/tutorials/localize-a-website/)
- [Example: rewrite links](/workers/examples/rewrite-links/)
- [Example: Inject Turnstile](/workers/examples/turnstile-html-rewriter/)

---

# Runtime APIs

URL: https://developers.cloudflare.com/workers/runtime-apis/

import { DirectoryListing } from "~/components";

The Workers runtime is designed to be [JavaScript standards compliant](https://ecma-international.org/publications-and-standards/standards/ecma-262/) and web-interoperable. Wherever possible, it uses web platform APIs, so that code can be reused across client and server, as well as across [WinterCG](https://wintercg.org/) JavaScript runtimes.

[Workers runtime features](/workers/runtime-apis/) are [compatible with a subset of Node.js APIs](/workers/runtime-apis/nodejs) and the ability to set a [compatibility date or compatibility flag](/workers/configuration/compatibility-dates/).

<DirectoryListing />

---

# Performance and timers

URL: https://developers.cloudflare.com/workers/runtime-apis/performance/

## Background

The Workers runtime supports a subset of the [`Performance` API](https://developer.mozilla.org/en-US/docs/Web/API/Performance), used to measure timing and performance, as well as timing of subrequests and other operations.

### `performance.now()`

The [`performance.now()` method](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now) returns timestamp in milliseconds, representing the time elapsed since `performance.timeOrigin`.

When Workers are deployed to Cloudflare, as a security measure to [mitigate against Spectre attacks](/workers/reference/security-model/#step-1-disallow-timers-and-multi-threading), APIs that return timers, including [`performance.now()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now) and [`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now), only advance or increment after I/O occurs. Consider the following examples:

```typescript title="Time is frozen — start will have the exact same value as end."
const start = performance.now();
for (let i = 0; i < 1e6; i++) {
  // do expensive work
}
const end = performance.now();
const timing = end - start; // 0
```

```typescript title="Time advances, because a subrequest has occurred between start and end."
const start = performance.now();
const response = await fetch("https://developers.cloudflare.com/");
const end = performance.now();
const timing = end - start; // duration of the subrequest to developers.cloudflare.com
```

By wrapping a subrequest in calls to `performance.now()` or `Date.now()` APIs, you can measure the timing of a subrequest, fetching a key from KV, an object from R2, or any other form of I/O in your Worker.

In local development, however, timers will increment regardless of whether I/O happens or not. This means that if you need to measure timing of a piece of code that is CPU intensive, that does not involve I/O, you can run your Worker locally, via [Wrangler](/workers/wrangler/), which uses the open-source Workers runtime, [workerd](https://github.com/cloudflare/workerd) — the same runtime that your Worker runs in when deployed to Cloudflare.

### `performance.timeOrigin`

The [`performance.timeOrigin`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/timeOrigin) API is a read-only property that returns a baseline timestamp to base other measurements off of.

In the Workers runtime, the `timeOrigin` property returns 0.

---

# Request

URL: https://developers.cloudflare.com/workers/runtime-apis/request/

import { Type, MetaInfo, Render } from "~/components";

The [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request) interface represents an HTTP request and is part of the [Fetch API](/workers/runtime-apis/fetch/).

## Background

The most common way you will encounter a `Request` object is as a property of an incoming request:

```js null {2}
export default {
	async fetch(request, env, ctx) {
		return new Response('Hello World!');
	},
};
```

You may also want to construct a `Request` yourself when you need to modify a request object, because the incoming `request` parameter that you receive from the [`fetch()` handler](/workers/runtime-apis/handlers/fetch/) is immutable.

```js
export default {
	async fetch(request, env, ctx) {
        const url = "https://example.com";
        const modifiedRequest = new Request(url, request);
		// ...
	},
};
```

The [`fetch() handler`](/workers/runtime-apis/handlers/fetch/) invokes the `Request` constructor. The [`RequestInit`](#options) and [`RequestInitCfProperties`](#the-cf-property-requestinitcfproperties) types defined below also describe the valid parameters that can be passed to the [`fetch() handler`](/workers/runtime-apis/handlers/fetch/).

***

## Constructor

```js
let request = new Request(input, options)
```

### Parameters



* `input` string | Request

  * Either a string that contains a URL, or an existing `Request` object.

* `options` options optional

  * Optional options object that contains settings to apply to the `Request`.



#### `options`

An object containing properties that you want to apply to the request.

* `cache` `undefined | 'no-store'` optional

	* Standard HTTP `cache` header. Only `cache: 'no-store'` is supported.
	Any other cache header will result in a `TypeError` with the message `Unsupported cache mode: <attempted-cache-mode>`.

* `cf` RequestInitCfProperties optional

  * Cloudflare-specific properties that can be set on the `Request` that control how Cloudflare’s global network handles the request.

* `method` <Type text="string" /> <MetaInfo text="optional" />

  * The HTTP request method. The default is `GET`. In Workers, all [HTTP request methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods) are supported, except for [`CONNECT`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/CONNECT).

* `headers` Headers optional

  * A [`Headers` object](https://developer.mozilla.org/en-US/docs/Web/API/Headers).

* `body` string | ReadableStream | FormData | URLSearchParams optional

  * The request body, if any.
  * Note that a request using the GET or HEAD method cannot have a body.

* `redirect` <Type text="string" /> <MetaInfo text="optional" />

  * The redirect mode to use: `follow`, `error`, or `manual`. The default  for a new `Request` object is `follow`. Note, however, that the incoming `Request` property of a `FetchEvent` will have redirect mode `manual`.

* `signal` AbortSignal optional
  * If provided, the request can be canceled by triggering an abort on the corresponding `AbortController`.


#### The `cf` property (`RequestInitCfProperties`)

An object containing Cloudflare-specific properties that can be set on the `Request` object. For example:

```js
// Disable ScrapeShield for this request.
fetch(event.request, { cf: { scrapeShield: false } })
```

Invalid or incorrectly-named keys in the `cf` object will be silently ignored. Consider using TypeScript and generating types by running [`wrangler types`](/workers/languages/typescript/#generate-types) to ensure proper use of the `cf` object.



* `apps` <Type text="boolean" /> <MetaInfo text="optional" />

  * Whether [Cloudflare Apps](https://www.cloudflare.com/apps/) should be enabled for this request. Defaults to `true`.

* `cacheEverything` <Type text="boolean" /> <MetaInfo text="optional" />

  * Treats all content as static and caches all [file types](/cache/concepts/default-cache-behavior#default-cached-file-extensions) beyond the Cloudflare default cached content. Respects cache headers from the origin web server. This is equivalent to setting the Page Rule [**Cache Level** (to **Cache Everything**)](/rules/page-rules/reference/settings/). Defaults to `false`.
    This option applies to `GET` and `HEAD` request methods only.

* `cacheKey` <Type text="string" /> <MetaInfo text="optional" />

  * A request’s cache key is what determines if two requests are the same for caching purposes. If a request has the same cache key as some previous request, then Cloudflare can serve the same cached response for both.

* `cacheTags` Array\<string> optional

  * This option appends additional [**Cache-Tag**](/cache/how-to/purge-cache/purge-by-tags/) headers to the response from the origin server. This allows for purges of cached content based on tags provided by the Worker, without modifications to the origin server. This is performed using the [**Purge by Tag**](/cache/how-to/purge-cache/purge-by-tags/#purge-using-cache-tags) feature.

* `cacheTtl` <Type text="number" /> <MetaInfo text="optional" />

  * This option forces Cloudflare to cache the response for this request, regardless of what headers are seen on the response. This is equivalent to setting two Page Rules: [**Edge Cache TTL**](/cache/how-to/edge-browser-cache-ttl/) and [**Cache Level** (to **Cache Everything**)](/rules/page-rules/reference/settings/). The value must be zero or a positive number. A value of `0` indicates that the cache asset expires immediately. This option applies to `GET` and `HEAD` request methods only.

* `cacheTtlByStatus` `{ [key: string]: number }` optional

  * This option is a version of the `cacheTtl` feature which chooses a TTL based on the response’s status code. If the response to this request has a status code that matches, Cloudflare will cache for the instructed time and override cache instructives sent by the origin. For example: `{ "200-299": 86400, "404": 1, "500-599": 0 }`. The value can be any integer, including zero and negative integers. A value of `0` indicates that the cache asset expires immediately. Any negative value instructs Cloudflare not to cache at all. This option applies to `GET` and `HEAD` request methods only.

* `image` Object | null optional

  * Enables [Image Resizing](/images/transform-images/) for this request. The possible values are described in [Transform images via Workers](/images/transform-images/transform-via-workers/) documentation.

* `mirage` <Type text="boolean" /> <MetaInfo text="optional" />

  * Whether [Mirage](https://www.cloudflare.com/website-optimization/mirage/) should be enabled for this request, if otherwise configured for this zone. Defaults to `true`.

* `polish` <Type text="string" /> <MetaInfo text="optional" />

  * Sets [Polish](https://blog.cloudflare.com/introducing-polish-automatic-image-optimizati/) mode. The possible values are `lossy`, `lossless` or `off`.

* `resolveOverride` <Type text="string" /> <MetaInfo text="optional" />

  * Directs the request to an alternate origin server by overriding the DNS lookup. The value of `resolveOverride` specifies an alternate hostname which will be used when determining the origin IP address, instead of using the hostname specified in the URL. The `Host` header of the request will still match what is in the URL. Thus, `resolveOverride` allows a request to be sent to a different server than the URL / `Host` header specifies. However, `resolveOverride` will only take effect if both the URL host and the host specified by `resolveOverride` are within your zone. If either specifies a host from a different zone / domain, then the option will be ignored for security reasons. If you need to direct a request to a host outside your zone (while keeping the `Host` header pointing within your zone), first create a CNAME record within your zone pointing to the outside host, and then set `resolveOverride` to point at the CNAME record. Note that, for security reasons, it is not possible to set the `Host` header to specify a host outside of your zone unless the request is actually being sent to that host.

* `scrapeShield` <Type text="boolean" /> <MetaInfo text="optional" />

  * Whether [ScrapeShield](https://blog.cloudflare.com/introducing-scrapeshield-discover-defend-dete/) should be enabled for this request, if otherwise configured for this zone. Defaults to `true`.

* `webp` <Type text="boolean" /> <MetaInfo text="optional" />

  * Enables or disables [WebP](https://blog.cloudflare.com/a-very-webp-new-year-from-cloudflare/) image format in [Polish](/images/polish/).



***

## Properties

All properties of an incoming `Request` object (the request you receive from the [`fetch()` handler](/workers/runtime-apis/handlers/fetch/)) are read-only. To modify the properties of an incoming request, create a new `Request` object and pass the options to modify to its [constructor](#constructor).



* `body` ReadableStream read-only

  * Stream of the body contents.

* `bodyUsed` Boolean read-only

  * Declares whether the body has been used in a response yet.

* `cf` IncomingRequestCfProperties read-only

  * An object containing properties about the incoming request provided by Cloudflare’s global network.
  * This property is read-only (unless created from an existing `Request`). To modify its values, pass in the new values on the [`cf` key of the `init` options argument](/workers/runtime-apis/request/#the-cf-property-requestinitcfproperties) when creating a new `Request` object.

* `headers` Headers read-only

  * A [`Headers` object](https://developer.mozilla.org/en-US/docs/Web/API/Headers).

  * Compared to browsers, Cloudflare Workers imposes very few restrictions on what headers you are allowed to send. For example, a browser will not allow you to set the `Cookie` header, since the browser is responsible for handling cookies itself. Workers, however, has no special understanding of cookies, and treats the `Cookie` header like any other header.

  :::caution

  If the response is a redirect and the redirect mode is set to `follow` (see below), then all headers will be forwarded to the redirect destination, even if the destination is a different hostname or domain. This includes sensitive headers like `Cookie`, `Authorization`, or any application-specific headers. If this is not the behavior you want, you should set redirect mode to `manual` and implement your own redirect policy. Note that redirect mode defaults to `manual` for requests that originated from the Worker's client, so this warning only applies to `fetch()`es made by a Worker that are not proxying the original request.
  :::

* `method` string read-only

  * Contains the request’s method, for example, `GET`, `POST`, etc.

* `redirect` string read-only

  * The redirect mode to use: `follow`, `error`, or `manual`. The `fetch` method will automatically follow redirects if the redirect mode is set to `follow`. If set to `manual`, the `3xx` redirect response will be returned to the caller as-is. The default for a new `Request` object is `follow`. Note, however, that the incoming `Request` property of a `FetchEvent` will have redirect mode `manual`.

* `signal` AbortSignal read-only
  * The `AbortSignal` corresponding to this request. If you use the [`enable_request_signal`](/workers/configuration/compatibility-flags/#enable-requestsignal-for-incoming-requests) compatibility flag, you can attach an event listener to the signal. This allows you to perform cleanup tasks or write to logs before your Worker's invocation ends.
    For example, if you run the Worker below, and then abort the request from the client, a log will be written:
    <Render file="request-signal-example" />

* `url` string read-only

  * Contains the URL of the request.



### `IncomingRequestCfProperties`

In addition to the properties on the standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object, the `request.cf` object on an inbound `Request` contains information about the request provided by Cloudflare’s global network.

All plans have access to:



* `asn` Number

  * ASN of the incoming request, for example, `395747`.

* `asOrganization` string

  * The organization which owns the ASN of the incoming request, for example, `Google Cloud`.

* `botManagement` Object | null

  * Only set when using Cloudflare Bot Management. Object with the following properties: `score`, `verifiedBot`, `staticResource`, `ja3Hash`, `ja4`, and `detectionIds`. Refer to [Bot Management Variables](/bots/reference/bot-management-variables/) for more details.

* `clientAcceptEncoding` string | null

  * If Cloudflare replaces the value of the `Accept-Encoding` header, the original value is stored in the `clientAcceptEncoding` property, for example, `"gzip, deflate, br"`.

* `colo` string

  * The three-letter [`IATA`](https://en.wikipedia.org/wiki/IATA_airport_code) airport code of the data center that the request hit, for example, `"DFW"`.

* `country` string | null

  * Country of the incoming request. The two-letter country code in the request. This is the same value as that provided in the `CF-IPCountry` header, for example, `"US"`.

* `isEUCountry` string | null

  * If the country of the incoming request is in the EU, this will return `"1"`. Otherwise, this property will be omitted.

* `httpProtocol` string

  * HTTP Protocol, for example, `"HTTP/2"`.

* `requestPriority` string | null

  * The browser-requested prioritization information in the request object, for example, `"weight=192;exclusive=0;group=3;group-weight=127"`.

* `tlsCipher` string

  * The cipher for the connection to Cloudflare, for example, `"AEAD-AES128-GCM-SHA256"`.

* `tlsClientAuth` Object | null

  * Only set when using Cloudflare Access or API Shield (mTLS). Object with the following properties: `certFingerprintSHA1`, `certFingerprintSHA256`, `certIssuerDN`, `certIssuerDNLegacy`, `certIssuerDNRFC2253`, `certIssuerSKI`, `certIssuerSerial`, `certNotAfter`, `certNotBefore`, `certPresented`, `certRevoked`, `certSKI`, `certSerial`, `certSubjectDN`, `certSubjectDNLegacy`, `certSubjectDNRFC2253`, `certVerified`.

* `tlsClientCiphersSha1` string

  * The SHA-1 hash (Base64-encoded) of the cipher suite sent by the client during the TLS handshake, encoded in big-endian format. For example, `"GXSPDLP4G3X+prK73a4wBuOaHRc="`.

* `tlsClientExtensionsSha1` string

  * The SHA-1 hash (Base64-encoded) of the TLS client extensions sent during the handshake, encoded in big-endian format. For example, `"OWFiM2I5ZDc0YWI0YWYzZmFkMGU0ZjhlYjhiYmVkMjgxNTU5YTU2Mg=="`.

* `tlsClientExtensionsSha1Le` string

  * The SHA-1 hash (Base64-encoded) of the TLS client extensions sent during the handshake, encoded in little-endian format. For example, `"7zIpdDU5pvFPPBI2/PCzqbaXnRA="`.

* `tlsClientHelloLength` string

  * The length of the client hello message sent in a [TLS handshake](https://www.cloudflare.com/learning/ssl/what-happens-in-a-tls-handshake/). For example, `"508"`. Specifically, the length of the bytestring of the client hello.

* `tlsClientRandom` string

  * The value of the 32-byte random value provided by the client in a [TLS handshake](https://www.cloudflare.com/learning/ssl/what-happens-in-a-tls-handshake/). Refer to [RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446#section-4.1.2) for more details.

* `tlsVersion` string

  * The TLS version of the connection to Cloudflare, for example, `TLSv1.3`.

* `city` string | null

  * City of the incoming request, for example, `"Austin"`.

* `continent` string | null

  * Continent of the incoming request, for example, `"NA"`.

* `latitude` string | null

  * Latitude of the incoming request, for example, `"30.27130"`.

* `longitude` string | null

  * Longitude of the incoming request, for example, `"-97.74260"`.

* `postalCode` string | null

  * Postal code of the incoming request, for example, `"78701"`.

* `metroCode` string | null

  * Metro code (DMA) of the incoming request, for example, `"635"`.

* `region` string | null

  * If known, the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) name for the first level region associated with the IP address of the incoming request, for example, `"Texas"`.

* `regionCode` string | null

  * If known, the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) code for the first-level region associated with the IP address of the incoming request, for example, `"TX"`.

* `timezone` string

  * Timezone of the incoming request, for example, `"America/Chicago"`.



:::caution


The `request.cf` object is not available in the Cloudflare Workers dashboard or Playground preview editor.


:::

***

## Methods

### Instance methods

These methods are only available on an instance of a `Request` object or through its prototype.



* `clone()` : Promise\<Request>

  * Creates a copy of the `Request` object.

* `arrayBuffer()` : Promise\<ArrayBuffer>

  * Returns a promise that resolves with an [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) representation of the request body.

* `formData()` : Promise\<FormData>

  * Returns a promise that resolves with a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) representation of the request body.

* `json()` : Promise\<Object>

  * Returns a promise that resolves with a JSON representation of the request body.

* `text()` : Promise\<string>

  * Returns a promise that resolves with a string (text) representation of the request body.



***

## The `Request` context

Each time a Worker is invoked by an incoming HTTP request, the [`fetch()` handler](/workers/runtime-apis/handlers/fetch) is called on your Worker. The `Request` context starts when the `fetch()` handler is called, and asynchronous tasks (such as making a subrequest using the [`fetch() API`](/workers/runtime-apis/fetch/)) can only be run inside the `Request` context:

```js
export default {
	async fetch(request, env, ctx) {
        // Request context starts here
		return new Response('Hello World!');
	},
};
```

### When passing a promise to fetch event `.respondWith()`

If you pass a Response promise to the fetch event `.respondWith()` method, the request context is active during any asynchronous tasks which run before the Response promise has settled. You can pass the event to an async handler, for example:

```js
addEventListener("fetch", event => {
  event.respondWith(eventHandler(event))
})

// No request context available here

async function eventHandler(event){
  // Request context available here
  return new Response("Hello, Workers!")
}
```

### Errors when attempting to access an inactive `Request` context

Any attempt to use APIs such as `fetch()` or access the `Request` context during script startup will throw an exception:

```js
const promise = fetch("https://example.com/") // Error
async function eventHandler(event){..}
```

This code snippet will throw during script startup, and the `"fetch"` event listener will never be registered.

***

### Set the `Content-Length` header

The `Content-Length` header will be automatically set by the runtime based on whatever the data source for the `Request` is. Any value manually set by user code in the `Headers` will be ignored. To have a `Content-Length` header with a specific value specified, the `body` of the `Request` must be either a `FixedLengthStream` or a fixed-length value just as a string or `TypedArray`.

A `FixedLengthStream` is an identity `TransformStream` that permits only a fixed number of bytes to be written to it.

```js
  const { writable, readable } = new FixedLengthStream(11);

  const enc = new TextEncoder();
  const writer = writable.getWriter();
  writer.write(enc.encode("hello world"));
  writer.end();

  const req = new Request('https://example.org', { method: 'POST', body: readable });
```

Using any other type of `ReadableStream` as the body of a request will result in Chunked-Encoding being used.

***

## Related resources

* [Examples: Modify request property](/workers/examples/modify-request-property/)
* [Examples: Accessing the `cf` object](/workers/examples/accessing-the-cloudflare-object/)
* [Reference: `Response`](/workers/runtime-apis/response/)
* Write your Worker code in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.

---

# Response

URL: https://developers.cloudflare.com/workers/runtime-apis/response/

The `Response` interface represents an HTTP response and is part of the Fetch API.

***

## Constructor

```js
let response = new Response(body, init);
```

### Parameters



* `body` optional

  * An object that defines the body text for the response. Can be `null` or any one of the following types:

    * BufferSource
    * FormData
    * ReadableStream
    * URLSearchParams
    * USVString

* `init` optional

  * An `options` object that contains custom settings to apply to the response.



Valid options for the `options` object include:

* `cf` any | null
  * An object that contains Cloudflare-specific information. This object is not part of the Fetch API standard and is only available in Cloudflare Workers. This field is only used by consumers of the Response for informational purposes and does not have any impact on Workers behavior.
* `encodeBody` string
  * Workers have to compress data according to the `content-encoding` header when transmitting, to serve data that is already compressed, this property has to be set to `"manual"`, otherwise the default is `"automatic"`.
* `headers` Headers | ByteString
  * Any headers to add to your response that are contained within a [`Headers`](/workers/runtime-apis/request/#parameters) object or object literal of [`ByteString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) key-value pairs.
* `status` int
  * The status code for the response, such as `200`.
* `statusText` string
  * The status message associated with the status code, such as, `OK`.
* `webSocket` WebSocket | null
  * This is present in successful WebSocket handshake responses. For example, if a client sends a WebSocket upgrade request to an origin and a Worker intercepts the request and then forwards it to the origin and the origin replies with a successful WebSocket upgrade response, the Worker sees `response.webSocket`. This establishes a WebSocket connection proxied through a Worker. Note that you cannot intercept data flowing over a WebSocket connection.



## Properties



* `response.body` Readable Stream
  * A getter to get the body contents.
* `response.bodyUsed` boolean
  * A boolean indicating if the body was used in the response.
* `response.headers` Headers
  * The headers for the response.
* `response.ok` boolean
  * A boolean indicating if the response was successful (status in the range `200`-`299`).
* `response.redirected` boolean
  * A boolean indicating if the response is the result of a redirect. If so, its URL list has more than one entry.
* `response.status` int
  * The status code of the response (for example, `200` to indicate success).
* `response.statusText` string
  * The status message corresponding to the status code (for example, `OK` for `200`).
* `response.url` string
  * The URL of the response. The value is the final URL obtained after any redirects.
* `response.webSocket` WebSocket?
  * This is present in successful WebSocket handshake responses. For example, if a client sends a WebSocket upgrade request to an origin and a Worker intercepts the request and then forwards it to the origin and the origin replies with a successful WebSocket upgrade response, the Worker sees `response.webSocket`. This establishes a WebSocket connection proxied through a Worker. Note that you cannot intercept data flowing over a WebSocket connection.



## Methods

### Instance methods



* `clone()` : Response

  * Creates a clone of a [`Response`](#response) object.

* `json()` : Response

  * Creates a new response with a JSON-serialized payload.

* `redirect()` : Response

  * Creates a new response with a different URL.



### Additional instance methods

`Response` implements the [`Body`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#body) mixin of the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), and therefore `Response` instances additionally have the following methods available:



* <code>arrayBuffer()</code> : Promise\<ArrayBuffer>

  * Takes a [`Response`](#response) stream, reads it to completion, and returns a promise that resolves with an [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer).

* <code>formData()</code> : Promise\<FormData>

  * Takes a [`Response`](#response) stream, reads it to completion, and returns a promise that resolves with a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object.

* <code>json()</code> : Promise\<JSON>

  * Takes a [`Response`](#response) stream, reads it to completion, and returns a promise that resolves with the result of parsing the body text as [`JSON`](https://developer.mozilla.org/en-US/docs/Web/).

* <code>text()</code> : Promise\<USVString>

  * Takes a [`Response`](#response) stream, reads it to completion, and returns a promise that resolves with a [`USVString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) (text).



### Set the `Content-Length` header

The `Content-Length` header will be automatically set by the runtime based on whatever the data source for the `Response` is. Any value manually set by user code in the `Headers` will be ignored. To have a `Content-Length` header with a specific value specified, the `body` of the `Response` must be either a `FixedLengthStream` or a fixed-length value just as a string or `TypedArray`.

A `FixedLengthStream` is an identity `TransformStream` that permits only a fixed number of bytes to be written to it.

```js
  const { writable, readable } = new FixedLengthStream(11);

  const enc = new TextEncoder();
  const writer = writable.getWriter();
  writer.write(enc.encode("hello world"));
  writer.end();

  return new Response(readable);
```

Using any other type of `ReadableStream` as the body of a response will result in chunked encoding being used.

***

## Related resources

* [Examples: Modify response](/workers/examples/modify-response/)
* [Examples: Conditional response](/workers/examples/conditional-response/)
* [Reference: `Request`](/workers/runtime-apis/request/)
* Write your Worker code in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.

---

# TCP sockets

URL: https://developers.cloudflare.com/workers/runtime-apis/tcp-sockets/

The Workers runtime provides the `connect()` API for creating outbound [TCP connections](https://www.cloudflare.com/learning/ddos/glossary/tcp-ip/) from Workers.

Many application-layer protocols are built on top of the Transmission Control Protocol (TCP). These application-layer protocols, including SSH, MQTT, SMTP, FTP, IRC, and most database wire protocols including MySQL, PostgreSQL, MongoDB, require an underlying TCP socket API in order to work.

:::note

Connecting to a PostgreSQL database? You should use [Hyperdrive](/hyperdrive/), which provides the `connect()` API with built-in connection pooling and query caching.
:::

:::note

TCP Workers outbound connections are sourced from a prefix that is not part of [list of IP ranges](https://www.cloudflare.com/ips/).
:::

## `connect()`

The `connect()` function returns a TCP socket, with both a [readable](/workers/runtime-apis/streams/readablestream/) and [writable](/workers/runtime-apis/streams/writablestream/) stream of data. This allows you to read and write data on an ongoing basis, as long as the connection remains open.

`connect()` is provided as a [Runtime API](/workers/runtime-apis/), and is accessed by importing the `connect` function from `cloudflare:sockets`. This process is similar to how one imports built-in modules in Node.js. Refer to the following codeblock for an example of creating a TCP socket, writing to it, and returning the readable side of the socket as a response:

```typescript
import { connect } from 'cloudflare:sockets';

export default {
  async fetch(req): Promise<Response> {
    const gopherAddr = { hostname: "gopher.floodgap.com", port: 70 };
    const url = new URL(req.url);

    try {
      const socket = connect(gopherAddr);

      const writer = socket.writable.getWriter()
      const encoder = new TextEncoder();
      const encoded = encoder.encode(url.pathname + "\r\n");
      await writer.write(encoded);
      await writer.close();

      return new Response(socket.readable, { headers: { "Content-Type": "text/plain" } });
    } catch (error) {
      return new Response("Socket connection failed: " + error, { status: 500 });
    }
  }
} satisfies ExportedHandler;
```



* <code>connect(address: SocketAddress | string, options?: optional SocketOptions)</code> : `Socket`
  * `connect()` accepts either a URL string or [`SocketAddress`](/workers/runtime-apis/tcp-sockets/#socketaddress) to define the hostname and port number to connect to, and an optional configuration object, [`SocketOptions`](/workers/runtime-apis/tcp-sockets/#socketoptions). It returns an instance of a [`Socket`](/workers/runtime-apis/tcp-sockets/#socket).


### `SocketAddress`



* `hostname` string
  * The hostname to connect to. Example: `cloudflare.com`.

* `port` number
  * The port number to connect to. Example: `5432`.



### `SocketOptions`



* `secureTransport` "off" | "on" | "starttls" — Defaults to `off`
  * Specifies whether or not to use [TLS](https://www.cloudflare.com/learning/ssl/transport-layer-security-tls/) when creating the TCP socket.
  * `off` — Do not use TLS.
  * `on` — Use TLS.
  * `starttls` — Do not use TLS initially, but allow the socket to be upgraded to use TLS by calling [`startTls()`](/workers/runtime-apis/tcp-sockets/#opportunistic-tls-starttls).

* `allowHalfOpen` boolean — Defaults to `false`
  * Defines whether the writable side of the TCP socket will automatically close on end-of-file (EOF). When set to `false`, the writable side of the TCP socket will automatically close on EOF. When set to `true`, the writable side of the TCP socket will remain open on EOF.
  * This option is similar to that offered by the Node.js [`net` module](https://nodejs.org/api/net.html) and allows interoperability with code which utilizes it.



### `SocketInfo`



* `remoteAddress` string | null
  * The address of the remote peer the socket is connected to. May not always be set.

* `localAddress` string | null
  * The address of the local network endpoint for this socket. May not always be set.



### `Socket`



* <code>readable</code> : ReadableStream
  * Returns the readable side of the TCP socket.

* <code>writable</code> : WritableStream
  * Returns the writable side of the TCP socket.
  * The `WritableStream` returned only accepts chunks of `Uint8Array` or its views.

* `opened` `Promise<SocketInfo>`
  * This promise is resolved when the socket connection is established and is rejected if the socket encounters an error.

* `closed` `Promise<void>`
  * This promise is resolved when the socket is closed and is rejected if the socket encounters an error.

* `close()` `Promise<void>`
  * Closes the TCP socket. Both the readable and writable streams are forcibly closed.

* <code>startTls()</code> : Socket
  * Upgrades an insecure socket to a secure one that uses TLS, returning a new [Socket](/workers/runtime-apis/tcp-sockets#socket). Note that in order to call `startTls()`, you must set [`secureTransport`](/workers/runtime-apis/tcp-sockets/#socketoptions) to `starttls` when initially calling `connect()` to create the socket.



## Opportunistic TLS (StartTLS)

Many TCP-based systems, including databases and email servers, require that clients use opportunistic TLS (otherwise known as [StartTLS](https://en.wikipedia.org/wiki/Opportunistic_TLS)) when connecting. In this pattern, the client first creates an insecure TCP socket, without TLS, and then upgrades it to a secure TCP socket, that uses TLS. The `connect()` API simplifies this by providing a method, `startTls()`, which returns a new `Socket` instance that uses TLS:

```typescript
import { connect } from "cloudflare:sockets"

const address = {
  hostname: "example-postgres-db.com",
  port: 5432
};
const socket = connect(address, { secureTransport: "starttls" });
const secureSocket = socket.startTls();
```

* `startTls()` can only be called if `secureTransport` is set to `starttls` when creating the initial TCP socket.
* Once `startTls()` is called, the initial socket is closed and can no longer be read from or written to. In the example above, anytime after `startTls()` is called, you would use the newly created `secureSocket`. Any existing readers and writers based off the original socket will no longer work. You must create new readers and writers from the newly created `secureSocket`.
* `startTls()` should only be called once on an existing socket.

## Handle errors

To handle errors when creating a new TCP socket, reading from a socket, or writing to a socket, wrap these calls inside `try..catch` blocks. The following example opens a connection to Google.com, initiates a HTTP request, and returns the response. If any of this fails and throws an exception, it returns a `500` response:

```typescript
import { connect } from 'cloudflare:sockets';
const connectionUrl = { hostname: "google.com", port: 80 };
export interface Env { }
export default {
  async fetch(req, env, ctx): Promise<Response> {
    try {
      const socket = connect(connectionUrl);
      const writer = socket.writable.getWriter();
      const encoder = new TextEncoder();
      const encoded = encoder.encode("GET / HTTP/1.0\r\n\r\n");
      await writer.write(encoded);
      await writer.close();

      return new Response(socket.readable, { headers: { "Content-Type": "text/plain" } });
    } catch (error) {
      return new Response(`Socket connection failed: ${error}`, { status: 500 });
    }
  }
} satisfies ExportedHandler<Env>;
```

## Close TCP connections

You can close a TCP connection by calling `close()` on the socket. This will close both the readable and writable sides of the socket.

```typescript
import { connect } from "cloudflare:sockets"

const socket = connect({ hostname: "my-url.com", port: 70 });
const reader = socket.readable.getReader();
socket.close();

// After close() is called, you can no longer read from the readable side of the socket
const reader = socket.readable.getReader(); // This fails
```

## Considerations

* Outbound TCP sockets to [Cloudflare IP ranges](https://www.cloudflare.com/ips/) are temporarily blocked, but will be re-enabled shortly.
* TCP sockets cannot be created in global scope and shared across requests. You should always create TCP sockets within a handler (ex: [`fetch()`](/workers/get-started/guide/#3-write-code), [`scheduled()`](/workers/runtime-apis/handlers/scheduled/), [`queue()`](/queues/configuration/javascript-apis/#consumer)) or [`alarm()`](/durable-objects/api/alarms/).
* Each open TCP socket counts towards the maximum number of [open connections](/workers/platform/limits/#simultaneous-open-connections) that can be simultaneously open.
* By default, Workers cannot create outbound TCP connections on port `25` to send email to SMTP mail servers. [Cloudflare Email Workers](/email-routing/email-workers/) provides APIs to process and forward email.
* Support for handling inbound TCP connections is [coming soon](https://blog.cloudflare.com/workers-tcp-socket-api-connect-databases/). Currently, it is not possible to make an inbound TCP connection to your Worker, for example, by using the `CONNECT` HTTP method.

## Troubleshooting

Review descriptions of common error messages you may see when working with TCP Sockets, what the error messages mean, and how to solve them.

### `proxy request failed, cannot connect to the specified address`

Your socket is connecting to an address that was disallowed. Examples of a disallowed address include Cloudflare IPs, `localhost`, and private network IPs.

If you need to connect to addresses on port `80` or `443` to make HTTP requests, use [`fetch`](/workers/runtime-apis/fetch/).

### `TCP Loop detected`

Your socket is connecting back to the Worker that initiated the outbound connection. In other words, the Worker is connecting back to itself. This is currently not supported.

### `Connections to port 25 are prohibited`

Your socket is connecting to an address on port `25`. This is usually the port used for SMTP mail servers. Workers cannot create outbound connections on port `25`. Consider using [Cloudflare Email Workers](/email-routing/email-workers/) instead.

---

# Web Crypto

URL: https://developers.cloudflare.com/workers/runtime-apis/web-crypto/

import { TabItem, Tabs } from "~/components"

## Background

The Web Crypto API provides a set of low-level functions for common cryptographic tasks. The Workers runtime implements the full surface of this API, but with some differences in the [supported algorithms](#supported-algorithms) compared to those implemented in most browsers.

Performing cryptographic operations using the Web Crypto API is significantly faster than performing them purely in JavaScript. If you want to perform CPU-intensive cryptographic operations, you should consider using the Web Crypto API.

The Web Crypto API is implemented through the `SubtleCrypto` interface, accessible via the global `crypto.subtle` binding. A simple example of calculating a digest (also known as a hash) is:

```js
const myText = new TextEncoder().encode('Hello world!');

const myDigest = await crypto.subtle.digest(
  {
    name: 'SHA-256',
  },
  myText // The data you want to hash as an ArrayBuffer
);

console.log(new Uint8Array(myDigest));
```

Some common uses include [signing requests](/workers/examples/signing-requests/).

:::caution

The Web Crypto API differs significantly from the [Node.js Crypto API](/workers/runtime-apis/nodejs/crypto/). If you are working with code that relies on the Node.js Crypto API, you can use it by enabling the [`nodejs_compat` compatibility flag](/workers/runtime-apis/nodejs/).
:::

***

## Constructors



* <code>crypto.DigestStream(algorithm)</code> DigestStream

  * A non-standard extension to the `crypto` API that supports generating a hash digest from streaming data. The `DigestStream` itself is a [`WritableStream`](/workers/runtime-apis/streams/writablestream/) that does not retain the data written into it. Instead, it generates a hash digest automatically when the flow of data has ended.



### Parameters



* <code>algorithm</code>string | object

  * Describes the algorithm to be used, including any required parameters, in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest#Syntax).



### Usage

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
  async fetch(req) {
    // Fetch from origin
    const res = await fetch(req);

    // We need to read the body twice so we `tee` it (get two instances)
    const [bodyOne, bodyTwo] = res.body.tee();
    // Make a new response so we can set the headers (responses from `fetch` are immutable)
    const newRes = new Response(bodyOne, res);
    // Create a SHA-256 digest stream and pipe the body into it
    const digestStream = new crypto.DigestStream("SHA-256");
    bodyTwo.pipeTo(digestStream);
    // Get the final result
    const digest = await digestStream.digest;
    // Turn it into a hex string
    const hexString = [...new Uint8Array(digest)]
      .map(b => b.toString(16).padStart(2, '0'))
      .join('')
    // Set a header with the SHA-256 hash and return the response
    newRes.headers.set("x-content-digest", `SHA-256=${hexString}`);
    return newRes;
  }
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
export default {
  async fetch(req): Promise<Response> {
    // Fetch from origin
    const res = await fetch(req);

    // We need to read the body twice so we `tee` it (get two instances)
    const [bodyOne, bodyTwo] = res.body.tee();
    // Make a new response so we can set the headers (responses from `fetch` are immutable)
    const newRes = new Response(bodyOne, res);
    // Create a SHA-256 digest stream and pipe the body into it
    const digestStream = new crypto.DigestStream("SHA-256");
    bodyTwo.pipeTo(digestStream);
    // Get the final result
    const digest = await digestStream.digest;
    // Turn it into a hex string
    const hexString = [...new Uint8Array(digest)]
      .map(b => b.toString(16).padStart(2, '0'))
      .join('')
    // Set a header with the SHA-256 hash and return the response
    newRes.headers.set("x-content-digest", `SHA-256=${hexString}`);
    return newRes;
  }
} satisfies ExportedHandler;
```

</TabItem> </Tabs>

## Methods



* <code>crypto.randomUUID()</code> : string

  * Generates a new random (version 4) UUID as defined in [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122.txt).

* <code>crypto.getRandomValues(bufferArrayBufferView)</code> : ArrayBufferView

  * Fills the passed <code>ArrayBufferView</code> with cryptographically sound random values and returns the <code>buffer</code>.



### Parameters



* <code>buffer</code>ArrayBufferView

  * Must be an Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | BigInt64Array | BigUint64Array.



## SubtleCrypto Methods

These methods are all accessed via [`crypto.subtle`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto#Methods), which is also documented in detail on MDN.

### encrypt



* <code>encrypt(algorithm, key, data)</code> : Promise\<ArrayBuffer>

  * Returns a Promise that fulfills with the encrypted data corresponding to the clear text, algorithm, and key given as parameters.



#### Parameters



* <code>algorithm</code>object

  * Describes the algorithm to be used, including any required parameters, in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/encrypt#Syntax).

* <code>key</code>CryptoKey

* <code>data</code>BufferSource



### decrypt



* <code>decrypt(algorithm, key, data)</code> : Promise\<ArrayBuffer>

  * Returns a Promise that fulfills with the clear data corresponding to the ciphertext, algorithm, and key given as parameters.



#### Parameters



* <code>algorithm</code>object

  * Describes the algorithm to be used, including any required parameters, in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/decrypt#Syntax).

* <code>key</code>CryptoKey

* <code>data</code>BufferSource



### sign



* <code>sign(algorithm, key, data)</code> : Promise\<ArrayBuffer>

  * Returns a Promise that fulfills with the signature corresponding to the text, algorithm, and key given as parameters.



#### Parameters



* <code>algorithm</code>string | object

  * Describes the algorithm to be used, including any required parameters, in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/sign#Syntax).

* <code>key</code>CryptoKey

* <code>data</code>ArrayBuffer



### verify



* <code>verify(algorithm, key, signature, data)</code> : Promise\<boolean>

  * Returns a Promise that fulfills with a Boolean value indicating if the signature given as a parameter matches the text, algorithm, and key that are also given as parameters.



#### Parameters



* <code>algorithm</code>string | object

  * Describes the algorithm to be used, including any required parameters, in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/verify#Syntax).

* <code>key</code>CryptoKey

* <code>signature</code>ArrayBuffer

* <code>data</code>ArrayBuffer



### digest



* <code>digest(algorithm, data)</code> : Promise\<ArrayBuffer>

  * Returns a Promise that fulfills with a digest generated from the algorithm and text given as parameters.



#### Parameters



* <code>algorithm</code>string | object

  * Describes the algorithm to be used, including any required parameters, in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest#Syntax).

* <code>data</code>ArrayBuffer



### generateKey



* <code>generateKey(algorithm, extractable, keyUsages)</code> : Promise\<CryptoKey> | Promise\<CryptoKeyPair>

  * Returns a Promise that fulfills with a newly-generated `CryptoKey`, for symmetrical algorithms, or a `CryptoKeyPair`, containing two newly generated keys, for asymmetrical algorithms. For example, to generate a new AES-GCM key:

  ```js
  let keyPair = await crypto.subtle.generateKey(
    {
      name: 'AES-GCM',
      length: 256,
    },
    true,
    ['encrypt', 'decrypt']
  );
  ```



#### Parameters



* <code>algorithm</code>object

  * Describes the algorithm to be used, including any required parameters, in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey#Syntax).

* <code>extractable</code>bool

* <code>keyUsages</code>Array

  * An Array of strings indicating the [possible usages of the new key](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/generateKey#Syntax).



### deriveKey



* <code>deriveKey(algorithm, baseKey, derivedKeyAlgorithm, extractable, keyUsages)</code> : Promise\<CryptoKey>

  * Returns a Promise that fulfills with a newly generated `CryptoKey` derived from the base key and specific algorithm given as parameters.



#### Parameters



* <code>algorithm</code>object

  * Describes the algorithm to be used, including any required parameters, in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/deriveKey#Syntax).

* <code>baseKeyCryptoKey</code>

* <code>derivedKeyAlgorithmobject</code>

  * Defines the algorithm the derived key will be used for in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/deriveKey#Syntax).

* <code>extractablebool</code>

* <code>keyUsagesArray</code>

  * An Array of strings indicating the [possible usages of the new key](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/deriveKey#Syntax)



### deriveBits



* <code>deriveBits(algorithm, baseKey, length)</code> : Promise\<ArrayBuffer>

  * Returns a Promise that fulfills with a newly generated buffer of pseudo-random bits derived from the base key and specific algorithm given as parameters. It returns a Promise which will be fulfilled with an `ArrayBuffer` containing the derived bits. This method is very similar to `deriveKey()`, except that `deriveKey()` returns a `CryptoKey` object rather than an `ArrayBuffer`. Essentially, `deriveKey()` is composed of `deriveBits()` followed by `importKey()`.



#### Parameters



* <code>algorithm</code>object

  * Describes the algorithm to be used, including any required parameters, in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/deriveBits#Syntax).

* <code>baseKey</code>CryptoKey

* <code>length</code>int

  * Length of the bit string to derive.



### importKey



* <code>importKey(format, keyData, algorithm, extractable, keyUsages)</code> : Promise\<CryptoKey>

  * Transform a key from some external, portable format into a `CryptoKey` for use with the Web Crypto API.



#### Parameters



* <code>format</code>string

  * Describes [the format of the key to be imported](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#Syntax).

* <code>keyData</code>ArrayBuffer

* <code>algorithm</code>object

  * Describes the algorithm to be used, including any required parameters, in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#Syntax).

* <code>extractable</code>bool

* <code>keyUsages</code>Array

  * An Array of strings indicating the [possible usages of the new key](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/importKey#Syntax)



### exportKey



* <code>exportKey(formatstring, keyCryptoKey)</code> : Promise\<ArrayBuffer>

  * Transform a `CryptoKey` into a portable format, if the `CryptoKey` is `extractable`.



#### Parameters



* <code>format</code>string

  * Describes the [format in which the key will be exported](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/exportKey#Syntax).

* <code>key</code>CryptoKey



### wrapKey



* <code>wrapKey(format, key, wrappingKey, wrapAlgo)</code> : Promise\<ArrayBuffer>

  * Transform a `CryptoKey` into a portable format, and then encrypt it with another key. This renders the `CryptoKey` suitable for storage or transmission in untrusted environments.



#### Parameters



* <code>format</code>string

  * Describes the [format in which the key will be exported](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/wrapKey#Syntax) before being encrypted.

* <code>key</code>CryptoKey

* <code>wrappingKey</code>CryptoKey

* <code>wrapAlgo</code>object

  * Describes the algorithm to be used to encrypt the exported key, including any required parameters, in [an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/wrapKey#Syntax).



### unwrapKey



* <code>unwrapKey(format, key, unwrappingKey, unwrapAlgo, <br/> unwrappedKeyAlgo, extractable, keyUsages)</code> : Promise\<CryptoKey>

  * Transform a key that was wrapped by `wrapKey()` back into a `CryptoKey`.



#### Parameters



* <code>format</code>string

  * Described the [data format of the key to be unwrapped](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/unwrapKey#Syntax).

* <code>key</code>CryptoKey

* <code>unwrappingKey</code>CryptoKey

* <code>unwrapAlgo</code>object

  * Describes the algorithm that was used to encrypt the wrapped key, [in an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/unwrapKey#Syntax).

* <code>unwrappedKeyAlgo</code>object

  * Describes the key to be unwrapped, [in an algorithm-specific format](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/unwrapKey#Syntax).

* <code>extractable</code>bool

* <code>keyUsages</code>Array

  * An Array of strings indicating the [possible usages of the new key](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/unwrapKey#Syntax)



### timingSafeEqual



* <code>timingSafeEqual(a, b)</code> : bool

  * Compare two buffers in a way that is resistant to timing attacks. This is a non-standard extension to the Web Crypto API.



#### Parameters



* <code>a</code>ArrayBuffer | TypedArray

* <code>b</code>ArrayBuffer | TypedArray



### Supported algorithms

Workers implements all operations of the [WebCrypto standard](https://www.w3.org/TR/WebCryptoAPI/), as shown in the following table.

A checkmark (✓) indicates that this feature is believed to be fully supported according to the spec.<br/>
An x (✘) indicates that this feature is part of the specification but not implemented.<br/>
If a feature only implements the operation partially, details are listed.



| Algorithm                                          | sign()<br/>verify() | encrypt()<br/>decrypt() | digest() | deriveBits()<br/>deriveKey() | generateKey() | wrapKey()<br/>unwrapKey() | exportKey() | importKey() |
| :------------------------------------------------- | :------------------ | :---------------------- | :------- | :--------------------------- | :------------ | :------------------------ | :---------- | :---------- |
| RSASSA PKCS1 v1.5                                  | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
| RSA PSS                                            | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
| RSA OAEP                                           |                     | ✓                       |          |                              | ✓             | ✓                         | ✓           | ✓           |
| ECDSA                                              | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
| ECDH                                               |                     |                         |          | ✓                            | ✓             |                           | ✓           | ✓           |
| Ed25519<sup><a href="#footnote-1">1</a></sup>      | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
| X25519<sup><a href="#footnote-1">1</a></sup>       |                     |                         |          | ✓                            | ✓             |                           | ✓           | ✓           |
| NODE ED25519<sup><a href="#footnote-2">2</a></sup> | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
| AES CTR                                            |                     | ✓                       |          |                              | ✓             | ✓                         | ✓           | ✓           |
| AES CBC                                            |                     | ✓                       |          |                              | ✓             | ✓                         | ✓           | ✓           |
| AES GCM                                            |                     | ✓                       |          |                              | ✓             | ✓                         | ✓           | ✓           |
| AES KW                                             |                     |                         |          |                              | ✓             | ✓                         | ✓           | ✓           |
| HMAC                                               | ✓                   |                         |          |                              | ✓             |                           | ✓           | ✓           |
| SHA 1                                              |                     |                         | ✓        |                              |               |                           |             |             |
| SHA 256                                            |                     |                         | ✓        |                              |               |                           |             |             |
| SHA 384                                            |                     |                         | ✓        |                              |               |                           |             |             |
| SHA 512                                            |                     |                         | ✓        |                              |               |                           |             |             |
| MD5<sup><a href="#footnote-3">3</a></sup>          |                     |                         | ✓        |                              |               |                           |             |             |
| HKDF                                               |                     |                         |          | ✓                            |               |                           |             | ✓           |
| PBKDF2                                             |                     |                         |          | ✓                            |               |                           |             | ✓           |



**Footnotes:**

1. <a name="footnote-1"></a> Algorithms as specified in the [Secure Curves API](https://wicg.github.io/webcrypto-secure-curves).

2. <a name="footnote-2"></a> Legacy non-standard EdDSA is supported for the Ed25519 curve in addition to the Secure Curves version. Since this algorithm is non-standard, note the following while using it:

   * Use <code>NODE-ED25519</code> as the algorithm and `namedCurve` parameters.
   * Unlike NodeJS, Cloudflare will not support raw import of private keys.
   * The algorithm implementation may change over time. While Cloudflare cannot guarantee it at this time, Cloudflare will strive to maintain backward compatibility and compatibility with NodeJS's behavior. Any notable compatibility notes will be communicated in release notes and via this developer documentation.

3. <a name="footnote-3"></a> MD5 is not part of the WebCrypto standard but is supported in Cloudflare Workers for interacting with legacy systems that require MD5. MD5 is considered a weak algorithm. Do not rely upon MD5 for security.

***

## Related resources

* [SubtleCrypto documentation on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto)
* [SubtleCrypto documentation as part of the W3C Web Crypto API specification](https://www.w3.org/TR/WebCryptoAPI//#subtlecrypto-interface)
* [Example: signing requests](/workers/examples/signing-requests/)

---

# Web standards

URL: https://developers.cloudflare.com/workers/runtime-apis/web-standards/

***

## JavaScript standards

The Cloudflare Workers runtime is [built on top of the V8 JavaScript and WebAssembly engine](/workers/reference/how-workers-works/). The Workers runtime is updated at least once a week, to at least the version of V8 that is currently used by Google Chrome's stable release. This means you can safely use the latest JavaScript features, with no need for transpilers.

All of the [standard built-in objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference) supported by the current Google Chrome stable release are supported, with a few notable exceptions:

* For security reasons, the following are not allowed:
  * `eval()`
  * `new Function`
  * [`WebAssembly.compile`](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/compile_static)
  * [`WebAssembly.compileStreaming`](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/compileStreaming_static)
  * `WebAssembly.instantiate` with a [buffer parameter](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/instantiate_static#primary_overload_%E2%80%94_taking_wasm_binary_code)
  * [`WebAssembly.instantiateStreaming`](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/instantiateStreaming_static)
* `Date.now()` returns the time of the last I/O; it does not advance during code execution.

***

## Web standards and global APIs

The following methods are available per the [Worker Global Scope](https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope):

### Base64 utility methods



* atob()

  * Decodes a string of data which has been encoded using base-64 encoding.

* btoa()

  * Creates a base-64 encoded ASCII string from a string of binary data.



### Timers



* setInterval()

  * Schedules a function to execute every time a given number of milliseconds elapses.

* clearInterval()

  * Cancels the repeated execution set using [`setInterval()`](https://developer.mozilla.org/en-US/docs/Web/API/setInterval).

* setTimeout()

  * Schedules a function to execute in a given amount of time.

* clearTimeout()

  * Cancels the delayed execution set using [`setTimeout()`](https://developer.mozilla.org/en-US/docs/Web/API/setTimeout).



:::note


Timers are only available inside of [the Request Context](/workers/runtime-apis/request/#the-request-context).


:::

### `performance.timeOrigin` and `performance.now()`

* performance.timeOrigin

  * Returns the high resolution time origin. Workers uses the UNIX epoch as the time origin, meaning that `performance.timeOrigin` will always return `0`.

* performance.now()

  * Returns a `DOMHighResTimeStamp` representing the number of milliseconds elapsed since `performance.timeOrigin`. Note that Workers intentionally reduces the precision of `performance.now()` such that it returns the time of the last I/O and does not advance during code execution. Effectively, because of this, and because `performance.timeOrigin` is always, `0`, `performance.now()` will always equal `Date.now()`, yielding a consistent view of the passage of time within a Worker.

### `EventTarget` and `Event`

The [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) and [`Event`](https://developer.mozilla.org/en-US/docs/Web/API/Event) API allow objects to publish and subscribe to events.

### `AbortController` and `AbortSignal`

The [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) and [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) APIs provide a common model for canceling asynchronous operations.

### Fetch global



* fetch()

  * Starts the process of fetching a resource from the network. Refer to [Fetch API](/workers/runtime-apis/fetch/).



:::note


The Fetch API is only available inside of [the Request Context](/workers/runtime-apis/request/#the-request-context).


:::

***

## Encoding API

Both `TextEncoder` and `TextDecoder` support UTF-8 encoding/decoding.

[Refer to the MDN documentation for more information](https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API).

The [`TextEncoderStream`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoderStream) and [`TextDecoderStream`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoderStream) classes are also available.

***

## URL API

The URL API supports URLs conforming to HTTP and HTTPS schemes.

[Refer to the MDN documentation for more information](https://developer.mozilla.org/en-US/docs/Web/API/URL)

:::note


The default URL class behavior differs from the URL Spec documented above.

A new spec-compliant implementation of the URL class can be enabled using the `url_standard` [compatibility flag](/workers/configuration/compatibility-flags/).


:::

***

## Compression Streams

The `CompressionStream` and `DecompressionStream` classes support the deflate, deflate-raw and gzip compression methods.

[Refer to the MDN documentation for more information](https://developer.mozilla.org/en-US/docs/Web/API/Compression_Streams_API)

***

## URLPattern API

The `URLPattern` API provides a mechanism for matching URLs based on a convenient pattern syntax.

[Refer to the MDN documentation for more information](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern).

***

## `Intl`

The `Intl` API allows you to format dates, times, numbers, and more to the format that is used by a provided locale (language and region).

[Refer to the MDN documentation for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl).

***

## `navigator.userAgent`

When the [`global_navigator`](/workers/configuration/compatibility-flags/#global-navigator) compatibility flag is set, the [`navigator.userAgent`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent) property is available with the value `'Cloudflare-Workers'`. This can be used, for example, to reliably determine that code is running within the Workers environment.

## Unhandled promise rejections

The [`unhandledrejection`](https://developer.mozilla.org/en-US/docs/Web/API/Window/unhandledrejection_event) event is emitted by the global scope when a JavaScript promise is rejected without a rejection handler attached.

The [`rejectionhandled`](https://developer.mozilla.org/en-US/docs/Web/API/Window/rejectionhandled_event) event is emitted by the global scope when a JavaScript promise rejection is handled late (after a rejection handler is attached to the promise after an `unhandledrejection` event has already been emitted).

```js title="worker.js"
addEventListener('unhandledrejection', (event) => {
  console.log(event.promise);  // The promise that was rejected.
  console.log(event.reason);  // The value or Error with which the promise was rejected.
});

addEventListener('rejectionhandled', (event) => {
  console.log(event.promise);  // The promise that was rejected.
  console.log(event.reason);  // The value or Error with which the promise was rejected.
});
```

***

## `navigator.sendBeacon(url[, data])`

When the [`global_navigator`](/workers/configuration/compatibility-flags/#global-navigator) compatibility flag is set, the [`navigator.sendBeacon(...)`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon) API is available to send an HTTP `POST` request containing a small amount of data to a web server. This API is intended as a means of transmitting analytics or diagnostics information asynchronously on a best-effort basis.

For example, you can replace:

```js
const promise = fetch('https://example.com', { method: 'POST', body: 'hello world' });
ctx.waitUntil(promise);
```

with `navigator.sendBeacon(...)`:

```js
navigator.sendBeacon('https://example.com', 'hello world');
```

---

# WebSockets

URL: https://developers.cloudflare.com/workers/runtime-apis/websockets/

## Background

WebSockets allow you to communicate in real time with your Cloudflare Workers serverless functions. For a complete example, refer to [Using the WebSockets API](/workers/examples/websockets/).

:::note


If your application needs to coordinate among multiple WebSocket connections, such as a chat room or game match, you will need clients to send messages to a single-point-of-coordination. Durable Objects provide a single-point-of-coordination for Cloudflare Workers, and are often used in parallel with WebSockets to persist state over multiple clients and connections. In this case, refer to [Durable Objects](/durable-objects/) to get started, and prefer using the Durable Objects' extended [WebSockets API](/durable-objects/best-practices/websockets/).


:::

## Constructor

```js
// { 0: <WebSocket>, 1: <WebSocket> }
let websocketPair = new WebSocketPair();
```

The WebSocketPair returned from this constructor is an Object, with two WebSockets at keys `0` and `1`.

These WebSockets are commonly referred to as `client` and `server`. The below example combines `Object.values` and ES6 destructuring to retrieve the WebSockets as `client` and `server`:

```js
let [client, server] = Object.values(new WebSocketPair());
```

## Methods

### accept



* <code>accept()</code>

  * Accepts the WebSocket connection and begins terminating requests for the WebSocket on Cloudflare's global network. This effectively enables the Workers runtime to begin responding to and handling WebSocket requests.



### addEventListener



* <code>addEventListener(eventWebSocketEvent, callbackFunctionFunction)</code>

  * Add callback functions to be executed when an event has occurred on the WebSocket.



#### Parameters



* `event` WebSocketEvent

  * The WebSocket event (refer to [Events](/workers/runtime-apis/websockets/#events)) to listen to.

* <code>callbackFunction(messageMessage)</code> Function

  * A function to be called when the WebSocket responds to a specific event.



### close



* <code>close(codenumber, reasonstring)</code>

  * Close the WebSocket connection.



#### Parameters



* <code>codeinteger</code> optional

  * An integer indicating the close code sent by the server. This should match an option from the [list of status codes](https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#status_codes) provided by the WebSocket spec.

* <code>reasonstring</code> optional

  * A human-readable string indicating why the WebSocket connection was closed.



### send



* <code>send(messagestring | ArrayBuffer | ArrayBufferView)</code>

  * Send a message to the other WebSocket in this WebSocket pair.



#### Parameters



* <code>messagestring</code>

  * The message to send down the WebSocket connection to the corresponding client. This should be a string or something coercible into a string; for example, strings and numbers will be simply cast into strings, but objects and arrays should be cast to JSON strings using <code>JSON.stringify</code>, and parsed in the client.



***

## Events



* <code>close</code>
  * An event indicating the WebSocket has closed.

* <code>error</code>
  * An event indicating there was an error with the WebSocket.

* <code>message</code>
  * An event indicating a new message received from the client, including the data passed by the client.



:::note


WebSocket messages received by a Worker have a size limit of 1 MiB (1048576).  If a larger message is sent, the WebSocket will be automatically closed with a `1009` "Message is too large" response.


:::

## Types

### Message



* `data` any - The data passed back from the other WebSocket in your pair.
* `type` string - Defaults to `message`.



***

## Related resources

* [Mozilla Developer Network's (MDN) documentation on the WebSocket class](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
* [Our WebSocket template for building applications on Workers using WebSockets](https://github.com/cloudflare/websocket-template)

---

# Testing

URL: https://developers.cloudflare.com/workers/testing/

import { Render, LinkButton } from "~/components";

The Workers platform has a variety of ways to test your applications, depending on your requirements. We recommend using the [Vitest integration](/workers/testing/vitest-integration), which allows you to run tests to _inside_ the Workers runtime, and unit test individual functions within your Worker.

<LinkButton href="/workers/testing/vitest-integration/write-your-first-test/">
	Get started with Vitest
</LinkButton>

## Testing comparison matrix

However, if you don't use Vitest, both [Miniflare's API](/workers/testing/miniflare/writing-tests) and the [`unstable_startWorker()`](/workers/wrangler/api/#unstable_startworker) API provide options for testing your Worker in any testing framework.

| Feature                               | [Vitest integration](/workers/testing/vitest-integration) | [`unstable_startWorker()`](/workers/testing/unstable_startworker/) | [Miniflare's API](/workers/testing/miniflare/writing-tests/) |
| ------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ |
| Unit testing                          | ✅                                                        | ❌                                                                 | ❌                                                           |
| Integration testing                   | ✅                                                        | ✅                                                                 | ✅                                                           |
| Loading Wrangler configuration files  | ✅                                                        | ✅                                                                 | ❌                                                           |
| Use bindings directly in tests        | ✅                                                        | ❌                                                                 | ✅                                                           |
| Isolated per-test storage             | ✅                                                        | ❌                                                                 | ❌                                                           |
| Outbound request mocking              | ✅                                                        | ❌                                                                 | ✅                                                           |
| Multiple Worker support               | ✅                                                        | ✅                                                                 | ✅                                                           |
| Direct access to Durable Objects      | ✅                                                        | ❌                                                                 | ❌                                                           |
| Run Durable Object alarms immediately | ✅                                                        | ❌                                                                 | ❌                                                           |
| List Durable Objects                  | ✅                                                        | ❌                                                                 | ❌                                                           |
| Testing service Workers               | ❌                                                        | ✅                                                                 | ✅                                                           |

<Render file="testing-pages-functions" product="workers" />

---

# Wrangler's unstable_startWorker()

URL: https://developers.cloudflare.com/workers/testing/unstable_startworker/

import { Render } from "~/components";
import { LinkButton } from "@astrojs/starlight/components";

:::note
For most users, Cloudflare recommends using the Workers Vitest integration. If you have been using `unstable_dev()`, refer to the [Migrate from `unstable_dev()` guide](/workers/testing/vitest-integration/migration-guides/migrate-from-unstable-dev/).
:::

:::caution
`unstable_startWorker()` is an experimental API subject to breaking changes.
:::

If you do not want to use Vitest, consider using [Wrangler's `unstable_startWorker()` API](/workers/wrangler/api/#unstable_startworker). This API exposes the internals of Wrangler's dev server, and allows you to customise how it runs. Compared to using [Miniflare directly for testing](/workers/testing/miniflare/writing-tests/), you can pass in a Wrangler configuration file, and it will automatically load the configuration for you.

This example uses `node:test`, but should apply to any testing framework:

    ```ts
    import assert from "node:assert";
    import test, { after, before, describe } from "node:test";
    import { unstable_startWorker } from "wrangler";

    describe("worker", () => {
    	let worker;

    	before(async () => {
    		worker = await unstable_startWorker({ config: "wrangler.json" });
    	});

    	test("hello world", async () => {
    		assert.strictEqual(
    			await (await worker.fetch("http://example.com")).text(),
    			"Hello world",
    		);
    	});

    	after(async () => {
    		await worker.dispose();
    	});
    });

    ```

---

# Billing and Limitations

URL: https://developers.cloudflare.com/workers/static-assets/billing-and-limitations/

## Billing

Requests to a project with static assets can either return static assets or invoke the Worker script, depending on if the request [matches a static asset or not](/workers/static-assets/routing/).

- Requests to static assets are free and unlimited. Requests to the Worker script (for example, in the case of SSR content) are billed according to Workers pricing. Refer to [pricing](/workers/platform/pricing/#example-2) for an example.
- There is no additional cost for storing Assets.
- **Important note for free tier users**: When using [`run_worker_first`](/workers/static-assets/binding/#run_worker_first), requests matching the specified patterns will always invoke your Worker script. If you exceed your free tier request limits, these requests will receive a 429 (Too Many Requests) response instead of falling back to static asset serving. Negative patterns (patterns beginning with `!/`) will continue to serve assets correctly, as requests are directed to assets, without invoking your Worker script.

## Limitations

See the [Platform Limits](/workers/platform/limits/#static-assets)

## Troubleshooting

- `assets.bucket is a required field` — if you see this error, you need to update Wrangler to at least `3.78.10` or later. `bucket` is not a required field.

---

# Configuration and Bindings

URL: https://developers.cloudflare.com/workers/static-assets/binding/

import {
	Badge,
	Description,
	FileTree,
	InlineBadge,
	Render,
	TabItem,
	Tabs,
	WranglerConfig,
} from "~/components";

Configuring a Worker with assets requires specifying a [directory](/workers/static-assets/binding/#directory) and, optionally, an [assets binding](/workers/static-assets/binding/), in your Worker's Wrangler file. The [assets binding](/workers/static-assets/binding/) allows you to dynamically fetch assets from within your Worker script (e.g. `env.ASSETS.fetch()`), similarly to how you might with a make a `fetch()` call with a [Service binding](/workers/runtime-apis/bindings/service-bindings/http/).

Only one collection of static assets can be configured in each Worker.

## `directory`

The folder of static assets to be served. For many frameworks, this is the `./public/`, `./dist/`, or `./build/` folder.

<WranglerConfig>

```toml title="wrangler.toml"
name = "my-worker"
compatibility_date = "2024-09-19"
assets = { directory = "./public/" }
```

</WranglerConfig>

### Ignoring assets

Sometime there are files in the asset directory that should not be uploaded.

In this case, create a `.assetsignore` file in the root of the assets directory.
This file takes the same format as `.gitignore`.

Wrangler will not upload asset files that match lines in this file.

**Example**

You are migrating from a Pages project where the assets directory is `dist`.
You do not want to upload the server-side Worker code nor Pages configuration files as public client-side assets.
Add the following `.assetsignore` file:

```txt
_worker.js
_redirects
_headers
```

Now Wrangler will not upload these files as client-side assets when deploying the Worker.

## `run_worker_first`

Controls whether to invoke the Worker script regardless of a request which would have otherwise matched an asset. `run_worker_first = false` (default) will serve any static asset matching a request, while `run_worker_first = true` will unconditionally [invoke your Worker script](/workers/static-assets/routing/worker-script/#run-your-worker-script-first).

<WranglerConfig>

```toml title="wrangler.toml"
name = "my-worker"
compatibility_date = "2024-09-19"
main = "src/index.ts"
 # The following configuration unconditionally invokes the Worker script at
 # `src/index.ts`, which can programatically fetch assets via the ASSETS binding
[assets]
directory = "./public/"
binding = "ASSETS"
run_worker_first = true
```

</WranglerConfig>

You can also specify `run_worker_first` as an array of route patterns to selectively run the Worker script first only for specific routes. This is often paired with the [`not_found_handling = "single-page-application"` setting](/workers/static-assets/routing/single-page-application/#advanced-routing-control):

<WranglerConfig>

```json
{
	"name": "my-spa-worker",
	"compatibility_date": "$today",
	"main": "./src/index.ts",
	"assets": {
		"directory": "./dist/",
		"not_found_handling": "single-page-application",
		"binding": "ASSETS",
		"run_worker_first": ["/api/*", "!/api/docs/*"]
	}
}
```

</WranglerConfig>
The array supports glob patterns with `*` for deep matching and exception patterns with `!` prefix. In this configuration, requests to `/api/*` routes will invoke the Worker script first, except for `/api/docs/*` which will follow the default asset-first routing behavior.

## `binding`

Configuring the optional [binding](/workers/runtime-apis/bindings) gives you access to the collection of assets from within your Worker script.

<WranglerConfig>

```toml title="wrangler.toml"
name = "my-worker"
main = "./src/index.js"
compatibility_date = "2024-09-19"

[assets]
directory = "./public/"
binding = "ASSETS"
```

</WranglerConfig>

In the example above, assets would be available through `env.ASSETS`.

### Runtime API Reference

#### `fetch()`

**Parameters**

- `request: Request | URL | string` Pass a [Request object](/workers/runtime-apis/request/), URL object, or URL string. Requests made through this method have `html_handling` and `not_found_handling` configuration applied to them.

**Response**

- `Promise<Response>` Returns a static asset response for the given request.

**Example**

Your dynamic code can make new, or forward incoming requests to your project's static assets using the assets binding. For example, `env.ASSETS.fetch(request)`, `env.ASSETS.fetch(new URL('https://assets.local/my-file'))` or `env.ASSETS.fetch('https://assets.local/my-file')`.

Take the following example that configures a Worker script to return a response under all requests headed for `/api/`. Otherwise, the Worker script will pass the incoming request through to the asset binding. In this case, because a Worker script is only invoked when the requested route has not matched any static assets, this will always evaluate [`not_found_handling`](/workers/static-assets/#routing-behavior) behavior.

<Tabs>
<TabItem label="JavaScript" icon="seti:javascript">
```js
export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		if (url.pathname.startsWith("/api/")) {
			// TODO: Add your custom /api/* logic here.
			return new Response("Ok");
		}
		// Passes the incoming request through to the assets binding.
		// No asset matched this request, so this will evaluate `not_found_handling` behavior.
		return env.ASSETS.fetch(request);
	},
};
```
</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">
```ts
interface Env {
	ASSETS: Fetcher;
}

export default {
	async fetch(request, env): Promise<Response> {
		const url = new URL(request.url);
		if (url.pathname.startsWith("/api/")) {
			// TODO: Add your custom /api/* logic here.
			return new Response("Ok");
		}
		// Passes the incoming request through to the assets binding.
		// No asset matched this request, so this will evaluate `not_found_handling` behavior.
		return env.ASSETS.fetch(request);
	},
} satisfies ExportedHandler<Env>;
```
</TabItem>
</Tabs>

## Routing configuration

For the various static asset routing configuration options, refer to [Routing](/workers/static-assets/routing/).

## Smart Placement

[Smart Placement](/workers/configuration/smart-placement/) can be used to place a Worker's code close to your back-end infrastructure. Smart Placement will only have an effect if you specified a `main`, pointing to your Worker code.

### Smart Placement with Worker Code First

If you desire to run your [Worker code ahead of assets](/workers/static-assets/routing/worker-script/#run-your-worker-script-first) by setting `run_worker_first=true`, all requests must first travel to your Smart-Placed Worker. As a result, you may experience increased latency for asset requests.

Use Smart Placement with `run_worker_first=true` when you need to integrate with other backend services, authenticate requests before serving any assets, or if your want to make modifications to your assets before serving them.

If you want some assets served as quickly as possible to the user, but others to be served behind a smart-placed Worker, considering splitting your app into multiple Workers and [using service bindings to connect them](/workers/configuration/smart-placement/#best-practices).

### Smart Placement with Assets First

Enabling Smart Placement with `run_worker_first=false` (or not specifying it) lets you serve assets from as close as possible to your users, but moves your Worker logic to run most efficiently (such as near a database).

Use Smart Placement with `run_worker_first=false` (or not specifying it) when prioritizing fast asset delivery.

This will not impact the [default routing behavior](/workers/static-assets/#routing-behavior).

---

# Direct Uploads

URL: https://developers.cloudflare.com/workers/static-assets/direct-upload/

import {
	Badge,
	Description,
	FileTree,
	InlineBadge,
	Render,
	TabItem,
	Tabs,
	TypeScriptExample,
} from "~/components";
import { Icon } from "astro-icon/components";

:::note

Directly uploading assets via APIs is an advanced approach which, unless you are building a programatic integration, most users will not need. Instead, we encourage users to deploy your Worker with [Wrangler](/workers/static-assets/get-started/#1-create-a-new-worker-project-using-the-cli).

:::

Our API empowers users to upload and include static assets as part of a Worker. These static assets can be served for free, and additionally, users can also fetch assets through an optional [assets binding](/workers/static-assets/binding/) to power more advanced applications. This guide will describe the process for attaching assets to your Worker directly with the API.

<Tabs syncKey="workers-vs-platforms" IconComponent={Icon}>
<TabItem icon="workers" label="Workers">
```mermaid
sequenceDiagram
    participant User
    participant Workers API
    User<<->>Workers API: Submit manifest<br/>POST /client/v4/accounts/:accountId/workers/scripts/:scriptName/assets-upload-session
    User<<->>Workers API: Upload files<br/>POST /client/v4/accounts/:accountId/workers/assets/upload?base64=true
    User<<->>Workers API: Upload script version<br/>PUT /client/v4/accounts/:accountId/workers/scripts/:scriptName
```
</TabItem>
<TabItem icon="cloudflare-for-platforms" label="Workers for Platforms">
```mermaid
sequenceDiagram
    participant User
    participant Workers API
    User<<->>Workers API: Submit manifest<br/>POST /client/v4/accounts/:accountId/workers/dispatch/namespaces/:dispatchNamespace/scripts/:scriptName/assets-upload-session
    User<<->>Workers API: Upload files<br/>POST /client/v4/accounts/:accountId/workers/assets/upload?base64=true
    User<<->>Workers API: Upload script version<br/>PUT /client/v4/accounts/:accountId/workers/dispatch/namespaces/:dispatchNamespace/scripts/:scriptName
```
</TabItem>
</Tabs>

The asset upload flow can be distilled into three distinct phases:

1. Registration of a manifest
2. Upload of the assets
3. Deployment of the Worker

## Upload manifest

The asset manifest is a ledger which keeps track of files we want to use in our Worker. This manifest is used to track assets associated with each Worker version, and eliminate the need to upload unchanged files prior to a new upload.

The [manifest upload request](/api/resources/workers/subresources/scripts/subresources/assets/subresources/upload/methods/create/) describes each file which we intend to upload. Each file is its own key representing the file path and name, and is an object which contains metadata about the file.

`hash` represents a 32 hexadecimal character hash of the file, while `size` is the size (in bytes) of the file.

<Tabs syncKey="workers-vs-platforms" IconComponent={Icon}>
<TabItem icon="workers" label="Workers">
```bash
curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/assets-upload-session \
--header 'content-type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "manifest": {
		"/filea.html": {
			"hash": "08f1dfda4574284ab3c21666d1",
			"size": 12
		},
		"/fileb.html": {
			"hash": "4f1c1af44620d531446ceef93f",
			"size": 23
		},
		"/filec.html": {
			"hash": "54995e302614e0523757a04ec1",
			"size": 23
		}
	}
}'
```
</TabItem>
<TabItem icon="cloudflare-for-platforms" label="Workers for Platforms">
```bash
curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{dispatch_namespace}/scripts/{script_name}/assets-upload-session \
--header 'content-type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "manifest": {
		"/filea.html": {
			"hash": "08f1dfda4574284ab3c21666d1",
			"size": 12
		},
		"/fileb.html": {
			"hash": "4f1c1af44620d531446ceef93f",
			"size": 23
		},
		"/filec.html": {
			"hash": "54995e302614e0523757a04ec1",
			"size": 23
		}
	}
}'
```
</TabItem>
</Tabs>

The resulting response will contain a JWT, which provides authentication during file upload. The JWT is valid for one hour.

In addition to the JWT, the response instructs users how to optimally batch upload their files. These instructions are encoded in the `buckets` field. Each array in `buckets` contains a list of file hashes which should be uploaded together. Unmodified files will not be returned in the `buckets` field (as they do not need to be re-uploaded) if they have recently been uploaded in previous versions of your Worker.

```json
{
	"result": {
		"jwt": "<UPLOAD_TOKEN>",
		"buckets": [
			["08f1dfda4574284ab3c21666d1", "4f1c1af44620d531446ceef93f"],
			["54995e302614e0523757a04ec1"]
		]
	},
	"success": true,
	"errors": null,
	"messages": null
}
```

:::note

If all assets have been previously uploaded, `buckets` will be empty, and `jwt` will contain a completion token. Uploading files is not necessary, and you can skip directly to [uploading a new script or version](/workers/static-assets/direct-upload/#createdeploy-new-version).

:::

### Limitations

- Each file must be under 25 MiB
- The overall manifest must not contain more than 20,000 file entries

## Upload Static Assets

The [file upload API](/api/resources/workers/subresources/assets/subresources/upload/methods/create/) requires files be uploaded using `multipart/form-data`. The contents of each file must be base64 encoded, and the `base64` query parameter in the URL must be set to `true`.

The provided `Content-Type` header of each file part will be attached when eventually serving the file. If you wish to avoid sending a `Content-Type` header in your deployment, `application/null` may be sent at upload time.

The `Authorization` header must be provided as a bearer token, using the JWT (upload token) from the aforementioned manifest upload call.

Once every file in the manifest has been uploaded, a status code of 201 will be returned, with the `jwt` field present. This JWT is a final "completion" token which can be used to create a deployment of a Worker with this set of assets. This completion token is valid for 1 hour.

## Create/Deploy New Version

[Script](/api/resources/workers/subresources/scripts/methods/update/), [Version](/api/resources/workers/subresources/scripts/subresources/versions/methods/create/), and [Workers for Platform script](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/methods/update/) upload endpoints require specifying a metadata part in the form data. Here, we can provide the completion token from the previous (upload assets) step.

```bash title="Example Worker Metadata Specifying Completion Token"
{
  "main_module": "main.js",
  "assets": {
    "jwt": "<completion_token>"
  },
  "compatibility_date": "2021-09-14"
}
```

If this is a Worker which already has assets, and you wish to just re-use the existing set of assets, we do not have to specify the completion token again. Instead, we can pass the boolean `keep_assets` option.

```bash title="Example Worker Metadata Specifying keep_assets"
{
  "main_module": "main.js",
  "keep_assets": true,
  "compatibility_date": "2021-09-14"
}
```

Asset [routing configuration](/workers/wrangler/configuration/#assets) can be provided in the `assets` object, such as `html_handling` and `not_found_handling`.

```bash title="Example Worker Metadata Specifying Asset Configuration"
{
  "main_module": "main.js",
  "assets": {
    "jwt": "<completion_token>",
    "config" {
      "html_handling": "auto-trailing-slash"
    }
  },
  "compatibility_date": "2021-09-14"
}
```

Optionally, an assets binding can be provided if you wish to fetch and serve assets from within your Worker code.

```bash title="Example Worker Metadata Specifying Asset Binding"
{
  "main_module": "main.js",
  "assets": {
    ...
  },
  "bindings": [
    ...
    {
      "name": "ASSETS",
      "type": "assets"
    }
    ...
  ]
  "compatibility_date": "2021-09-14"
}
```

## Programmatic Example

<TypeScriptExample>

```ts
import * as fs from "fs";
import * as path from "path";
import * as crypto from "crypto";
import { FormData, fetch } from "undici";
import "node:process";

const accountId: string = ""; // Replace with your actual account ID
const filesDirectory: string = "assets"; // Adjust to your assets directory
const scriptName: string = "my-new-script"; // Replace with desired script name
const dispatchNamespace: string = ""; // Replace with a dispatch namespace if using Workers for Platforms

interface FileMetadata {
	hash: string;
	size: number;
}

interface UploadSessionData {
	uploadToken: string;
	buckets: string[][];
	fileMetadata: Record<string, FileMetadata>;
}

interface UploadResponse {
	result: {
		jwt: string;
		buckets: string[][];
	};
	success: boolean;
	errors: any;
	messages: any;
}

// Function to calculate the SHA-256 hash of a file and truncate to 32 characters
function calculateFileHash(filePath: string): {
	fileHash: string;
	fileSize: number;
} {
	const hash = crypto.createHash("sha256");
	const fileBuffer = fs.readFileSync(filePath);
	hash.update(fileBuffer);
	const fileHash = hash.digest("hex").slice(0, 32); // Grab the first 32 characters
	const fileSize = fileBuffer.length;
	return { fileHash, fileSize };
}

// Function to gather file metadata for all files in the directory
function gatherFileMetadata(directory: string): Record<string, FileMetadata> {
	const files = fs.readdirSync(directory);
	const fileMetadata: Record<string, FileMetadata> = {};

	files.forEach((file) => {
		const filePath = path.join(directory, file);
		const { fileHash, fileSize } = calculateFileHash(filePath);
		fileMetadata["/" + file] = {
			hash: fileHash,
			size: fileSize,
		};
	});

	return fileMetadata;
}

function findMatch(
	fileHash: string,
	fileMetadata: Record<string, FileMetadata>,
): string {
	for (let prop in fileMetadata) {
		const file = fileMetadata[prop] as FileMetadata;
		if (file.hash === fileHash) {
			return prop;
		}
	}
	throw new Error("unknown fileHash");
}

// Function to upload a batch of files using the JWT from the first response
async function uploadFilesBatch(
	jwt: string,
	fileHashes: string[][],
	fileMetadata: Record<string, FileMetadata>,
): Promise<string> {
	const form = new FormData();

	for (const bucket of fileHashes) {
		bucket.forEach((fileHash) => {
			const fullPath = findMatch(fileHash, fileMetadata);
			const relPath = filesDirectory + "/" + path.basename(fullPath);
			const fileBuffer = fs.readFileSync(relPath);
			const base64Data = fileBuffer.toString("base64"); // Convert file to Base64

			form.append(
				fileHash,
				new File([base64Data], fileHash, {
					type: "text/html", // Modify Content-Type header based on type of file
				}),
				fileHash,
			);
		});

		const response = await fetch(
			`https://api.cloudflare.com/client/v4/accounts/${accountId}/workers/assets/upload?base64=true`,
			{
				method: "POST",
				headers: {
					Authorization: `Bearer ${jwt}`,
				},
				body: form,
			},
		);

		const data = (await response.json()) as UploadResponse;
		if (data && data.result.jwt) {
			return data.result.jwt;
		}
	}

	throw new Error("Should have received completion token");
}

async function scriptUpload(completionToken: string): Promise<void> {
	const form = new FormData();

	// Configure metadata
	form.append(
		"metadata",
		JSON.stringify({
			main_module: "index.mjs",
			compatibility_date: "2022-03-11",
			assets: {
				jwt: completionToken, // Provide the completion token from file uploads
			},
			bindings: [{ name: "ASSETS", type: "assets" }], // Optional assets binding to fetch from user worker
		}),
	);

	// Configure (optional) user worker
	form.append(
		"index.js",
		new File(
			[
				"export default {async fetch(request, env) { return new Response('Hello world from user worker!'); }}",
			],
			"index.mjs",
			{
				type: "application/javascript+module",
			},
		),
	);

	const url = dispatchNamespace
		? `https://api.cloudflare.com/client/v4/accounts/${accountId}/workers/dispatch/namespaces/${dispatchNamespace}/scripts/${scriptName}`
		: `https://api.cloudflare.com/client/v4/accounts/${accountId}/workers/scripts/${scriptName}`;

	const response = await fetch(url, {
		method: "PUT",
		headers: {
			Authorization: `Bearer ${process.env.CLOUDFLARE_API_TOKEN}`,
		},
		body: form,
	});

	if (response.status != 200) {
		throw new Error("unexpected status code");
	}
}

// Function to make the POST request to start the assets upload session
async function startUploadSession(): Promise<UploadSessionData> {
	const fileMetadata = gatherFileMetadata(filesDirectory);

	const requestBody = JSON.stringify({
		manifest: fileMetadata,
	});

	const url = dispatchNamespace
		? `https://api.cloudflare.com/client/v4/accounts/${accountId}/workers/dispatch/namespaces/${dispatchNamespace}/scripts/${scriptName}/assets-upload-session`
		: `https://api.cloudflare.com/client/v4/accounts/${accountId}/workers/scripts/${scriptName}/assets-upload-session`;

	const response = await fetch(url, {
		method: "POST",
		headers: {
			Authorization: `Bearer ${process.env.CLOUDFLARE_API_TOKEN}`,
			"Content-Type": "application/json",
		},
		body: requestBody,
	});

	const data = (await response.json()) as UploadResponse;
	const jwt = data.result.jwt;

	return {
		uploadToken: jwt,
		buckets: data.result.buckets,
		fileMetadata,
	};
}

// Begin the upload session by uploading a new manifest
const { uploadToken, buckets, fileMetadata } = await startUploadSession();

// If all files are already uploaded, a completion token will be immediately returned. Otherwise,
// we should upload the missing files
let completionToken = uploadToken;
if (buckets.length > 0) {
	completionToken = await uploadFilesBatch(uploadToken, buckets, fileMetadata);
}

// Once we have uploaded all of our files, we can upload a new script, and assets, with completion token
await scriptUpload(completionToken);
```

</TypeScriptExample>

---

# Get Started

URL: https://developers.cloudflare.com/workers/static-assets/get-started/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
} from "~/components";

For most front-end applications, you'll want to use a framework. Workers supports number of popular [frameworks](/workers/framework-guides/) that come with ready-to-use components, a pre-defined and structured architecture, and community support. View [framework specific guides](/workers/framework-guides/) to get started using a framework.

Alternatively, you may prefer to build your website from scratch if:

- You're interested in learning by implementing core functionalities on your own.
- You're working on a simple project where you might not need a framework.
- You want to optimize for performance by minimizing external dependencies.
- You require complete control over every aspect of the application.
- You want to build your own framework.

This guide will instruct you through setting up and deploying a static site or a full-stack application without a framework on Workers.

## Deploy a static site

This guide will instruct you through setting up and deploying a static site on Workers.

### 1. Create a new Worker project using the CLI

[C3 (`create-cloudflare-cli`)](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare) is a command-line tool designed to help you set up and deploy new applications to Cloudflare. Open a terminal window and run C3 to create your Worker project:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"my-static-site"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Static site",
		lang: "TypeScript",
	}}
/>

After setting up your project, change your directory by running the following command:

```sh
cd my-static-site
```

### 2. Develop locally

After you have created your Worker, run the [`wrangler dev`](/workers/wrangler/commands/#dev) in the project directory to start a local server. This will allow you to preview your project locally during development.

```sh
npx wrangler dev
```

### 3. Deploy your project

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).

The [`wrangler deploy`](/workers/wrangler/commands/#deploy) will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

```sh
npx wrangler deploy
```

:::note

Learn about how assets are configured and how routing works from [Routing configuration](/workers/static-assets/routing/).

:::

## Deploy a full-stack application

This guide will instruct you through setting up and deploying dynamic and interactive server-side rendered (SSR) applications on Cloudflare Workers.

When building a full-stack application, you can use any [Workers bindings](/workers/runtime-apis/bindings/), [including assets' own](/workers/static-assets/binding/), to interact with resources on the Cloudflare Developer Platform.

### 1. Create a new Worker project

[C3 (`create-cloudflare-cli`)](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare) is a command-line tool designed to help you set up and deploy new applications to Cloudflare.

Open a terminal window and run C3 to create your Worker project:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"my-dynamic-site"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "SSR / full-stack app",
		lang: "TypeScript",
	}}
/>

After setting up your project, change your directory by running the following command:

```sh
cd my-dynamic-site
```

### 2. Develop locally

After you have created your Worker, run the [`wrangler dev`](/workers/wrangler/commands/#dev) in the project directory to start a local server. This will allow you to preview your project locally during development.

```sh
npx wrangler dev
```

### 3. Modify your Project

With your new project generated and running, you can begin to write and edit your project:

- The `src/index.ts` file is populated with sample code. Modify its content to change the server-side behavior of your Worker.
- The `public/index.html` file is populated with sample code. Modify its content, or anything else in `public/`, to change the static assets of your Worker.

Then, save the files and reload the page. Your project's output will have changed based on your modifications.

### 4. Deploy your Project

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).

The [`wrangler deploy`](/workers/wrangler/commands/#deploy) will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

```sh
npx wrangler deploy
```

:::note

Learn about how assets are configured and how routing works from [Routing configuration](/workers/static-assets/routing/).

:::

---

# Headers

URL: https://developers.cloudflare.com/workers/static-assets/headers/

import { Render } from "~/components";

## Default headers

When serving static assets, Workers will attach some headers to the response by default. These are:

- **`Content-Type`**

  A `Content-Type` header is attached to the response if one is provided during [the asset upload process](/workers/static-assets/direct-upload/). [Wrangler](/workers/wrangler/commands/#deploy) automatically determines the MIME type of the file, based on its extension.

- **`Cache-Control: public, max-age=0, must-revalidate`**

  Sent when the request does not have an `Authorization` or `Range` header, this response header tells the browser that the asset can be cached, but that the browser should revalidate the freshness of the content every time before using it. This default behavior ensures good website performance for static pages, while still guaranteeing that stale content will never be served.

- **`ETag`**

  This header complements the default `Cache-Control` header. Its value is a hash of the static asset file, and browsers can use this in subsequent requests with an `If-None-Match` header to check for freshness, without needing to re-download the entire file in the case of a match.

- **`CF-Cache-Status`**

  This header indicates whether the asset was served from the cache (`HIT`) or not (`MISS`).[^1]

Cloudflare reserves the right to attach new headers to static asset responses at any time in order to improve performance or harden the security of your Worker application.

<Render file="custom_headers" params={{ product: "workers" }} />

[^1]: Due to a technical limitation that we hope to address in the future, the `CF-Cache-Status` header is not always entirely accurate. It is possible for false-positives and false-negatives to occur. This should be rare. In the meantime, this header should be considered as returning a "probablistic" result.

---

# Static Assets

URL: https://developers.cloudflare.com/workers/static-assets/

import {
	Aside,
	Badge,
	Card,
	CardGrid,
	Details,
	Description,
	InlineBadge,
	Icon,
	Render,
	TabItem,
	Tabs,
	Feature,
	LinkButton,
	LinkCard,
	Stream,
	Flex,
	WranglerConfig,
	Steps,
	PackageManagers,
} from "~/components";

You can upload static assets (HTML, CSS, images and other files) as part of your Worker, and Cloudflare will handle caching and serving them to web browsers.

**Start from CLI** - Scaffold a React SPA with an API Worker, and use the [Cloudflare Vite plugin](/workers/vite-plugin/).

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-react-app --framework=react"
/>
---

**Or just deploy to Cloudflare**

[![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create/deploy-to-workers&repository=https://github.com/cloudflare/templates/tree/main/vite-react-template)

Learn more about supported frameworks on Workers.

<LinkCard
	title="Supported frameworks"
	href="/workers/framework-guides/"
	description="Start building on Workers with our framework guides."
/>

### How it works

When you deploy your project, Cloudflare deploys both your Worker code and your static assets in a single operation. This deployment operates as a tightly integrated "unit" running across Cloudflare's network, combining static file hosting, custom logic, and global caching.

The **assets directory** specified in your [Wrangler configuration file](/workers/wrangler/configuration/#assets) is central to this design. During deployment, Wrangler automatically uploads the files from this directory to Cloudflare's infrastructure. Once deployed, requests for these assets are routed efficiently to locations closest to your users.

<WranglerConfig>

    ```toml {3-4}
    	name = "my-spa"
    	main = "src/index.js"
    	compatibility_date = "2025-01-01"
    	[assets]
    	directory = "./dist"
    	binding = "ASSETS"
    	```

</WranglerConfig>

:::note
If you are using the [Cloudflare Vite plugin](/workers/vite-plugin/), you do not need to specify `assets.directory`. For more information about using static assets with the Vite plugin, refer to the [plugin documentation](/workers/vite-plugin/reference/static-assets/).
:::

By adding an [**assets binding**](/workers/static-assets/binding/#binding), you can directly fetch and serve assets within your Worker code.

```js {13}
// index.js

export default {
	async fetch(request, env) {
		const url = new URL(request.url);

		if (url.pathname.startsWith("/api/")) {
			return new Response(JSON.stringify({ name: "Cloudflare" }), {
				headers: { "Content-Type": "application/json" },
			});
		}

		return env.ASSETS.fetch(request);
	},
};
```

### Routing behavior

By default, if a requested URL matches a file in the static assets directory, that file will be served — without invoking Worker code. If no matching asset is found and a Worker script is present, the request will be processed by the Worker. The Worker can return a response or choose to defer again to static assets by using the [assets binding](/workers/static-assets/binding/) (e.g. `env.ASSETS.fetch(request)`). If no Worker script is present, a `404 Not Found` response is returned.

The default behavior for requests which don't match a static asset can be changed by setting the [`not_found_handling` option under `assets`](/workers/wrangler/configuration/#assets) in your Wrangler configuration file:

- [`not_found_handling = "single-page-application"`](/workers/static-assets/routing/single-page-application/): Sets your application to return a `200 OK` response with `index.html` for requests which don't match a static asset. Use this if you have a Single Page Application. We recommend pairing this with selective routing using `run_worker_first` for [advanced routing control](/workers/static-assets/routing/single-page-application/#advanced-routing-control).
- [`not_found_handling = "404-page"`](/workers/static-assets/routing/static-site-generation/#custom-404-pages): Sets your application to return a `404 Not Found` response with the nearest `404.html` for requests which don't match a static asset.

<WranglerConfig>

    ```toml
    	[assets]
    	directory = "./dist"
    	not_found_handling = "single-page-application"

    	```

</WranglerConfig>

If you want the Worker code to execute before serving assets, you can use the `run_worker_first` option. This can be set to `true` to invoke the Worker script for all requests, or configured as an array of route patterns for selective Worker-script-first routing:

**Invoking your Worker script on specific paths:**

<WranglerConfig>

```json
{
	"name": "my-spa-worker",
	"compatibility_date": "$today",
	"main": "./src/index.ts",
	"assets": {
		"directory": "./dist/",
		"not_found_handling": "single-page-application",
		"binding": "ASSETS",
		"run_worker_first": ["/api/*", "!/api/docs/*"]
	}
}
```

</WranglerConfig>

<LinkCard
	title="Routing options"
	href="/workers/static-assets/routing/"
	description="Learn more about how you can customize routing behavior."
/>

### Caching behavior

Cloudflare provides automatic caching for static assets across its network, ensuring fast delivery to users worldwide. When a static asset is requested, it is automatically cached for future requests.

- **First Request:** When an asset is requested for the first time, it is fetched from storage and cached at the nearest Cloudflare location.

- **Subsequent Requests:** If a request for the same asset reaches a data center that does not have it cached, Cloudflare's [tiered caching system](/cache/how-to/tiered-cache/) allows it to be retrieved from a nearby cache rather than going back to storage. This improves cache hit ratio, reduces latency, and reduces unnecessary origin fetches.

## Try it out

<LinkCard
	title="Vite + React SPA tutorial"
	href="/workers/vite-plugin/tutorial/"
	description="Learn how to build and deploy a full-stack Single Page Application with static assets and API routes."
/>

## Learn more

<LinkCard
	title="Supported frameworks"
	href="/workers/framework-guides/"
	description="Start building on Workers with our framework guides."
/>

<LinkCard
	title="Billing and limitations"
	href="/workers/static-assets/billing-and-limitations/"
	description="Learn more about how requests are billed, current limitations, and troubleshooting."
/>

---

# Redirects

URL: https://developers.cloudflare.com/workers/static-assets/redirects/

import { Render } from "~/components";

<Render file="redirects" params={{ product: "workers" }} />

---

# Vite plugin

URL: https://developers.cloudflare.com/workers/vite-plugin/

The Cloudflare Vite plugin enables a full-featured integration between [Vite](https://vite.dev/) and the [Workers runtime](/workers/runtime-apis/).
Your Worker code runs inside [workerd](https://github.com/cloudflare/workerd), matching the production behavior as closely as possible and providing confidence as you develop and deploy your applications.

## Features

- Uses the Vite [Environment API](https://vite.dev/guide/api-environment) to integrate Vite with the Workers runtime
- Provides direct access to [Workers runtime APIs](/workers/runtime-apis/) and [bindings](/workers/runtime-apis/bindings/)
- Builds your front-end assets for deployment to Cloudflare, enabling you to build static sites, SPAs, and full-stack applications
- Official support for [React Router v7](https://reactrouter.com/) with server-side rendering
- Leverages Vite's hot module replacement for consistently fast updates
- Supports `vite preview` for previewing your build output in the Workers runtime prior to deployment

## Use cases

- [React Router v7](https://reactrouter.com/) (support for more full-stack frameworks is coming soon)
- Static sites, such as single-page applications, with or without an integrated backend API
- Standalone Workers
- Multi-Worker applications

## Get started

To create a new application from a ready-to-go template, refer to the [React Router](/workers/framework-guides/web-apps/react-router/), [React](/workers/framework-guides/web-apps/react/) or [Vue](/workers/framework-guides/web-apps/vue/) framework guides.

To create a standalone Worker from scratch, refer to [Get started](/workers/vite-plugin/get-started/).

For a more in-depth look at adapting an existing Vite project and an introduction to key concepts, refer to the [Tutorial](/workers/vite-plugin/tutorial/).

---

# Tutorial - React SPA with an API

URL: https://developers.cloudflare.com/workers/vite-plugin/tutorial/

import { PackageManagers, WranglerConfig } from "~/components";

This tutorial takes you through the steps needed to adapt a Vite project to use the Cloudflare Vite plugin.
Much of the content can also be applied to adapting existing Vite projects and to front-end frameworks other than React.

:::note
If you want to start a new app with a template already set up with Vite, React and the Cloudflare Vite plugin, refer to the [React framework guide](/workers/framework-guides/web-apps/react/).
To create a standalone Worker, refer to [Get started](/workers/vite-plugin/get-started/).
:::

## Introduction

In this tutorial, you will create a React SPA that can be deployed as a Worker with static assets.
You will then add an API Worker that can be accessed from the front-end code.
You will develop, build, and preview the application using Vite before finally deploying to Cloudflare.

## Set up and configure the React SPA

### Scaffold a Vite project

Start by creating a React TypeScript project with Vite.

<PackageManagers
	type="create"
	pkg="vite@latest"
	args="cloudflare-vite-tutorial --template react-ts"
/>

Next, open the `cloudflare-vite-tutorial` directory in your editor of choice.

### Add the Cloudflare dependencies

<PackageManagers type="add" pkg="@cloudflare/vite-plugin wrangler" dev />

### Add the plugin to your Vite config

```ts {3, 6} title="vite.config.ts"
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [react(), cloudflare()],
});
```

The Cloudflare Vite plugin doesn't require any configuration by default and will look for a `wrangler.jsonc`, `wrangler.json` or `wrangler.toml` in the root of your application.

Refer to the [API reference](/workers/vite-plugin/reference/api/) for configuration options.

### Create your Worker config file

<WranglerConfig>

```toml
name = "cloudflare-vite-tutorial"
compatibility_date = "2025-04-03"
assets = { not_found_handling = "single-page-application" }
```

</WranglerConfig>

The [`not_found_handling`](/workers/static-assets/routing/single-page-application/) value has been set to `single-page-application`.
This means that all not found requests will serve the `index.html` file.
With the Cloudflare plugin, the `assets` routing configuration is used in place of Vite's default behavior.
This ensures that your application's [routing configuration](/workers/static-assets/routing/) works the same way while developing as it does when deployed to production.

Note that the [`directory`](/workers/static-assets/binding/#directory) field is not used when configuring assets with Vite.
The `directory` in the output configuration will automatically point to the client build output.
See [Static Assets](/workers/vite-plugin/reference/static-assets/) for more information.

:::note
When using the Cloudflare Vite plugin, the Worker config (for example, `wrangler.jsonc`) that you provide is the input configuration file.
A separate output `wrangler.json` file is created when you run `vite build`.
This output file is a snapshot of your configuration at the time of the build and is modified to reference your build artifacts.
It is the configuration that is used for preview and deployment.
:::

### Update the .gitignore file

When developing Workers, additional files are used and/or generated that should not be stored in git.
Add the following lines to your `.gitignore` file:

```txt title=".gitignore"
.wrangler
.dev.vars*
```

### Run the development server

Run `npm run dev` to start the Vite development server and verify that your application is working as expected.

For a purely front-end application, you could now build (`npm run build`), preview (`npm run preview`), and deploy (`npm exec wrangler deploy`) your application.
This tutorial, however, will show you how to go a step further and add an API Worker.

## Add an API Worker

### Configure TypeScript for your Worker code

<PackageManagers type="add" pkg="@cloudflare/workers-types" dev />

```jsonc title="tsconfig.worker.json"
{
	"extends": "./tsconfig.node.json",
	"compilerOptions": {
		"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.worker.tsbuildinfo",
		"types": ["@cloudflare/workers-types/2023-07-01", "vite/client"],
	},
	"include": ["worker"],
}
```

```jsonc {6} title="tsconfig.json"
{
	"files": [],
	"references": [
		{ "path": "./tsconfig.app.json" },
		{ "path": "./tsconfig.node.json" },
		{ "path": "./tsconfig.worker.json" },
	],
}
```

### Add to your Worker configuration

<WranglerConfig>

```toml
name = "cloudflare-vite-tutorial"
compatibility_date = "2025-04-03"
assets = { not_found_handling = "single-page-application" }
main = "./worker/index.ts"
```

</WranglerConfig>

The `main` field specifies the entry file for your Worker code.

### Add your API Worker

```ts title="worker/index.ts"
interface Env {
	ASSETS: Fetcher;
}

export default {
	fetch(request, env) {
		const url = new URL(request.url);

		if (url.pathname.startsWith("/api/")) {
			return Response.json({
				name: "Cloudflare",
			});
		}

		return new Response(null, { status: 404 });
	},
} satisfies ExportedHandler<Env>;
```

The Worker above will be invoked for any non-navigation request that does not match a static asset.
It returns a JSON response if the `pathname` starts with `/api/` and otherwise return a `404` response.

:::note
For top-level navigation requests, browsers send a `Sec-Fetch-Mode: navigate` header.
If this is present and the URL does not match a static asset, the `not_found_handling` behavior will be invoked rather than the Worker.
:::

### Call the API from the client

Edit `src/App.tsx` so that it includes an additional button that calls the API and sets some state:

```tsx {8, 32-46} collapse={12-27} title="src/App.tsx"
import { useState } from "react";
import reactLogo from "./assets/react.svg";
import viteLogo from "/vite.svg";
import "./App.css";

function App() {
	const [count, setCount] = useState(0);
	const [name, setName] = useState("unknown");

	return (
		<>
			<div>
				<a href="https://vite.dev" target="_blank">
					<img src={viteLogo} className="logo" alt="Vite logo" />
				</a>
				<a href="https://react.dev" target="_blank">
					<img src={reactLogo} className="logo react" alt="React logo" />
				</a>
			</div>
			<h1>Vite + React</h1>
			<div className="card">
				<button
					onClick={() => setCount((count) => count + 1)}
					aria-label="increment"
				>
					count is {count}
				</button>
				<p>
					Edit <code>src/App.tsx</code> and save to test HMR
				</p>
			</div>
			<div className="card">
				<button
					onClick={() => {
						fetch("/api/")
							.then((res) => res.json() as Promise<{ name: string }>)
							.then((data) => setName(data.name));
					}}
					aria-label="get name"
				>
					Name from API is: {name}
				</button>
				<p>
					Edit <code>api/index.ts</code> to change the name
				</p>
			</div>
			<p className="read-the-docs">
				Click on the Vite and React logos to learn more
			</p>
		</>
	);
}

export default App;
```

Now, if you click the button, it will display 'Name from API is: Cloudflare'.

Increment the counter to update the application state in the browser.
Next, edit `api/index.ts` by changing the `name` it returns to `'Cloudflare Workers'`.
If you click the button again, it will display the new `name` while preserving the previously set counter value.

With Vite and the Cloudflare plugin, you can iterate on the client and server parts of your app together, without losing UI state between edits.

### Build your application

Run `npm run build` to build your application.

```sh
npm run build
```

If you inspect the `dist` directory, you will see that it contains two subdirectories:

- `client` - the client code that runs in the browser
- `cloudflare-vite-tutorial` - the Worker code alongside the output `wrangler.json` configuration file

### Preview your application

Run `npm run preview` to validate that your application runs as expected.

```sh
npm run preview
```

This command will run your build output locally in the Workers runtime, closely matching its behaviour in production.

### Deploy to Cloudflare

Run `npm exec wrangler deploy` to deploy your application to Cloudflare.

```sh
npm exec wrangler deploy
```

This command will automatically use the output `wrangler.json` that was included in the build output.

## Next steps

In this tutorial, we created an SPA that could be deployed as a Worker with static assets.
We then added an API Worker that could be accessed from the front-end code.
Finally, we deployed both the client and server-side parts of the application to Cloudflare.

Possible next steps include:

- Adding a binding to another Cloudflare service such as a [KV namespace](/kv/) or [D1 database](/d1/)
- Expanding the API to include additional routes
- Using a library, such as [Hono](https://hono.dev/) or [tRPC](https://trpc.io/), in your API Worker

---

# Get started

URL: https://developers.cloudflare.com/workers/vite-plugin/get-started/

import { PackageManagers, WranglerConfig } from "~/components";

:::note
This guide demonstrates creating a standalone Worker from scratch.
If you would instead like to create a new application from a ready-to-go template, refer to the [React Router](/workers/framework-guides/web-apps/react-router/), [React](/workers/framework-guides/web-apps/react/) or [Vue](/workers/framework-guides/web-apps/vue/) framework guides.
:::

## Start with a basic `package.json`

```json title="package.json"
{
	"name": "cloudflare-vite-get-started",
	"private": true,
	"version": "0.0.0",
	"type": "module",
	"scripts": {
		"dev": "vite dev",
		"build": "vite build",
		"preview": "npm run build && vite preview",
		"deploy": "npm run build && wrangler deploy"
	}
}
```

:::note
Ensure that you include `"type": "module"` in order to use ES modules by default.
:::

## Install the dependencies

<PackageManagers type="add" pkg="vite @cloudflare/vite-plugin wrangler" dev />

## Create your Vite config file and include the Cloudflare plugin

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [cloudflare()],
});
```

The Cloudflare Vite plugin doesn't require any configuration by default and will look for a `wrangler.jsonc`, `wrangler.json` or `wrangler.toml` in the root of your application.

Refer to the [API reference](/workers/vite-plugin/reference/api/) for configuration options.

## Create your Worker config file

<WranglerConfig>

```toml
name = "cloudflare-vite-get-started"
compatibility_date = "2025-04-03"
main = "./src/index.ts"
```

</WranglerConfig>

The `name` field specifies the name of your Worker.
By default, this is also used as the name of the Worker's Vite Environment (see [Vite Environments](/workers/vite-plugin/reference/vite-environments/) for more information).
The `main` field specifies the entry file for your Worker code.

For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/).

## Create your Worker entry file

```ts title="src/index.ts"
export default {
	fetch() {
		return new Response(`Running in ${navigator.userAgent}!`);
	},
};
```

A request to this Worker will return **'Running in Cloudflare-Workers!'**, demonstrating that the code is running inside the Workers runtime.

## Dev, build, preview and deploy

You can now start the Vite development server (`npm run dev`), build the application (`npm run build`), preview the built application (`npm run preview`), and deploy to Cloudflare (`npm run deploy`).

---

# Tutorials

URL: https://developers.cloudflare.com/workers/tutorials/

import { GlossaryTooltip, ListTutorials, YouTubeVideos } from "~/components";

View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Workers.

## Docs

<ListTutorials />

## Videos

<YouTubeVideos products={["Workers"]} />

---

# API

URL: https://developers.cloudflare.com/workers/wrangler/api/

import {
	Render,
	TabItem,
	Tabs,
	Type,
	MetaInfo,
	WranglerConfig,
	PackageManagers,
} from "~/components";

Wrangler offers APIs to programmatically interact with your Cloudflare Workers.

- [`unstable_startWorker`](#unstable_startworker) - Start a server for running integration tests against your Worker.
- [`unstable_dev`](#unstable_dev) - Start a server for running either end-to-end (e2e) or integration tests against your Worker.
- [`getPlatformProxy`](#getplatformproxy) - Get proxies and values for emulating the Cloudflare Workers platform in a Node.js process.

## `unstable_startWorker`

This API exposes the internals of Wrangler's dev server, and allows you to customise how it runs. For example, you could use `unstable_startWorker()` to run integration tests against your Worker. This example uses `node:test`, but should apply to any testing framework:

```js
import assert from "node:assert";
import test, { after, before, describe } from "node:test";
import { unstable_startWorker } from "wrangler";

describe("worker", () => {
	let worker;

	before(async () => {
		worker = await unstable_startWorker({ config: "wrangler.json" });
	});

	test("hello world", async () => {
		assert.strictEqual(
			await (await worker.fetch("http://example.com")).text(),
			"Hello world",
		);
	});

	after(async () => {
		await worker.dispose();
	});
});
```

## `unstable_dev`

Start an HTTP server for testing your Worker.

Once called, `unstable_dev` will return a `fetch()` function for invoking your Worker without needing to know the address or port, as well as a `stop()` function to shut down the HTTP server.

By default, `unstable_dev` will perform integration tests against a local server. If you wish to perform an e2e test against a preview Worker, pass `local: false` in the `options` object when calling the `unstable_dev()` function. Note that e2e tests can be significantly slower than integration tests.

:::note

The `unstable_dev()` function has an `unstable_` prefix because the API is experimental and may change in the future. We recommend migrating to the `unstable_startWorker()` API, documented above.

If you have been using `unstable_dev()` for integration testing and want to migrate to Cloudflare's Vitest integration, refer to the [Migrate from `unstable_dev` migration guide](/workers/testing/vitest-integration/migration-guides/migrate-from-unstable-dev/) for more information.

:::

### Constructor

```js
const worker = await unstable_dev(script, options);
```

### Parameters

- `script` <Type text="string" />

  - A string containing a path to your Worker script, relative to your Worker project's root directory.

- `options` <Type text="object" /> <MetaInfo text="optional" />

  - Optional options object containing `wrangler dev` configuration settings.
  - Include an `experimental` object inside `options` to access experimental features such as `disableExperimentalWarning`.
    - Set `disableExperimentalWarning` to `true` to disable Wrangler's warning about using `unstable_` prefixed APIs.

### Return Type

`unstable_dev()` returns an object containing the following methods:

- `fetch()` `Promise<Response>`

  - Send a request to your Worker. Returns a Promise that resolves with a [`Response`](/workers/runtime-apis/response) object.
  - Refer to [`Fetch`](/workers/runtime-apis/fetch/).

- `stop()` `Promise<void>`

  - Shuts down the dev server.

### Usage

When initiating each test suite, use a `beforeAll()` function to start `unstable_dev()`. The `beforeAll()` function is used to minimize overhead: starting the dev server takes a few hundred milliseconds, starting and stopping for each individual test adds up quickly, slowing your tests down.

In each test case, call `await worker.fetch()`, and check that the response is what you expect.

To wrap up a test suite, call `await worker.stop()` in an `afterAll` function.

#### Single Worker example

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
const { unstable_dev } = require("wrangler");

describe("Worker", () => {
	let worker;

	beforeAll(async () => {
		worker = await unstable_dev("src/index.js", {
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await worker.stop();
	});

	it("should return Hello World", async () => {
		const resp = await worker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});
});
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { unstable_dev } from "wrangler";
import type { UnstableDevWorker } from "wrangler";

describe("Worker", () => {
	let worker: UnstableDevWorker;

	beforeAll(async () => {
		worker = await unstable_dev("src/index.ts", {
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await worker.stop();
	});

	it("should return Hello World", async () => {
		const resp = await worker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});
});
```

</TabItem> </Tabs>

#### Multi-Worker example

You can test Workers that call other Workers. In the below example, we refer to the Worker that calls other Workers as the parent Worker, and the Worker being called as a child Worker.

If you shut down the child Worker prematurely, the parent Worker will not know the child Worker exists and your tests will fail.

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
import { unstable_dev } from "wrangler";

describe("multi-worker testing", () => {
	let childWorker;
	let parentWorker;

	beforeAll(async () => {
		childWorker = await unstable_dev("src/child-worker.js", {
			config: "src/child-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
		parentWorker = await unstable_dev("src/parent-worker.js", {
			config: "src/parent-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await childWorker.stop();
		await parentWorker.stop();
	});

	it("childWorker should return Hello World itself", async () => {
		const resp = await childWorker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});

	it("parentWorker should return Hello World by invoking the child worker", async () => {
		const resp = await parentWorker.fetch();
		const parsedResp = await resp.text();
		expect(parsedResp).toEqual("Parent worker sees: Hello World!");
	});
});
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
import { unstable_dev } from "wrangler";
import type { UnstableDevWorker } from "wrangler";

describe("multi-worker testing", () => {
	let childWorker: UnstableDevWorker;
	let parentWorker: UnstableDevWorker;

	beforeAll(async () => {
		childWorker = await unstable_dev("src/child-worker.js", {
			config: "src/child-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
		parentWorker = await unstable_dev("src/parent-worker.js", {
			config: "src/parent-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await childWorker.stop();
		await parentWorker.stop();
	});

	it("childWorker should return Hello World itself", async () => {
		const resp = await childWorker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});

	it("parentWorker should return Hello World by invoking the child worker", async () => {
		const resp = await parentWorker.fetch();
		const parsedResp = await resp.text();
		expect(parsedResp).toEqual("Parent worker sees: Hello World!");
	});
});
```

</TabItem> </Tabs>

## `getPlatformProxy`

The `getPlatformProxy` function provides a way to obtain an object containing proxies (to **local** `workerd` bindings) and emulations of Cloudflare Workers specific values, allowing the emulation of such in a Node.js process.

:::caution

`getPlatformProxy` is, by design, to be used exclusively in Node.js applications. `getPlatformProxy` cannot be run inside the Workers runtime.

:::

One general use case for getting a platform proxy is for emulating bindings in applications targeting Workers, but running outside the Workers runtime (for example, framework local development servers running in Node.js), or for testing purposes (for example, ensuring code properly interacts with a type of binding).

:::note

Binding proxies provided by this function are a best effort emulation of the real production bindings. Although they are designed to be as close as possible to the real thing, there might be slight differences and inconsistencies between the two.

:::

### Syntax

```js
const platform = await getPlatformProxy(options);
```

### Parameters

- `options` <Type text="object" /> <MetaInfo text="optional" />

  - Optional options object containing preferences for the bindings:

    - `environment` string

      The environment to use.

    - `configPath` string

      The path to the config file to use.

      If no path is specified, the default behavior is to search from the current directory up the filesystem for a [Wrangler configuration file](/workers/wrangler/configuration/) to use.

      **Note:** this field is optional but if a path is specified it must point to a valid file on the filesystem.

    - `persist` boolean | `{ path: string }`

      Indicates if and where to persist the bindings data. If `true` or `undefined`, defaults to the same location used by Wrangler, so data can be shared between it and the caller. If `false`, no data is persisted to or read from the filesystem.

      **Note:** If you use `wrangler`'s `--persist-to` option, note that this option adds a subdirectory called `v3` under the hood while `getPlatformProxy`'s `persist` does not. For example, if you run `wrangler dev --persist-to ./my-directory`, to reuse the same location using `getPlatformProxy`, you will have to specify: `persist: { path: "./my-directory/v3" }`.

    - `experimental` `{ remoteBindings: boolean }`

      Object used to enable experimental features, no guarantees are made to the stability of this API, use at your own risk.

      - `remoteBindings` Enables `getPlatformProxy` to connect to [remote bindings](/workers/development-testing/#remote-bindings).

### Return Type

`getPlatformProxy()` returns a `Promise` resolving to an object containing the following fields.

- `env` `Record<string, unknown>`

  - Object containing proxies to bindings that can be used in the same way as production bindings. This matches the shape of the `env` object passed as the second argument to modules-format workers. These proxy to binding implementations run inside `workerd`.
  - TypeScript Tip: `getPlatformProxy<Env>()` is a generic function. You can pass the shape of the bindings record as a type argument to get proper types without `unknown` values.

- `cf` IncomingRequestCfProperties read-only

  - Mock of the `Request`'s `cf` property, containing data similar to what you would see in production.

- `ctx` object

  - Mock object containing implementations of the [`waitUntil`](/workers/runtime-apis/context/#waituntil) and [`passThroughOnException`](/workers/runtime-apis/context/#passthroughonexception) functions that do nothing.

- `caches` object

  - Emulation of the [Workers `caches` runtime API](/workers/runtime-apis/cache/).
  - For the time being, all cache operations do nothing. A more accurate emulation will be made available soon.

- `dispose()` () => `Promise<void>`

  - Terminates the underlying `workerd` process.
  - Call this after the platform proxy is no longer required by the program. If you are running a long running process (such as a dev server) that can indefinitely make use of the proxy, you do not need to call this function.

### Usage

The `getPlatformProxy` function uses bindings found in the [Wrangler configuration file](/workers/wrangler/configuration/). For example, if you have an [environment variable](/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) configuration set up in the Wrangler configuration file:

<WranglerConfig>

```toml
[vars]
MY_VARIABLE = "test"
```

</WranglerConfig>

You can access the bindings by importing `getPlatformProxy` like this:

```js
import { getPlatformProxy } from "wrangler";

const { env } = await getPlatformProxy();
```

To access the value of the `MY_VARIABLE` binding add the following to your code:

```js
console.log(`MY_VARIABLE = ${env.MY_VARIABLE}`);
```

This will print the following output: `MY_VARIABLE = test`.

### Supported bindings

All supported bindings found in your [Wrangler configuration file](/workers/wrangler/configuration/) are available to you via `env`.

The bindings supported by `getPlatformProxy` are:

- [Environment variables](/workers/configuration/environment-variables/)

- [Service bindings](/workers/runtime-apis/bindings/service-bindings/)

- [KV namespace bindings](/kv/api/)

- [R2 bucket bindings](/r2/api/workers/workers-api-reference/)

- [Queue bindings](/queues/configuration/javascript-apis/)

- [D1 database bindings](/d1/worker-api/)

- [Hyperdrive bindings](/hyperdrive)

  :::note[Hyperdrive values are simple passthrough ones]

  Values provided by hyperdrive bindings such as `connectionString` and `host` do not have a valid meaning outside of a `workerd` process.
  This means that Hyperdrive proxies return passthrough values, which are values corresponding to the database connection provided by the user. Otherwise, it would return values which would be unusable from within node.js.

  :::

- [Workers AI bindings](/workers-ai/get-started/workers-wrangler/#2-connect-your-worker-to-workers-ai)

  <Render file="ai-local-usage-charges" product="workers" />

- [Durable Object bindings](/durable-objects/api/)

  - To use a Durable Object binding with `getPlatformProxy`, always specify a [`script_name`](/workers/wrangler/configuration/#durable-objects).

    For example, you might have the following binding in a Wrangler configuration file read by `getPlatformProxy`.

    <WranglerConfig>

    ```toml
    [[durable_objects.bindings]]
    name = "MyDurableObject"
    class_name = "MyDurableObject"
    script_name = "external-do-worker"
    ```

    </WranglerConfig>

    You will need to declare your Durable Object `"MyDurableObject"` in another Worker, called `external-do-worker` in this example.

        ```ts title="./external-do-worker/src/index.ts"
        export class MyDurableObject extends DurableObject {
        	// Your DO code goes here
        }

        export default {
        	fetch() {
        			// Doesn't have to do anything, but a DO cannot be the default export
        			return new Response("Hello, world!");
        	},
        };
        ```
        That Worker also needs a Wrangler configuration file that looks like this:

        <WranglerConfig>
        ```json
        {
        	"name": "external-do-worker",
        	"main": "src/index.ts",
        	"compatibility_date": "XXXX-XX-XX"
        }
        ```
        </WranglerConfig>

        If you are not using RPC with your Durable Object, you can run a separate Wrangler dev session alongside your framework development server.

        Otherwise, you can build your application and run both Workers in the same Wrangler dev session.

        If you are using Pages run:
        <PackageManagers type="exec" pkg="wrangler" args="pages dev -c path/to/pages/wrangler.jsonc -c path/to/external-do-worker/wrangler.jsonc" />

        If you are using Workers with Assets run:
        <PackageManagers type="exec" pkg="wrangler" args="dev -c path/to/workers-assets/wrangler.jsonc -c path/to/external-do-worker/wrangler.jsonc" />

---

# Bundling

URL: https://developers.cloudflare.com/workers/wrangler/bundling/

By default, Wrangler bundles your Worker code using [`esbuild`](https://esbuild.github.io/). This means that Wrangler has built-in support for importing modules from [npm](https://www.npmjs.com/) defined in your `package.json`. To review the exact code that Wrangler will upload to Cloudflare, run `npx wrangler deploy --dry-run --outdir dist`, which will show your Worker code after Wrangler's bundling.

<details>
<summary>`esbuild` version</summary>

Wrangler uses `esbuild`. We periodically update the `esbuild` version included with Wrangler, and since `esbuild` is a pre-1.0.0 tool, this may sometimes include breaking changes to how bundling works. In particular, we may bump the `esbuild` version in a Wrangler minor version.

</details>

:::note

Wrangler's inbuilt bundling usually provides the best experience, but we understand there are cases where you will need more flexibility.
You can provide `rules` and set `find_additional_modules` in your configuration to control which files are included in the deployed Worker but not bundled into the entry-point file.
Furthermore, we have an escape hatch in the form of [Custom Builds](/workers/wrangler/custom-builds/), which lets you run your own build before Wrangler's built-in one.
:::

## Including non-JavaScript modules

Bundling your Worker code takes multiple modules and bundles them into one file.
Sometimes, you might have modules that cannot be inlined directly into the bundle.
For example, instead of bundling a Wasm file into your JavaScript Worker, you would want to upload the Wasm file as a separate module that can be imported at runtime.
Wrangler supports this for the following file types:

- `.txt`
- `.html`
- `.bin`
- `.wasm` and `.wasm?module`

Refer to [Bundling configuration](/workers/wrangler/configuration/#bundling) to customize these file types.

For example, with the following import, the variable `data` will be a string containing the contents of `example.html`:

```js
import data from "./example.html"; // Where `example.html` is a file in your local directory
```

This is also the basis of Wasm support with Wrangler. To use a Wasm module in a Worker developed with Wrangler, add the following to your Worker:

```js
import wasm from "./example.wasm"; // Where `example.wasm` is a file in your local directory
const instance = await WebAssembly.instantiate(wasm); // Instantiate Wasm modules in global scope, not within the fetch() handler

export default {
	fetch(request) {
		const result = instance.exports.exported_func();
	},
};
```

:::caution

Cloudflare Workers does not support `WebAssembly.instantiateStreaming()`.
:::

## Find additional modules

By setting `find_additional_modules` to `true` in your configuration file, Wrangler will traverse the file tree below `base_dir`.
Any files that match the `rules` you define will also be included as unbundled, external modules in the deployed Worker.

This approach is useful for supporting lazy loading of large or dynamically imported JavaScript files:

- Normally, a large lazy-imported file (for example, `await import("./large-dep.mjs")`) would be bundled directly into your entrypoint, reducing the effectiveness of the lazy loading.
  If matching rule is added to `rules`, then this file would only be loaded and executed at runtime when it is actually imported.
- Previously, variable based dynamic imports (for example, ``await import(`./lang/${language}.mjs`)``) would always fail at runtime because Wrangler had no way of knowing which modules to include in the upload.
  Providing a rule that matches all these files, such as `{ type = "EsModule", globs = ["./land/**/*.mjs"], fallthrough = true }`, will ensure this module is available at runtime.
- "Partial bundling" is supported when `find_additional_modules` is `true`, and a source file matches one of the configured `rules`, since Wrangler will then treat it as "external" and not try to bundle it into the entry-point file.

## Conditional exports

Wrangler respects the [conditional `exports` field](https://nodejs.org/api/packages.html#conditional-exports) in `package.json`. This allows developers to implement isomorphic libraries that have different implementations depending on the JavaScript runtime they are running in. When bundling, Wrangler will try to load the [`workerd` key](https://runtime-keys.proposal.wintercg.org/#workerd). Refer to the Wrangler repository for [an example isomorphic package](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/isomorphic-random-example).

## Disable bundling

:::caution

Disabling bundling is not recommended in most scenarios. Use this option only when deploying code pre-processed by other tooling.
:::

If your build tooling already produces build artifacts suitable for direct deployment to Cloudflare, you can opt out of bundling by using the `--no-bundle` command line flag: `npx wrangler deploy --no-bundle`. If you opt out of bundling, Wrangler will not process your code and some features introduced by Wrangler bundling (for example minification, and polyfills injection) will not be available.

Use [Custom Builds](/workers/wrangler/custom-builds/) to customize what Wrangler will bundle and upload to the Cloudflare global network when you use [`wrangler dev`](/workers/wrangler/commands/#dev) and [`wrangler deploy`](/workers/wrangler/commands/#deploy).

## Generated Wrangler configuration

Some framework tools, or custom pre-build processes, generate a modified Wrangler configuration to be used to deploy the Worker code.
It is possible for Wrangler to automatically use this generated configuration rather than the original, user's configuration.

See [Generated Wrangler configuration](/workers/wrangler/configuration/#generated-wrangler-configuration) for more information.

---

# Commands

URL: https://developers.cloudflare.com/workers/wrangler/commands/

import {
	TabItem,
	Tabs,
	Render,
	Type,
	MetaInfo,
	WranglerConfig,
	PackageManagers,
} from "~/components";

Wrangler offers a number of commands to manage your Cloudflare Workers.

- [`docs`](#docs) - Open this page in your default browser.
- [`init`](#init) - Create a new project from a variety of web frameworks and templates.
- [`containers`](#containers) - Interact with Containers.
- [`d1`](#d1) - Interact with D1.
- [`vectorize`](#vectorize) - Interact with Vectorize indexes.
- [`hyperdrive`](#hyperdrive) - Manage your Hyperdrives.
- [`deploy`](#deploy) - Deploy your Worker to Cloudflare.
- [`dev`](#dev) - Start a local server for developing your Worker.
- [`delete`](#delete-1) - Delete your Worker from Cloudflare.
- [`kv namespace`](#kv-namespace) - Manage Workers KV namespaces.
- [`kv key`](#kv-key) - Manage key-value pairs within a Workers KV namespace.
- [`kv bulk`](#kv-bulk) - Manage multiple key-value pairs within a Workers KV namespace in batches.
- [`r2 bucket`](#r2-bucket) - Manage Workers R2 buckets.
- [`r2 object`](#r2-object) - Manage Workers R2 objects.
- [`secret`](#secret) - Manage the secret variables for a Worker.
- [`secret bulk`](#secret-bulk) - Manage multiple secret variables for a Worker.
- [`secrets-store secret`](#secrets-store-secret) - Manage account secrets within a secrets store.
- [`secrets-store store`](#secrets-store-store) - Manage your store within secrets store.
- [`workflows`](#workflows) - Manage and configure Workflows.
- [`tail`](#tail) - Start a session to livestream logs from a deployed Worker.
- [`pages`](#pages) - Configure Cloudflare Pages.
- [`pipelines`](#pipelines) - Configure Cloudflare Pipelines.
- [`queues`](#queues) - Configure Workers Queues.
- [`login`](#login) - Authorize Wrangler with your Cloudflare account using OAuth.
- [`logout`](#logout) - Remove Wrangler’s authorization for accessing your account.
- [`whoami`](#whoami) - Retrieve your user information and test your authentication configuration.
- [`versions`](#versions) - Retrieve details for recent versions.
- [`deployments`](#deployments) - Retrieve details for recent deployments.
- [`rollback`](#rollback) - Rollback to a recent deployment.
- [`dispatch-namespace`](#dispatch-namespace) - Interact with a [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace).
- [`mtls-certificate`](#mtls-certificate) - Manage certificates used for mTLS connections.
- [`cert`](#cert) - Manage certificates used for mTLS and Certificate Authority (CA) chain connections.
- [`types`](#types) - Generate types from bindings and module rules in configuration.
- [`telemetry`](#telemetry) - Configure whether Wrangler can collect anonymous usage data.
- [`check`](#check) - Validate your Worker.

:::note

<Render file="wrangler-commands/global-flags" product="workers" />

:::

---

## How to run Wrangler commands

This page provides a reference for Wrangler commands.

```txt
wrangler <COMMAND> <SUBCOMMAND> [PARAMETERS] [OPTIONS]
```

Since Cloudflare recommends [installing Wrangler locally](/workers/wrangler/install-and-update/) in your project(rather than globally), the way to run Wrangler will depend on your specific setup and package manager.

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="<COMMAND> <SUBCOMMAND> [PARAMETERS] [OPTIONS]"
/>

You can add Wrangler commands that you use often as scripts in your project's `package.json` file:

```json
{
  ...
  "scripts": {
    "deploy": "wrangler deploy",
    "dev": "wrangler dev"
  }
  ...
}
```

You can then run them using your package manager of choice:

<PackageManagers type="run" args="deploy" />

---

## `docs`

Open the Cloudflare developer documentation in your default browser.

```txt
wrangler docs [<COMMAND>]
```

- `COMMAND` <Type text="string" /> <MetaInfo text="optional" />
  - The Wrangler command you want to learn more about. This opens your default browser to the section of the documentation that describes the command.

<Render file="wrangler-commands/global-flags" product="workers" />

## `init`

Create a new project via the [create-cloudflare-cli (C3) tool](/workers/get-started/guide/#1-create-a-new-worker-project). A variety of web frameworks are available to choose from as well as templates. Dependencies are installed by default, with the option to deploy your project immediately.

```txt
wrangler init [<NAME>] [OPTIONS]
```

- `NAME` <Type text="string" /> <MetaInfo text="optional (default: name of working directory)" />
  - The name of the Workers project. This is both the directory name and `name` property in the generated [Wrangler configuration](/workers/wrangler/configuration/).
- `--yes` <Type text="boolean" /> <MetaInfo text="optional" />
  - Answer yes to any prompts for new projects.
- `--from-dash` <Type text="string" /> <MetaInfo text="optional" />
  - Fetch a Worker initialized from the dashboard. This is done by passing the flag and the Worker name. `wrangler init --from-dash <WORKER_NAME>`.
  - The `--from-dash` command will not automatically sync changes made to the dashboard after the command is used. Therefore, it is recommended that you continue using the CLI.

<Render file="wrangler-commands/global-flags" product="workers" />

---

## `containers`

Interact with Cloudflare's Container Platform.

<Render file="wrangler-commands/containers" product="workers" />

## `d1`

Interact with Cloudflare's D1 service.

<Render file="wrangler-commands/d1" product="workers" />

---

## `hyperdrive`

Manage [Hyperdrive](/hyperdrive/) database configurations.

<Render file="wrangler-commands/hyperdrive" product="workers" />

---

## `vectorize`

Interact with a [Vectorize](/vectorize/) vector database.

<Render file="wrangler-commands/vectorize" product="workers" />

---

## `dev`

Start a local server for developing your Worker.

```txt
wrangler dev [<SCRIPT>] [OPTIONS]
```

:::note

None of the options for this command are required. Many of these options can be set in your Wrangler file. Refer to the [Wrangler configuration](/workers/wrangler/configuration) documentation for more information.

:::

- `SCRIPT` <Type text="string" />
  - The path to an entry point for your Worker. Only required if your [Wrangler configuration file](/workers/wrangler/configuration/) does not include a `main` key (for example, `main = "index.js"`).
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Name of the Worker.
- `--config`, `-c` <Type text="string[]" /> <MetaInfo text="optional" />
  - Path(s) to [Wrangler configuration file](/workers/wrangler/configuration/). If not provided, Wrangler will use the nearest config file based on your current working directory.
  - You can provide multiple configuration files to run multiple Workers in one dev session like this: `wrangler dev -c ./wrangler.toml -c ../other-worker/wrangler.toml`. The first config will be treated as the _primary_ Worker, which will be exposed over HTTP. The remaining config files will only be accessible via a service binding from the primary Worker.
- `--no-bundle` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - Skip Wrangler's build steps. Particularly useful when using custom builds. Refer to [Bundling](https://developers.cloudflare.com/workers/wrangler/bundling/) for more information.
- `--env` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific environment.
- `--compatibility-date` <Type text="string" /> <MetaInfo text="optional" />
  - A date in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used.
- `--compatibility-flags`, `--compatibility-flag` <Type text="string[]" /> <MetaInfo text="optional" />
  - Flags to use for compatibility checks.
- `--latest` <Type text="boolean" /> <MetaInfo text="(default: true) optional" />
  - Use the latest version of the Workers runtime.
- `--ip` <Type text="string" /> <MetaInfo text="optional" />
  - IP address to listen on, defaults to `localhost`.
- `--port` <Type text="number" /> <MetaInfo text="optional" />
  - Port to listen on.
- `--inspector-port` <Type text="number" /> <MetaInfo text="optional" />
  - Port for devtools to connect to.
- `--routes`, `--route` <Type text="string[]" /> <MetaInfo text="optional" />
  - Routes to upload.
  - For example: `--route example.com/*`.
- `--host` <Type text="string" /> <MetaInfo text="optional" />
  - Host to forward requests to, defaults to the zone of project.
- `--local-protocol` <Type text="'http'|'https'" /> <MetaInfo text="(default: http) optional" />
  - Protocol to listen to requests on.
- `--https-key-path` <Type text="string" /> <MetaInfo text="optional" />
  - Path to a custom certificate key.
- `--https-cert-path` <Type text="string" /> <MetaInfo text="optional" />
  - Path to a custom certificate.
- `--local-upstream` <Type text="string" /> <MetaInfo text="optional" />
  - Host to act as origin in local mode, defaults to `dev.host` or route.
- `--assets` <Type text="string" /> <MetaInfo text="optional beta" />
  - Folder of static assets to be served. Replaces [Workers Sites](/workers/configuration/sites/). Visit [assets](/workers/static-assets/) for more information.
- `--site` <Type text="string" /> <MetaInfo text="optional deprecated, use `--assets`" />
  - Folder of static assets for Workers Sites.
    :::caution
    Workers Sites is deprecated. Please use [Workers Assets](/workers/static-assets/) or [Pages](/pages/).
    :::
- `--site-include` <Type text="string[]" /> <MetaInfo text="optional deprecated" />
  - Array of `.gitignore`-style patterns that match file or directory names from the sites directory. Only matched items will be uploaded.
- `--site-exclude` <Type text="string[]" /> <MetaInfo text="optional deprecated" />
  - Array of `.gitignore`-style patterns that match file or directory names from the sites directory. Matched items will not be uploaded.
- `--upstream-protocol` <Type text="'http'|'https'" /> <MetaInfo text="(default: https) optional" />
  - Protocol to forward requests to host on.
- `--var` <Type text="key:value\[]" /> <MetaInfo text="optional" />
  - Array of `key:value` pairs to inject as variables into your code. The value will always be passed as a string to your Worker.
  - For example, `--var "git_hash:'$(git rev-parse HEAD)'" "test:123"` makes the `git_hash` and `test` variables available in your Worker's `env`.
  - This flag is an alternative to defining [`vars`](/workers/wrangler/configuration/#non-inheritable-keys) in your [Wrangler configuration file](/workers/wrangler/configuration/). If defined in both places, this flag's values will be used.
- `--define` <Type text="key:value\[]" /> <MetaInfo text="optional" />
  - Array of `key:value` pairs to replace global identifiers in your code.
  - For example, `--define "GIT_HASH:'$(git rev-parse HEAD)'"` will replace all uses of `GIT_HASH` with the actual value at build time.
  - This flag is an alternative to defining [`define`](/workers/wrangler/configuration/#non-inheritable-keys) in your [Wrangler configuration file](/workers/wrangler/configuration/). If defined in both places, this flag's values will be used.
- `--tsconfig` <Type text="string" /> <MetaInfo text="optional" />
  - Path to a custom `tsconfig.json` file.
- `--minify` <Type text="boolean" /> <MetaInfo text="optional" />
  - Minify the Worker.
- `--persist-to` <Type text="string" /> <MetaInfo text="optional" />
  - Specify directory to use for local persistence.
- `--remote` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - Develop against remote resources and data stored on Cloudflare's network.
- `--test-scheduled` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - Exposes a `/__scheduled` fetch route which will trigger a scheduled event (Cron Trigger) for testing during development. To simulate different cron patterns, a `cron` query parameter can be passed in: `/__scheduled?cron=*+*+*+*+*` or `/cdn-cgi/handler/scheduled?cron=*+*+*+*+*`.
- `--log-level` <Type text="'debug'|'info'|'log'|'warn'|'error|'none'" /> <MetaInfo text="(default: log) optional" />
  - Specify Wrangler's logging level.
- `--show-interactive-dev-session` <Type text="boolean" /> <MetaInfo text="(default: true if the terminal supports interactivity) optional" />
  - Show the interactive dev session.
- `--alias` `Array<string>`
  - Specify modules to alias using [module aliasing](/workers/wrangler/configuration/#module-aliasing).

<Render file="wrangler-commands/global-flags" product="workers" />

`wrangler dev` is a way to [locally test](/workers/development-testing/) your Worker while developing. With `wrangler dev` running, send HTTP requests to `localhost:8787` and your Worker should execute as expected. You will also see `console.log` messages and exceptions appearing in your terminal.

---

## `deploy`

Deploy your Worker to Cloudflare.

```txt
wrangler deploy [<SCRIPT>] [OPTIONS]
```

:::note

None of the options for this command are required. Also, many can be set in your Wrangler file. Refer to the [Wrangler configuration](/workers/wrangler/configuration/) documentation for more information.

:::

- `SCRIPT` <Type text="string" />
  - The path to an entry point for your Worker. Only required if your [Wrangler configuration file](/workers/wrangler/configuration/) does not include a `main` key (for example, `main = "index.js"`).
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Name of the Worker.
- `--no-bundle` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - Skip Wrangler's build steps. Particularly useful when using custom builds. Refer to [Bundling](https://developers.cloudflare.com/workers/wrangler/bundling/) for more information.
- `--env` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific environment.
    <Render file="vite-environments" />
- `--outdir` <Type text="string" /> <MetaInfo text="optional" />
  - Path to directory where Wrangler will write the bundled Worker files.
- `--compatibility-date` <Type text="string" /> <MetaInfo text="optional" />
  - A date in the form yyyy-mm-dd, which will be used to determine which version of the Workers runtime is used.
- `--compatibility-flags`, `--compatibility-flag` <Type text="string[]" /> <MetaInfo text="optional" />
  - Flags to use for compatibility checks.
- `--latest` <Type text="boolean" /> <MetaInfo text="(default: true) optional" />
  - Use the latest version of the Workers runtime.
- `--assets` <Type text="string" /> <MetaInfo text="optional beta" />
  - Folder of static assets to be served. Replaces [Workers Sites](/workers/configuration/sites/). Visit [assets](/workers/static-assets/) for more information.
- `--site` <Type text="string" /> <MetaInfo text="optional deprecated, use `--assets`" />
  - Folder of static assets for Workers Sites.
    :::caution
    Workers Sites is deprecated. Please use [Workers Assets](/workers/static-assets/) or [Pages](/pages/).
    :::
- `--site-include` <Type text="string[]" /> <MetaInfo text="optional deprecated" />
  - Array of `.gitignore`-style patterns that match file or directory names from the sites directory. Only matched items will be uploaded.
- `--site-exclude` <Type text="string[]" /> <MetaInfo text="optional deprecated" />
  - Array of `.gitignore`-style patterns that match file or directory names from the sites directory. Matched items will not be uploaded.
- `--var` <Type text="key:value\[]" /> <MetaInfo text="optional" />
  - Array of `key:value` pairs to inject as variables into your code. The value will always be passed as a string to your Worker.
  - For example, `--var git_hash:$(git rev-parse HEAD) test:123` makes the `git_hash` and `test` variables available in your Worker's `env`.
  - This flag is an alternative to defining [`vars`](/workers/wrangler/configuration/#non-inheritable-keys) in your [Wrangler configuration file](/workers/wrangler/configuration/). If defined in both places, this flag's values will be used.
- `--define` <Type text="key:value\[]" /> <MetaInfo text="optional" />
  - Array of `key:value` pairs to replace global identifiers in your code.
  - For example, `--define GIT_HASH:$(git rev-parse HEAD)` will replace all uses of `GIT_HASH` with the actual value at build time.
  - This flag is an alternative to defining [`define`](/workers/wrangler/configuration/#non-inheritable-keys) in your [Wrangler configuration file](/workers/wrangler/configuration/). If defined in both places, this flag's values will be used.
- `--triggers`, `--schedule`, `--schedules` <Type text="string[]" /> <MetaInfo text="optional" />
  - Cron schedules to attach to the deployed Worker. Refer to [Cron Trigger Examples](/workers/configuration/cron-triggers/#examples).
- `--routes`, `--route` string\[] optional
  - Routes where this Worker will be deployed.
  - For example: `--route example.com/*`.
- `--tsconfig` <Type text="string" /> <MetaInfo text="optional" />
  - Path to a custom `tsconfig.json` file.
- `--minify` <Type text="boolean" /> <MetaInfo text="optional" />
  - Minify the bundled Worker before deploying.
- `--dry-run` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - Compile a project without actually deploying to live servers. Combined with `--outdir`, this is also useful for testing the output of `npx wrangler deploy`. It also gives developers a chance to upload our generated sourcemap to a service like Sentry, so that errors from the Worker can be mapped against source code, but before the service goes live.
- `--keep-vars` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - It is recommended best practice to treat your Wrangler developer environment as a source of truth for your Worker configuration, and avoid making changes via the Cloudflare dashboard.
  - If you change your environment variables in the Cloudflare dashboard, Wrangler will override them the next time you deploy. If you want to disable this behaviour set `keep-vars` to `true`.
  - Secrets are never deleted by a deployment whether this flag is true or false.
- `--dispatch-namespace` <Type text="string" /> <MetaInfo text="optional" />
  - Specify the [Workers for Platforms dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/get-started/configuration/#2-create-a-dispatch-namespace) to upload this Worker to.
- `--metafile` <Type text="string" /> <MetaInfo text="optional" />
  - Specify a file to write the build metadata from esbuild to. If flag is used without a path string, this defaults to `bundle-meta.json` inside the directory specified by `--outdir`. This can be useful for understanding the bundle size.

<Render file="wrangler-commands/global-flags" product="workers" />

---

## `delete`

Delete your Worker and all associated Cloudflare developer platform resources.

```txt
wrangler delete [<SCRIPT>] [OPTIONS]
```

- `SCRIPT` <Type text="string" />
  - The path to an entry point for your Worker. Only required if your [Wrangler configuration file](/workers/wrangler/configuration/) does not include a `main` key (for example, `main = "index.js"`).
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Name of the Worker.
- `--env` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific environment.
- `--dry-run` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - Do not actually delete the Worker. This is useful for testing the output of `wrangler delete`.

<Render file="wrangler-commands/global-flags" product="workers" />

---

<Render file="wrangler-commands/kv" product="workers" />

---

<Render file="wrangler-commands/r2" product="workers" />

---

## `secret`

Manage the secret variables for a Worker.

This action creates a new [version](/workers/configuration/versions-and-deployments/#versions) of the Worker and [deploys](/workers/configuration/versions-and-deployments/#deployments) it immediately. To only create a new version of the Worker, use the [`wrangler versions secret`](/workers/wrangler/commands/#secret-put) commands.

### `put`

Create or replace a secret for a Worker.

```txt
wrangler secret put <KEY> [OPTIONS]
```

- `KEY` <Type text="string" /> <MetaInfo text="required" />
  - The variable name for this secret to be accessed in the Worker.
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from a [Wrangler configuration file](/workers/wrangler/configuration/).
- `--env` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific environment.

<Render file="wrangler-commands/global-flags" product="workers" />

When running this command, you will be prompted to input the secret's value:

```sh
npx wrangler secret put FOO
```

```sh output
? Enter a secret value: › ***
🌀 Creating the secret for script worker-app
✨ Success! Uploaded secret FOO
```

The `put` command can also receive piped input. For example:

```sh
echo "-----BEGIN PRIVATE KEY-----\nM...==\n-----END PRIVATE KEY-----\n" | wrangler secret put PRIVATE_KEY
```

### `delete`

Delete a secret for a Worker.

```txt
wrangler secret delete <KEY> [OPTIONS]
```

- `KEY` <Type text="string" /> <MetaInfo text="required" />
  - The variable name for this secret to be accessed in the Worker.
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).
- `--env` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific environment.

<Render file="wrangler-commands/global-flags" product="workers" />

### `list`

List the names of all the secrets for a Worker.

```txt
wrangler secret list [OPTIONS]
```

- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).
- `--env` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific environment

<Render file="wrangler-commands/global-flags" product="workers" />

The following is an example of listing the secrets for the current Worker.

```sh
npx wrangler secret list
```

```sh output
[
  {
    "name": "FOO",
    "type": "secret_text"
  }
]
```

---

## `secret bulk`

Upload multiple secrets for a Worker at once.

```txt
wrangler secret bulk [<FILENAME>] [OPTIONS]
```

- `FILENAME` <Type text="string" /> <MetaInfo text="optional" />
  - A file containing either [JSON](https://www.json.org/json-en.html) or the [.env](https://www.dotenv.org/docs/security/env) format
  - The JSON file containing key-value pairs to upload as secrets, in the form `{"SECRET_NAME": "secret value", ...}`.
  - The `.env` file containing [key-value pairs to upload as secrets](/workers/configuration/secrets/#local-development-with-secrets), in the form `SECRET_NAME=secret value`.
  - If omitted, Wrangler expects to receive input from `stdin` rather than a file.
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).
- `--env` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific environment.

<Render file="wrangler-commands/global-flags" product="workers" />

The following is an example of uploading secrets from a JSON file redirected to `stdin`. When complete, the output summary will show the number of secrets uploaded and the number of secrets that failed to upload.

```json
{
	"secret-name-1": "secret-value-1",
	"secret-name-2": "secret-value-2"
}
```

```sh
npx wrangler secret bulk < secrets.json
```

```sh output
🌀 Creating the secrets for the Worker "script-name"
✨ Successfully created secret for key: secret-name-1
...
🚨 Error uploading secret for key: secret-name-1
✨ Successfully created secret for key: secret-name-2

Finished processing secrets JSON file:
✨ 1 secrets successfully uploaded
🚨 1 secrets failed to upload
```

## `secrets-store secret`

With the release of [Secrets Store](/secrets-store/) in open beta, you can use the following commands to manage your account secrets.

:::note[`--remote` option]
In order to interact with Secrets Store in production, you should append `--remote` to your command. Without it, your command will default to [local development mode](/workers/development-testing/).
:::

### `create`

Create a secret within a store.

```txt
wrangler secrets-store secret create <STORE_ID> [OPTIONS]
```

- `STORE_ID` <Type text="string" /> <MetaInfo text="required" />
  - The secret store public ID. You can find it and copy from the [Secrets Store tab](https://dash.cloudflare.com/?to=/:account/secrets-store/) on the dashboard.
- `--name` <Type text="string" /> <MetaInfo text="required" />
  - A descriptive name for the account-level secret. Cannot contain spaces.
- `--value` <Type text="string" /> <MetaInfo text="test only" />
  - Value of the secret.
    :::caution[Only use for testing]
    This will leave the secret value in plain-text in terminal history. For real secret values, use the automatic prompt instead. Find an example below.
    :::
- `--scopes` <Type text="string" /> <MetaInfo text="required" />
  - Which services will have access to the account-level secret. Currently, only `workers` is available.
- `--comment` <Type text="string" /> <MetaInfo text="optional" />
  - Additional information about the account-level secret.
- `--remote` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - Execute the command against the remote Secrets Store. To interact with account-level secrets in production, make sure to append `--remote` to your commands.

The following is an example of using the `create` command to create an account-level secret.

```sh
npx wrangler secrets-store secret create 8f7a1cdced6342c18d223ece462fd88d --name ServiceA_key-1 --scopes workers --remote
```

```sh output
✓ Enter a secret value: › ***

🔐 Creating secret... (Name: ServiceA_key-1, Value: REDACTED, Scopes: workers, Comment: undefined)
✓ Select an account: › My account
✅ Created secret! (ID: 13bc7498c6374a4e9d13be091c3c65f1)
```

### `update`

Update a secret within a store.

```txt
wrangler secrets-store secret update <STORE_ID> [OPTIONS]
```

- `STORE_ID` <Type text="string" /> <MetaInfo text="required" />
  - The ID of the secrets store that contains the secret you are updating.
- `--secret-id` <Type text="string" /> <MetaInfo text="required" />
  - The ID of the secret to update.
- `--value` <Type text="string" /> <MetaInfo text="test only" />
  - Updated value of the secret.
    :::caution[Only use for testing]
    This will leave the secret value in plain-text in terminal history. For real secret values, use the automatic prompt instead.
    :::
- `--scopes` <Type text="string" /> <MetaInfo text="required" />
  - Which services will have access to the account-level secret. Currently, only `workers` is available.
- `--comment` <Type text="string" /> <MetaInfo text="optional" />
  - Updated comment for the account-level secret.
- `--remote` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - Execute the command against the remote Secrets Store. To interact with account-level secrets in production, make sure to append `--remote` to your commands.

### `duplicate`

Duplicate a secret within a store. Use this command to create a new secret that holds the same secret value as an existing secret.

```txt
wrangler secrets-store secret duplicate <STORE_ID> [OPTIONS]
```

- `STORE_ID` <Type text="string" /> <MetaInfo text="required" />
  - The ID of the secrets store that contains the secret you are duplicating.
- `--secret-id` <Type text="string" /> <MetaInfo text="required" />
  - The ID of the secret you are duplicating.
- `--name` <Type text="string" /> <MetaInfo text="required" />
  - A name for the new secret. Cannot contain spaces.
- `--scopes` <Type text="string" /> <MetaInfo text="required" />
  - Which services will have access to the new account-level secret. Currently, only `workers` is available.
- `--comment` <Type text="string" /> <MetaInfo text="optional" />
  - Additional information about the new account-level secret.
- `--remote` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - Execute the command against the remote Secrets Store. To interact with account-level secrets in production, make sure to append `--remote` to your commands.

### `get`

Get information on a secret within a store.

```txt
wrangler secrets-store secret get <STORE_ID> [OPTIONS]
```

- `STORE_ID` <Type text="string" /> <MetaInfo text="required" />
  - The ID of the secrets store that contains the secret you want to get.
- `--secret-id` <Type text="string" /> <MetaInfo text="required" />
  - The ID of the secret you want to get.
- `--remote` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - Execute the command against the remote Secrets Store. To interact with account-level secrets in production, make sure to append `--remote` to your commands.

The following is an example with the expected output:

```sh
npx wrangler secrets-store secret get 8f7a1cdced6342c18d223ece462fd88d --secret-id 13bc7498c6374a4e9d13be091c3c65f1 --remote
```

```sh output
🔐 Getting secret... (ID: 13bc7498c6374a4e9d13be091c3c65f1)
✓ Select an account: › My account
| Name                        | ID                                  | StoreID                             | Comment | Scopes  | Status  | Created                | Modified               |
|-----------------------------|-------------------------------------|-------------------------------------|---------|---------|---------|------------------------|------------------------|
| ServiceA_key-1          | 13bc7498c6374a4e9d13be091c3c65f1    | 8f7a1cdced6342c18d223ece462fd88d    |         | workers | active  | 4/9/2025, 10:06:01 PM  | 4/15/2025, 09:13:05 AM |
```

### `delete`

Delete a secret within a store.

:::caution
Before deleting a secret, make sure it is not deployed in any Workers application.
:::

```txt
wrangler secrets-store secret delete <STORE_ID> [OPTIONS]
```

- `STORE_ID` <Type text="string" /> <MetaInfo text="required" />
  - The ID of the secrets store that contains the secret you are deleting.
- `--secret-id` <Type text="string" /> <MetaInfo text="required" />
  - The ID of the secret you are deleting.
- `--remote` <Type text="boolean" /> <MetaInfo text="(default: false) optional" />
  - Execute the command against the remote Secrets Store. To interact with account-level secrets in production, make sure to append `--remote` to your commands.

### `list`

List secrets within a store.

```txt
wrangler secrets-store secret list <STORE_ID>
```

- `STORE_ID` <Type text="string" /> <MetaInfo text="required" />
  - The secret store public ID. You can find it and copy from the [Secrets Store tab](https://dash.cloudflare.com/?to=/:account/secrets-store/) on the dashboard.

## `secrets-store store`

Use the following commands to manage your store.

:::note[Store limitation]
[Secrets Store](/secrets-store/) is in open beta. Currently, you can only have one store per Cloudflare account.
:::

### `create`

Create a store within Secrets Store.

```txt
wrangler secrets-store store create <name>
```

- `name` <Type text="string" /> <MetaInfo text="required" />
  - A descriptive name for the account-level secret. Cannot contain spaces.
- `--remote` <Type text="boolean" /> <MetaInfo text="(default: false) required" />
  - Execute the command against the remote Secrets Store.

The following is an example of using the `create` command to create a store.

```sh
npx wrangler secrets-store store create default --remote
```

```sh output
🔐 Creating store... (Name: default)
✅ Created store! (Name: default, ID: 2e2a82d317134506b58defbe16982d54)
```

### `delete`

Delete a store within Secrets Store.

```txt
wrangler secrets-store store delete <STORE_ID>
```

- `STORE_ID` <Type text="string" /> <MetaInfo text="required" />
  - The secret store public ID. You can find it and copy from the [Secrets Store tab](https://dash.cloudflare.com/?to=/:account/secrets-store/) on the dashboard.
- `--remote` <Type text="boolean" /> <MetaInfo text="(default: false) required" />
  - Execute the command against the remote Secrets Store.

The following is an example of using the `delete` command to delete a store.

```sh
npx wrangler secrets-store store delete d2dafaeac9434de2b6d08b292ce08211 --remote
```

```sh output
🔐 Deleting store... (Name: d2dafaeac9434de2b6d08b292ce08211)
✅ Deleted store! (ID: d2dafaeac9434de2b6d08b292ce08211)
```

### `list`

List the stores within an account.

```txt
wrangler secrets-store store list
```

- `--remote` <Type text="boolean" /> <MetaInfo text="(default: false) required" />
  - Execute the command against the remote Secrets Store.

The following is an example of using the `list` command to list stores.

```sh
npx wrangler secrets-store store list --remote
```

```sh output
🔐 Listing stores...
┌─────────┬──────────────────────────────────┬──────────────────────────────────┬──────────────────────┬──────────────────────┐
│ Name    │ ID                               │ AccountID                        │ Created              │ Modified             │
├─────────┼──────────────────────────────────┼──────────────────────────────────┼──────────────────────┼──────────────────────┤
│ default │ 8876bad33f164462bf0743fe8adf98f4 │ REDACTED │ 4/9/2025, 1:11:48 PM  │ 4/9/2025, 1:11:48 PM │
└─────────┴──────────────────────────────────┴──────────────────────────────────┴──────────────────────┴──────────────────────┘
```

## `workflows`

:::note

The `wrangler workflows` command requires Wrangler version `3.83.0` or greater. Use `npx wrangler@latest` to always use the latest Wrangler version when invoking commands.

:::

Manage and configure [Workflows](/workflows/).

### `list`

Lists the registered Workflows for this account.

```sh
wrangler workflows list
```

- `--page` <Type text="number" /> <MetaInfo text="optional" />
  - Show a specific page from the listing. You can configure page size using "per-page".
- `--per-page` <Type text="number" /> <MetaInfo text="optional" />
  - Configure the maximum number of Workflows to show per page.

<Render file="wrangler-commands/global-flags" product="workers" />

### `instances`

Manage and interact with specific instances of a Workflow.

### `instances list`

List Workflow instances.

```sh
wrangler workflows instances list <WORKFLOW_NAME> [OPTIONS]
```

- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of a registered Workflow.

<Render file="wrangler-commands/global-flags" product="workers" />

### `instances describe`

Describe a specific instance of a Workflow, including its current status, any persisted state, and per-step outputs.

```sh
wrangler workflows instances describe <WORKFLOW_NAME> <ID> [OPTIONS]
```

- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of a registered Workflow.
- `ID` <Type text="string" /> <MetaInfo text="required" />
  - The ID of a Workflow instance. You can optionally provide `latest` to refer to the most recently created instance of a Workflow.

<Render file="wrangler-commands/global-flags" product="workers" />

```sh
# Passing `latest` instead of an explicit ID will describe the most recently queued instance
wrangler workflows instances describe my-workflow latest
```

```sh output
Workflow Name:         my-workflow
Instance Id:           51c73fc8-7fd5-47d9-bd82-9e301506ee72
Version Id:            cedc33a0-11fa-4c26-8a8e-7d28d381a291
Status:                ✅ Completed
Trigger:               🌎 API
Queued:                10/16/2024, 2:00:39 PM
Success:               ✅ Yes
Start:                 10/16/2024, 2:00:39 PM
End:                   10/16/2024, 2:01:40 PM
Duration:              1 minute
# Remaining output truncated
```

### `instances terminate`

Terminate (permanently stop) a Workflow instance.

```sh
wrangler workflows instances terminate <WORKFLOW_NAME> <ID> [OPTIONS]
```

- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of a registered Workflow.
- `ID` <Type text="string" /> <MetaInfo text="required" />
  - The ID of a Workflow instance.

<Render file="wrangler-commands/global-flags" product="workers" />

### `instances pause`

Pause (until resumed) a Workflow instance.

```sh
wrangler workflows instances pause <WORKFLOW_NAME> <ID> [OPTIONS]
```

- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of a registered Workflow.
- `ID` <Type text="string" /> <MetaInfo text="required" />
  - The ID of a Workflow instance.

<Render file="wrangler-commands/global-flags" product="workers" />

### `instances resume`

Resume a paused Workflow instance.

```sh
wrangler workflows instances resume <WORKFLOW_NAME> <ID> [OPTIONS]
```

- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of a registered Workflow.
- `ID` <Type text="string" /> <MetaInfo text="required" />
  - The ID of a Workflow instance.

<Render file="wrangler-commands/global-flags" product="workers" />

### `describe`

```sh
wrangler workflows describe <WORKFLOW_NAME> [OPTIONS]
```

- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of a registered Workflow.

<Render file="wrangler-commands/global-flags" product="workers" />

### `delete`

Delete a Workflow and all its instances.

```sh
wrangler workflows delete <WORKFLOW_NAME> [OPTIONS]
```

- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of a registered Workflow.

<Render file="wrangler-commands/global-flags" product="workers" />

```sh
wrangler workflows instances delete my-workflow
```

### `trigger`

Trigger (create) a Workflow instance.

```sh
wrangler workflows trigger <WORKFLOW_NAME> <PARAMS> [OPTIONS]
```

- `WORKFLOW_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of a registered Workflow.
- `PARAMS` <Type text="string" /> <MetaInfo text="optional" />
  - The parameters to pass to the Workflow as an event. Must be a JSON-encoded string.

<Render file="wrangler-commands/global-flags" product="workers" />

```sh
# Pass optional params to the Workflow.
wrangler workflows trigger my-workflow '{"hello":"world"}'
```

## `tail`

Start a session to livestream logs from a deployed Worker.

```txt
wrangler tail <WORKER> [OPTIONS]
```

- `WORKER` <Type text="string" /> <MetaInfo text="required" />
  - The name of your Worker or the route the Worker is running on.
- `--format` <Type text="'json'|'pretty'" /> <MetaInfo text="optional" />
  - The format of the log entries.
- `--status` <Type text="'ok'|'error'|'canceled'" /> <MetaInfo text="optional" />
  - Filter by invocation status.
- `--header` <Type text="string" /> <MetaInfo text="optional" />
  - Filter by HTTP header.
- `--method` <Type text="string" /> <MetaInfo text="optional" />
  - Filter by HTTP method.
- `--sampling-rate` <Type text="number" /> <MetaInfo text="optional" />
  - Add a fraction of requests to log sampling rate (between `0` and `1`).
- `--search` <Type text="string" /> <MetaInfo text="optional" />
  - Filter by a text match in `console.log` messages.
- `--ip` <Type text="(string|'self')\[]" />" <MetaInfo text="optional" />
  - Filter by the IP address the request originates from. Use `"self"` to show only messages from your own IP.
- `--version-id` <Type text="string" /> <MetaInfo text="optional" />
  - Filter by Worker version.

<Render file="wrangler-commands/global-flags" product="workers" />

After starting `wrangler tail`, you will receive a live feed of console and exception logs for each request your Worker receives.

If your Worker has a high volume of traffic, the tail might enter sampling mode. This will cause some of your messages to be dropped and a warning to appear in your tail logs. To prevent messages from being dropped, add the options listed above to filter the volume of tail messages.

:::note

It may take up to 1 minute (60 seconds) for a tail to exit sampling mode after adding an option to filter tail messages.
:::

If sampling persists after using options to filter messages, consider using [instant logs](https://developers.cloudflare.com/logs/instant-logs/).

---

## `pages`

Configure Cloudflare Pages.

### `dev`

Develop your full-stack Pages application locally.

```txt
wrangler pages dev [<DIRECTORY>] [OPTIONS]
```

- `DIRECTORY` <Type text="string" /> <MetaInfo text="optional" />
  - The directory of static assets to serve.
- `--local` <Type text="boolean" /> <MetaInfo text="optional (default: true)" />
  - Run on your local machine.
- `--ip` <Type text="string" /> <MetaInfo text="optional" />
  - IP address to listen on, defaults to `localhost`.
- `--port` <Type text="number" /> <MetaInfo text="optional (default: 8788)" />
  - The port to listen on (serve from).
- `--config`, `-c` <Type text="string[]" /> <MetaInfo text="optional" />
  - Path(s) to [Wrangler configuration file](/workers/wrangler/configuration/). If not provided, Wrangler will use the nearest config file based on your current working directory.
  - You can provide additional configuration files in order to run Workers alongside your Pages project, like this: `wrangler pages dev -c ./wrangler.toml -c ../other-worker/wrangler.toml`. The first argument must point to your Pages configuration file, and the subsequent configurations will be accessible via a Service binding from your Pages project.
- `--binding` <Type text="string[]" /> <MetaInfo text="optional" />
  - Bind an environment variable or secret (for example, `--binding <VARIABLE_NAME>=<VALUE>`).
- `--kv` <Type text="string[]" /> optional
  - Binding name of [KV namespace](/kv/) to bind (for example, `--kv <BINDING_NAME>`).
- `--r2` <Type text="string[]" /> <MetaInfo text="optional" />
  - Binding name of [R2 bucket](/pages/functions/bindings/#interact-with-your-r2-buckets-locally) to bind (for example, `--r2 <BINDING_NAME>`).
- `--d1` <Type text="string[]" /> <MetaInfo text="optional" />
  - Binding name of [D1 database](/pages/functions/bindings/#interact-with-your-d1-databases-locally) to bind (for example, `--d1 <BINDING_NAME>`).
- `--do` <Type text="string[]" /> <MetaInfo text="optional" />
  - Binding name of Durable Object to bind (for example, `--do <BINDING_NAME>=<CLASS>`).
- `--live-reload` <Type text="boolean" /> <MetaInfo text="optional (default: false)" />
  - Auto reload HTML pages when change is detected.
- `--compatibility-flag` <Type text="string[]" /> <MetaInfo text="optional" />
  - Runtime compatibility flags to apply.
- `--compatibility-date` <Type text="string" /> <MetaInfo text="optional" />
  - Runtime compatibility date to apply.
- `--show-interactive-dev-session` <Type text="boolean" /> <MetaInfo text="optional (default: true if the terminal supports interactivity)" />
  - Show the interactive dev session.
- `--https-key-path` <Type text="string" /> <MetaInfo text="optional" />
  - Path to a custom certificate key.
- `--https-cert-path` <Type text="string" /> <MetaInfo text="optional" />
  - Path to a custom certificate.

<Render file="wrangler-commands/global-flags" product="workers" />

### `download config`

Download your Pages project config as a [Wrangler configuration file](/workers/wrangler/configuration/).

```txt
wrangler pages download config <PROJECT_NAME>
```

<Render file="wrangler-commands/global-flags" product="workers" />

### `project list`

List your Pages projects.

```txt
wrangler pages project list
```

<Render file="wrangler-commands/global-flags" product="workers" />

### `project create`

Create a new Cloudflare Pages project.

```txt
wrangler pages project create <PROJECT_NAME> [OPTIONS]
```

- `PROJECT_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of your Pages project.
- `--production-branch` <Type text="string" /> <MetaInfo text="optional" />
  - The name of the production branch of your project.

<Render file="wrangler-commands/global-flags" product="workers" />

### `project delete`

Delete a Cloudflare Pages project.

```txt
wrangler pages project delete <PROJECT_NAME> [OPTIONS]
```

- `PROJECT_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of the Pages project to delete.
- `--yes` <Type text="boolean" /> <MetaInfo text="optional" />
  - Answer `"yes"` to confirmation prompt.

<Render file="wrangler-commands/global-flags" product="workers" />

### `deployment list`

List deployments in your Cloudflare Pages project.

```txt
wrangler pages deployment list [--project-name <PROJECT_NAME>]
```

- `--project-name` <Type text="string" /> <MetaInfo text="optional" />
  - The name of the project you would like to list deployments for.
- `--environment` <Type text="'production'|'preview'" /> <MetaInfo text="optional" />
  - Environment type to list deployments for.

<Render file="wrangler-commands/global-flags" product="workers" />

### `deployment tail`

Start a session to livestream logs from your deployed Pages Functions.

```txt
wrangler pages deployment tail [<DEPLOYMENT>] [OPTIONS]
```

- `DEPLOYMENT` <Type text="string" /> <MetaInfo text="optional" />
  - ID or URL of the deployment to tail. Specify by environment if deployment ID is unknown.
- `--project-name` <Type text="string" /> <MetaInfo text="optional" />
  - The name of the project you would like to tail.
- `--environment` <Type text="'production'|'preview'" /> <MetaInfo text="optional" />
  - When not providing a specific deployment ID, specifying environment will grab the latest production or preview deployment.
- `--format` <Type text="'json'|'pretty'" /> <MetaInfo text="optional" />
  - The format of the log entries.
- `--status` <Type text="'ok'|'error'|'canceled'" /> <MetaInfo text="optional" />
  - Filter by invocation status.
- `--header` <Type text="string" /> <MetaInfo text="optional" />
  - Filter by HTTP header.
- `--method` <Type text="string" /> <MetaInfo text="optional" />
  - Filter by HTTP method.
- `--sampling-rate` <Type text="number" /> <MetaInfo text="optional" />
  - Add a percentage of requests to log sampling rate.
- `--search` <Type text="string" /> <MetaInfo text="optional" />
  - Filter by a text match in `console.log` messages.
- `--ip` <Type text="(string|'self')\[]" /> <MetaInfo text="optional" />
  - Filter by the IP address the request originates from. Use `"self"` to show only messages from your own IP.

<Render file="wrangler-commands/global-flags" product="workers" />

:::note

Filtering with `--ip self` will allow tailing your deployed Functions beyond the normal request per second limits.
:::

After starting `wrangler pages deployment tail`, you will receive a live stream of console and exception logs for each request your Functions receive.

### `deploy`

Deploy a directory of static assets as a Pages deployment.

```txt
wrangler pages deploy <BUILD_OUTPUT_DIRECTORY> [OPTIONS]
```

- `BUILD_OUTPUT_DIRECTORY` <Type text="string" /> <MetaInfo text="optional" />
  - The [directory](/pages/configuration/build-configuration/#framework-presets) of static files to upload. As of Wrangler 3.45.0, this is only required when your Pages project does not have a Wrangler file. Refer to the [Pages Functions configuration guide](/pages/functions/wrangler-configuration/) for more information.
- `--project-name` <Type text="string" /> <MetaInfo text="optional" />
  - The name of the project you want to deploy to.
- `--branch` <Type text="string" /> <MetaInfo text="optional" />
  - The name of the branch you want to deploy to.
- `--commit-hash` <Type text="string" /> <MetaInfo text="optional" />
  - The SHA to attach to this deployment.
- `--commit-message` <Type text="string" /> <MetaInfo text="optional" />
  - The commit message to attach to this deployment.
- `--commit-dirty` <Type text="boolean" /> <MetaInfo text="optional" />
  - Whether or not the workspace should be considered dirty for this deployment.

<Render file="wrangler-commands/global-flags" product="workers" />

:::note

Your site is deployed to `<PROJECT_NAME>.pages.dev`. If you do not provide the `--project-name` argument, you will be prompted to enter a project name in your terminal after you run the command.

:::

### `secret put`

Create or update a secret for a Pages project.

```txt
wrangler pages secret put <KEY> [OPTIONS]
```

- `KEY` <Type text="string" /> <MetaInfo text="required" />
  - The variable name for this secret to be accessed in the Pages project.
- `--project-name` <Type text="string" /> <MetaInfo text="optional" />
  - The name of your Pages project.

<Render file="wrangler-commands/global-flags" product="workers" />

### `secret delete`

Delete a secret from a Pages project.

```txt
wrangler pages secret delete <KEY> [OPTIONS]
```

- `KEY` <Type text="string" /> <MetaInfo text="required" />
  - The variable name for this secret to be accessed in the Pages project.
- `--project-name` <Type text="string" /> <MetaInfo text="optional" />
  - The name of your Pages project.

<Render file="wrangler-commands/global-flags" product="workers" />

### `secret list`

List the names of all the secrets for a Pages project.

```txt
wrangler pages secret list [OPTIONS]
```

- `--project-name` <Type text="string" /> <MetaInfo text="optional" />
  - The name of your Pages project.

<Render file="wrangler-commands/global-flags" product="workers" />

### `secret bulk`

Upload multiple secrets for a Pages project at once.

```txt
wrangler pages secret bulk [<FILENAME>] [OPTIONS]
```

- `FILENAME` <Type text="string" /> <MetaInfo text="optional" />
  - A file containing either [JSON](https://www.json.org/json-en.html) or the [.env](https://www.dotenv.org/docs/security/env) format
  - The JSON file containing key-value pairs to upload as secrets, in the form `{"SECRET_NAME": "secret value", ...}`.
  - The `.env` file containing [key-value pairs to upload as secrets](/workers/configuration/secrets/#local-development-with-secrets), in the form `SECRET_NAME=secret value`.
  - If omitted, Wrangler expects to receive input from `stdin` rather than a file.
- `--project-name` <Type text="string" /> <MetaInfo text="optional" />
  - The name of your Pages project.

<Render file="wrangler-commands/global-flags" product="workers" />

### `functions build`

Compile a folder of Pages Functions into a single Worker.

```txt
wrangler pages functions build [<DIRECTORY>] [OPTIONS]
```

- `DIRECTORY` <Type text="string" /> <MetaInfo text="optional (default: `functions`)" />
  - The directory of Pages Functions.
- `--outdir` <Type text="string" /> <MetaInfo text="optional" />
  - Output directory for the bundled Worker.
- `--fallback-service` <Type text="string" /> <MetaInfo text="optional (default: `ASSETS`)" />
  - The service to fallback to at the end of the `next` chain. Setting to `''` will fallback to the global `fetch`.
- `--compatibility-date` <Type text="string" /> <MetaInfo text="optional" />
  - Date to use for compatibility checks.
- `--compatibility-flags` <Type text="string[]" /> <MetaInfo text="optional" />
  - Flags to use for compatibility checks.
- `--metafile` <Type text="string" /> <MetaInfo text="optional" />
  - Specify a file to write the build metadata from esbuild to. If flag is used without a path string, this defaults to `bundle-meta.json` inside the directory specified by `--outdir`. This can be useful for understanding the bundle size.

<Render file="wrangler-commands/global-flags" product="workers" />

---

## `pipelines`

Manage your [Pipelines](/pipelines/).

<Render file="wrangler-commands/pipelines" product="workers" />

## `queues`

Manage your Workers [Queues](/queues/) configurations.

### `create`

Create a new queue.

```txt
wrangler queues create <name> [OPTIONS]
```

- `name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the queue to create.
- `--delivery-delay-secs` <Type text="number" /> <MetaInfo text="optional" />
  - How long a published message should be delayed for, in seconds. Must be a positive integer.
- `--message-retention-period-secs` <Type text="number" /> <MetaInfo text="optional" />
  - How long a published message is retained in the Queue. Must be a positive integer between 60 and 1209600 (14 days). Defaults to 345600 (4 days).

<Render file="wrangler-commands/global-flags" product="workers" />

### `update`

Update an existing queue.

```txt
wrangler queues update <name> [OPTIONS]
```

- `name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the queue to update.
- `--delivery-delay-secs` <Type text="number" /> <MetaInfo text="optional" />
  - How long a published message should be delayed for, in seconds. Must be a positive integer.
- `--message-retention-period-secs` <Type text="number" /> <MetaInfo text="optional" />
  - How long a published message is retained on the Queue. Must be a positive integer between 60 and 1209600 (14 days). Defaults to 345600 (4 days).

<Render file="wrangler-commands/global-flags" product="workers" />

### `delete`

Delete an existing queue.

```txt
wrangler queues delete <name> [OPTIONS]
```

- `name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the queue to delete.

<Render file="wrangler-commands/global-flags" product="workers" />

### `list`

List all queues in the current account.

```txt
wrangler queues list [OPTIONS]
```

<Render file="wrangler-commands/global-flags" product="workers" />

### `info`

Get information on individual queues.

```txt
wrangler queues info <name>
```

- `name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the queue to inspect.

### `consumer`

Manage queue consumer configurations.

### `consumer add <script-name>`

Add a Worker script as a [queue consumer](/queues/reference/how-queues-works/#consumers).

```txt
wrangler queues consumer add <queue-name> <script-name> [OPTIONS]
```

- `queue-name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the queue to add the consumer to.
- `script-name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the Workers script to add as a consumer of the named queue.
- `--batch-size` <Type text="number" /> <MetaInfo text="optional" />
  - Maximum number of messages per batch. Must be a positive integer.
- `--batch-timeout` <Type text="number" /> <MetaInfo text="optional" />
  - Maximum number of seconds to wait to fill a batch with messages. Must be a positive integer.
- `--message-retries` <Type text="number" /> <MetaInfo text="optional" />
  - Maximum number of retries for each message. Must be a positive integer.
- `--max-concurrency` <Type text="number" /> <MetaInfo text="optional" />
  - The maximum number of concurrent consumer invocations that will be scaled up to handle incoming message volume. Must be a positive integer.
- `--retry-delay-secs` <Type text="number" /> <MetaInfo text="optional" />
  - How long a retried message should be delayed for, in seconds. Must be a positive integer.

<Render file="wrangler-commands/global-flags" product="workers" />

### `consumer remove`

Remove a consumer from a queue.

```txt
wrangler queues consumer remove <queue-name> <script-name>
```

- `queue-name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the queue to remove the consumer from.
- `script-name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the Workers script to remove as the consumer.

<Render file="wrangler-commands/global-flags" product="workers" />

### `purge`

Permanently delete all messages in a queue.

```txt
wrangler queues purge <queue-name>
```

- `queue-name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the queue from which messages should be deleted.

### `pause-delivery`

Pause message delivery from a Queue to consumers (including push consumers, and HTTP pull consumers)

```txt
wrangler queues pause-delivery <queue-name>
```

- `queue-name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the queue which delivery should be paused.

### `resume-delivery`

Resume delivery from a Queue to consumers (including push consumers, and HTTP pull consumers)

```txt
wrangler queues resume-delivery <queue-name>
```

- `queue-name` <Type text="string" /> <MetaInfo text="required" />
  - The name of the queue from which delivery should be resumed.

---

## `login`

Authorize Wrangler with your Cloudflare account using OAuth. Wrangler will attempt to automatically open your web browser to login with your Cloudflare account.

If you prefer to use API tokens for authentication, such as in headless or continuous integration environments, refer to [Running Wrangler in CI/CD](/workers/ci-cd/).

```txt
wrangler login [OPTIONS]
```

- `--scopes-list` <Type text="string" /> <MetaInfo text="optional" />
  - List all the available OAuth scopes with descriptions.
- `--scopes` <Type text="string" /> <MetaInfo text="optional" />
  - Allows to choose your set of OAuth scopes. The set of scopes must be entered in a whitespace-separated list,
    for example, `npx wrangler login --scopes account:read user:read`.
- `--callback-host` <Type text="string" /> <MetaInfo text="optional" />
  - Defaults to `localhost`. Sets the IP or hostname where Wrangler should listen for the OAuth callback.
- `--callback-port` <Type text="string" /> <MetaInfo text="optional" />
  - Defaults to `8976`. Sets the port where Wrangler should listen for the OAuth callback.

:::note

`wrangler login` uses all the available scopes by default if no flags are provided.
:::

<Render file="wrangler-commands/global-flags" product="workers" />

If Wrangler fails to open a browser, you can copy and paste the URL generated by `wrangler login` in your terminal into a browser and log in.

### Use `wrangler login` on a remote machine

If you are using Wrangler from a remote machine, but run the login flow from your local browser, you will receive the following error message after logging in:`This site can't be reached`.

To finish the login flow, run `wrangler login` and go through the login flow in the browser:

```sh
npx wrangler login
```

```sh output
 ⛅️ wrangler 2.1.6
-------------------
Attempting to login via OAuth...
Opening a link in your default browser: https://dash.cloudflare.com/oauth2/auth?xyz...
```

The browser login flow will redirect you to a `localhost` URL on your machine.

Leave the login flow active. Open a second terminal session. In that second terminal session, use `curl` or an equivalent request library on the remote machine to fetch this `localhost` URL. Copy and paste the `localhost` URL that was generated during the `wrangler login` flow and run:

```sh
curl <LOCALHOST_URL>
```

---

## `logout`

Remove Wrangler's authorization for accessing your account. This command will invalidate your current OAuth token.

```txt
wrangler logout
```

<Render file="wrangler-commands/global-flags" product="workers" />

If you are using `CLOUDFLARE_API_TOKEN` instead of OAuth, and you can logout by deleting your API token in the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/).
2. Go to **My Profile** > **API Tokens**.
3. Select the three-dot menu on your Wrangler token.
4. Select **Delete**.

---

## `whoami`

Retrieve your user information and test your authentication configuration.

```txt
wrangler whoami
```

<Render file="wrangler-commands/global-flags" product="workers" />

---

## `versions`

:::note
The minimum required wrangler version to use these commands is 3.40.0. For versions before 3.73.0, you will need to add the `--x-versions` flag.
:::

### `upload`

Upload a new [version](/workers/configuration/versions-and-deployments/#versions) of your Worker that is not deployed immediately.

```txt
wrangler versions upload [OPTIONS]
```

- `--tag` <Type text="string" /> <MetaInfo text="optional" />
  - Add a version tag. Accepts empty string.
- `--message` <Type text="string" /> <MetaInfo text="optional" />
  - Add a version message. Accepts empty string.
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).
- `--env` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific environment.
    <Render file="vite-environments" />

<Render file="wrangler-commands/global-flags" product="workers" />

### `deploy`

Deploy a previously created [version](/workers/configuration/versions-and-deployments/#versions) of your Worker all at once or create a [gradual deployment](/workers/configuration/versions-and-deployments/gradual-deployments/) to incrementally shift traffic to a new version by following an interactive prompt.

```txt
wrangler versions deploy [OPTIONS]
```

- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).

<Render file="wrangler-commands/global-flags" product="workers" />

:::note

The non-interactive version of this prompt is: `wrangler versions deploy version-id-1@percentage-1% version-id-2@percentage-2 -y`

For example:
`wrangler versions deploy 095f00a7-23a7-43b7-a227-e4c97cab5f22@10%   1a88955c-2fbd-4a72-9d9b-3ba1e59842f2@90% -y`

:::

### `list`

Retrieve details for the 10 most recent versions. Details include `Version ID`, `Created on`, `Author`, `Source`, and optionally, `Tag` or `Message`.

```txt
wrangler versions list [OPTIONS]
```

- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).

<Render file="wrangler-commands/global-flags" product="workers" />

### `secret put`

Create or replace a secret for a Worker. Creates a new [version](/workers/configuration/versions-and-deployments/#versions) with modified secrets without [deploying](/workers/configuration/versions-and-deployments/#deployments) the Worker.

```txt
wrangler versions secret put <KEY> [OPTIONS]
```

- `KEY` <Type text="string" /> <MetaInfo text="required" />
  - The variable name for this secret to be accessed in the Worker.
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).
- `--env` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific environment.

<Render file="wrangler-commands/global-flags" product="workers" />

### `secret delete`

Delete a secret for a Worker. Creates a new [version](/workers/configuration/versions-and-deployments/#versions) with modified secrets without [deploying](/workers/configuration/versions-and-deployments/#deployments) the Worker.

```txt
wrangler versions delete <KEY> [OPTIONS]
```

- `KEY` <Type text="string" /> <MetaInfo text="required" />
  - The variable name for this secret to be accessed in the Worker.
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).
- `--env` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific environment.

<Render file="wrangler-commands/global-flags" product="workers" />

### `secret bulk`

Upload multiple secrets for a Worker at once. Creates a new [version](/workers/configuration/versions-and-deployments/#versions) with modified secrets without [deploying](/workers/configuration/versions-and-deployments/#deployments) the Worker.

```txt
wrangler versions secret bulk <FILENAME> [OPTIONS]
```

- `FILENAME` <Type text="string" /> <MetaInfo text="optional" />
  - A file containing either [JSON](https://www.json.org/json-en.html) or the [.env](https://www.dotenv.org/docs/security/env) format
  - The JSON file containing key-value pairs to upload as secrets, in the form `{"SECRET_NAME": "secret value", ...}`.
  - The `.env` file containing key-value pairs to upload as secrets, in the form `SECRET_NAME=secret value`.
  - If omitted, Wrangler expects to receive input from `stdin` rather than a file.
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).
- `--env` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific environment.

<Render file="wrangler-commands/global-flags" product="workers" />

---

## `triggers`

:::note
The minimum required wrangler version to use these commands is 3.40.0. For versions before 3.73.0, you will need to add the `--x-versions` flag.
:::

### `deploy`

Apply changes to triggers ([Routes or domains](/workers/configuration/routing/) and [Cron Triggers](/workers/configuration/cron-triggers/)) when using [`wrangler versions upload`](/workers/wrangler/commands/#upload).

```txt
wrangler triggers deploy [OPTIONS]
```

- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).

<Render file="wrangler-commands/global-flags" product="workers" />

---

## `deployments`

[Deployments](/workers/configuration/versions-and-deployments/#deployments) track the version(s) of your Worker that are actively serving traffic.

### `list`

:::note
The minimum required wrangler version to use these commands is 3.40.0. For versions before 3.73.0, you will need to add the `--x-versions` flag.
:::

Retrieve details for the 10 most recent [deployments](/workers/configuration/versions-and-deployments/#deployments). Details include `Created on`, `Author`, `Source`, an optional `Message`, and metadata about the `Version(s)` in the deployment.

```txt
wrangler deployments list [OPTIONS]
```

- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).

<Render file="wrangler-commands/global-flags" product="workers" />

### `status`

Retrieve details for the most recent deployment. Details include `Created on`, `Author`, `Source`, an optional `Message`, and metadata about the `Version(s)` in the deployment.

```txt
wrangler deployments status
```

- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).

<Render file="wrangler-commands/global-flags" product="workers" />

## `rollback`

:::caution
A rollback will immediately create a new deployment with the specified version of your Worker and become the active deployment across all your deployed routes and domains. This change will not affect work in your local development environment.
:::

```txt
wrangler rollback [<VERSION_ID>] [OPTIONS]
```

- `VERSION_ID` <Type text="string" /> <MetaInfo text="optional" />
  - The ID of the version you wish to roll back to. If not supplied, the `rollback` command defaults to the version uploaded before the latest version.
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - Perform on a specific Worker rather than inheriting from the [Wrangler configuration file](/workers/wrangler/configuration/).
- `--message` <Type text="string" /> <MetaInfo text="optional" />
  - Add message for rollback. Accepts empty string. When specified, interactive prompts for rollback confirmation and message are skipped.

<Render file="wrangler-commands/global-flags" product="workers" />

---

## dispatch namespace

### `list`

List all dispatch namespaces.

```txt
wrangler dispatch-namespace list
```

<Render file="wrangler-commands/global-flags" product="workers" />

### `get`

Get information about a dispatch namespace.

```txt
wrangler dispatch-namespace get <NAME>
```

- `NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of the dispatch namespace to get details about.

<Render file="wrangler-commands/global-flags" product="workers" />

### `create`

Create a dispatch namespace.

```txt
wrangler dispatch-namespace create <NAME>
```

- `NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of the dispatch namespace to create.

<Render file="wrangler-commands/global-flags" product="workers" />

### `delete`

Delete a dispatch namespace.

```txt
wrangler dispatch-namespace get <NAME>
```

:::note

You must delete all user Workers in the dispatch namespace before it can be deleted.
:::

- `NAME` <Type text="string" /> <MetaInfo text="required" />
  - The name of the dispatch namespace to delete.

<Render file="wrangler-commands/global-flags" product="workers" />

### `rename`

Rename a dispatch namespace.

```txt
wrangler dispatch-namespace get <OLD_NAME> <NEW_NAME>
```

- `OLD_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The previous name of the dispatch namespace.
- `NEW_NAME` <Type text="string" /> <MetaInfo text="required" />
  - The new name of the dispatch namespace.

<Render file="wrangler-commands/global-flags" product="workers" />

---

## `mtls-certificate`

Manage client certificates used for mTLS connections in subrequests.

These certificates can be used in [`mtls_certificate` bindings](/workers/runtime-apis/bindings/mtls), which allow a Worker to present the certificate when establishing a connection with an origin that requires client authentication (mTLS).

### `upload`

Upload a client certificate.

```txt
wrangler mtls-certificate upload --cert <PATH> --key <PATH> [OPTIONS]
```

- `--cert` <Type text="string" /> <MetaInfo text="required" />
  - A path to the TLS certificate to upload. Certificate chains are supported.
- `--key` <Type text="string" /> <MetaInfo text="required" />
  - A path to the private key to upload.
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - The name assigned to the mTLS certificate at upload.

<Render file="wrangler-commands/global-flags" product="workers" />

The following is an example of using the `upload` command to upload an mTLS certificate.

```sh
npx wrangler mtls-certificate upload --cert cert.pem --key key.pem --name my-origin-cert
```

```sh output
Uploading mTLS Certificate my-origin-cert...
Success! Uploaded mTLS Certificate my-origin-cert
ID: 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d
Issuer: CN=my-secured-origin.com,OU=my-team,O=my-org,L=San Francisco,ST=California,C=US
Expires: 1/01/2025
```

You can then add this certificate as a [binding](/workers/runtime-apis/bindings/) in your [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
mtls_certificates = [
  { binding = "MY_CERT", certificate_id = "99f5fef1-6cc1-46b8-bd79-44a0d5082b8d" }
]
```

</WranglerConfig>

Note that the certificate and private keys must be in separate (typically `.pem`) files when uploading.

### `list`

List mTLS certificates associated with the current account ID.

```txt
wrangler mtls-certificate list
```

<Render file="wrangler-commands/global-flags" product="workers" />

The following is an example of using the `list` command to upload an mTLS certificate.

```sh
npx wrangler mtls-certificate list
```

```sh output
ID: 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d
Name: my-origin-cert
Issuer: CN=my-secured-origin.com,OU=my-team,O=my-org,L=San Francisco,ST=California,C=US
Created on: 1/01/2023
Expires: 1/01/2025

ID: c5d004d1-8312-402c-b8ed-6194328d5cbe
Issuer: CN=another-origin.com,OU=my-team,O=my-org,L=San Francisco,ST=California,C=US
Created on: 1/01/2023
Expires: 1/01/2025
```

### `delete`

Delete a client certificate.

```txt
wrangler mtls-certificate delete {--id <ID|--name <NAME>}
```

- `--id` <Type text="string" />
  - The ID of the mTLS certificate.
- `--name` <Type text="string" />
  - The name assigned to the mTLS certificate at upload.

<Render file="wrangler-commands/global-flags" product="workers" />

The following is an example of using the `delete` command to delete an mTLS certificate.

```sh
npx wrangler mtls-certificate delete --id 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d
```

```sh output
Are you sure you want to delete certificate 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d (my-origin-cert)? [y/n]
yes
Deleting certificate 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d...
Deleted certificate 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d successfully
```

---

## `cert`

Manage mTLS client certificates and Certificate Authority (CA) chain certificates used for secured connections.

These certificates can be used in Hyperdrive configurations, enabling them to present the certificate when connecting to an origin database that requires client authentication (mTLS) or a custom Certificate Authority (CA).

### `upload mtls-certificate`

Upload a client certificate.

```txt
wrangler cert upload mtls-certificate --cert <PATH> --key <PATH> [OPTIONS]
```

- `--cert` <Type text="string" /> <MetaInfo text="required" />
  - A path to the TLS certificate to upload. Certificate chains are supported.
- `--key` <Type text="string" /> <MetaInfo text="required" />
  - A path to the private key to upload.
- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - The name assigned to the mTLS certificate at upload.

<Render file="wrangler-commands/global-flags" product="workers" />

The following is an example of using the `upload` command to upload an mTLS certificate.

```sh
npx wrangler cert upload --cert cert.pem --key key.pem --name my-origin-cert
```

```sh output
Uploading mTLS Certificate my-origin-cert...
Success! Uploaded mTLS Certificate my-origin-cert
ID: 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d
Issuer: CN=my-secured-origin.com,OU=my-team,O=my-org,L=San Francisco,ST=California,C=US
Expires: 1/01/2025
```

Note that the certificate and private keys must be in separate (typically `.pem`) files when uploading.

### `upload certificate-authority`

Upload a client certificate.

```txt
wrangler cert upload certificate-authority --ca-cert <PATH> [OPTIONS]
```

- `--ca-cert` <Type text="string" /> <MetaInfo text="required" />

  - A path to the Certificate Authority (CA) chain certificate to upload.

- `--name` <Type text="string" /> <MetaInfo text="optional" />
  - The name assigned to the mTLS certificate at upload.

<Render file="wrangler-commands/global-flags" product="workers" />

The following is an example of using the `upload` command to upload an CA certificate.

```sh
npx wrangler cert upload certificate-authority --ca-cert server-ca-chain.pem --name SERVER_CA_CHAIN

```

```sh output
Uploading CA Certificate SERVER_CA_CHAIN...
Success! Uploaded CA Certificate SERVER_CA_CHAIN
ID: 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d
Issuer: CN=my-secured-origin.com,OU=my-team,O=my-org,L=San Francisco,ST=California,C=US
Expires: 1/01/2025
```

### `list`

List mTLS certificates associated with the current account ID. This will display both mTLS certificates and CA certificates.

```txt
wrangler cert list
```

<Render file="wrangler-commands/global-flags" product="workers" />

The following is an example of using the `list` command to upload an mTLS or CA certificate.

```sh
npx wrangler cert list
```

```sh output
ID: 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d
Name: my-origin-cert
Issuer: CN=my-secured-origin.com,OU=my-team,O=my-org,L=San Francisco,ST=California,C=US
Created on: 1/01/2023
Expires: 1/01/2025

ID: c5d004d1-8312-402c-b8ed-6194328d5cbe
Issuer: CN=another-origin.com,OU=my-team,O=my-org,L=San Francisco,ST=California,C=US
Created on: 1/01/2023
Expires: 1/01/2025
```

### `delete`

Delete a client certificate.

```txt
wrangler cert delete {--id <ID|--name <NAME>}
```

- `--id` <Type text="string" />
  - The ID of the mTLS or CA certificate.
- `--name` <Type text="string" />
  - The name assigned to the mTLS or CA certificate at upload.

<Render file="wrangler-commands/global-flags" product="workers" />

The following is an example of using the `delete` command to delete an mTLS or CA certificate.

```sh
npx wrangler cert delete --id 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d
```

```sh output
Are you sure you want to delete certificate 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d (my-origin-cert)? [y/n]
yes
Deleting certificate 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d...
Deleted certificate 99f5fef1-6cc1-46b8-bd79-44a0d5082b8d successfully
```

---

## `types`

Generate types based on your Worker configuration, including `Env` types based on your bindings, module rules, and [runtime types](/workers/languages/typescript/) based on the`compatibility_date` and `compatibility_flags` in your [config file](/workers/wrangler/configuration/).

```txt
wrangler types [<PATH>] [OPTIONS]
```

:::note

<Render file="wrangler-commands/runtime-types" product="workers" />

:::

- `PATH` <Type text="string" /> <MetaInfo text="(default: `./worker-configuration.d.ts`)" />
  - The path to where types for your Worker will be written.
  - The path must have a `d.ts` extension.
- `--env-interface` <Type text="string" /> <MetaInfo text="(default: `Env`)" />
  - The name of the interface to generate for the environment object.
  - Not valid if the Worker uses the Service Worker syntax.
- `--include-runtime` <Type text="boolean" /> <MetaInfo text="(default: true)" />
  - Whether to generate runtime types based on the`compatibility_date` and `compatibility_flags` in your [config file](/workers/wrangler/configuration/).
- `--include-env` <Type text="boolean" /> <MetaInfo text="(default: true)" />
  - Whether to generate `Env` types based on your Worker bindings.
- `--strict-vars` <Type text="boolean" /> <MetaInfo text="optional (default: true)" />
  - Control the types that Wrangler generates for `vars` bindings.
  - If `true`, (the default) Wrangler generates literal and union types for bindings (e.g. `myVar: 'my dev variable' | 'my prod variable'`).
  - If `false`, Wrangler generates generic types (e.g. `myVar: string`). This is useful when variables change frequently, especially when working across multiple environments.
- `--config`, `-c` <Type text="string[]" /> <MetaInfo text="optional" />
  - Path(s) to [Wrangler configuration file](/workers/wrangler/configuration/). If the Worker you are generating types for has service bindings or bindings to Durable Objects, you can also provide the paths to those configuration files so that the generated `Env` type will include RPC types. For example, given a Worker with a service binding, `wrangler types -c wrangler.toml -c ../bound-worker/wrangler.toml` will generate an `Env` type like this:
  ```ts
  interface Env {
  	SERVICE_BINDING: Service<import("../bound-worker/src/index").Entrypoint>;
  }
  ```
  - If your service binding targets a [`WorkerEntrypoint`](/workers/runtime-apis/bindings/service-bindings/rpc/) that is a default export, make sure you set `entrypoint: "default"` in your Wrangler config when you configure your service binding.

---

## `telemetry`

Cloudflare collects anonymous usage data to improve Wrangler. You can learn more about this in our [data policy](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md).

You can manage sharing of usage data at any time using these commands.

### `disable`

Disable telemetry collection for Wrangler.

```txt
wrangler telemetry disable
```

### `enable`

Enable telemetry collection for Wrangler.

```txt
wrangler telemetry enable
```

### `status`

Check whether telemetry collection is currently enabled. The return result is specific to the directory where you have run the command.

This will resolve the global status set by `wrangler telemetry disable / enable`, the environment variable [`WRANGLER_SEND_METRICS`](/workers/wrangler/system-environment-variables/#supported-environment-variables), and the [`send_metrics`](/workers/wrangler/configuration/#top-level-only-keys) key in the [Wrangler configuration file](/workers/wrangler/configuration/).

```txt
wrangler telemetry status
```

<Render file="wrangler-commands/global-flags" product="workers" />

---

## `check`

### `startup`

Generate a CPU profile of your Worker's startup phase.

After you run `wrangler check startup`, you can import the profile into Chrome DevTools or open it directly in VSCode to view a flamegraph of your Worker's startup phase. Additionally, when a Worker deployment fails with a startup time error Wrangler will automatically generate a CPU profile for easy investigation.

```sh
wrangler check startup
```

- `--args` <Type text="string" /> <MetaInfo text="optional" />
  - To customise the way `wrangler check startup` builds your Worker for analysis, provide the exact arguments you use when deploying your Worker with `wrangler deploy`, or your Pages project with `wrangler pages functions build`. For instance, if you deploy your Worker with `wrangler deploy --no-bundle`, you should use `wrangler check startup --args="--no-bundle"` to profile the startup phase.
- `--worker` <Type text="string" /> <MetaInfo text="optional" />
  - If you don't use Wrangler to deploy your Worker, you can use this argument to provide a Worker bundle to analyse. This should be a file path to a serialized multipart upload, with the exact same format as [the API expects](/api/resources/workers/subresources/scripts/methods/update/).
- `--pages` <Type text="boolean" /> <MetaInfo text="optional" />
  - If you don't use a Wrangler config file with your Pages project (i.e. a Wrangler config file containing `pages_build_output_dir`), use this flag to force `wrangler check startup` to treat your project as a Pages project.

<Render file="wrangler-commands/global-flags" product="workers" />

---

# Custom builds

URL: https://developers.cloudflare.com/workers/wrangler/custom-builds/

import { Render, Type, MetaInfo, WranglerConfig } from "~/components";

Custom builds are a way for you to customize how your code is compiled, before being processed by Wrangler.

:::note

Wrangler runs [esbuild](https://esbuild.github.io/) by default as part of the `dev` and `deploy` commands, and bundles your Worker project into a single Worker script. Refer to [Bundling](/workers/wrangler/bundling/).
:::

## Configure custom builds

Custom builds are configured by adding a `[build]` section in your [Wrangler configuration file](/workers/wrangler/configuration/), and using the following options for configuring your custom build.

- `command` <Type text="string" /> <MetaInfo text="optional" />

  - The command used to build your Worker. On Linux and macOS, the command is executed in the `sh` shell and the `cmd` shell for Windows. The `&&` and `||` shell operators may be used. This command will be run as part of `wrangler dev` and `npx wrangler deploy`.

- `cwd` <Type text="string" /> <MetaInfo text="optional" />

  - The directory in which the command is executed.

- `watch_dir` <Type text="string | string\[]" /> <MetaInfo text="optional" />

  - The directory to watch for changes while using `wrangler dev`. Defaults to the current working directory.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[build]
command = "npm run build"
cwd = "build_cwd"
watch_dir = "build_watch_dir"
```

</WranglerConfig>

---

# Configuration

URL: https://developers.cloudflare.com/workers/wrangler/configuration/

import { Render, Type, MetaInfo, WranglerConfig } from "~/components";
import { FileTree } from "@astrojs/starlight/components";

Wrangler optionally uses a configuration file to customize the development and deployment setup for a Worker.

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

The format of Wrangler's configuration file is exactly the same across both languages, only the syntax differs.

You can use one of the many available online converters to easily switch between the two.

Throughout this page and the rest of Cloudflare's documentation, configuration snippets are provided as both JSON and TOML.

:::

It is best practice to treat Wrangler's configuration file as the [source of truth](#source-of-truth) for configuring a Worker.

## Sample Wrangler configuration

<WranglerConfig>

```toml
# Top-level configuration
name = "my-worker"
main = "src/index.js"
compatibility_date = "2022-07-12"

workers_dev = false
route = { pattern = "example.org/*", zone_name = "example.org" }

kv_namespaces = [
  { binding = "<MY_NAMESPACE>", id = "<KV_ID>" }
]

[env.staging]
name = "my-worker-staging"
route = { pattern = "staging.example.org/*", zone_name = "example.org" }

kv_namespaces = [
  { binding = "<MY_NAMESPACE>", id = "<STAGING_KV_ID>" }
]
```

</WranglerConfig>

## Environments

You can define different configurations for a Worker using Wrangler [environments](/workers/wrangler/environments/).
There is a default (top-level) environment and you can create named environments that provide environment-specific configuration.

These are defined under `[env.<name>]` keys, such as `[env.staging]` which you can then preview or deploy with the `-e` / `--env` flag in the `wrangler` commands like `npx wrangler deploy --env staging`.

The majority of keys are inheritable, meaning that top-level configuration can be used in environments. [Bindings](/workers/runtime-apis/bindings/), such as `vars` or `kv_namespaces`, are not inheritable and need to be defined explicitly.

Further, there are a few keys that can _only_ appear at the top-level.

<Render file="vite-environments" />

## Top-level only keys

Top-level keys apply to the Worker as a whole (and therefore all environments). They cannot be defined within named environments.

- `keep_vars` <Type text="boolean" /> <MetaInfo text="optional" />

  - Whether Wrangler should keep variables configured in the dashboard on deploy. Refer to [source of truth](#source-of-truth).

- `migrations` <Type text="object[]" /> <MetaInfo text="optional" />

  - When making changes to your Durable Object classes, you must perform a migration. Refer to [Durable Object migrations](/durable-objects/reference/durable-objects-migrations/).

- `send_metrics` <Type text="boolean" /> <MetaInfo text="optional" />

  - Whether Wrangler should send usage data to Cloudflare for this project. Defaults to `true`. You can learn more about this in our [data policy](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md).

- `site` <Type text="object" /> <MetaInfo text="optional deprecated" />

  - See the [Workers Sites](#workers-sites) section below for more information. Cloudflare Pages and Workers Assets is preferred over this approach.
  - This is not supported by the [Cloudflare Vite plugin](/workers/vite-plugin/).

## Inheritable keys

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

:::note

At a minimum, the `name`, `main` and `compatibility_date` keys are required to deploy a Worker.
:::

- `name` <Type text="string" /> <MetaInfo text="required" />

  - The name of your Worker. Alphanumeric characters (`a`,`b`,`c`, etc.) and dashes (`-`) only. Do not use underscores (`_`).

- `main` <Type text="string" /> <MetaInfo text="required" />

  - The path to the entrypoint of your Worker that will be executed. For example: `./src/index.ts`.

- `compatibility_date` <Type text="string" /> <MetaInfo text="required" />

  - A date in the form `yyyy-mm-dd`, which will be used to determine which version of the Workers runtime is used. Refer to [Compatibility dates](/workers/configuration/compatibility-dates/).

- `account_id` <Type text="string" /> <MetaInfo text="optional" />

  - This is the ID of the account associated with your zone. You might have more than one account, so make sure to use the ID of the account associated with the zone/route you provide, if you provide one. It can also be specified through the `CLOUDFLARE_ACCOUNT_ID` environment variable.

- `compatibility_flags` <Type text="string[]" /> <MetaInfo text="optional" />

  - A list of flags that enable features from upcoming features of the Workers runtime, usually used together with `compatibility_date`. Refer to [compatibility dates](/workers/configuration/compatibility-dates/).

- `workers_dev` <Type text="boolean" /> <MetaInfo text="optional" />

  - Enables use of `*.workers.dev` subdomain to deploy your Worker. If you have a Worker that is only for `scheduled` events, you can set this to `false`. Defaults to `true`. Refer to [types of routes](#types-of-routes).

- `preview_urls` <Type text="boolean" /> <MetaInfo text="optional" />

  - Enables use of Preview URLs to test your Worker. Defaults to `true`. Refer to [Preview URLs](/workers/configuration/previews).

- `route` <Type text="Route" /> <MetaInfo text="optional" />

  - A route that your Worker should be deployed to. Only one of `routes` or `route` is required. Refer to [types of routes](#types-of-routes).

- `routes` <Type text="Route[]" /> <MetaInfo text="optional" />

  - An array of routes that your Worker should be deployed to. Only one of `routes` or `route` is required. Refer to [types of routes](#types-of-routes).

- `tsconfig` <Type text="string" /> <MetaInfo text="optional" />

  - Path to a custom `tsconfig`.
  - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/).

- `triggers` <Type text="object" /> <MetaInfo text="optional" />

  - Cron definitions to trigger a Worker's `scheduled` function. Refer to [triggers](#triggers).

- `rules` <Type text="Rule" /> <MetaInfo text="optional" />

  - An ordered list of rules that define which modules to import, and what type to import them as. You will need to specify rules to use `Text`, `Data` and `CompiledWasm` modules, or when you wish to have a `.js` file be treated as an `ESModule` instead of `CommonJS`.
  - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/).

- `build` <Type text="Build" /> <MetaInfo text="optional" />

  - Configures a custom build step to be run by Wrangler when building your Worker. Refer to [Custom builds](#custom-builds).
  - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/).

- `no_bundle` <Type text="boolean" /> <MetaInfo text="optional" />

  - Skip internal build steps and directly deploy your Worker script. You must have a plain JavaScript Worker with no dependencies.
  - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/).

- `find_additional_modules` <Type text="boolean" /> <MetaInfo text="optional" />

  - If true then Wrangler will traverse the file tree below `base_dir`.
    Any files that match `rules` will be included in the deployed Worker.
    Defaults to true if `no_bundle` is true, otherwise false.
    Can only be used with Module format Workers (not Service Worker format).
  - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/).

- `base_dir` <Type text="string" /> <MetaInfo text="optional" />

  - The directory in which module "rules" should be evaluated when including additional files (via `find_additional_modules`) into a Worker deployment. Defaults to the directory containing the `main` entry point of the Worker if not specified.
  - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/).

- `preserve_file_names` <Type text="boolean" /> <MetaInfo text="optional" />

  - Determines whether Wrangler will preserve the file names of additional modules bundled with the Worker.
    The default is to prepend filenames with a content hash.
    For example, `34de60b44167af5c5a709e62a4e20c4f18c9e3b6-favicon.ico`.
  - Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/).

- `minify` <Type text="boolean" /> <MetaInfo text="optional" />

  - Minify the Worker script before uploading.
  - If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), `minify` is replaced by Vite's [`build.minify`](https://vite.dev/config/build-options.html#build-minify).

- `keep_names` <Type text="boolean" /> <MetaInfo text="optional" />

  - Wrangler uses esbuild to process the Worker code for development and deployment. This option allows
    you to specify whether esbuild should apply its [keepNames](https://esbuild.github.io/api/#keep-names) logic to the code or not. Defaults to `true`.

- `logpush` <Type text="boolean" /> <MetaInfo text="optional" />

  - Enables Workers Trace Events Logpush for a Worker. Any scripts with this property will automatically get picked up by the Workers Logpush job configured for your account. Defaults to `false`. Refer to [Workers Logpush](/workers/observability/logs/logpush/).

- `limits` <Type text="Limits" /> <MetaInfo text="optional" />

  - Configures limits to be imposed on execution at runtime. Refer to [Limits](#limits).

* `observability` <Type text="object" /> <MetaInfo text="optional" />

  - Configures automatic observability settings for telemetry data emitted from your Worker. Refer to [Observability](#observability).

* `assets` <Type text="Assets" /> <MetaInfo text="optional" />

  - Configures static assets that will be served. Refer to [Assets](/workers/static-assets/binding/) for more details.

* `migrations` <Type text="object"/> <MetaInfo text="optional"/>
  - Maps a Durable Object from a class name to a runtime state. This communicates changes to the Durable Object (creation / deletion / rename / transfer) to the Workers runtime and provides the runtime with instructions on how to deal with those changes. Refer to [Durable Objects migrations](/durable-objects/reference/durable-objects-migrations/#durable-object-migrations-in-wranglertoml).

## Non-inheritable keys

Non-inheritable keys are configurable at the top-level, but cannot be inherited by environments and must be specified for each environment.

- `define` <Type text="Record<string, string>" /> <MetaInfo text="optional" />

  - A map of values to substitute when deploying your Worker.
  - If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), `define` is replaced by Vite's [`define`](https://vite.dev/config/shared-options.html#define).

- `vars` <Type text="object" /> <MetaInfo text="optional" />

  - A map of environment variables to set when deploying your Worker. Refer to [Environment variables](/workers/configuration/environment-variables/).

- `durable_objects` <Type text="object" /> <MetaInfo text="optional" />

  - A list of Durable Objects that your Worker should be bound to. Refer to [Durable Objects](#durable-objects).

- `kv_namespaces` <Type text="object" /> <MetaInfo text="optional" />

  - A list of KV namespaces that your Worker should be bound to. Refer to [KV namespaces](#kv-namespaces).

- `r2_buckets` <Type text="object" /> <MetaInfo text="optional" />

  - A list of R2 buckets that your Worker should be bound to. Refer to [R2 buckets](#r2-buckets).

- `vectorize` <Type text="object" /> <MetaInfo text="optional" />

  - A list of Vectorize indexes that your Worker should be bound to. Refer to [Vectorize indexes](#vectorize-indexes).

- `services` <Type text="object" /> <MetaInfo text="optional" />

  - A list of service bindings that your Worker should be bound to. Refer to [service bindings](#service-bindings).

- `tail_consumers` <Type text="object" /> <MetaInfo text="optional" />

  - A list of the Tail Workers your Worker sends data to. Refer to [Tail Workers](/workers/observability/logs/tail-workers/).

## Types of routes

There are three types of [routes](/workers/configuration/routing/): [Custom Domains](/workers/configuration/routing/custom-domains/), [routes](/workers/configuration/routing/routes/), and [`workers.dev`](/workers/configuration/routing/workers-dev/).

### Custom Domains

[Custom Domains](/workers/configuration/routing/custom-domains/) allow you to connect your Worker to a domain or subdomain, without having to make changes to your DNS settings or perform any certificate management.

- `pattern` <Type text="string" /> <MetaInfo text="required" />

  - The pattern that your Worker should be run on, for example, `"example.com"`.

- `custom_domain` <Type text="boolean" /> <MetaInfo text="optional" />

  - Whether the Worker should be on a Custom Domain as opposed to a route. Defaults to `false`.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
routes = [
	{ pattern = "shop.example.com", custom_domain = true }
]
```

</WranglerConfig>

### Routes

[Routes](/workers/configuration/routing/routes/) allow users to map a URL pattern to a Worker. A route can be configured as a zone ID route, a zone name route, or a simple route.

#### Zone ID route

- `pattern` <Type text="string" /> <MetaInfo text="required" />

  - The pattern that your Worker can be run on, for example,`"example.com/*"`.

- `zone_id` <Type text="string" /> <MetaInfo text="required" />

  - The ID of the zone that your `pattern` is associated with. Refer to [Find zone and account IDs](/fundamentals/account/find-account-and-zone-ids/).

Example:

<WranglerConfig>

```toml title="wrangler.toml"
routes = [
	{ pattern = "subdomain.example.com/*", zone_id = "<YOUR_ZONE_ID>" }
]
```

</WranglerConfig>

#### Zone name route

- `pattern` <Type text="string" /> <MetaInfo text="required" />

  - The pattern that your Worker should be run on, for example, `"example.com/*"`.

- `zone_name` <Type text="string" /> <MetaInfo text="required" />

  - The name of the zone that your `pattern` is associated with. If you are using API tokens, this will require the `Account` scope.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
routes = [
	{ pattern = "subdomain.example.com/*", zone_name = "example.com" }
]
```

</WranglerConfig>

#### Simple route

This is a simple route that only requires a pattern.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
route = "example.com/*"
```

</WranglerConfig>

### `workers.dev`

Cloudflare Workers accounts come with a `workers.dev` subdomain that is configurable in the Cloudflare dashboard.

- `workers_dev` <Type text="boolean" /> <MetaInfo text="optional" />

  - Whether the Worker runs on a custom `workers.dev` account subdomain. Defaults to `true`.

<WranglerConfig>

```toml title="wrangler.toml"
workers_dev = false
```

</WranglerConfig>

## Triggers

Triggers allow you to define the `cron` expression to invoke your Worker's `scheduled` function. Refer to [Supported cron expressions](/workers/configuration/cron-triggers/#supported-cron-expressions).

- `crons` <Type text="string[]" /> <MetaInfo text="required" />

  - An array of `cron` expressions.
  - To disable a Cron Trigger, set `crons = []`. Commenting out the `crons` key will not disable a Cron Trigger.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[triggers]
crons = ["* * * * *"]
```

</WranglerConfig>

## Observability

The [Observability](/workers/observability/logs/workers-logs) setting allows you to automatically ingest, store, filter, and analyze logging data emitted from Cloudflare Workers directly from your Cloudflare Worker's dashboard.

- `enabled` <Type text="boolean" /> <MetaInfo text="required" />

  - When set to `true` on a Worker, logs for the Worker are persisted. Defaults to `true` for all new Workers.

- `head_sampling_rate` <Type text="number" /> <MetaInfo text="optional" />
  - A number between 0 and 1, where 0 indicates zero out of one hundred requests are logged, and 1 indicates every request is logged. If `head_sampling_rate` is unspecified, it is configured to a default value of 1 (100%). Read more about [head-based sampling](/workers/observability/logs/workers-logs/#head-based-sampling).

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[observability]
enabled = true
head_sampling_rate = 0.1 # 10% of requests are logged
```

</WranglerConfig>

## Custom builds

:::note
Not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/).
:::

You can configure a custom build step that will be run before your Worker is deployed. Refer to [Custom builds](/workers/wrangler/custom-builds/).

- `command` <Type text="string" /> <MetaInfo text="optional" />

  - The command used to build your Worker. On Linux and macOS, the command is executed in the `sh` shell and the `cmd` shell for Windows. The `&&` and `||` shell operators may be used.

- `cwd` <Type text="string" /> <MetaInfo text="optional" />

  - The directory in which the command is executed.

- `watch_dir` <Type text="string | string[]" /> <MetaInfo text="optional" />

  - The directory to watch for changes while using `wrangler dev`. Defaults to the current working directory.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[build]
command = "npm run build"
cwd = "build_cwd"
watch_dir = "build_watch_dir"
```

</WranglerConfig>

## Limits

You can impose limits on your Worker's behavior at runtime. Limits are only supported for the [Standard Usage Model](/workers/platform/pricing/#example-pricing-standard-usage-model).
Limits are only enforced when deployed to Cloudflare's network, not in local development. The CPU limit
can be set to a maximum of 300,000 milliseconds (5 minutes).

<Render file="isolate-cpu-flexibility" /> <br />

- `cpu_ms` <Type text="number" /> <MetaInfo text="optional" />

  - The maximum CPU time allowed per invocation, in milliseconds.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[limits]
cpu_ms = 100
```

</WranglerConfig>

## Bindings

### Browser Rendering

The [Workers Browser Rendering API](/browser-rendering/) allows developers to programmatically control and interact with a headless browser instance and create automation flows for their applications and products.

A [browser binding](/workers/runtime-apis/bindings/) will provide your Worker with an authenticated endpoint to interact with a dedicated Chromium browser instance.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name used to refer to the browser binding. The value (string) you set will be used to reference this headless browser in your Worker. The binding must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). For example, `binding = "HEAD_LESS"` or `binding = "simulatedBrowser"` would both be valid names for the binding.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[browser]
binding = "<BINDING_NAME>"
```

</WranglerConfig>

### D1 databases

[D1](/d1/) is Cloudflare's serverless SQL database. A Worker can query a D1 database (or databases) by creating a [binding](/workers/runtime-apis/bindings/) to each database for [D1 Workers Binding API](/d1/worker-api/).

To bind D1 databases to your Worker, assign an array of the below object to the `[[d1_databases]]` key.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name used to refer to the D1 database. The value (string) you set will be used to reference this database in your Worker. The binding must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). For example, `binding = "MY_DB"` or `binding = "productionDB"` would both be valid names for the binding.

- `database_name` <Type text="string" /> <MetaInfo text="required" />

  - The name of the database. This is a human-readable name that allows you to distinguish between different databases, and is set when you first create the database.

- `database_id` <Type text="string" /> <MetaInfo text="required" />

  - The ID of the database. The database ID is available when you first use `wrangler d1 create` or when you call `wrangler d1 list`, and uniquely identifies your database.

- `preview_database_id` <Type text="string" /> <MetaInfo text="optional" />

  - The preview ID of this D1 database. If provided, `wrangler dev` uses this ID. Otherwise, it uses `database_id`. This option is required when using `wrangler dev --remote`.

- `migrations_dir` <Type text="string" /> <MetaInfo text="optional" />

  - The migration directory containing the migration files. By default, `wrangler d1 migrations create` creates a folder named `migrations`. You can use `migrations_dir` to specify a different folder containing the migration files (for example, if you have a mono-repo setup, and want to use a single D1 instance across your apps/packages).
  - For more information, refer to [D1 Wrangler `migrations` commands](/workers/wrangler/commands/#migrations-create) and [D1 migrations](/d1/reference/migrations/).

:::note

When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production database. Refer to [Local development and testing](/workers/development-testing/) for more details.

:::

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[[d1_databases]]
binding = "<BINDING_NAME>"
database_name = "<DATABASE_NAME>"
database_id = "<DATABASE_ID>"
```

</WranglerConfig>

### Dispatch namespace bindings (Workers for Platforms)

Dispatch namespace bindings allow for communication between a [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) and a [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace). Dispatch namespace bindings are used in [Workers for Platforms](/cloudflare-for-platforms/workers-for-platforms/). Workers for Platforms helps you deploy serverless functions programmatically on behalf of your customers.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name. The value (string) you set will be used to reference this database in your Worker. The binding must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). For example, `binding = "MY_NAMESPACE"` or `binding = "productionNamespace"` would both be valid names for the binding.

- `namespace` <Type text="string" /> <MetaInfo text="required" />

  - The name of the [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace).

- `outbound` <Type text="object" /> <MetaInfo text="optional" />

  - `service` <Type text="string" /> <MetaInfo text="required" /> The name of the [outbound Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/) to bind to.
  - `parameters` array optional A list of parameters to pass data from your [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) to the [outbound Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/).

<WranglerConfig>

```toml title="wrangler.toml"
[[dispatch_namespaces]]
binding = "<BINDING_NAME>"
namespace = "<NAMESPACE_NAME>"
outbound = {service = "<WORKER_NAME>", parameters = ["params_object"]}

```

</WranglerConfig>

### Durable Objects

[Durable Objects](/durable-objects/) provide low-latency coordination and consistent storage for the Workers platform.

To bind Durable Objects to your Worker, assign an array of the below object to the `durable_objects.bindings` key.

- `name` <Type text="string" /> <MetaInfo text="required" />

  - The name of the binding used to refer to the Durable Object.

- `class_name` <Type text="string" /> <MetaInfo text="required" />

  - The exported class name of the Durable Object.

- `script_name` <Type text="string" /> <MetaInfo text="optional" />

  - The name of the Worker where the Durable Object is defined, if it is external to this Worker. This option can be used both in local and remote development. In local development, you must run the external Worker in a separate process (via `wrangler dev`). In remote development, the appropriate remote binding must be used.

- `environment` <Type text="string" /> <MetaInfo text="optional" />

  - The environment of the `script_name` to bind to.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[[durable_objects.bindings]]
name = "<BINDING_NAME>"
class_name = "<CLASS_NAME>"

```

</WranglerConfig>

#### Migrations

When making changes to your Durable Object classes, you must perform a migration. Refer to [Durable Object migrations](/durable-objects/reference/durable-objects-migrations/).

- `tag` <Type text="string" /> <MetaInfo text="required" />

  - A unique identifier for this migration.

- `new_sqlite_classes` <Type text="string[]" /> <MetaInfo text="optional" />

  - The new Durable Objects being defined.

- `renamed_classes` <Type text="{from: string, to: string}[]" /> <MetaInfo text="optional" />

  - The Durable Objects being renamed.

- `deleted_classes` <Type text="string[]" /> <MetaInfo text="optional" />

  - The Durable Objects being removed.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[[migrations]]
tag = "v1" # Should be unique for each entry
new_sqlite_classes = ["DurableObjectExample"] # Array of new classes

[[migrations]]
tag = "v2"
renamed_classes = [{from = "DurableObjectExample", to = "UpdatedName" }] # Array of rename directives
deleted_classes = ["DeprecatedClass"] # Array of deleted class names
```

</WranglerConfig>

### Email bindings

<Render
	file="send-emails-workers-intro"
	product="email-routing"
	params={{
		one: "Then, assign an array to the object (send_email) with the type of email binding you need.",
	}}
/>

- `name` <Type text="string" /> <MetaInfo text="required" />

  - The binding name.

- `destination_address` <Type text="string" /> <MetaInfo text="optional" />

  - The [chosen email address](/email-routing/email-workers/send-email-workers/#types-of-bindings) you send emails to.

- `allowed_destination_addresses` <Type text="string[]" /> <MetaInfo text="optional" />

  - The [allowlist of email addresses](/email-routing/email-workers/send-email-workers/#types-of-bindings) you send emails to.

<Render file="types-bindings" product="email-routing" />

### Environment variables

[Environment variables](/workers/configuration/environment-variables/) are a type of binding that allow you to attach text strings or JSON values to your Worker.

Example:

<Render file="envvar-example" />

### Hyperdrive

[Hyperdrive](/hyperdrive/) bindings allow you to interact with and query any Postgres database from within a Worker.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name.

- `id` <Type text="string" /> <MetaInfo text="required" />

  - The ID of the Hyperdrive configuration.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
# required for database drivers to function
compatibility_flags = ["nodejs_compat_v2"]

[[hyperdrive]]
binding = "<BINDING_NAME>"
id = "<ID>"
```

</WranglerConfig>

### Images

[Cloudflare Images](/images/transform-images/transform-via-workers/) lets you make transformation requests to optimize, resize, and manipulate images stored in remote sources.

To bind Images to your Worker, assign an array of the below object to the `images` key.

`binding` (required). The name of the binding used to refer to the Images API.

<WranglerConfig>

```jsonc
{
	"images": {
		"binding": "IMAGES", // i.e. available in your Worker on env.IMAGES
	},
}
```

</WranglerConfig>

### KV namespaces

[Workers KV](/kv/api/) is a global, low-latency, key-value data store. It stores data in a small number of centralized data centers, then caches that data in Cloudflare’s data centers after access.

To bind KV namespaces to your Worker, assign an array of the below object to the `kv_namespaces` key.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name used to refer to the KV namespace.

- `id` <Type text="string" /> <MetaInfo text="required" />

  - The ID of the KV namespace.

- `preview_id` <Type text="string" /> <MetaInfo text="optional" />

  - The preview ID of this KV namespace. This option is **required** when using `wrangler dev --remote` to develop against remote resources. If developing locally (without `--remote`), this is an optional field. `wrangler dev` will use this ID for the KV namespace. Otherwise, `wrangler dev` will use `id`.

:::note

When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production namespace. Refer to [Local development and testing](/workers/development-testing/) for more details.

:::

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[[kv_namespaces]]
binding = "<BINDING_NAME1>"
id = "<NAMESPACE_ID1>"

[[kv_namespaces]]
binding = "<BINDING_NAME2>"
id = "<NAMESPACE_ID2>"
```

</WranglerConfig>

### Queues

[Queues](/queues/) is Cloudflare's global message queueing service, providing [guaranteed delivery](/queues/reference/delivery-guarantees/) and [message batching](/queues/configuration/batching-retries/). To interact with a queue with Workers, you need a producer Worker to send messages to the queue and a consumer Worker to pull batches of messages out of the Queue. A single Worker can produce to and consume from multiple Queues.

To bind Queues to your producer Worker, assign an array of the below object to the `[[queues.producers]]` key.

- `queue` <Type text="string" /> <MetaInfo text="required" />

  - The name of the queue, used on the Cloudflare dashboard.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name used to refer to the queue in your Worker. The binding must be [a valid JavaScript variable name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variables). For example, `binding = "MY_QUEUE"` or `binding = "productionQueue"` would both be valid names for the binding.

- `delivery_delay` <Type text="number" /> <MetaInfo text="optional" />

  - The number of seconds to [delay messages sent to a queue](/queues/configuration/batching-retries/#delay-messages) for by default. This can be overridden on a per-message or per-batch basis.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[[queues.producers]]
  binding = "<BINDING_NAME>"
  queue = "<QUEUE_NAME>"
  delivery_delay = 60 # Delay messages by 60 seconds before they are delivered to a consumer
```

</WranglerConfig>

To bind Queues to your consumer Worker, assign an array of the below object to the `[[queues.consumers]]` key.

- `queue` <Type text="string" /> <MetaInfo text="required" />

  - The name of the queue, used on the Cloudflare dashboard.

- `max_batch_size` <Type text="number" /> <MetaInfo text="optional" />

  - The maximum number of messages allowed in each batch.

- `max_batch_timeout` <Type text="number" /> <MetaInfo text="optional" />

  - The maximum number of seconds to wait for messages to fill a batch before the batch is sent to the consumer Worker.

- `max_retries` <Type text="number" /> <MetaInfo text="optional" />

  - The maximum number of retries for a message, if it fails or [`retryAll()`](/queues/configuration/javascript-apis/#messagebatch) is invoked.

- `dead_letter_queue` <Type text="string" /> <MetaInfo text="optional" />

  - The name of another queue to send a message if it fails processing at least `max_retries` times.
  - If a `dead_letter_queue` is not defined, messages that repeatedly fail processing will be discarded.
  - If there is no queue with the specified name, it will be created automatically.

- `max_concurrency` <Type text="number" /> <MetaInfo text="optional" />

  - The maximum number of concurrent consumers allowed to run at once. Leaving this unset will mean that the number of invocations will scale to the [currently supported maximum](/queues/platform/limits/).
  - Refer to [Consumer concurrency](/queues/configuration/consumer-concurrency/) for more information on how consumers autoscale, particularly when messages are retried.

- `retry_delay` <Type text="number" /> <MetaInfo text="optional" />

  - The number of seconds to [delay retried messages](/queues/configuration/batching-retries/#delay-messages) for by default, before they are re-delivered to the consumer. This can be overridden on a per-message or per-batch basis [when retrying messages](/queues/configuration/batching-retries/#explicit-acknowledgement-and-retries).

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[[queues.consumers]]
  queue = "my-queue"
  max_batch_size = 10
  max_batch_timeout = 30
  max_retries = 10
  dead_letter_queue = "my-queue-dlq"
  max_concurrency = 5
  retry_delay = 120 # Delay retried messages by 2 minutes before re-attempting delivery
```

</WranglerConfig>

### R2 buckets

[Cloudflare R2 Storage](/r2) allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.

To bind R2 buckets to your Worker, assign an array of the below object to the `r2_buckets` key.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name used to refer to the R2 bucket.

- `bucket_name` <Type text="string" /> <MetaInfo text="required" />

  - The name of this R2 bucket.

- `jurisdiction` <Type text="string" /> <MetaInfo text="optional" />

  - The jurisdiction where this R2 bucket is located, if a jurisdiction has been specified. Refer to [Jurisdictional Restrictions](/r2/reference/data-location/#jurisdictional-restrictions).

- `preview_bucket_name` <Type text="string" /> <MetaInfo text="optional" />

  - The preview name of this R2 bucket. If provided, `wrangler dev` will use this name for the R2 bucket. Otherwise, it will use `bucket_name`. This option is required when using `wrangler dev --remote`.

:::note

When using Wrangler in the default local development mode, files will be written to local storage instead of the preview or production bucket. Refer to [Local development and testing](/workers/development-testing/) for more details.

:::

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[[r2_buckets]]
binding = "<BINDING_NAME1>"
bucket_name = "<BUCKET_NAME1>"

[[r2_buckets]]
binding = "<BINDING_NAME2>"
bucket_name = "<BUCKET_NAME2>"
```

</WranglerConfig>

### Vectorize indexes

A [Vectorize index](/vectorize/) allows you to insert and query vector embeddings for semantic search, classification and other vector search use-cases.

To bind Vectorize indexes to your Worker, assign an array of the below object to the `vectorize` key.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name used to refer to the bound index from your Worker code.

- `index_name` <Type text="string" /> <MetaInfo text="required" />

  - The name of the index to bind.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[[vectorize]]
binding = "<BINDING_NAME>"
index_name = "<INDEX_NAME>"
```

</WranglerConfig>

### Service bindings

A service binding allows you to send HTTP requests to another Worker without those requests going over the Internet. The request immediately invokes the downstream Worker, reducing latency as compared to a request to a third-party service. Refer to [About Service Bindings](/workers/runtime-apis/bindings/service-bindings/).

To bind other Workers to your Worker, assign an array of the below object to the `services` key.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name used to refer to the bound Worker.

- `service` <Type text="string" /> <MetaInfo text="required" />

  - The name of the Worker.
  - To bind to a Worker in a specific [environment](/workers/wrangler/environments), you need to append the environment name to the Worker name. This should be in the format `<worker-name>-<environment-name>`. For example, to bind to a Worker called `worker-name` in its `staging` environment, `service` should be set to `worker-name-staging`.

- `entrypoint` <Type text="string" /> <MetaInfo text="optional" />

  - The name of the [entrypoint](/workers/runtime-apis/bindings/service-bindings/rpc/#named-entrypoints) to bind to. If you do not specify an entrypoint, the default export of the Worker will be used.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[[services]]
binding = "<BINDING_NAME>"
service = "<WORKER_NAME>"
entrypoint = "<ENTRYPOINT_NAME>"
```

</WranglerConfig>

### Static assets

Refer to [Assets](#assets).

### Analytics Engine Datasets

[Workers Analytics Engine](/analytics/analytics-engine/) provides analytics, observability and data logging from Workers. Write data points to your Worker binding then query the data using the [SQL API](/analytics/analytics-engine/sql-api/).

To bind Analytics Engine datasets to your Worker, assign an array of the below object to the `analytics_engine_datasets` key.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name used to refer to the dataset.

- `dataset` <Type text="string" /> <MetaInfo text="optional" />

  - The dataset name to write to. This will default to the same name as the binding if it is not supplied.

Example:

<WranglerConfig>

```toml
[[analytics_engine_datasets]]
binding = "<BINDING_NAME>"
dataset = "<DATASET_NAME>"
```

</WranglerConfig>

### mTLS Certificates

To communicate with origins that require client authentication, a Worker can present a certificate for mTLS in subrequests. Wrangler provides the `mtls-certificate` [command](/workers/wrangler/commands#mtls-certificate) to upload and manage these certificates.

To create a [binding](/workers/runtime-apis/bindings/) to an mTLS certificate for your Worker, assign an array of objects with the following shape to the `mtls_certificates` key.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name used to refer to the certificate.

- `certificate_id` <Type text="string" /> <MetaInfo text="required" />

  - The ID of the certificate. Wrangler displays this via the `mtls-certificate upload` and `mtls-certificate list` commands.

Example of a Wrangler configuration file that includes an mTLS certificate binding:

<WranglerConfig>

```toml title="wrangler.toml"
[[mtls_certificates]]
binding = "<BINDING_NAME1>"
certificate_id = "<CERTIFICATE_ID1>"

[[mtls_certificates]]
binding = "<BINDING_NAME2>"
certificate_id = "<CERTIFICATE_ID2>"
```

</WranglerConfig>

mTLS certificate bindings can then be used at runtime to communicate with secured origins via their [`fetch` method](/workers/runtime-apis/bindings/mtls).

### Workers AI

[Workers AI](/workers-ai/) allows you to run machine learning models, on the Cloudflare network, from your own code –
whether that be from Workers, Pages, or anywhere via REST API.

<Render file="ai-local-usage-charges" product="workers" />

Unlike other bindings, this binding is limited to one AI binding per Worker project.

- `binding` <Type text="string" /> <MetaInfo text="required" />

  - The binding name.

Example:

<WranglerConfig>

```toml
[ai]
binding = "AI" # available in your Worker code on `env.AI`
```

</WranglerConfig>

## Assets

[Static assets](/workers/static-assets/) allows developers to run front-end websites on Workers. You can configure the directory of assets, an optional runtime binding, and routing configuration options.

You can only configure one collection of assets per Worker.

The following options are available under the `assets` key.

- `directory` <Type text="string" /> <MetaInfo text="optional" />

  - Folder of static assets to be served.
  - Not required if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), which will automatically point to the client build output.

- `binding` <Type text="string" /> <MetaInfo text="optional" />

  - The binding name used to refer to the assets. Optional, and only useful when a Worker script is set with `main`.

- `run_worker_first` <Type text="boolean | string[]" /> <MetaInfo text="optional, defaults to false" />

  - Controls whether static assets are fetched directly, or a Worker script is invoked. Can be a boolean (`true`/`false`) or an array of route pattern strings with support for glob patterns (`*`) and exception patterns (`!` prefix). Patterns must begin with `/` or `!/`. Learn more about fetching assets when using [`run_worker_first`](/workers/static-assets/routing/worker-script/#run-your-worker-script-first).

- `html_handling`: <Type text={'"auto-trailing-slash" | "force-trailing-slash" | "drop-trailing-slash" | "none"'} /> <MetaInfo text={'optional, defaults to "auto-trailing-slash"'} />

  - Determines the redirects and rewrites of requests for HTML content. Learn more about the various options in [assets routing](/workers/static-assets/routing/advanced/html-handling/).

- `not_found_handling`: <Type text={'"single-page-application" | "404-page" | "none"'} /> <MetaInfo text={'optional, defaults to "none"'} />

  - Determines the handling of requests that do not map to an asset. Learn more about the various options for [routing behavior](/workers/static-assets/#routing-behavior).

Example:

<WranglerConfig>

```toml title="wrangler.toml"
assets = { directory = "./public", binding = "ASSETS", html_handling = "force-trailing-slash", not_found_handling = "404-page" }
```

</WranglerConfig>

You can also configure `run_worker_first` with an array of route patterns:

<WranglerConfig>

```toml title="wrangler.toml"
[assets]
directory = "./public"
binding = "ASSETS"
run_worker_first = [
  "/api/*",        # API calls go to Worker first
  "!/api/docs/*"   # EXCEPTION: For /api/docs/*, try static assets first
]
```

</WranglerConfig>

## Containers

You can define [Containers](/containers) to run alongside your Worker using the `containers` field.

:::note
You must also define a Durable Object to communicate with your Container via Workers. This Durable Object's
class name must match the `class_name` value in container configuration.
:::

The following options are available:

- `image` <Type text="string" /> <MetaInfo text="required" />

  - The image to use for the container. This can either be a local path, in which case `wrangler deploy` will
    build and push the image. Or it can be an image URL. Currently, only the Cloudflare Registry is a supported registry.

- `class_name` <Type text="string" /> <MetaInfo text="required" />

  - The corresponding Durable Object class name. This will make this Durable Object a container-enabled Durable Object
    and allow each instance to control a container. See [Durable Object Container Methods](/durable-objects/api/container/) for details.

- `instance_type` <Type text="string" /> <MetaInfo text="optional" />

  - The instance type of the container. This determines the amount of memory, CPU, and disk given to the container
    instance. The current options are `"dev"`, `"basic"`, and `"standard"`. The default is `"dev"`. For more information,
    the see [instance types documentation](/containers/platform-details#instance-types).

- `max_instances` <Type text="string" /> <MetaInfo text="optional" />

  - The maxiumum number of concurrent container instances you want to run. If you have more Durable Objects that
    request to run a container than this number, the container request will error. You may have more Durable Objects
    than this number over a longer time period, but you may not have more concurrently.

- `name` <Type text="string" /> <MetaInfo text="optional" />

  - The name of your container. Used as an identifier. This will default to a comination of your Worker name, the class
    name, and your environment.

- `image_build_context` <Type text="string" /> <MetaInfo text="optional" />

  - The build context of the application, by default it is the directory of `image`.

- `image_vars` <Type text="Record<string, string>" /> <MetaInfo text="optional" />

  - Environment variables to set in the container. These will be used during the build phase and will be defaults
    when running the container, though they can be overridden at runtime when starting the container.

<WranglerConfig>

```toml title="wrangler.toml"
[[containers]]
class_name = "MyContainer"
image = "./Dockerfile"
max_instances = 10
instance_type = "basic" # Optional, defaults to "dev"
image_vars = { FOO = "BAR" }

[[durable_objects.bindings]]
name = "MY_CONTAINER"
class_name = "MyContainer"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["MyContainer"]
```

</WranglerConfig>

## Bundling

:::note
Wrangler bundling is not applicable if you're using the [Cloudflare Vite plugin](/workers/vite-plugin/).
:::

Wrangler can operate in two modes: the default bundling mode and `--no-bundle` mode.
In bundling mode, Wrangler will traverse all the imports of your code and generate a single JavaScript "entry-point" file.
Imported source code is "inlined/bundled" into this entry-point file.

It is also possible to include additional modules into your Worker, which are uploaded alongside the entry-point.
You specify which additional modules should be included into your Worker using the `rules` key, making these modules available to be imported when your Worker is invoked.
The `rules` key will be an array of the below object.

- `type` <Type text="string" /> <MetaInfo text="required" />

  - The type of module. Must be one of: `ESModule`, `CommonJS`, `CompiledWasm`, `Text` or `Data`.

- `globs` <Type text="string[]" /> <MetaInfo text="required" />

  - An array of glob rules (for example, `["**/*.md"]`). Refer to [glob](https://man7.org/linux/man-pages/man7/glob.7.html).

- `fallthrough` <Type text="boolean" /> <MetaInfo text="optional" />

  - When set to `true` on a rule, this allows you to have multiple rules for the same `Type`.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
rules = [
  { type = "Text", globs = ["**/*.md"], fallthrough = true }
]
```

</WranglerConfig>

### Importing modules within a Worker

You can import and refer to these modules within your Worker, like so:

```js title="index.js" {1}
import markdown from "./example.md";

export default {
	async fetch() {
		return new Response(markdown);
	},
};
```

### Find additional modules

Normally Wrangler will only include additional modules that are statically imported in your source code as in the example above.
By setting `find_additional_modules` to `true` in your configuration file, Wrangler will traverse the file tree below `base_dir`.
Any files that match `rules` will also be included as unbundled, external modules in the deployed Worker.
`base_dir` defaults to the directory containing your `main` entrypoint.

See https://developers.cloudflare.com/workers/wrangler/bundling/ for more details and examples.

## Local development settings

:::note
If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), you should use Vite's [server options](https://vite.dev/config/server-options.html) instead.
:::

You can configure various aspects of local development, such as the local protocol or port.

- `ip` <Type text="string" /> <MetaInfo text="optional" />

* IP address for the local dev server to listen on. Defaults to `localhost`.

- `port` <Type text="number" /> <MetaInfo text="optional" />

* Port for the local dev server to listen on. Defaults to `8787`.

- `local_protocol` <Type text="string" /> <MetaInfo text="optional" />

  - Protocol that local dev server listens to requests on. Defaults to `http`.

- `upstream_protocol` <Type text="string" /> <MetaInfo text="optional" />

  - Protocol that the local dev server forwards requests on. Defaults to `https`.

- `host` <Type text="string" /> <MetaInfo text="optional" />

  - Host to forward requests to, defaults to the host of the first `route` of the Worker.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[dev]
ip = "192.168.1.1"
port = 8080
local_protocol = "http"
```

</WranglerConfig>

### Secrets

[Secrets](/workers/configuration/secrets/) are a type of binding that allow you to [attach encrypted text values](/workers/wrangler/commands/#secret) to your Worker.

<Render file="secrets-in-dev" />

## Module Aliasing

:::note
If you're using the [Cloudflare Vite plugin](/workers/vite-plugin/), `alias` is replaced Vite's [`resolve.alias`](https://vite.dev/config/shared-options.html#resolve-alias).
:::

You can configure Wrangler to replace all calls to import a particular package with a module of your choice, by configuring the `alias` field:

<WranglerConfig>

```toml title="wrangler.toml"
[alias]
"foo" = "./replacement-module-filepath"
```

</WranglerConfig>

```js title="replacement-module-filepath.js"
export const bar = "baz";
```

With the configuration above, any calls to `import` or `require()` the module `foo` will be aliased to point to your replacement module:

```js
import { bar } from "foo";

console.log(bar); // returns "baz"
```

### Example: Aliasing dependencies from NPM

You can use module aliasing to provide an implementation of an NPM package that does not work on Workers — even if you only rely on that NPM package indirectly, as a dependency of one of your Worker's dependencies.

For example, some NPM packages depend on [`node-fetch`](https://www.npmjs.com/package/node-fetch), a package that provided a polyfill of the [`fetch()` API](/workers/runtime-apis/fetch/), before it was built into Node.js.

`node-fetch` isn't needed in Workers, because the `fetch()` API is provided by the Workers runtime. And `node-fetch` doesn't work on Workers, because it relies on currently unsupported Node.js APIs from the `http`/`https` modules.

You can alias all imports of `node-fetch` to instead point directly to the `fetch()` API that is built into the Workers runtime:

<WranglerConfig>

```toml title="wrangler.toml"
[alias]
"node-fetch" = "./fetch-nolyfill"
```

</WranglerConfig>

```js title="./fetch-nolyfill"
export default fetch;
```

### Example: Aliasing Node.js APIs

You can use module aliasing to provide your own polyfill implementation of a Node.js API that is not yet available in the Workers runtime.

For example, let's say the NPM package you rely on calls [`fs.readFile`](https://nodejs.org/api/fs.html#fsreadfilepath-options-callback). You can alias the fs module by adding the following to your Worker's Wrangler configuration file:

<WranglerConfig>

```toml title="wrangler.toml"
[alias]
"fs" = "./fs-polyfill"
```

</WranglerConfig>

```js title="./fs-polyfill"
export function readFile() {
	// ...
}
```

In many cases, this allows you to work provide just enough of an API to make a dependency work. You can learn more about Cloudflare Workers' support for Node.js APIs on the [Cloudflare Workers Node.js API documentation page](/workers/runtime-apis/nodejs/).

## Source maps

[Source maps](/workers/observability/source-maps/) translate compiled and minified code back to the original code that you wrote. Source maps are combined with the stack trace returned by the JavaScript runtime to present you with a stack trace.

- `upload_source_maps` <Type text="boolean" />

  - When `upload_source_maps` is set to `true`, Wrangler will automatically generate and upload source map files when you run [`wrangler deploy`](/workers/wrangler/commands/#deploy) or [`wrangler versions deploy`](/workers/wrangler/commands/#deploy-2).

Example:

<WranglerConfig>

```toml title="wrangler.toml"
upload_source_maps = true

```

</WranglerConfig>

## Workers Sites

<Render file="workers_sites" />

[Workers Sites](/workers/configuration/sites/) allows you to host static websites, or dynamic websites using frameworks like Vue or React, on Workers.

- `bucket` <Type text="string" /> <MetaInfo text="required" />

  - The directory containing your static assets. It must be a path relative to your Wrangler configuration file.

- `include` <Type text="string[]" /> <MetaInfo text="optional" />

  - An exclusive list of `.gitignore`-style patterns that match file or directory names from your bucket location. Only matched items will be uploaded.

- `exclude` <Type text="string[]" /> <MetaInfo text="optional" />

  - A list of `.gitignore`-style patterns that match files or directories in your bucket that should be excluded from uploads.

Example:

<WranglerConfig>

```toml title="wrangler.toml"
[site]
bucket = "./public"
include = ["upload_dir"]
exclude = ["ignore_dir"]
```

</WranglerConfig>

## Proxy support

Corporate networks will often have proxies on their networks and this can sometimes cause connectivity issues. To configure Wrangler with the appropriate proxy details, [add the following environmental variables](/workers/configuration/environment-variables/):

- `https_proxy`
- `HTTPS_PROXY`
- `http_proxy`
- `HTTP_PROXY`

To configure this on macOS, add `HTTP_PROXY=http://<YOUR_PROXY_HOST>:<YOUR_PROXY_PORT>` before your Wrangler commands.

Example:

```sh
$ HTTP_PROXY=http://localhost:8080 wrangler dev
```

If your IT team has configured your computer's proxy settings, be aware that the first non-empty environment variable in this list will be used when Wrangler makes outgoing requests.

For example, if both `https_proxy` and `http_proxy` are set, Wrangler will only use `https_proxy` for outgoing requests.

## Source of truth

We recommend treating your Wrangler configuration file as the source of truth for your Worker configuration, and to avoid making changes to your Worker via the Cloudflare dashboard if you are using Wrangler.

If you need to make changes to your Worker from the Cloudflare dashboard, the dashboard will generate a TOML snippet for you to copy into your Wrangler configuration file, which will help ensure your Wrangler configuration file is always up to date.

If you change your environment variables in the Cloudflare dashboard, Wrangler will override them the next time you deploy. If you want to disable this behavior, add `keep_vars = true` to your Wrangler configuration file.

If you change your routes in the dashboard, Wrangler will override them in the next deploy with the routes you have set in your Wrangler configuration file. To manage routes via the Cloudflare dashboard only, remove any route and routes keys from your Wrangler configuration file. Then add `workers_dev = false` to your Wrangler configuration file. For more information, refer to [Deprecations](/workers/wrangler/deprecations/#other-deprecated-behavior).

Wrangler will not delete your secrets (encrypted environment variables) unless you run `wrangler secret delete <key>`.

## Generated Wrangler configuration

:::note

This section describes a feature that can be implemented by frameworks and other build tools that are integrating with Wrangler.

It is unlikely that an application developer will need to use this feature, but it is documented here to help you understand when Wrangler is using a generated configuration rather than the original, user's configuration.

For example, when using the [Cloudflare Vite plugin](/workers/vite-plugin/), an output Worker configuration file is generated as part of the build. This is then used for preview and deployment.

:::

Some framework tools, or custom pre-build processes, generate a modified Wrangler configuration to be used to deploy the Worker code.
In this case, the tool may also create a special `.wrangler/deploy/config.json` file that redirects Wrangler to use the generated configuration rather than the original, user's configuration.

Wrangler uses this generated configuration only for the following deploy and dev related commands:

- `wrangler deploy`
- `wrangler dev`
- `wrangler versions upload`
- `wrangler versions deploy`
- `wrangler pages deploy`
- `wrangler pages functions build`

When running these commands, Wrangler looks up the directory tree from the current working directory for a file at the path `.wrangler/deploy/config.json`.
This file must contain only a single JSON object of the form:

```json
{ "configPath": "../../path/to/wrangler.jsonc" }
```

When this `config.json` file exists, Wrangler will follow the `configPath` (relative to the `.wrangler/deploy/config.json` file) to find the generated Wrangler configuration file to load and use in the current command.
Wrangler will display messaging to the user to indicate that the configuration has been redirected to a different file than the user's configuration file.

### Custom build tool example

A common example of using a redirected configuration is where a custom build tool, or framework, wants to modify the user's configuration to be used when deploying, by generating a new configuration in a `dist` directory.

- First, the user writes code that uses Cloudflare Workers resources, configured via a user's Wrangler configuration file.

<WranglerConfig>

```toml title="wrangler.toml"
name = "my-worker"
main = "src/index.ts"
[[kv_namespaces]]
binding = "<BINDING_NAME1>"
id = "<NAMESPACE_ID1>"
```

</WranglerConfig>

Note that this configuration points `main` at the user's code entry-point.

- Then, the user runs a custom build, which might read the user's Wrangler configuration file to find the source code entry-point:

  ```bash
  > my-tool build
  ```

- This `my-tool` generates a `dist` directory that contains both compiled code and a new generated deployment configuration file.
  It also creates a `.wrangler/deploy/config.json` file that redirects Wrangler to the new, generated deployment configuration file:

  <FileTree>

  - dist
    - index.js
    - wrangler.jsonc
  - .wrangler
    - deploy
      - config.json

  </FileTree>

  The generated `dist/wrangler.jsonc` might contain:

  ```json
  {
  	"name": "my-worker",
  	"main": "./index.js",
  	"kv_namespaces": [{ "binding": "<BINDING_NAME1>", "id": "<NAMESPACE_ID1>" }]
  }
  ```

  Note that, now, the `main` property points to the generated code entry-point.

  And the `.wrangler/deploy/config.json` contains the path to the generated configuration file:

  ```json
  {
  	"configPath": "../../dist/wrangler.jsonc"
  }
  ```

---

# Deprecations

URL: https://developers.cloudflare.com/workers/wrangler/deprecations/

Review the difference between Wrangler versions, specifically deprecations and breaking changes.

## Wrangler v4

### Workers Sites

Usage of [Workers Sites](/workers/wrangler/configuration/#workers-sites) is deprecated. Instead, we recommend migrating to [Workers Static Assets](/workers/static-assets/). Support for using Workers Sites with Wrangler will be removed in a future version of Wrangler.

### Service environments

Usage of [Service Environments](https://blog.cloudflare.com/introducing-worker-services/#services-have-environments), enabled via the `legacy_env` property in Wrangler config, is deprecated. Instead, we recommend migrating to [Wrangler Environments](/workers/wrangler/configuration/#environments). Support for using Service Environments with Wrangler will be removed in a future version of Wrangler.

## Wrangler v3

### Deprecated commands

The following commands are deprecated in Wrangler as of Wrangler v3. These commands will be fully removed in a future version of Wrangler.

#### `generate`

The `wrangler generate` command is deprecated, but still active in v3. `wrangler generate` will be fully removed in v4.

Use `npm create cloudflare@latest` for new Workers and Pages projects.

#### `publish`

The `wrangler publish` command is deprecated, but still active in v3. `wrangler publish` will be fully removed in v4.

Use [`npx wrangler deploy`](/workers/wrangler/commands/#deploy) to deploy Workers.

#### `pages publish`

The `wrangler pages publish` command is deprecated, but still active in v3. `wrangler pages publish` will be fully removed in v4.

Use [`wrangler pages deploy`](/workers/wrangler/commands/#deploy-1) to deploy Pages.

#### `version`

Instead, use `wrangler --version` to check the current version of Wrangler.

### Deprecated options

#### `--experimental-local`

`wrangler dev` in v3 is local by default so this option is no longer necessary.

#### `--local`

`wrangler dev` in v3 is local by default so this option is no longer necessary.

#### `--persist`

`wrangler dev` automatically persists data by default so this option is no longer necessary.

#### `-- <command>`, `--proxy`, and `--script-path` in `wrangler pages dev`

These options prevent `wrangler pages dev` from being able to accurately emulate production's behavior for serving static assets and have therefore been deprecated. Instead of relying on Wrangler to proxy through to some other upstream dev server, you can emulate a more accurate behavior by building your static assets to a directory and pointing Wrangler to that directory with `wrangler pages dev <directory>`.

#### `--legacy-assets` and the `legacy_assets` config file property

We recommend you [migrate to Workers assets](https://developers.cloudflare.com/workers/static-assets/)

#### `--node-compat` and the `node_compat` config file property

Instead, use the [`nodejs_compat` compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs). This includes the functionality from legacy `node_compat` polyfills and natively implemented Node.js APIs.

#### The `usage_model` config file property

This no longer has any effect, after the [rollout of Workers Standard Pricing](https://blog.cloudflare.com/workers-pricing-scale-to-zero/).

## Wrangler v2

Wrangler v2 introduces new fields for configuration and new features for developing and deploying a Worker, while deprecating some redundant fields.

* `wrangler.toml` is no longer mandatory.
* `dev` and `publish` accept CLI arguments.
* `tail` can be run on arbitrary Worker names.
* `init` creates a project boilerplate.
* JSON bindings for `vars`.
* Local mode for `wrangler dev`.
* Module system (for both modules and service worker format Workers).
* DevTools.
* TypeScript support.
* Sharing development environment on the Internet.
* Wider platform compatibility.
* Developer hotkeys.
* Better configuration validation.

The following video describes some of the major changes in Wrangler v2, and shows you how Wrangler v2 can help speed up your workflow.

<div style="position: relative; padding-top: 56.25%;"><iframe src="https://iframe.videodelivery.net/6ce3c7bd51288e1e8439f50ad63eda1d?poster=https%3A%2F%2Fcloudflarestream.com%2F6ce3c7bd51288e1e8439f50ad63eda1d%2Fthumbnails%2Fthumbnail.jpg%3Ftime%3D%26height%3D600" style="border: none; position: absolute; top: 0; left: 0; height: 100%; width: 100%;" allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;" allowfullscreen="true"></iframe></div>

### Common deprecations

Refer to the following list for common fields that are no longer required.

* `type` is no longer required. Wrangler will infer the correct project type automatically.
* `zone_id` is no longer required. It can be deduced from the routes directly.
* `build.upload.format` is no longer used. The format is now inferred automatically from the code.
* `build.upload.main` and `build.upload.dir` are no longer required. Use the top level `main` field, which now serves as the entry-point for the Worker.
* `site.entry-point` is no longer required. The entry point should be specified through the `main` field.
* `webpack_config` and `webpack` properties are no longer supported. Refer to [Migrate webpack projects from Wrangler version 1](/workers/wrangler/migration/v1-to-v2/eject-webpack/).
  Here are the Wrangler v1 commands that are no longer supported:
* `wrangler preview` - Use the `wrangler dev` command, for running your worker in your local environment.
* `wrangler generate` - If you want to use a starter template, clone its GitHub repository and manually initialize it.
* `wrangler route` - Routes are defined in the [Wrangler configuration file](/workers/wrangler/configuration/).
* `wrangler report` - If you find a bug, report it at [Wrangler issues](https://github.com/cloudflare/workers-sdk/issues/new/choose).
* `wrangler build` - If you wish to access the output from bundling your Worker, use `wrangler publish --outdir=path/to/output`.

#### New fields

These are new fields that can be added to your [Wrangler configuration file](/workers/wrangler/configuration/).

* **`main`**: `string`, optional

  The `main` field is used to specify an entry point to the Worker. It may be in the established service worker format, or the newer, preferred modules format. An entry point is now explicitly required, and can be configured either via the `main` field, or passed directly as a command line, for example, `wrangler dev index.js`. This field replaces the legacy `build.upload.main` field (which only applied to modules format Workers).

* **`rules`**: `array`, optional

  The `rules` field is an array of mappings between module types and file patterns. It instructs Wrangler to interpret specific files differently than JavaScript. For example, this is useful for reading text-like content as text files, or compiled WASM as ready to instantiate and execute. These rules can apply to Workers of both the established service worker format, and the newer modules format. This field replaces the legacy `build.upload.rules` field (which only applied to modules format Workers).

{/* <!-- - **`legacy_env`**: _boolean_, optional. default: `true`

  The `legacy_env` field toggles how environments are handled by `wrangler`.

  - When `legacy_env` is `true`, it uses the legacy-style environments, where each environment is treated as a separate Worker in the dashboard, and environment names are appended to the `name` when published.
  - When `legacy_env` is `false`, it uses the newer service environments, where scripts for a given Worker are grouped under the same script name in the Cloudflare Workers dashboard, and environments are subdomains for a given published script (when `workers_dev = true`).
    Read more at (ref:)[] --> */}

{/* <!-- - **`services`**: TODO

- **`node-compat`**: TODO

- **`public`**: TODO --> */}

#### Non-mandatory fields

A few configuration fields which were previously required, are now optional in particular situations. They can either be inferred, or added as an optimization. No fields are required anymore when starting with Wrangler v2, and you can gradually add configuration as the need arises.

* **`name`**: `string`

  The `name` configuration field is now not required for `wrangler dev`, or any of the `wrangler kv:*` commands. Further, it can also be passed as a command line argument as `--name <name>`. It is still required for `wrangler publish`.

* **`account_id`**: `string`

  The `account_id` field is not required for any of the commands. Any relevant commands will check if you are logged in, and if not, will prompt you to log in. Once logged in, it will use your account ID and will not prompt you again until your login session expires. If you have multiple account IDs, you will be presented with a list of accounts to choose from.

  You can still configure `account_id` in your Wrangler file, or as an environment variable `CLOUDFLARE_ACCOUNT_ID`. This makes startup faster and bypasses the list of choices if you have multiple IDs. The `CLOUDFLARE_API_TOKEN` environment variable is also useful for situations where it is not possible to login interactively. To learn more, visit [Running in CI/CD](/workers/ci-cd/external-cicd/).

* **`workers_dev`** `boolean`, default: `true` when no routes are present

  The `workers_dev` field is used to indicate that the Worker should be published to a `*.workers.dev` subdomain. For example, for a Worker named `my-worker` and a previously configured `*.workers.dev` subdomain `username`, the Worker will get published to `my-worker.username.workers.dev.com`. This field is not mandatory, and defaults to `true` when `route` or `routes` are not configured. When routes are present, it defaults to `false`. If you want to neither publish it to a `*.workers.dev` subdomain nor any routes, set `workers_dev` to `false`. This useful when you are publishing a Worker as a standalone service that can only be accessed from another Worker with (`services`).

#### Deprecated fields (non-breaking)

A few configuration fields are deprecated, but their presence is not a breaking change yet. It is recommended to read the warning messages and follow the instructions to migrate to the new configuration. They will be removed and stop working in a future version.

* **`zone_id`**: `string`, deprecated

  The `zone_id` field is deprecated and will be removed in a future release. It is now inferred from `route`/`routes`, and optionally from `dev.host` when using `wrangler dev`. This also makes it simpler to deploy a single Worker to multiple domains.

* **`build.upload`**: `object`, deprecated

  The `build.upload` field is deprecated and will be removed in a future release. Its usage results in a warning with suggestions on rewriting the configuration file to remove the warnings.

  * `build.upload.main`/`build.upload.dir` are replaced by the `main` fields and are applicable to both service worker format and modules format Workers.
  * `build.upload.rules` is replaced by the `rules` field and is applicable to both service worker format and modules format Workers.
  * `build.upload.format` is no longer specified and is automatically inferred by `wrangler`.

#### Deprecated fields (breaking)

A few configuration fields are deprecated and will not work as expected anymore. It is recommended to read the error messages and follow the instructions to migrate to the new configuration.

* **`site.entry-point`**: `string`, deprecated

  The `site.entry-point` configuration was used to specify an entry point for Workers with a `[site]` configuration. This has been replaced by the top-level `main` field.

* **`type`**: `rust` | `javascript` | `webpack`, deprecated

  The `type` configuration was used to specify the type of Worker. It has since been made redundant and is now inferred from usage. If you were using `type = "webpack"` (and the optional `webpack_config` field), you should read the [webpack migration guide](/workers/wrangler/migration/v1-to-v2/eject-webpack/) to modify your project and use a custom build instead.

### Deprecated commands

The following commands are deprecated in Wrangler as of Wrangler v2.

#### `build`

The `wrangler build` command is no longer available for building the Worker.

The equivalent functionality can be achieved by `wrangler publish --dry-run --outdir=path/to/build`.

#### `config`

The `wrangler config` command is no longer available for authenticating via an API token.

Use `wrangler login` / `wrangler logout` to manage OAuth authentication, or provide an API token via the `CLOUDFLARE_API_TOKEN` environment variable.

#### `preview`

The `wrangler preview` command is no longer available for creating a temporary preview instance of the Worker.

Try using `wrangler dev` to try out a worker during development.

#### subdomain

The `wrangler subdomain` command is no longer available for creating a `workers.dev` subdomain.

Create the `workers.dev` subdomain in **Workers & Pages** > select your Worker > Your subdomain > **Change**.

#### route

The `wrangler route` command is no longer available to configure a route for a Worker.

Routes are specified in the [Wrangler configuration file](/workers/wrangler/configuration/).

### Other deprecated behavior

* Cloudflare dashboard-defined routes will not be added alongside Wrangler-defined routes. Wrangler-defined routes are the `route` or `routes` key in your `wrangler.toml`. If both are defined, only routes defined in `wrangler.toml` will be valid. To manage routes via the Cloudflare dashboard only, remove any `route` and `routes` keys from and add `workers_dev = false` to your Wrangler file.

* Wrangler will no longer use `index.js` in the directory where `wrangler dev` is called as the entry point to a Worker. Use the `main` configuration field, or explicitly pass it as a command line argument, for example: `wrangler dev index.js`.

* Wrangler will no longer assume that bare specifiers are file names if they are not represented as a path. For example, in a folder like so:

  ```
  project
  ├── index.js
  └── some-dependency.js
  ```

  where the content of `index.js` is:

  ```js
  import SomeDependency from "some-dependency.js";

  addEventListener("fetch", (event) => {
    // ...
  });
  ```

  Wrangler v1 would resolve `import SomeDependency from "some-dependency.js";` to the file `some-dependency.js`. This will also work in Wrangler v2, but will also log a deprecation warning. In the future, this will break with an error. Instead, you should rewrite the import to specify that it is a relative path, like so:

  ```diff
  - import SomeDependency from "some-dependency.js";
  + import SomeDependency from "./some-dependency.js";
  ```

### Wrangler v1 and v2 comparison tables

#### Commands

| Command     | v1 | v2 | Notes                                          |
| ----------- | -- | -- | ---------------------------------------------- |
| `publish`   | ✅  | ✅  |                                                |
| `dev`       | ✅  | ✅  |                                                |
| `preview`   | ✅  | ❌  | Removed, use `dev` instead.                    |
| `init`      | ✅  | ✅  |                                                |
| `generate`  | ✅  | ❌  | Removed, use `git clone` instead.              |
| `build`     | ✅  | ❌  | Removed, invoke your own build script instead. |
| `secret`    | ✅  | ✅  |                                                |
| `route`     | ✅  | ❌  | Removed, use `publish` instead.                |
| `tail`      | ✅  | ✅  |                                                |
| `kv`        | ✅  | ✅  |                                                |
| `r2`        | 🚧 | ✅  | Introduced in Wrangler v1.19.8.                |
| `pages`     | ❌  | ✅  |                                                |
| `config`    | ✅  | ❓  |                                                |
| `login`     | ✅  | ✅  |                                                |
| `logout`    | ✅  | ✅  |                                                |
| `whoami`    | ✅  | ✅  |                                                |
| `subdomain` | ✅  | ❓  |                                                |
| `report`    | ✅  | ❌  | Removed, error reports are made interactively. |

#### Configuration

| Property              | v1 | v2 | Notes                                                                                                                                            |
| --------------------- | -- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type = "webpack"`    | ✅  | ❌  | Removed, refer to [this guide](/workers/wrangler/migration/v1-to-v2/eject-webpack/) to migrate. |
| `type = "rust"`       | ✅  | ❌  | Removed, use [`workers-rs`](https://github.com/cloudflare/workers-rs) instead.                                                                   |
| `type = "javascript"` | ✅  | 🚧 | No longer required, can be omitted.                                                                                                              |

#### Features

| Feature    | v1 | v2 | Notes                                                                                                                                                                                                 |
| ---------- | -- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| TypeScript | ❌  | ✅  | You can give wrangler a TypeScript file, and it will automatically transpile it to JavaScript using [`esbuild`](https://github.com/evanw/esbuild) under-the-hood.                                     |
| Local mode | ❌  | ✅  | `wrangler dev --local` will run your Worker on your local machine instead of on our network. This is powered by [Miniflare](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare/). |

---

# Wrangler

URL: https://developers.cloudflare.com/workers/wrangler/

import { DirectoryListing } from "~/components";

Wrangler, the Cloudflare Developer Platform command-line interface (CLI), allows you to manage Worker projects.

<DirectoryListing descriptions />

---

# Install/Update Wrangler

URL: https://developers.cloudflare.com/workers/wrangler/install-and-update/

import { Render, PackageManagers } from "~/components";

Wrangler is a command-line tool for building with Cloudflare developer products.

## Install Wrangler

To install [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler), ensure you have [Node.js](https://nodejs.org/en/) and [npm](https://docs.npmjs.com/getting-started) installed, preferably using a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm). Using a version manager helps avoid permission issues and allows you to change Node.js versions.

<details>
<summary>Wrangler System Requirements</summary>

We support running the Wrangler CLI with the [Current, Active, and Maintenance](https://nodejs.org/en/about/previous-releases) versions of Node.js. Your Worker will always be executed in `workerd`, the open source Cloudflare Workers runtime.

Wrangler is only supported on macOS 13.5+, Windows 11, and Linux distros that support glib 2.35. This follows [`workerd`'s OS support policy](https://github.com/cloudflare/workerd?tab=readme-ov-file#running-workerd).

</details>

Wrangler is installed locally into each of your projects. This allows you and your team to use the same Wrangler version, control Wrangler versions for each project, and roll back to an earlier version of Wrangler, if needed.

To install Wrangler within your Worker project, run:

<PackageManagers pkg="wrangler@latest" dev />

Since Cloudflare recommends installing Wrangler locally in your project (rather than globally), the way to run Wrangler will depend on your specific setup and package manager. Refer to [How to run Wrangler commands](/workers/wrangler/commands/#how-to-run-wrangler-commands) for more information.

:::caution

If Wrangler is not installed, running `npx wrangler` will use the latest version of Wrangler.

:::

## Check your Wrangler version

To check your Wrangler version, run:

```sh
npx wrangler --version
// or
npx wrangler version
// or
npx wrangler -v
```

## Update Wrangler

To update the version of Wrangler used in your project, run:

<PackageManagers pkg="wrangler@latest" dev />

## Related resources

- [Commands](/workers/wrangler/commands/) - A detailed list of the commands that Wrangler supports.
- [Configuration](/workers/wrangler/configuration/) - Learn more about Wrangler's configuration file.

---

# Environments

URL: https://developers.cloudflare.com/workers/wrangler/environments/

import { WranglerConfig, Render, Steps } from "~/components";

Wrangler allows you to use environments to create different configurations for the same Worker application. Environments are configured in the Worker's [Wrangler configuration file](/workers/wrangler/configuration/).

When you create an environment, Cloudflare effectively creates a new Worker with the name `<top-level-name>-<environment-name>`. For example, a Worker project named `my-worker` with an environment `dev` would deploy as a Worker named `my-worker-dev`.

Review the following environments flow:

<Steps>
1. Create a Worker, named `my-worker` for example.
2. Create an environment, for example `dev`, in the Worker's [Wrangler configuration file](/workers/wrangler/configuration/), by adding a `[env.<ENV_NAME>]` section.

    <WranglerConfig>

    ```json
    {
    	"name": "my-worker",
    	"env": {
    		"<ENV_NAME>": {
    			// environment-specific configuration goes here
    		}
    	}
    }
    ```
    </WranglerConfig>

3.  You can configure the `dev` environment with different values to the top-level environment. Refer [here](/workers/wrangler/configuration/#environments) for how different options are inherited - or not inherited - between environments.
    For example, to set a different route for a Worker in the `dev` environment:

    <WranglerConfig>

    ```toml
    name = "your-worker"
    route = "example.com"

    [env.dev]
    route = "dev.example.com"
    ```

    </WranglerConfig>

4.  Environments are used with the `--env` or `-e` flag on Wrangler commands. For example, you can develop the Worker in the `dev` environment by running `npx wrangler dev -e=dev`, and deploy it with `npx wrangler deploy -e=dev`.

        <Render file="vite-environments" />

</Steps>

## Non-inheritable keys and environments

[Non-inheritable keys](/workers/wrangler/configuration/#non-inheritable-keys) are configurable at the top-level, but cannot be inherited by environments and must be specified for each environment.

For example, [bindings](/workers/runtime-apis/bindings/) and [environment variables](/workers/configuration/environment-variables/) are non-inheritable, and must be specified per [environment](/workers/wrangler/environments/) in your [Wrangler configuration file](/workers/wrangler/configuration/).

Review the following example Wrangler file:

<WranglerConfig>

```toml
name = "my-worker"

vars = { API_HOST = "example.com" }

kv_namespaces = [
  { binding = "<BINDING_NAME>", id = "<KV_NAMESPACE_ID_DEV>" }
]

[env.production]

vars = { API_HOST = "production.example.com" }

kv_namespaces = [
  { binding = "<BINDING_NAME>", id = "<KV_NAMESPACE_ID_PRODUCTION>" }
]
```

</WranglerConfig>

### Service bindings

To use a [service binding](/workers/wrangler/configuration/#service-bindings) that targets a Worker in a specific environment, you need to append the environment name to the target Worker name in the `service` field. This should be in the format `<worker-name>-<environment-name>`.
In the example below, we have two Workers, both with a `staging` environment. `worker-b` has a service binding to `worker-a`. Note how the `service` field in the `staging` environment points to `worker-a-staging`, whereas the top-level service binding points to `worker-a`.

<WranglerConfig>

```toml
name = "worker-a"

vars = { FOO = "<top-level-var>" }
[env.staging.vars]
FOO = "<staging-var>"
```

</WranglerConfig>

<WranglerConfig>

```toml
name = "worker-b"

services = { binding = "<BINDING_NAME>", service = "worker-a" }

# Note how `service = "worker-a-staging"`
env.staging.service ={ binding = "<BINDING_NAME>", service = "worker-a-staging" }
```

</WranglerConfig>

### Secrets

You may assign environment-specific [secrets](/workers/configuration/secrets/) by running the command [`wrangler secret put <KEY> -env`](/workers/wrangler/commands/#put). You can also create `dotenv` type files named `.dev.vars.<environment-name>`.

Like other environment variables, secrets are [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) and must be defined per environment.

---

## Examples

### Staging and production environments

The following Wrangler file adds two environments, `[env.staging]` and `[env.production]`, to the Wrangler file. If you are deploying to a [Custom Domain](/workers/configuration/routing/custom-domains/) or [route](/workers/configuration/routing/routes/), you must provide a [`route` or `routes` key](/workers/wrangler/configuration/) for each environment.

<WranglerConfig>

```toml
name = "my-worker"
route = "dev.example.com/*"
vars = { ENVIRONMENT = "dev" }

[env.staging]
vars = { ENVIRONMENT = "staging" }
route = "staging.example.com/*"

[env.production]
vars = { ENVIRONMENT = "production" }
routes = [
  "example.com/foo/*",
  "example.com/bar/*"
]
```

</WranglerConfig>

You can pass the name of the environment via the `--env` flag to run commands in a specific environment.

With this configuration, Wrangler will behave in the following manner:

```sh
npx wrangler deploy
```

```sh output
Uploaded my-worker
Published my-worker
  dev.example.com/*
```

```sh
npx wrangler deploy --env staging
```

```sh output
Uploaded my-worker-staging
Published my-worker-staging
  staging.example.com/*
```

```sh
npx wrangler deploy --env production
```

```sh output
Uploaded my-worker-production
Published my-worker-production
  example.com/*
```

Any defined [environment variables](/workers/configuration/environment-variables/) (the [`vars`](/workers/wrangler/configuration/) key) are exposed as global variables to your Worker.

With this configuration, the `ENVIRONMENT` variable can be used to call specific code depending on the given environment:

```js
if (ENVIRONMENT === "staging") {
	// staging-specific code
} else if (ENVIRONMENT === "production") {
	// production-specific code
}
```

### Staging environment with \*.workers.dev

To deploy your code to your `*.workers.dev` subdomain, include `workers_dev = true` in the desired environment. Your Wrangler file may look like this:

<WranglerConfig>

```toml
name = "my-worker"
route = "example.com/*"

[env.staging]
workers_dev = true
```

</WranglerConfig>

With this configuration, Wrangler will behave in the following manner:

```sh
npx wrangler deploy
```

```sh output
Uploaded my-worker
Published my-worker
  example.com/*
```

```sh
npx wrangler deploy --env staging
```

```sh output
Uploaded my-worker
Published my-worker
  https://my-worker-staging.<YOUR_SUBDOMAIN>.workers.dev
```

:::caution

When you create a Worker via an environment, Cloudflare automatically creates an SSL certification for it. SSL certifications are discoverable and a matter of public record. Be careful when naming your environments that they do not contain sensitive information, such as, `migrating-service-from-company1-to-company2` or `company1-acquisition-load-test`.

:::

---

# System environment variables

URL: https://developers.cloudflare.com/workers/wrangler/system-environment-variables/

import { Render, Type, MetaInfo } from "~/components"

System environment variables are local environment variables that can change Wrangler's behavior. There are three ways to set system environment variables:

1. Create an `.env` file in your project directory. Set the values of your environment variables in your [`.env`](/workers/wrangler/system-environment-variables/#example-env-file) file. This is the recommended way to set these variables, as it persists the values between Wrangler sessions.

2. Inline the values in your Wrangler command. For example, `WRANGLER_LOG="debug" npx wrangler deploy` will set the value of `WRANGLER_LOG` to `"debug"` for this execution of the command.

3. Set the values in your shell environment. For example, if you are using Z shell, adding `export CLOUDFLARE_API_TOKEN=...` to your `~/.zshrc` file will set this token as part of your shell configuration.

:::note

To set different system environment variables for each environment, create files named `.env.<environment-name>`. When you use `wrangler <command> --env <environment-name>`, the corresponding environment-specific file will be loaded instead of the `.env` file, so the two files are not merged.
:::

## Supported environment variables

Wrangler supports the following environment variables:



* `CLOUDFLARE_ACCOUNT_ID` <Type text="string" /> <MetaInfo text="optional" />

  * The [account ID](/fundamentals/account/find-account-and-zone-ids/) for the Workers related account.

* `CLOUDFLARE_API_TOKEN` <Type text="string" /> <MetaInfo text="optional" />

  * The [API token](/fundamentals/api/get-started/create-token/) for your Cloudflare account, can be used for authentication for situations like CI/CD, and other automation.

* `CLOUDFLARE_API_KEY` <Type text="string" /> <MetaInfo text="optional" />

  * The API key for your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_EMAIL=`.

* `CLOUDFLARE_EMAIL` <Type text="string" /> <MetaInfo text="optional" />

  * The email address associated with your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_API_KEY=`.

* `WRANGLER_SEND_METRICS` <Type text="string" /> <MetaInfo text="optional" />

  * Options for this are `true` and `false`. Defaults to `true`. Controls whether Wrangler can send anonymous usage data to Cloudflare for this project. You can learn more about this in our [data policy](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md).

* `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>`<Type text="string" /> <MetaInfo text="optional" />

  * The [local connection string](/hyperdrive/configuration/local-development/) for your database to use in local development with [Hyperdrive](/hyperdrive/). For example, if the binding for your Hyperdrive is named `PROD_DB`, this would be `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_PROD_DB="postgres://user:password@127.0.0.1:5432/testdb"`. Each Hyperdrive is uniquely distinguished by the binding name.

* `CLOUDFLARE_API_BASE_URL` <Type text="string" /> <MetaInfo text="optional" />

  * The default value is `"https://api.cloudflare.com/client/v4"`.

* `WRANGLER_LOG` <Type text="string" /> <MetaInfo text="optional" />

  * Options for Logging levels are `"none"`, `"error"`, `"warn"`, `"info"`, `"log"` and `"debug"`. Levels are case-insensitive and default to `"log"`. If an invalid level is specified, Wrangler will fallback to the default. Logs can include requests to Cloudflare's API, any usage data being collected, and more verbose error logs.

* `WRANGLER_LOG_PATH` <Type text="string" /> <MetaInfo text="optional" />

  * A file or directory path where Wrangler will write debug logs. If the path ends in `.log`, Wrangler will consider this the path to a file where all logs will be written. Otherwise, Wrangler will treat the path as a directory where it will write one or more log files using a timestamp for the filenames.

* `FORCE_COLOR` <Type text="string" /> <MetaInfo text="optional" />

  * By setting this to `0`, you can disable Wrangler's colorised output, which makes it easier to read with some terminal setups. For example, `FORCE_COLOR=0`.





## Example `.env` file

The following is an example `.env` file:

```bash
CLOUDFLARE_ACCOUNT_ID=<YOUR_ACCOUNT_ID_VALUE>
CLOUDFLARE_API_TOKEN=<YOUR_API_TOKEN_VALUE>
CLOUDFLARE_EMAIL=<YOUR_EMAIL>
WRANGLER_SEND_METRICS=true
CLOUDFLARE_API_BASE_URL=https://api.cloudflare.com/client/v4
WRANGLER_LOG=debug
WRANGLER_LOG_PATH=../Desktop/my-logs/my-log-file.log
```

## Deprecated global variables

The following variables are deprecated. Use the new variables listed above to prevent any issues or unwanted messaging.

* `CF_ACCOUNT_ID`
* `CF_API_TOKEN`
* `CF_API_KEY`
* `CF_EMAIL`
* `CF_API_BASE_URL`

---

# Call Workflows from Pages

URL: https://developers.cloudflare.com/workflows/build/call-workflows-from-pages/

import { WranglerConfig, TypeScriptExample } from "~/components";

You can bind and trigger Workflows from [Pages Functions](/pages/functions/) by deploying a Workers project with your Workflow definition and then invoking that Worker using [service bindings](/pages/functions/bindings/#service-bindings) or a standard `fetch()` call.

:::note

You will need to deploy your Workflow as a standalone Workers project first before your Pages Function can call it. If you have not yet deployed a Workflow, refer to the Workflows [get started guide](/workflows/get-started/guide/).

:::

### Use Service Bindings

[Service Bindings](/workers/runtime-apis/bindings/service-bindings/) allow you to call a Worker from another Worker or a Pages Function without needing to expose it directly.

To do this, you will need to:

1. Deploy your Workflow in a Worker
2. Create a Service Binding to that Worker in your Pages project
3. Call the Worker remotely using the binding

For example, if you have a Worker called `workflows-starter`, you would create a new Service Binding in your Pages project as follows, ensuring that the `service` name matches the name of the Worker your Workflow is defined in:

<WranglerConfig>
```toml
services = [
  { binding = "WORKFLOW_SERVICE", service = "workflows-starter" }
]
```
</WranglerConfig>

Your Worker can expose a specific method (or methods) that only other Workers or Pages Functions can call over the Service Binding.

In the following example, we expose a specific `createInstance` method that accepts our `Payload` and returns the [`InstanceStatus`](/workflows/build/workers-api/#instancestatus) from the Workflows API:

<TypeScriptExample filename="index.ts">
```ts
import { WorkerEntrypoint } from "cloudflare:workers";

interface Env {
	MY_WORKFLOW: Workflow;
}

type Payload = {
	hello: string;
}

export default class WorkflowsService extends WorkerEntrypoint<Env> {
  // Currently, entrypoints without a named handler are not supported
  async fetch() { return new Response(null, {status: 404}); }

  async createInstance(payload: Payload) {
    let instance = await this.env.MY_WORKFLOW.create({
    	params: payload
    });

    return Response.json({
      id: instance.id,
      details: await instance.status(),
    });
  }
}
```
</TypeScriptExample>

Your Pages Function would resemble the following:

<TypeScriptExample filename="functions/request.ts">
```ts
interface Env {
	WORKFLOW_SERVICE: Service;
}

export const onRequest: PagesFunction<Env> = async (context) => {
	// This payload could be anything from within your app or from your frontend
	let payload = {"hello": "world"}
	return context.env.WORKFLOWS_SERVICE.createInstance(payload)
};
```
</TypeScriptExample>

To learn more about binding to resources from Pages Functions, including how to bind via the Cloudflare dashboard, refer to the [bindings documentation for Pages Functions](/pages/functions/bindings/#service-bindings).

### Using fetch

:::note[Service Bindings vs. fetch]

We recommend using [Service Bindings](/workers/runtime-apis/bindings/service-bindings/) when calling a Worker in your own account.

Service Bindings don't require you to expose a public endpoint from your Worker, don't require you to configure authentication, and allow you to call methods on your Worker directly, avoiding the overhead of managing HTTP requests and responses.

:::

An alternative to setting up a Service Binding is to call the Worker over HTTP by using the Workflows [Workers API](/workflows/build/workers-api/#workflow) to `create` a new Workflow instance for each incoming HTTP call to the Worker:

<TypeScriptExample filename="index.ts">
```ts
// This is in the same file as your Workflow definition
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    let instance = await env.MY_WORKFLOW.create({
    	params: payload
    });
    return Response.json({
      id: instance.id,
      details: await instance.status(),
    });
  },
};
```
</TypeScriptExample>

Your [Pages Function](/pages/functions/get-started/) can then make a regular `fetch` call to the Worker:

<TypeScriptExample filename="functions/request.ts">
```ts
export const onRequest: PagesFunction<Env> = async (context) => {
	// Other code
	let payload = {"hello": "world"}
  const instanceStatus = await fetch("https://YOUR_WORKER.workers.dev/", {
  	method: "POST",
    body: JSON.stringify(payload) // Send a payload for our Worker to pass to the Workflow
  })

  return Response.json(instanceStatus);
};
```
</TypeScriptExample>

You can also choose to authenticate these requests by passing a shared secret in a header and validating that in your Worker.

### Next steps

* Learn more about how to programatically call and trigger Workflows from the [Workers API](/workflows/build/workers-api/)
* Understand how to send [events and parameters](/workflows/build/events-and-parameters/) when triggering a Workflow
* Review the [Rules of Workflows](/workflows/build/rules-of-workflows/) and best practices for writing Workflows

---

# Events and parameters

URL: https://developers.cloudflare.com/workflows/build/events-and-parameters/

import { MetaInfo, Render, Type, WranglerConfig, TypeScriptExample } from "~/components";

When a Workflow is triggered, it can receive an optional event. This event can include data that your Workflow can act on, including request details, user data fetched from your database (such as D1 or KV) or from a webhook, or messages from a Queue consumer.

Events are a powerful part of a Workflow, as you often want a Workflow to act on data. Because a given Workflow instance executes durably, events are a useful way to provide a Workflow with data that should be immutable (not changing) and/or represents data the Workflow needs to operate on at that point in time.

## Pass data to a Workflow

You can pass parameters to a Workflow in three ways:

* As an optional argument to the `create` method on a [Workflow binding](/workers/wrangler/commands/#trigger) when triggering a Workflow from a Worker.
* Via the `--params` flag when using the `wrangler` CLI to trigger a Workflow.
* Via the `step.waitForEvent` API, which allows a Workflow instance to wait for an event (and optional data) to be received _while it is running_. Workflow instances can be sent events from external services over HTTP or via the Workers API for Workflows.

You can pass any JSON-serializable object as a parameter.

:::caution

A `WorkflowEvent` and its associated `payload` property are effectively _immutable_: any changes to an event are not persisted across the steps of a Workflow. This includes both cases when a Workflow is progressing normally, and in cases where a Workflow has to be restarted due to a failure.

Store state durably by returning it from your `step.do` callbacks.

:::

<TypeScriptExample>

```ts
export default {
  async fetch(req: Request, env: Env) {
    let someEvent = { url: req.url, createdTimestamp: Date.now() }
    // Trigger our Workflow
    // Pass our event as the second parameter to the `create` method
    // on our Workflow binding.
    let instance = await env.MY_WORKFLOW.create({
      id: await crypto.randomUUID(),
      params: someEvent
    });

    return Response.json({
      id: instance.id,
      details: await instance.status(),
    });
  },
};
```

</TypeScriptExample>

To pass parameters via the `wrangler` command-line interface, pass a JSON string as the second parameter to the `workflows trigger` sub-command:

```sh
npx wrangler@latest workflows trigger workflows-starter '{"some":"data"}'
```
```sh output
🚀 Workflow instance "57c7913b-8e1d-4a78-a0dd-dce5a0b7aa30" has been queued successfully
```

### Wait for events

A running Workflow can wait for an event (or events) by calling `step.waitForEvent` within the Workflow, which allows you to send events to the Workflow in one of two ways:

1. Via the [Workers API binding](/workflows/build/workers-api/): call `instance.sendEvent` to send events to specific workflow instances.
2. Using the REST API (HTTP API)'s [Events endpoint](/api/resources/workflows/subresources/instances/subresources/events/methods/create/).

Because `waitForEvent` is part of the `WorkflowStep` API, you can call it multiple times within a Workflow, and use control flow to conditionally wait for an event.

Calling `waitForEvent` requires you to specify an `type`, which is used to match the corresponding `type` when sending an event to a Workflow instance.

For example, to wait for billing webhook:

<TypeScriptExample>

```ts
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// Other steps in your Workflow
		let event = await step.waitForEvent<IncomingStripeWebhook>("receive invoice paid webhook from Stripe", { type: "stripe-webhook", timeout: "1 hour" })
		// Rest of your Workflow
	}
}
```

</TypeScriptExample>

The above example:

* Calls `waitForEvent` with a `type` of `stripe-webhook` - the corresponding `sendEvent` call would thus be `await instance.sendEvent({type: "stripe-webhook", payload: webhookPayload})`.
* Uses a TypeScript [type parameter](https://www.typescriptlang.org/docs/handbook/2/generics.html) to type the return value of `step.waitForEvent` as our `IncomingStripeWebhook`.
* Continues on with the rest of the Workflow.

### Send events to running workflows

Workflow instances that are waiting on events using the `waitForEvent` API can be sent events using the `instance.sendEvent` API:

<TypeScriptExample>

```ts
export default {
  async fetch(req: Request, env: Env) {
    const instanceId = new URL(req.url).searchParams.get("instanceId")
    const webhookPayload = await req.json<Payload>()

    let instance = await env.MY_WORKFLOW.get(instanceId);
    // Send our event, with `type` matching the event type defined in
    // our step.waitForEvent call
    await instance.sendEvent({type: "stripe-webhook", payload: webhookPayload})

    return Response.json({
      status: await instance.status(),
    });
  },
};
```

</TypeScriptExample>

* Similar to the [`waitForEvent`](#wait-for-events) example in this guide, the `type` property in our `waitForEvent` and `sendEvent` fields must match.
* To send multiple events to a Workflow that has multiple `waitForEvent` calls, call `sendEvent` with the corresponding `type` property set.
* Events can also be sent using the REST API (HTTP API)'s [Events endpoint](/api/resources/workflows/subresources/instances/subresources/events/methods/create/).

## TypeScript and type parameters

By default, the `WorkflowEvent` passed to the `run` method of your Workflow definition has a type that conforms to the following, with `payload` (your data), `timestamp`, and `instanceId` properties:

```ts
export type WorkflowEvent<T> = {
  // The data passed as the parameter when the Workflow instance was triggered
  payload: T;
  // The timestamp that the Workflow was triggered
  timestamp: Date;
  // ID of the current Workflow instance
  instanceId: string;
};
```

You can optionally type these events by defining your own type and passing it as a [type parameter](https://www.typescriptlang.org/docs/handbook/2/generics.html#working-with-generic-type-variables) to the `WorkflowEvent`:

```ts
// Define a type that conforms to the events your Workflow instance is
// instantiated with
interface YourEventType {
  userEmail: string;
  createdTimestamp: number;
  metadata?: Record<string, string>;
}
```

When you pass your `YourEventType` to `WorkflowEvent` as a type parameter, the `event.payload` property now has the type `YourEventType` throughout your workflow definition:

```ts title="src/index.ts"
// Import the Workflow definition
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent} from 'cloudflare:workers';

export class MyWorkflow extends WorkflowEntrypoint {
    // Pass your type as a type parameter to WorkflowEvent
    // The 'payload' property will have the type of your parameter.
    async run(event: WorkflowEvent<YourEventType>, step: WorkflowStep) {
        let state = step.do("my first step", async () => {
          // Access your properties via event.payload
          let userEmail = event.payload.userEmail
          let createdTimestamp = event.payload.createdTimestamp
        })

        step.do("my second step", async () => { /* your code here */ )
    }
}
```

<Render file="workflows-type-parameters"/>

---

# Build with Workflows

URL: https://developers.cloudflare.com/workflows/build/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Local Development

URL: https://developers.cloudflare.com/workflows/build/local-development/

Workflows support local development using [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Workers. Wrangler runs an emulated version of Workflows compared to the one that Cloudflare runs globally.

## Prerequisites

To develop locally with Workflows, you will need:

- [Wrangler v3.89.0](https://blog.cloudflare.com/wrangler3/) or later.

- Node.js version of `18.0.0` or later. Consider using a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change Node versions.

- If you are new to Workflows and/or Cloudflare Workers, refer to the [Workflows Guide](/workflows/get-started/guide/) to install `wrangler` and deploy their first Workflows.

## Start a local development session

Open your terminal and run the following commands to start a local development session:

```sh
# Confirm we are using wrangler v3.89.0+
npx wrangler --version
```

```sh output
⛅️ wrangler 3.89.0
```

Start a local dev session

```sh
# Start a local dev session:
npx wrangler dev
```

```sh output
------------------
Your worker has access to the following bindings:
- Workflows:
  - MY_WORKFLOW: MyWorkflow
⎔ Starting local server...
[wrangler:inf] Ready on http://127.0.0.1:8787/
```

Local development sessions create a standalone, local-only environment that mirrors the production environment Workflows runs in so you can test your Workflows _before_ you deploy to production.

Refer to the [`wrangler dev` documentation](/workers/wrangler/commands/#dev) to learn more about how to configure a local development session.

## Known Issues

Workflows does not support `npx wrangler dev --remote`.

Wrangler Workflows commands `npx wrangler workflow [cmd]` are not supported for local development, as they target production API.

---

# Rules of Workflows

URL: https://developers.cloudflare.com/workflows/build/rules-of-workflows/

import { WranglerConfig, TypeScriptExample } from "~/components";

A Workflow contains one or more steps. Each step is a self-contained, individually retriable component of a Workflow. Steps may emit (optional) state that allows a Workflow to persist and continue from that step, even if a Workflow fails due to a network or infrastructure issue.

This is a small guidebook on how to build more resilient and correct Workflows.

### Ensure API/Binding calls are idempotent

Because a step might be retried multiple times, your steps should (ideally) be idempotent. For context, idempotency is a logical property where the operation (in this case a step),
can be applied multiple times without changing the result beyond the initial application.

As an example, let us assume you have a Workflow that charges your customers, and you really do not want to charge them twice by accident. Before charging them, you should
check if they were already charged:

<TypeScriptExample filename="index.ts">
```ts
export class MyWorkflow extends WorkflowEntrypoint {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		const customer_id = 123456;
		// ✅ Good: Non-idempotent API/Binding calls are always done **after** checking if the operation is
		// still needed.
		await step.do(
			`charge ${customer_id} for its monthly subscription`,
			async () => {
				// API call to check if customer was already charged
				const subscription = await fetch(
					`https://payment.processor/subscriptions/${customer_id}`,
				).then((res) => res.json());

				// return early if the customer was already charged, this can happen if the destination service dies
				// in the middle of the request but still commits it, or if the Workflows Engine restarts.
				if (subscription.charged) {
					return;
				}

				// non-idempotent call, this operation can fail and retry but still commit in the payment
				// processor - which means that, on retry, it would mischarge the customer again if the above checks
				// were not in place.
				return await fetch(
					`https://payment.processor/subscriptions/${customer_id}`,
					{
						method: "POST",
						body: JSON.stringify({ amount: 10.0 }),
					},
				);
			},
		);
	}
}
```
</TypeScriptExample>

:::note

Guaranteeing idempotency might be optional in your specific use-case and implementation, but we recommend that you always try to guarantee it.

:::

### Make your steps granular

Steps should be as self-contained as possible. This allows your own logic to be more durable in case of failures in third-party APIs, network errors, and so on.

You can also think of it as a transaction, or a unit of work.

- ✅ Minimize the number of API/binding calls per step (unless you need multiple calls to prove idempotency).

<TypeScriptExample filename="index.ts">
```ts
export class MyWorkflow extends WorkflowEntrypoint {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// ✅ Good: Unrelated API/Binding calls are self-contained, so that in case one of them fails
		// it can retry them individually. It also has an extra advantage: you can control retry or
		// timeout policies for each granular step - you might not to want to overload http.cat in
		// case of it being down.
		const httpCat = await step.do("get cutest cat from KV", async () => {
			return await env.KV.get("cutest-http-cat");
		});

		const image = await step.do("fetch cat image from http.cat", async () => {
			return await fetch(`https://http.cat/${httpCat}`);
		});
	}
}
```
</TypeScriptExample>

Otherwise, your entire Workflow might not be as durable as you might think, and you may encounter some undefined behaviour. You can avoid them by following the rules below:

- 🔴 Do not encapsulate your entire logic in one single step.
- 🔴 Do not call separate services in the same step (unless you need it to prove idempotency).
- 🔴 Do not make too many service calls in the same step (unless you need it to prove idempotency).
- 🔴 Do not do too much CPU-intensive work inside a single step - sometimes the engine may have to restart, and it will start over from the beginning of that step.

<TypeScriptExample filename="index.ts">
```ts
export class MyWorkflow extends WorkflowEntrypoint {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// 🔴 Bad: you are calling two separate services from within the same step. This might cause
		// some extra calls to the first service in case the second one fails, and in some cases, makes
		// the step non-idempotent altogether
		const image = await step.do("get cutest cat from KV", async () => {
			const httpCat = await env.KV.get("cutest-http-cat");
			return fetch(`https://http.cat/${httpCat}`);
		});
	}
}
```
</TypeScriptExample>

### Do not rely on state outside of a step

Workflows may hibernate and lose all in-memory state. This will happen when engine detects that there is no pending work and can hibernate until it needs to wake-up (because of a sleep, retry, or event).

This means that you should not store state outside of a step:

<TypeScriptExample filename="index.ts">
```ts
function getRandomInt(min, max) {
	const minCeiled = Math.ceil(min);
	const maxFloored = Math.floor(max);
	return Math.floor(Math.random() * (maxFloored - minCeiled) + minCeiled); // The maximum is exclusive and the minimum is inclusive
}

export class MyWorkflow extends WorkflowEntrypoint {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// 🔴 Bad: `imageList` will be not persisted across engine's lifetimes. Which means that after hibernation,
		// `imageList` will be empty again, even though the following two steps have already ran.
		const imageList: string[] = [];

		await step.do("get first cutest cat from KV", async () => {
			const httpCat = await env.KV.get("cutest-http-cat-1");

			imageList.append(httpCat);
		});

		await step.do("get second cutest cat from KV", async () => {
			const httpCat = await env.KV.get("cutest-http-cat-2");

			imageList.append(httpCat);
		});

		// A long sleep can (and probably will) hibernate the engine which means that the first engine lifetime ends here
		await step.sleep("💤💤💤💤", "3 hours");

		// When this runs, it will be on the second engine lifetime - which means `imageList` will be empty.
		await step.do(
			"choose a random cat from the list and download it",
			async () => {
				const randomCat = imageList.at(getRandomInt(0, imageList.length));
				// this will fail since `randomCat` is undefined because `imageList` is empty
				return await fetch(`https://http.cat/${randomCat}`);
			},
		);
	}
}
```
</TypeScriptExample>

Instead, you should build top-level state exclusively comprised of `step.do` returns:

<TypeScriptExample filename="index.ts">
```ts
function getRandomInt(min, max) {
	const minCeiled = Math.ceil(min);
	const maxFloored = Math.floor(max);
	return Math.floor(Math.random() * (maxFloored - minCeiled) + minCeiled); // The maximum is exclusive and the minimum is inclusive
}

export class MyWorkflow extends WorkflowEntrypoint {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// ✅ Good: imageList state is exclusively comprised of step returns - this means that in the event of
		// multiple engine lifetimes, imageList will be built accordingly
		const imageList: string[] = await Promise.all([
			step.do("get first cutest cat from KV", async () => {
				return await env.KV.get("cutest-http-cat-1");
			}),

			step.do("get second cutest cat from KV", async () => {
				return await env.KV.get("cutest-http-cat-2");
			}),
		]);

		// A long sleep can (and probably will) hibernate the engine which means that the first engine lifetime ends here
		await step.sleep("💤💤💤💤", "3 hours");

		// When this runs, it will be on the second engine lifetime - but this time, imageList will contain
		// the two most cutest cats
		await step.do(
			"choose a random cat from the list and download it",
			async () => {
				const randomCat = imageList.at(getRandomInt(0, imageList.length));
				// this will eventually succeed since `randomCat` is defined
				return await fetch(`https://http.cat/${randomCat}`);
			},
		);
	}
}
```
</TypeScriptExample>

### Do not mutate your incoming events

The `event` passed to your Workflow's `run` method is immutable: changes you make to the event are not persisted across steps and/or Workflow restarts.

<TypeScriptExample filename="index.ts">
```ts
interface MyEvent {
  user: string;
  data: string;
}

export class MyWorkflow extends WorkflowEntrypoint {
	async run(event: WorkflowEvent<MyEvent>, step: WorkflowStep) {
		// 🔴 Bad: Mutating the event
		// This will not be persisted across steps and `event.payload` will
		// take on its original value.
		await step.do("bad step that mutates the incoming event", async () => {
		    let userData = await env.KV.get(event.payload.user)
				event.payload = userData
		})

		// ✅ Good: persist data by returning it as state from your step
		// Use that state in subsequent steps
		let userData = await step.do("good step that returns state", async () => {
		  return await env.KV.get(event.payload.user)
		})

		let someOtherData = await step.do("following step that uses that state", async () => {
		  // Access to userData here
			// Will always be the same if this step is retried
		})
	}
}
```
</TypeScriptExample>

### Name steps deterministically

Steps should be named deterministically (that is, not using the current date/time, randomness, etc). This ensures that their state is cached, and prevents the step from being rerun unnecessarily. Step names act as the "cache key" in your Workflow.

<TypeScriptExample filename="index.ts">
```ts
export class MyWorkflow extends WorkflowEntrypoint {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// 🔴 Bad: Naming the step non-deterministically prevents it from being cached
		// This will cause the step to be re-run if subsequent steps fail.
		await step.do(`step #1 running at: ${Date.now()}`, async () => {
		    let userData = await env.KV.get(event.payload.user)
				// Do not mutate event.payload
				event.payload = userData
		})

		// ✅ Good: give steps a deterministic name.
		// Return dynamic values in your state, or log them instead.
		let state = await step.do("fetch user data from KV", async () => {
		    let userData = await env.KV.get(event.payload.user)
				console.log(`fetched at ${Date.now}`)
				return userData
		})

		// ✅ Good: steps that are dynamically named are constructed in a deterministic way.
		// In this case, `catList` is a step output, which is stable, and `catList` is
		// traversed in a deterministic fashion (no shuffles or random accesses) so,
		// it's fine to dynamically name steps (e.g: create a step per list entry).
		let catList = await step.do("get cat list from KV", async () => {
			return await env.KV.get("cat-list")
		})

		for(const cat of catList) {
			await step.do(`get cat: ${cat}`, async () => {
				return await env.KV.get(cat)
			})
		}
	}
}
```
</TypeScriptExample>

### Take care with `Promise.race()` and `Promise.any()`

Workflows allows the usage steps within the `Promise.race()` or `Promise.any()` methods as a way to achieve concurrent steps execution. However, some considerations must be taken.

Due to the nature of Workflows' instance lifecycle, and given that a step inside a Promise will run until it finishes, the step that is returned during the first passage may not be the actual cached step, as [steps are cached by their names](#name-steps-deterministically).

<TypeScriptExample filename="index.ts">
```ts

// helper sleep method
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

export class MyWorkflow extends WorkflowEntrypoint {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// 🔴 Bad: The `Promise.race` is not surrounded by a `step.do`, which may cause undeterministic caching behavior.
		const race_return = await Promise.race(
			[
				step.do(
					'Promise first race',
					async () => {
						await sleep(1000);
						return "first";
					}
				),
				step.do(
					'Promise second race',
					async () => {
						return "second";
					}
				),
			]
		);

		await step.sleep("Sleep step", "2 hours");

		return await step.do(
			'Another step',
			async () => {
				// This step will return `first`, even though the `Promise.race` first returned `second`.
				return race_return;
			},
		);
	}
}
```
</TypeScriptExample>

To ensure consistency, we suggest to surround the `Promise.race()` or `Promise.any()` within a `step.do()`, as this will ensure caching consistency across multiple passages.

<TypeScriptExample filename="index.ts">
```ts

// helper sleep method
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

export class MyWorkflow extends WorkflowEntrypoint {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// ✅ Good: The `Promise.race` is surrounded by a `step.do`, ensuring deterministic caching behavior.
		const race_return = await step.do(
			'Promise step',
			async () => {
				return await Promise.race(
					[
						step.do(
							'Promise first race',
							async () => {
								await sleep(1000);
								return "first";
							}
						),
						step.do(
							'Promise second race',
							async () => {
								return "second";
							}
						),
					]
				);
			}
		);

		await step.sleep("Sleep step", "2 hours");

		return await step.do(
			'Another step',
			async () => {
				// This step will return `second` because the `Promise.race` was surround by the `step.do` method.
				return race_return;
			},
		);
	}
}
```
</TypeScriptExample>

### Instance IDs are unique

Workflow [instance IDs](/workflows/build/workers-api/#workflowinstance) are unique per Workflow. The ID is the unique identifier that associates logs, metrics, state and status of a run to a specific instance, even after completion. Allowing ID re-use would make it hard to understand if a Workflow instance ID referred to an instance that run yesterday, last week or today.

It would also present a problem if you wanted to run multiple different Workflow instances with different [input parameters](/workflows/build/events-and-parameters/) for the same user ID, as you would immediately need to determine a new ID mapping.

If you need to associate multiple instances with a specific user, merchant or other "customer" ID in your system, consider using a composite ID or using randomly generated IDs and storing the mapping in a database like [D1](/d1/).

<TypeScriptExample filename="index.ts">
```ts
// This is in the same file as your Workflow definition
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
		// 🔴 Bad: Use an ID that isn't unique across future Workflow invocations
		let userId = getUserId(req) // Returns the userId
    let badInstance = await env.MY_WORKFLOW.create({
    	id: userId,
    	params: payload
    });

    // ✅ Good: use an ID that is unique
    // e.g. a transaction ID, order ID, or task ID are good options
    let instanceId = getTransactionId() // e.g. assuming transaction IDs are unique
    // or: compose a composite ID and store it in your database
    // so that you can track all instances associated with a specific user or merchant.
    instanceId = `${getUserId(request)}-${await crypto.randomUUID().slice(0, 6)}`
    let { result } = await addNewInstanceToDB(userId, instanceId)
    let goodInstance = await env.MY_WORKFLOW.create({
    	id: userId,
    	params: payload
    });

    return Response.json({
      id: goodInstance.id,
      details: await goodInstance.status(),
    });
  },
};
```
</TypeScriptExample>

### `await` your steps

When calling `step.do` or `step.sleep`, use `await` to avoid introducing bugs and race conditions into your Workflow code.

If you don't call `await step.do` or `await step.sleep`, you create a dangling Promise. This occurs when a Promise is created but not properly `await`ed, leading to potential bugs and race conditions.

This happens when you do not use the `await` keyword or fail to chain `.then()` methods to handle the result of a Promise. For example, calling `fetch(GITHUB_URL)` without awaiting its response will cause subsequent code to execute immediately, regardless of whether the fetch completed. This can cause issues like premature logging, exceptions being swallowed (and not terminating the Workflow), and lost return values (state).

<TypeScriptExample filename="index.ts">
```ts
export class MyWorkflow extends WorkflowEntrypoint {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// 🔴 Bad: The step isn't await'ed, and any state or errors is swallowed before it returns.
	  const issues = step.do(`fetch issues from GitHub`, async () => {
				// The step will return before this call is done
		    let issues = await getIssues(event.payload.repoName)
				return issues
		})

		// ✅ Good: The step is correctly await'ed.
	  const issues = await step.do(`fetch issues from GitHub`, async () => {
		    let issues = await getIssues(event.payload.repoName)
				return issues
		})

		// Rest of your Workflow goes here!
	}
}
```
</TypeScriptExample>

### Batch multiple Workflow invocations

When creating multiple Workflow instances, use the [`createBatch`](/workflows/build/workers-api/#createBatch) method to batch the invocations together. This allows you to create multiple Workflow instances in a single request, which will reduce the number of requests made to the Workflows API and increase the number of instances you can create per minute.

<TypeScriptExample filename="index.ts">

```ts
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
		let instances = [{"id": "user1", "params": {"name": "John"}}, {"id": "user2", "params": {"name": "Jane"}}, {"id": "user3", "params": {"name": "Alice"}}, {"id": "user4", "params": {"name": "Bob"}}];

		// 🔴 Bad: Create them one by one, which is more likely to hit creation rate limits.
		for (let instance of instances) {
			await env.MY_WORKFLOW.create({
				id: instance.id,
				params: instance.params
			});
		}

    // ✅ Good: Batch calls together
    // This improves throughput.
    let instances = await env.MY_WORKFLOW.createBatch(instances);
    return Response.json({ instances })
  },
};
```

</TypeScriptExample>

---

# Sleeping and retrying

URL: https://developers.cloudflare.com/workflows/build/sleeping-and-retrying/

This guide details how to sleep a Workflow and/or configure retries for a Workflow step.

## Sleep a Workflow

You can set a Workflow to sleep as an explicit step, which can be useful when you want a Workflow to wait, schedule work ahead, or pause until an input or other external state is ready.

:::note

A Workflow instance that is resuming from sleep will take priority over newly scheduled (queued) instances. This helps ensure that older Workflow instances can run to completion and are not blocked by newer instances.

:::

### Sleep for a relative period

Use `step.sleep` to have a Workflow sleep for a relative period of time:

```ts
await step.sleep("sleep for a bit", "1 hour")
```

The second argument to `step.sleep` accepts both `number` (milliseconds) or a human-readable format, such as "1 minute" or "26 hours". The accepted units for `step.sleep` when used this way are as follows:

```ts
| "second"
| "minute"
| "hour"
| "day"
| "week"
| "month"
| "year"
```

### Sleep until a fixed date

Use `step.sleepUntil` to have a Workflow sleep to a specific `Date`: this can be useful when you have a timestamp from another system or want to "schedule" work to occur at a specific time (e.g. Sunday, 9AM UTC).

```ts
// sleepUntil accepts a Date object as its second argument
const workflowsLaunchDate = Date.parse("24 Oct 2024 13:00:00 UTC");
await step.sleepUntil("sleep until X times out", workflowsLaunchDate)
```

You can also provide a UNIX timestamp (milliseconds since the UNIX epoch) directly to `sleepUntil`.

## Retry steps

Each call to `step.do` in a Workflow accepts an optional `StepConfig`, which allows you define the retry behaviour for that step.

If you do not provide your own retry configuration, Workflows applies the following defaults:

```ts
const defaultConfig: WorkflowStepConfig = {
	retries: {
		limit: 5,
		delay: 10000,
		backoff: 'exponential',
	},
	timeout: '10 minutes',
};
```

When providing your own `StepConfig`, you can configure:

* The total number of attempts to make for a step (accepts `Infinity` for unlimited retries)
* The delay between attempts (accepts both `number` (ms) or a human-readable format)
* What backoff algorithm to apply between each attempt: any of `constant`, `linear`, or `exponential`
* When to timeout (in duration) before considering the step as failed (including during a retry attempt, as the timeout is set per attempt)

For example, to limit a step to 10 retries and have it apply an exponential delay (starting at 10 seconds) between each attempt, you would pass the following configuration as an optional object to `step.do`:

```ts
let someState = step.do("call an API", {
  retries: {
    limit: 10, // The total number of attempts
    delay: "10 seconds", // Delay between each retry
    backoff: "exponential" // Any of "constant" | "linear" | "exponential";
  },
  timeout: "30 minutes",
}, async () => { /* Step code goes here /* }
```

## Force a Workflow instance to fail

You can also force a Workflow instance to fail and _not_ retry by throwing a `NonRetryableError` from within the step.

This can be useful when you detect a terminal (permanent) error from an upstream system (such as an authentication failure) or other errors where retrying would not help.

```ts
// Import the NonRetryableError definition
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';
import { NonRetryableError } from 'cloudflare:workflows';

// In your step code:
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
	  await step.do("some step", async () => {
			  if !(event.payload.data) {
					throw new NonRetryableError("event.payload.data did not contain the expected payload")
				}
			})
	}
}
```

The Workflow instance itself will fail immediately, no further steps will be invoked, and the Workflow will not be retried.

## Catch Workflow errors

Any uncaught exceptions that propagate to the top level, or any steps that reach their retry limit, will cause the Workflow to end execution in an `Errored` state.

If you want to avoid this, you can catch exceptions emitted by a `step`. This can be useful if you need to trigger clean-up tasks or have conditional logic that triggers additional steps.

To allow the Workflow to continue its execution, surround the intended steps that are allowed to fail with a `try-catch` block.


```ts
...
await step.do('task', async () => {
	// work to be done
});

try {
    await step.do('non-retryable-task', async () => {
		// work not to be retried
        throw new NonRetryableError('oh no');
    });
} catch(e as Error) {
    console.log(`Step failed: ${e.message}`);
    await step.do('clean-up-task', async () => {
      // Clean up code here
    });
}

// the Workflow will not fail and will continue its execution

await step.do('next-task', async() => {
	// more work to be done
});
...
```

---

# Trigger Workflows

URL: https://developers.cloudflare.com/workflows/build/trigger-workflows/

import { WranglerConfig } from "~/components";

You can trigger Workflows both programmatically and via the Workflows APIs, including:

1. With [Workers](/workers) via HTTP requests in a `fetch` handler, or bindings from a `queue` or `scheduled` handler
2. Using the [Workflows REST API](/api/resources/workflows/methods/list/)
2. Via the [wrangler CLI](/workers/wrangler/commands/#workflows) in your terminal

## Workers API (Bindings)

You can interact with Workflows programmatically from any Worker script by creating a binding to a Workflow. A Worker can bind to multiple Workflows, including Workflows defined in other Workers projects (scripts) within your account.

You can interact with a Workflow:

* Directly over HTTP via the [`fetch`](/workers/runtime-apis/handlers/fetch/) handler
* From a [Queue consumer](/queues/configuration/javascript-apis/#consumer) inside a `queue` handler
* From a [Cron Trigger](/workers/configuration/cron-triggers/) inside a `scheduled` handler
* Within a [Durable Object](/durable-objects/)

:::note

New to Workflows? Start with the [Workflows tutorial](/workflows/get-started/guide/) to deploy your first Workflow and familiarize yourself with Workflows concepts.

:::

To bind to a Workflow from your Workers code, you need to define a [binding](/workers/wrangler/configuration/) to a specific Workflow. For example, to bind to the Workflow defined in the [get started guide](/workflows/get-started/guide/), you would configure the [Wrangler configuration file](/workers/wrangler/configuration/) with the below:

<WranglerConfig>

```toml title="wrangler.toml"
name = "workflows-tutorial"
main = "src/index.ts"
compatibility_date = "2024-10-22"

[[workflows]]
# The name of the Workflow
name = "workflows-tutorial"
# The binding name, which must be a valid JavaScript variable name.  This will
# be how you call (run) your Workflow from your other Workers handlers or
# scripts.
binding = "MY_WORKFLOW"
# Must match the class defined in your code that extends the Workflow class
class_name = "MyWorkflow"
```

</WranglerConfig>

The `binding = "MY_WORKFLOW"` line defines the JavaScript variable that our Workflow methods are accessible on, including `create` (which triggers a new instance) or `get` (which returns the status of an existing instance).

The following example shows how you can manage Workflows from within a Worker, including:

* Retrieving the status of an existing Workflow instance by its ID
* Creating (triggering) a new Workflow instance
* Returning the status of a given instance ID

```ts title="src/index.ts"
interface Env {
	MY_WORKFLOW: Workflow;
}

export default {
	async fetch(req: Request, env: Env) {
    // Get instanceId from query parameters
    const instanceId = new URL(req.url).searchParams.get("instanceId")

    // If an ?instanceId=<id> query parameter is provided, fetch the status
    // of an existing Workflow by its ID.
    if (instanceId) {
      let instance = await env.MY_WORKFLOW.get(instanceId);
			return Response.json({
				status: await instance.status(),
			});
    }

    // Else, create a new instance of our Workflow, passing in any (optional)
    // params and return the ID.
		const newId = await crypto.randomUUID();
		let instance = await env.MY_WORKFLOW.create({ id: newId });
		return Response.json({
			id: instance.id,
			details: await instance.status(),
		});

		return Response.json({ result });
	},
};
```

### Inspect a Workflow's status

You can inspect the status of any running Workflow instance by calling `status` against a specific instance ID. This allows you to programmatically inspect whether an instance is queued (waiting to be scheduled), actively running, paused, or errored.

```ts
let instance = await env.MY_WORKFLOW.get("abc-123")
let status = await instance.status() // Returns an InstanceStatus
```

The possible values of status are as follows:

```ts
  status:
    | "queued" // means that instance is waiting to be started (see concurrency limits)
    | "running"
    | "paused"
    | "errored"
    | "terminated" // user terminated the instance while it was running
    | "complete"
    | "waiting" // instance is hibernating and waiting for sleep or event to finish
    | "waitingForPause" // instance is finishing the current work to pause
    | "unknown";
  error?: string;
  output?: object;
};
```
{/*
### Explicitly pause a Workflow

You can explicitly pause a Workflow instance (and later resume it) by calling `pause` against a specific instance ID.

```ts
let instance = await env.MY_WORKFLOW.get("abc-123")
await instance.pause() // Returns Promise<void>
```

### Resume a Workflow

You can resume a paused Workflow instance by calling `resume` against a specific instance ID.

```ts
let instance = await env.MY_WORKFLOW.get("abc-123")
await instance.resume() // Returns Promise<void>
```

Calling `resume` on an instance that is not currently paused will have no effect.
*/}

### Stop a Workflow

You can stop/terminate a Workflow instance by calling `terminate` against a specific instance ID.

```ts
let instance = await env.MY_WORKFLOW.get("abc-123")
await instance.terminate() // Returns Promise<void>
```

Once stopped/terminated, the Workflow instance *cannot* be resumed.

### Restart a Workflow

:::caution

**Known issue**: Restarting a Workflow via the `restart()` method is not currently supported and will throw an exception (error).

:::

```ts
let instance = await env.MY_WORKFLOW.get("abc-123")
await instance.restart() // Returns Promise<void>
```

Restarting an instance will immediately cancel any in-progress steps, erase any intermediate state, and treat the Workflow as if it was run for the first time.

## REST API (HTTP)

Refer to the [Workflows REST API documentation](/api/resources/workflows/subresources/instances/methods/create/).

## Command line (CLI)

Refer to the [CLI quick start](/workflows/get-started/cli-quick-start/) to learn more about how to manage and trigger Workflows via the command-line.

---

# Workers API

URL: https://developers.cloudflare.com/workflows/build/workers-api/

import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";

This guide details the Workflows API within Cloudflare Workers, including methods, types, and usage examples.

## WorkflowEntrypoint

The `WorkflowEntrypoint` class is the core element of a Workflow definition. A Workflow must extend this class and define a `run` method with at least one `step` call to be considered a valid Workflow.

```ts
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
	  // Steps here
	}
};
```

### run

* <code>run(event: WorkflowEvent&lt;T&gt;, step: WorkflowStep): Promise&lt;T&gt;</code>

  * `event` - the event passed to the Workflow, including an optional `payload` containing data (parameters)
  * `step` - the `WorkflowStep` type that provides the step methods for your Workflow

The `run` method can optionally return data, which is available when querying the instance status via the [Workers API](/workflows/build/workers-api/#instancestatus), [REST API](/api/resources/workflows/subresources/instances/subresources/status/) and the Workflows dashboard. This can be useful if your Workflow is computing a result, returning the key to data stored in object storage, or generating some kind of identifier you need to act on.

```ts
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
	  // Steps here
		let someComputedState = step.do("my step", async () => { })

		// Optional: return state from our run() method
		return someComputedState
	}
};
```

The `WorkflowEvent` type accepts an optional [type parameter](https://www.typescriptlang.org/docs/handbook/2/generics.html#working-with-generic-type-variables) that allows you to provide a type for the `payload` property within the `WorkflowEvent`.

Refer to the [events and parameters](/workflows/build/events-and-parameters/) documentation for how to handle events within your Workflow code.

Finally, any JS control-flow primitive (if conditions, loops, try-catches, promises, etc) can be used to manage steps inside the `run` method.

## WorkflowEvent

```ts
export type WorkflowEvent<T> = {
  payload: Readonly<T>;
  timestamp: Date;
  instanceId: string;
};
```

* The `WorkflowEvent` is the first argument to a Workflow's `run` method, and includes an optional `payload` parameter and a `timestamp` property.

  * `payload` - a default type of `any` or type `T` if a type parameter is provided.
  * `timestamp` - a `Date` object set to the time the Workflow instance was created (triggered).
  * `instanceId` - the ID of the associated instance.

Refer to the [events and parameters](/workflows/build/events-and-parameters/) documentation for how to handle events within your Workflow code.

## WorkflowStep

### step

* <code>step.do(name: string, callback: (): RpcSerializable): Promise&lt;T&gt;</code>
* <code>step.do(name: string, config?: WorkflowStepConfig, callback: (): RpcSerializable): Promise&lt;T&gt;</code>

  * `name` - the name of the step.
  * `config` (optional) - an optional `WorkflowStepConfig` for configuring [step specific retry behaviour](/workflows/build/sleeping-and-retrying/).
  * `callback` - an asynchronous function that optionally returns serializable state for the Workflow to persist.

:::note[Returning state]

When returning state from a `step`, ensure that the object you return is _serializable_.

Primitive types like `string`, `number`, and `boolean`, along with composite structures such as `Array` and `Object` (provided they only contain serializable values), can be serialized.

Objects that include `Function` or `Symbol` types, and objects with circular references, cannot be serialized and the Workflow instance will throw an error if objects with those types is returned.

:::

* <code>step.sleep(name: string, duration: WorkflowDuration): Promise&lt;void&gt;</code>

  * `name` - the name of the step.
  * `duration` - the duration to sleep until, in either seconds or as a `WorkflowDuration` compatible string.
  * Refer to the [documentation on sleeping and retrying](/workflows/build/sleeping-and-retrying/) to learn more about how Workflows are retried.

* <code>step.sleepUntil(name: string, timestamp: Date | number): Promise&lt;void&gt;</code>

  * `name` - the name of the step.
  * `timestamp` - a JavaScript `Date` object or seconds from the Unix epoch to sleep the Workflow instance until.

:::note

`step.sleep` and `step.sleepUntil` methods do not count towards the maximum Workflow steps limit.

More information about the limits imposed on Workflow can be found in the [Workflows limits documentation](/workflows/reference/limits/).

:::

* <code>step.waitForEvent(name: string, options: ): Promise&lt;void&gt;</code>

  * `name` - the name of the step.
  * `options` - an object with properties for `type`, which determines which event type this `waitForEvent` call will match on when calling `instance.sendEvent`, and an optional `timeout` property, which defines how long the `waitForEvent` call will block for before throwing a timeout exception. The default timeout is 24 hours.

<TypeScriptExample>

```ts
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// Other steps in your Workflow
		let event = await step.waitForEvent<IncomingStripeWebhook>("receive invoice paid webhook from Stripe", { type: "stripe-webhook", timeout: "1 hour" })
		// Rest of your Workflow
	}
}
```

</TypeScriptExample>

Review the documentation on [events and parameters](/workflows/build/events-and-parameters/) to learn how to send events to a running Workflow instance.

## WorkflowStepConfig

```ts
export type WorkflowStepConfig = {
  retries?: {
    limit: number;
    delay: string | number;
    backoff?: WorkflowBackoff;
  };
  timeout?: string | number;
};
```

* A `WorkflowStepConfig` is an optional argument to the `do` method of a `WorkflowStep` and defines properties that allow you to configure the retry behaviour of that step.

Refer to the [documentation on sleeping and retrying](/workflows/build/sleeping-and-retrying/) to learn more about how Workflows are retried.

## NonRetryableError

* <code>throw new NonRetryableError(message: <Type text='string' />, name <Type text='string' /> <MetaInfo text='optional' />)</code>: <Type text='NonRetryableError' />

  * Throws an error that forces the current Workflow instance to fail and not be retried.
  * Refer to the [documentation on sleeping and retrying](/workflows/build/sleeping-and-retrying/) to learn more about how Workflows are retried.

## Call Workflows from Workers

Workflows exposes an API directly to your Workers scripts via the [bindings](/workers/runtime-apis/bindings/#what-is-a-binding) concept. Bindings allow you to securely call a Workflow without having to manage API keys or clients.

You can bind to a Workflow by defining a `[[workflows]]` binding within your Wrangler configuration.

For example, to bind to a Workflow called `workflows-starter` and to make it available on the `MY_WORKFLOW` variable to your Worker script, you would configure the following fields within the `[[workflows]]` binding definition:

<WranglerConfig>

```toml title="wrangler.toml"
#:schema node_modules/wrangler/config-schema.json
name = "workflows-starter"
main = "src/index.ts"
compatibility_date = "2024-10-22"

[[workflows]]
# name of your workflow
name = "workflows-starter"
# binding name env.MY_WORKFLOW
binding = "MY_WORKFLOW"
# this is class that extends the Workflow class in src/index.ts
class_name = "MyWorkflow"
```
</WranglerConfig>

### Bind from Pages

You can bind and trigger Workflows from [Pages Functions](/pages/functions/) by deploying a Workers project with your Workflow definition and then invoking that Worker using [service bindings](/pages/functions/bindings/#service-bindings) or a standard `fetch()` call.

Visit the documentation on [calling Workflows from Pages](/workflows/build/call-workflows-from-pages/) for examples.

### Cross-script calls

You can also bind to a Workflow that is defined in a different Worker script from the script your Workflow definition is in. To do this, provide the `script_name` key with the name of the script to the `[[workflows]]` binding definition in your Wrangler configuration.

For example, if your Workflow is defined in a Worker script named `billing-worker`, but you are calling it from your `web-api-worker` script, your [Wrangler configuration file](/workers/wrangler/configuration/) would resemble the following:

<WranglerConfig>

```toml title="wrangler.toml"
#:schema node_modules/wrangler/config-schema.json
name = "web-api-worker"
main = "src/index.ts"
compatibility_date = "2024-10-22"

[[workflows]]
# name of your workflow
name = "billing-workflow"
# binding name env.MY_WORKFLOW
binding = "MY_WORKFLOW"
# this is class that extends the Workflow class in src/index.ts
class_name = "MyWorkflow"
# the script name where the Workflow is defined.
# required if the Workflow is defined in another script.
script_name = "billing-worker"
```

</WranglerConfig>

<Render file="wrangler-typegen" product="workers" />

## Workflow

:::note

Ensure you have a compatibility date `2024-10-22` or later installed when binding to Workflows from within a Workers project.

:::

The `Workflow` type provides methods that allow you to create, inspect the status, and manage running Workflow instances from within a Worker script.
It is part of the generated types produced by [`wrangler types`](/workers/wrangler/commands/#types).
 
```ts title="./worker-configuration.d.ts"
interface Env {
  // The 'MY_WORKFLOW' variable should match the "binding" value set in the Wrangler config file
  MY_WORKFLOW: Workflow;
}
```

The `Workflow` type exports the following methods:

### create

Create (trigger) a new instance of the given Workflow.

* <code>create(options?: WorkflowInstanceCreateOptions): Promise&lt;WorkflowInstance&gt;</code>

  * `options` - optional properties to pass when creating an instance, including a user-provided ID and payload parameters.

An ID is automatically generated, but a user-provided ID can be specified (up to 64 characters [^1]). This can be useful when mapping Workflows to users, merchants or other identifiers in your system. You can also provide a JSON object as the `params` property, allowing you to pass data for the Workflow instance to act on as its [`WorkflowEvent`](/workflows/build/events-and-parameters/).

```ts
// Create a new Workflow instance with your own ID and pass params to the Workflow instance
let instance = await env.MY_WORKFLOW.create({
	id: myIdDefinedFromOtherSystem,
	params: { "hello": "world" }
})
return Response.json({
	id: instance.id,
	details: await instance.status(),
});
```

Returns a `WorkflowInstance`.

<Render file="workflows-type-parameters"/>

To provide an optional type parameter to the `Workflow`, pass a type argument with your type when defining your Workflow bindings:

```ts
interface User {
	email: string;
	createdTimestamp: number;
}

interface Env {
	// Pass our User type as the type parameter to the Workflow definition
  MY_WORKFLOW: Workflow<User>;
}

export default {
	async fetch(request, env, ctx) {
		// More likely to come from your database or via the request body!
		const user: User = {
			email: user@example.com,
			createdTimestamp: Date.now()
		}

		let instance = await env.MY_WORKFLOW.create({
			// params expects the type User
			params: user
		})

		return Response.json({
			id: instance.id,
			details: await instance.status(),
		});
	}
}
```

### createBatch

Create (trigger) a batch of new instance of the given Workflow, up to 100 instances at a time.

This is useful when you are scheduling multiple instances at once. A call to `createBatch` is treated the same as a call to `create` (for a single instance) and allows you to work within the [instance creation limit](/workflows/reference/limits/).

* <code>createBatch(batch: WorkflowInstanceCreateOptions[]): Promise&lt;WorkflowInstance[]&gt;</code>

  * `batch` - list of Options to pass when creating an instance, including a user-provided ID and payload parameters.

Each element of the `batch` list is expected to include both `id` and `params` properties:

```ts
// Create a new batch of 3 Workflow instances, each with its own ID and pass params to the Workflow instances
const listOfInstances = [
  { id: "id-abc123", params: { "hello": "world-0" } },
  { id: "id-def456", params: { "hello": "world-1" } },
  { id: "id-ghi789", params: { "hello": "world-2" } }
];
let instances = await env.MY_WORKFLOW.createBatch(listOfInstances);
```

Returns an array of `WorkflowInstance`.

### get

Get a specific Workflow instance by ID.

* <code>get(id: string): Promise&lt;WorkflowInstance&gt;</code>

  * `id` - the ID of the Workflow instance.

Returns a `WorkflowInstance`. Throws an exception if the instance ID does not exist.

```ts
// Fetch an existing Workflow instance by ID:
try {
  let instance = await env.MY_WORKFLOW.get(id)
  return Response.json({
	  id: instance.id,
	  details: await instance.status(),
  });
} catch (e: any) {
  // Handle errors
  // .get will throw an exception if the ID doesn't exist or is invalid.
  const msg = `failed to get instance ${id}: ${e.message}`
  console.error(msg)
  return Response.json({error: msg}, { status: 400 })
}
```

## WorkflowInstanceCreateOptions

Optional properties to pass when creating an instance.

```ts
interface WorkflowInstanceCreateOptions {
  /**
   * An id for your Workflow instance. Must be unique within the Workflow.
   */
  id?: string;
  /**
   * The event payload the Workflow instance is triggered with
   */
  params?: unknown;
}
```

## WorkflowInstance

Represents a specific instance of a Workflow, and provides methods to manage the instance.

```ts
declare abstract class WorkflowInstance {
  public id: string;
  /**
   * Pause the instance.
   */
  public pause(): Promise<void>;
  /**
   * Resume the instance. If it is already running, an error will be thrown.
   */
  public resume(): Promise<void>;
  /**
   * Terminate the instance. If it is errored, terminated or complete, an error will be thrown.
   */
  public terminate(): Promise<void>;
  /**
   * Restart the instance.
   */
  public restart(): Promise<void>;
  /**
   * Returns the current status of the instance.
   */
  public status(): Promise<InstanceStatus>;
}
```

### id

Return the id of a Workflow.

* <code>id: string</code>

### status

Return the status of a running Workflow instance.

* <code>status(): Promise&lt;void&gt;</code>

### pause

Pause a running Workflow instance.

* <code>pause(): Promise&lt;void&gt;</code>

### resume

Resume a paused Workflow instance.

* <code>resume(): Promise&lt;void&gt;</code>

### restart

Restart a Workflow instance.

* <code>restart(): Promise&lt;void&gt;</code>

### terminate

Terminate a Workflow instance.

* <code>terminate(): Promise&lt;void&gt;</code>

### sendEvent

[Send an event](/workflows/build/events-and-parameters/) to a running Workflow instance.

* <code>sendEvent(): Promise&lt;void&gt;</code>

  * `options` - the event `type` and `payload` to send to the Workflow instance. The `type` must match the `type` in the corresponding `waitForEvent` call in your Workflow.

Return `void` on success; throws an exception if the Workflow is not running or is an errored state.

<TypeScriptExample>

```ts
export default {
  async fetch(req: Request, env: Env) {
    const instanceId = new URL(req.url).searchParams.get("instanceId")
    const webhookPayload = await req.json<Payload>()

    let instance = await env.MY_WORKFLOW.get(instanceId);
    // Send our event, with `type` matching the event type defined in
    // our step.waitForEvent call
    await instance.sendEvent({type: "stripe-webhook", payload: webhookPayload})

    return Response.json({
      status: await instance.status(),
    });
  },
};
```

</TypeScriptExample>

You can call `sendEvent` multiple times, setting the value of the `type` property to match the specific `waitForEvent` calls in your Workflow.

This allows you to wait for multiple events at once, or use `Promise.race` to wait for multiple events and allow the first event to progress the Workflow.

### InstanceStatus

Details the status of a Workflow instance.

```ts
type InstanceStatus = {
  status:
    | "queued" // means that instance is waiting to be started (see concurrency limits)
    | "running"
    | "paused"
    | "errored"
    | "terminated" // user terminated the instance while it was running
    | "complete"
    | "waiting" // instance is hibernating and waiting for sleep or event to finish
    | "waitingForPause" // instance is finishing the current work to pause
    | "unknown";
  error?: string;
  output?: object;
};
```

[^1]: Match pattern: _```^[a-zA-Z0-9_][a-zA-Z0-9-_]*$```_

---

# Export and save D1 database

URL: https://developers.cloudflare.com/workflows/examples/backup-d1/

import { TabItem, Tabs, WranglerConfig } from "~/components";

In this example, we implement a Workflow periodically triggered by a [Cron Trigger](/workers/configuration/cron-triggers). That Workflow initiates a backup for a D1 database using the REST API, and then stores the SQL dump in an [R2](/r2) bucket.

When the Workflow is triggered, it fetches the REST API to initiate an export job for a specific database. Then it fetches the same endpoint to check if the backup job is ready and the SQL dump is available to download.

As shown in this example, Workflows handles both the responses and failures, thereby removing the burden from the developer. Workflows retries the following steps:

- API calls until it gets a successful response
- Fetching the backup from the URL provided
- Saving the file to [R2](/r2)

The Workflow can run until the backup file is ready, handling all of the possible conditions until it is completed.

This example provides simplified steps for backing up a [D1](/d1) database to help you understand the possibilities of Workflows. In every step, it uses the [default](/workflows/build/sleeping-and-retrying) sleeping and retrying configuration. In a real-world scenario, more steps and additional logic would likely be needed.

```ts
import {
	WorkflowEntrypoint,
	WorkflowStep,
	WorkflowEvent,
} from "cloudflare:workers";

// We are using R2 to store the D1 backup
type Env = {
	BACKUP_WORKFLOW: Workflow;
	D1_REST_API_TOKEN: string;
	BACKUP_BUCKET: R2Bucket;
};

// Workflow parameters: we expect accountId and databaseId
type Params = {
	accountId: string;
	databaseId: string;
};

// Workflow logic
export class backupWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		const { accountId, databaseId } = event.payload;

		const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/d1/database/${databaseId}/export`;
		const method = "POST";
		const headers = new Headers();
		headers.append("Content-Type", "application/json");
		headers.append("Authorization", `Bearer ${this.env.D1_REST_API_TOKEN}`);

		const bookmark = await step.do(
			`Starting backup for ${databaseId}`,
			async () => {
				const payload = { output_format: "polling" };

				const res = await fetch(url, {
					method,
					headers,
					body: JSON.stringify(payload),
				});
				const { result } = (await res.json()) as any;

				// If we don't get `at_bookmark` we throw to retry the step
				if (!result?.at_bookmark) throw new Error("Missing `at_bookmark`");

				return result.at_bookmark;
			},
		);

		await step.do("Check backup status and store it on R2", async () => {
			const payload = { current_bookmark: bookmark };

			const res = await fetch(url, {
				method,
				headers,
				body: JSON.stringify(payload),
			});
			const { result } = (await res.json()) as any;

			// The endpoint sends `signed_url` when the backup is ready to download.
			// If we don't get `signed_url` we throw to retry the step.
			if (!result?.signed_url) throw new Error("Missing `signed_url`");

			const dumpResponse = await fetch(result.signed_url);
			if (!dumpResponse.ok) throw new Error("Failed to fetch dump file");

			// Finally, stream the file directly to R2
			await this.env.BACKUP_BUCKET.put(result.filename, dumpResponse.body);
		});
	}
}

export default {
	async fetch(req: Request, env: Env): Promise<Response> {
		return new Response("Not found", { status: 404 });
	},
	async scheduled(
		controller: ScheduledController,
		env: Env,
		ctx: ExecutionContext,
	) {
		const params: Params = {
			accountId: "{accountId}",
			databaseId: "{databaseId}",
		};
		const instance = await env.BACKUP_WORKFLOW.create({ params });
		console.log(`Started workflow: ${instance.id}`);
	},
};
```

Here is a minimal package.json:

```json
{
	"devDependencies": {
		"wrangler": "^3.99.0"
	}
}
```

Here is a [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
name = "backup-d1"
main = "src/index.ts"
compatibility_date = "2024-12-27"
compatibility_flags = [ "nodejs_compat" ]

[[workflows]]
name = "backup-workflow"
binding = "BACKUP_WORKFLOW"
class_name = "backupWorkflow"

[[r2_buckets]]
binding = "BACKUP_BUCKET"
bucket_name = "d1-backups"

[triggers]
crons = [ "0 0 * * *" ]
```

</WranglerConfig>

---

# Examples

URL: https://developers.cloudflare.com/workflows/examples/

import { GlossaryTooltip, ListExamples } from "~/components";

Explore the following <GlossaryTooltip term="code example">examples</GlossaryTooltip> for Workflows.

<ListExamples />

---

# Pay cart and send invoice

URL: https://developers.cloudflare.com/workflows/examples/send-invoices/

import { TabItem, Tabs, WranglerConfig, Render } from "~/components";

In this example, we implement a Workflow for an e-commerce website that is triggered every time a shopping cart is created.

Once a Workflow instance is triggered, it starts polling a [D1](/d1) database for the cart ID until it has been checked out. Once the shopping cart is checked out, we proceed to process the payment with an external provider doing a fetch POST. Finally, assuming everything goes well, we try to send an email using [Email Workers](/email-routing/email-workers/) with the invoice to the customer.

As you can see, Workflows handles all the different service responses and failures; it will retry D1 until the cart is checked out, retry the payment processor if it fails for some reason, and retry sending the email with the invoice if it can't. The developer doesn't have to care about any of that logic, and the workflow can run for hours, handling all the possible conditions until it is completed.

This is a simplified example of processing a shopping cart. We would assume more steps and additional logic in a real-life scenario, but this example gives you a good idea of what you can do with Workflows.

```ts
import {
	WorkflowEntrypoint,
	WorkflowStep,
	WorkflowEvent,
} from "cloudflare:workers";
import { EmailMessage } from "cloudflare:email";
import { createMimeMessage } from "mimetext";

// We are using Email Routing to send emails out and D1 for our cart database
type Env = {
	CART_WORKFLOW: Workflow;
	SEND_EMAIL: any;
	DB: any;
};

// Workflow parameters: we expect a cartId
type Params = {
	cartId: string;
};

// Adjust this to your Cloudflare zone using Email Routing
const merchantEmail = "merchant@example.com";

// Uses mimetext npm to generate Email
const genEmail = (email: string, amount: number) => {
	const msg = createMimeMessage();
	msg.setSender({ name: "Pet shop", addr: merchantEmail });
	msg.setRecipient(email);
	msg.setSubject("You invoice");
	msg.addMessage({
		contentType: "text/plain",
		data: `Your invoice for ${amount} has been paid. Your products will be shipped shortly.`,
	});

	return new EmailMessage(merchantEmail, email, msg.asRaw());
};

// Workflow logic
export class cartInvoicesWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		await step.sleep("sleep for a while", "10 seconds");

		// Retrieve the cart from the D1 database
		// if the cart hasn't been checked out yet retry every 2 minutes, 10 times, otherwise give up
		const cart = await step.do(
			"retrieve cart",
			{
				retries: {
					limit: 10,
					delay: 2000 * 60,
					backoff: "constant",
				},
				timeout: "30 seconds",
			},
			async () => {
				const { results } = await this.env.DB.prepare(
					`SELECT * FROM cart WHERE id = ?`,
				)
					.bind(event.payload.cartId)
					.all();
				// should return { checkedOut: true, amount: 250 , account: { email: "celsomartinho@gmail.com" }};
				if (results[0].checkedOut === false) {
					throw new Error("cart hasn't been checked out yet");
				}
				return results[0];
			},
		);

		// Proceed to payment, retry 10 times every minute or give up
		const payment = await step.do(
			"payment",
			{
				retries: {
					limit: 10,
					delay: 1000 * 60,
					backoff: "constant",
				},
				timeout: "30 seconds",
			},
			async () => {
				let resp = await fetch("https://payment-processor.example.com/", {
					method: "POST",
					headers: {
						"Content-Type": "application/json; charset=utf-8",
					},
					body: JSON.stringify({ amount: cart.amount }),
				});

				if (!resp.ok) {
					throw new Error("payment has failed");
				}

				return { success: true, amount: cart.amount };
			},
		);

		// Send invoice to the customer, retry 10 times every 5 minutes or give up
		// Requires that cart.account.email has previously been validated in Email Routing,
		// See https://developers.cloudflare.com/email-routing/email-workers/
		await step.do(
			"send invoice",
			{
				retries: {
					limit: 10,
					delay: 5000 * 60,
					backoff: "constant",
				},
				timeout: "30 seconds",
			},
			async () => {
				const message = genEmail(cart.account.email, payment.amount);
				try {
					await this.env.SEND_EMAIL.send(message);
				} catch (e) {
					throw new Error("failed to send invoice");
				}
			},
		);
	}
}

// Default page for admin
// Remove in production

export default {
	async fetch(req: Request, env: Env): Promise<Response> {
		let url = new URL(req.url);

		let id = new URL(req.url).searchParams.get("instanceId");

		// Get the status of an existing instance, if provided
		if (id) {
			let instance = await env.CART_WORKFLOW.get(id);
			return Response.json({
				status: await instance.status(),
			});
		}

		if (url.pathname.startsWith("/new")) {
			let instance = await env.CART_WORKFLOW.create({
				params: {
					cartId: "123",
				},
			});
			return Response.json({
				id: instance.id,
				details: await instance.status(),
			});
		}

		return new Response(
			`<html><body><a href="/new">new instance</a> or add ?instanceId=...</body></html>`,
			{
				headers: {
					"content-type": "text/html;charset=UTF-8",
				},
			},
		);
	},
};
```

Here's a minimal package.json:

```json
{
	"devDependencies": {
		"wrangler": "^3.83.0"
	},
	"dependencies": {
		"mimetext": "^3.0.24"
	}
}
```

And finally [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
name = "cart-invoices"
main = "src/index.ts"
compatibility_date = "2024-10-22"
compatibility_flags = ["nodejs_compat" ]

[[workflows]]
name = "cart-invoices-workflow"
binding = "CART_WORKFLOW"
class_name = "cartInvoicesWorkflow"

[[send_email]]
name = "SEND_EMAIL"
```

</WranglerConfig>

<Render file="wrangler-typegen" product="workers" />

---

# Integrate Workflows with Twilio

URL: https://developers.cloudflare.com/workflows/examples/twilio/

import { Stream } from "~/components";

Using the following [repository](https://github.com/craigsdennis/twilio-cloudflare-workflow), learn how to integrate Cloudflare Workflows with Twilio, a popular cloud communications platform that enables developers to integrate messaging, voice, video, and authentication features into applications via APIs. By the end of the video tutorial, you will become familiarized with the process of setting up Cloudflare Workflows to seamlessly interact with Twilio's APIs, enabling you to build interesting communication features directly into your applications.

<Stream
	id="8b8a1a7c2673adf107bb769ffffa5d77"
	title="Twilio and Workflows"
	thumbnail="2.5s"
/>

---

# Human-in-the-Loop Image Tagging with waitForEvent

URL: https://developers.cloudflare.com/workflows/examples/wait-for-event/

import {  GitHubCode, WranglerConfig } from "~/components"

This example demonstrates how to use the `waitForEvent()` API in Cloudflare Workflows to introduce a human-in-the-loop step. The Workflow is triggered by an image upload, during which metadata is stored in a D1 database. The Workflow then waits for user approval, and upon approval, it uses Workers AI to generate image tags, which are stored in the database. An accompanying Next.js frontend application facilitates the image upload and approval process.

:::note
The example on this page includes only a subset of the full implementation. For the complete codebase and deployment instructions, please refer to the [GitHub repository](https://github.com/cloudflare/docs-examples/tree/main/workflows/waitForEvent).
:::

## Overview of the Workflow

In this Workflow, we simulate a scenario where an uploaded image requires human approval before AI-based processing. An image is uploaded to R2, then Workflow performs the following steps:

1. Stores image metadata in a D1 database.
2. Pauses execution using `waitForEvent()` and waits for an external event sent from the Next.js frontend, indicating approval or rejection.
3. If approved, the Workflow uses Workers AI to generate image tags and stores the tags in the D1 database.
4. If rejected, the Workflow ends without further action.

This pattern is useful in scenarios where certain operations should not proceed without explicit human consent, adding an extra layer of control and safety.

## Frontend Integration

This example includes a Next.js frontend application that facilitates the image upload and approval process. The frontend provides an interface for uploading images, reviewing them, and approving or rejecting them. Upon image upload, the application triggers the Cloudflare Workflow, which then manages the subsequent steps, including waiting for user approval and performing AI-based image tagging upon approval.

Refer to the `/nextjs-workflow-frontend` folder in the [GitHub repository](https://github.com/cloudflare/docs-examples/tree/main/workflows/waitForEvent) for the complete frontend implementation and deployment details.

## Workflow index.ts

The `index.ts` file defines the core logic of the Cloudflare Workflow responsible for handling image uploads, awaiting human approval, and performing AI-based image tagging upon approval. It extends the `WorkflowEntrypoint` class and implements the `run()` method.

For the complete implementation of the `index.ts` file, please refer to the [GitHub repository](https://github.com/cloudflare/docs-examples/blob/main/workflows/waitForEvent/workflow/src/index.ts).

<GitHubCode
  repo="cloudflare/docs-examples"
  file="workflows/waitForEvent/workflow/src/index.ts"
  commit="43b2d19fc9f1098d5138871d06d0b47f0f9c6a43"
  lang="ts"
	lines="17-57"
  useTypeScriptExample={true}
/>

## Workflow wrangler.jsonc

The Workflow configuration is defined in the `wrangler.jsonc` file. This file includes bindings for the R2 bucket, D1 database, Workers AI, and the Workflow itself. Ensure that all necessary bindings and environment variables are correctly set up to match your Cloudflare account and services.

<WranglerConfig>

```json
{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "workflows-waitforevent",
	"main": "src/index.ts",
	"compatibility_date": "2025-04-14",
	"observability": {
		"enabled": true,
		"head_sampling_rate": 1,
	},
	"ai": {
		"binding": "AI"
	},
	"workflows": [
		{
			"name": "workflows-starter",
			"binding": "MY_WORKFLOW",
			"class_name": "MyWorkflow"
		}
	],
	"r2_buckets": [
		{
			"bucket_name": "workflow-demo",
			"binding": "workflow_demo_bucket"
		}
	],
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "workflows-demo-d1",
			"database_id": "66e4fbe9-06ac-4548-abba-2dc42088e13a"
		}
	]
}
```

</WranglerConfig>

For access to the codebase, deployment instructions, and reference architecture, please visit the [GitHub repository](https://github.com/cloudflare/docs-examples/tree/main/workflows/waitForEvent). This resource provides all the necessary tools and information to effectively implement the Workflow and Next.js frontend application.

---

# CLI quick start

URL: https://developers.cloudflare.com/workflows/get-started/cli-quick-start/

import { Render, PackageManagers, WranglerConfig } from "~/components"

Workflows allow you to build durable, multi-step applications using the Workers platform. A Workflow can automatically retry, persist state, run for hours or days, and coordinate between third-party APIs.

You can build Workflows to post-process file uploads to [R2 object storage](/r2/), automate generation of [Workers AI](/workers-ai/) embeddings into a [Vectorize](/vectorize/) vector database, or to trigger user lifecycle emails using your favorite email API.

## Prerequisites

:::caution

This guide is for users who are already familiar with Cloudflare Workers the [durable execution](/workflows/reference/glossary/) programming model it enables.

If you are new to either, we recommend the [introduction to Workflows](/workflows/get-started/guide/) guide, which walks you through how a Workflow is defined, how to persist state, and how to deploy and run your first Workflow.

:::
<Render file="prereqs" product="workers" />

## 1. Create a Workflow

Workflows are defined as part of a Worker script.

To create a Workflow, use the `create cloudflare` (C3) CLI tool, specifying the Workflows starter template:

```sh
npm create cloudflare@latest workflows-starter -- --template "cloudflare/workflows-starter"
```

This will create a new folder called `workflows-tutorial`, which contains two files:

* `src/index.ts` - this is where your Worker script, including your Workflows definition, is defined.
* wrangler.jsonc - the [Wrangler configuration file](/workers/wrangler/configuration/) for your Workers project and your Workflow.

Open the `src/index.ts` file in your text editor. This file contains the following code, which is the most basic instance of a Workflow definition:

```ts title="src/index.ts"
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';

type Env = {
	// Add your bindings here, e.g. Workers KV, D1, Workers AI, etc.
	MY_WORKFLOW: Workflow;
};

// User-defined params passed to your workflow
type Params = {
	email: string;
	metadata: Record<string, string>;
};

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// Can access bindings on `this.env`
		// Can access params on `event.payload`

		const files = await step.do('my first step', async () => {
			// Fetch a list of files from $SOME_SERVICE
			return {
				files: [
					'doc_7392_rev3.pdf',
					'report_x29_final.pdf',
					'memo_2024_05_12.pdf',
					'file_089_update.pdf',
					'proj_alpha_v2.pdf',
					'data_analysis_q2.pdf',
					'notes_meeting_52.pdf',
					'summary_fy24_draft.pdf',
				],
			};
		});

		const apiResponse = await step.do('some other step', async () => {
			let resp = await fetch('https://api.cloudflare.com/client/v4/ips');
			return await resp.json<any>();
		});

		await step.sleep('wait on something', '1 minute');

		await step.do(
			'make a call to write that could maybe, just might, fail',
			// Define a retry strategy
			{
				retries: {
					limit: 5,
					delay: '5 second',
					backoff: 'exponential',
				},
				timeout: '15 minutes',
			},
			async () => {
				// Do stuff here, with access to the state from our previous steps
				if (Math.random() > 0.5) {
					throw new Error('API call to $STORAGE_SYSTEM failed');
				}
			},
		);
	}
}

export default {
	async fetch(req: Request, env: Env): Promise<Response> {
		let id = new URL(req.url).searchParams.get('instanceId');

		// Get the status of an existing instance, if provided
		if (id) {
			let instance = await env.MY_WORKFLOW.get(id);
			return Response.json({
				status: await instance.status(),
			});
		}

		// Spawn a new instance and return the ID and status
		let instance = await env.MY_WORKFLOW.create();
		return Response.json({
			id: instance.id,
			details: await instance.status(),
		});
	},
};
```

Specifically, the code above:

1. Extends the Workflows base class (`WorkflowsEntrypoint`) and defines a `run` method for our Workflow.
2. Passes in our `Params` type as a [type parameter](/workflows/build/events-and-parameters/) so that events that trigger our Workflow are typed.
3. Defines several steps that return state.
4. Defines a custom retry configuration for a step.
5. Binds to the Workflow from a Worker's `fetch` handler so that we can create (trigger) instances of our Workflow via a HTTP call.

You can edit this Workflow by adding (or removing) additional `step` calls, changing the retry configuration, and/or making your own API calls. This Workflow template is designed to illustrate some of Workflows APIs.

## 2. Deploy a Workflow

Workflows are deployed via [`wrangler`](/workers/wrangler/install-and-update/), which is installed when you first ran `npm create cloudflare` above. Workflows are Worker scripts, and are deployed the same way:

```sh
npx wrangler@latest deploy
```

## 3. Run a Workflow

You can run a Workflow via the `wrangler` CLI, via a Worker binding, or via the Workflows [REST API](/api/resources/workflows/methods/list/).

### `wrangler` CLI

```sh
# Trigger a Workflow from the CLI, and pass (optional) parameters as an event to the Workflow.
npx wrangler@latest workflows trigger workflows-tutorial --params={"email": "user@example.com", "metadata": {"id": "1"}}
```

Refer to the [events and parameters documentation](/workflows/build/events-and-parameters/) to understand how events are passed to Workflows.

### Worker binding

You can [bind to a Workflow](/workers/runtime-apis/bindings/#what-is-a-binding) from any handler in a Workers script, allowing you to programatically trigger and pass parameters to a Workflow instance from your own application code.

To bind a Workflow to a Worker, you need to define a `[[workflows]]` binding in your Wrangler configuration:

<WranglerConfig>

```toml
[[workflows]]
# name of your workflow
name = "workflows-starter"
# binding name env.MY_WORKFLOW
binding = "MY_WORKFLOW"
# this is class that extends the Workflow class in src/index.ts
class_name = "MyWorkflow"
```

</WranglerConfig>

You can then invoke the methods on this binding directly from your Worker script's `env` parameter. The `Workflow` type has methods for:

* `create()` - creating (triggering) a new instance of the Workflow, returning the ID.
* `createBatch()` - creating (triggering) a batch of new instances of the Workflow, returning the IDs.
* `get()`- retrieve a Workflow instance by its ID.
* `status()` - get the current status of a unique Workflow instance.

For example, the following Worker will fetch the status of an existing Workflow instance by ID (if supplied), else it will create a new Workflow instance and return its ID:

```ts title="src/index.ts"
// Import the Workflow definition
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent} from 'cloudflare:workers';

interface Env {
  // Matches the binding definition in your Wrangler configuration file
  MY_WORKFLOW: Workflow;
}

export default {
	async fetch(req: Request, env: Env): Promise<Response> {
		let id = new URL(req.url).searchParams.get('instanceId');

		// Get the status of an existing instance, if provided
		if (id) {
			let instance = await env.MY_WORKFLOW.get(id);
			return Response.json({
				status: await instance.status(),
			});
		}

		// Spawn a new instance and return the ID and status
		let instance = await env.MY_WORKFLOW.create();
		return Response.json({
			id: instance.id,
			details: await instance.status(),
		});
	},
};
```

Refer to the [triggering Workflows](/workflows/build/trigger-workflows/) documentation for how to trigger a Workflow from other Workers' handler functions.

## 4. Manage Workflows

:::note

The `wrangler workflows` command requires Wrangler version `3.83.0` or greater. Use `npx wrangler@latest` to always use the latest Wrangler version when invoking commands.

:::

The `wrangler workflows` command group has several sub-commands for managing and inspecting Workflows and their instances:

* List Workflows: `wrangler workflows list`
* Inspect the instances of a Workflow: `wrangler workflows instances list YOUR_WORKFLOW_NAME`
* View the state of a running Workflow instance by its ID: `wrangler workflows instances describe YOUR_WORKFLOW_NAME WORKFLOW_ID`

You can also view the state of the latest instance of a Workflow by using the `latest` keyword instead of an ID:

```sh
npx wrangler@latest workflows instances describe workflows-starter latest
# Or by ID:
# npx wrangler@latest workflows instances describe workflows-starter 12dc179f-9f77-4a37-b973-709dca4189ba
```

The output of `instances describe` shows:

* The status (success, failure, running) of each step
* Any state emitted by the step
* Any `sleep` state, including when the Workflow will wake up
* Retries associated with each step
* Errors, including exception messages

:::note

You do not have to wait for a Workflow instance to finish executing to inspect its current status. The `wrangler workflows instances describe` sub-command will show the status of an in-progress instance, including any persisted state, if it is sleeping, and any errors or retries. This can be especially useful when debugging a Workflow during development.

:::

## Next steps

* Learn more about [how events are passed to a Workflow](/workflows/build/events-and-parameters/).
* Binding to and triggering Workflow instances using the [Workers API](/workflows/build/workers-api/).
* The [Rules of Workflows](/workflows/build/rules-of-workflows/) and best practices for building applications using Workflows.

If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the [Cloudflare Developers community on Discord](https://discord.cloudflare.com).

---

# Guide

URL: https://developers.cloudflare.com/workflows/get-started/guide/

import { Render, PackageManagers, WranglerConfig } from "~/components"

Workflows allow you to build durable, multi-step applications using the Workers platform. A Workflow can automatically retry, persist state, run for hours or days, and coordinate between third-party APIs.

You can build Workflows to post-process file uploads to [R2 object storage](/r2/), automate generation of [Workers AI](/workers-ai/) embeddings into a [Vectorize](/vectorize/) vector database, or to trigger user lifecycle emails using your favorite email API.

This guide will instruct you through:

* Defining your first Workflow and publishing it
* Deploying the Workflow to your Cloudflare account
* Running (triggering) your Workflow and observing its output

At the end of this guide, you should be able to author, deploy and debug your own Workflows applications.

## Prerequisites

<Render file="prereqs" product="workers" />

## 1. Define your Workflow

To create your first Workflow, use the `create cloudflare` (C3) CLI tool, specifying the Workflows starter template:

```sh
npm create cloudflare@latest workflows-starter -- --template "cloudflare/workflows-starter"
```

This will create a new folder called `workflows-starter`.

Open the `src/index.ts` file in your text editor. This file contains the following code, which is the most basic instance of a Workflow definition:

```ts title="src/index.ts"
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';

type Env = {
	// Add your bindings here, e.g. Workers KV, D1, Workers AI, etc.
	MY_WORKFLOW: Workflow;
};

// User-defined params passed to your workflow
type Params = {
	email: string;
	metadata: Record<string, string>;
};

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// Can access bindings on `this.env`
		// Can access params on `event.payload`

		const files = await step.do('my first step', async () => {
			// Fetch a list of files from $SOME_SERVICE
			return {
				files: [
					'doc_7392_rev3.pdf',
					'report_x29_final.pdf',
					'memo_2024_05_12.pdf',
					'file_089_update.pdf',
					'proj_alpha_v2.pdf',
					'data_analysis_q2.pdf',
					'notes_meeting_52.pdf',
					'summary_fy24_draft.pdf',
				],
			};
		});

		const apiResponse = await step.do('some other step', async () => {
			let resp = await fetch('https://api.cloudflare.com/client/v4/ips');
			return await resp.json<any>();
		});

		await step.sleep('wait on something', '1 minute');

		await step.do(
			'make a call to write that could maybe, just might, fail',
			// Define a retry strategy
			{
				retries: {
					limit: 5,
					delay: '5 second',
					backoff: 'exponential',
				},
				timeout: '15 minutes',
			},
			async () => {
				// Do stuff here, with access to the state from our previous steps
				if (Math.random() > 0.5) {
					throw new Error('API call to $STORAGE_SYSTEM failed');
				}
			},
		);
	}
}
```

A Workflow definition:

1. Defines a `run` method that contains the primary logic for your workflow.
2. Has at least one or more calls to `step.do` that encapsulates the logic of your Workflow.
3. Allows steps to return (optional) state, allowing a Workflow to continue execution even if subsequent steps fail, without having to re-run all previous steps.

A single Worker application can contain multiple Workflow definitions, as long as each Workflow has a unique class name. This can be useful for code re-use or to define Workflows which are related to each other conceptually.

Each Workflow is otherwise entirely independent: a Worker that defines multiple Workflows is no different from a set of Workers that define one Workflow each.

## 2. Create your Workflows steps

Each `step` in a Workflow is an independently retriable function.

A `step` is what makes a Workflow powerful, as you can encapsulate errors and persist state as your Workflow progresses from step to step, avoiding your application from having to start from scratch on failure and ultimately build more reliable applications.

* A step can execute code (`step.do`) or sleep a Workflow (`step.sleep`).
* If a step fails (throws an exception), it will be automatically be retried based on your retry logic.
* If a step succeeds, any state it returns will be persisted within the Workflow.

At its most basic, a step looks like this:

```ts title="src/index.ts"
// Import the Workflow definition
import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from "cloudflare:workers"

type Params = {}

// Create your own class that implements a Workflow
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
    // Define a run() method
    async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
        // Define one or more steps that optionally return state.
        let state = step.do("my first step", async () => {

        })

        step.do("my second step", async () => {

        })
    }
}
```

Each call to `step.do` accepts three arguments:

1. (Required) A step name, which identifies the step in logs and telemetry
2. (Required) A callback function that contains the code to run for your step, and any state you want the Workflow to persist
3. (Optional) A `StepConfig` that defines the retry configuration (max retries, delay, and backoff algorithm) for the step

When trying to decide whether to break code up into more than one step, a good rule of thumb is to ask "do I want _all_ of this code to run again if just one part of it fails?". In many cases, you do _not_ want to repeatedly call an API if the following data processing stage fails, or if you get an error when attempting to send a completion or welcome email.

For example, each of the below tasks is ideally encapsulated in its own step, so that any failure — such as a file not existing, a third-party API being down or rate limited — does not cause your entire program to fail.

* Reading or writing files from [R2](/r2/)
* Running an AI task using [Workers AI](/workers-ai/)
* Querying a [D1 database](/d1/) or a database via [Hyperdrive](/hyperdrive/)
* Calling a third-party API

If a subsequent step fails, your Workflow can retry from that step, using any state returned from a previous step. This can also help you avoid unnecessarily querying a database or calling an paid API repeatedly for data you have already fetched.

:::note

The term "Durable Execution" is widely used to describe this programming model.

"Durable" describes the ability of the program (application) to implicitly persist state without you having to manually write to an external store or serialize program state.

:::

## 3. Configure your Workflow

Before you can deploy a Workflow, you need to configure it.

Open the Wrangler file at the root of your `workflows-starter` folder, which contains the following `[[workflows]]` configuration:

<WranglerConfig>

```toml title="wrangler.toml"
#:schema node_modules/wrangler/config-schema.json
name = "workflows-starter"
main = "src/index.ts"
compatibility_date = "2024-10-22"

[[workflows]]
# name of your workflow
name = "workflows-starter"
# binding name env.MY_WORKFLOW
binding = "MY_WORKFLOW"
# this is class that extends the Workflow class in src/index.ts
class_name = "MyWorkflow"
```

</WranglerConfig>

:::note

If you have changed the name of the Workflow in your Wrangler commands, the JavaScript class name, or the name of the project you created, ensure that you update the values above to match the changes.

:::

This configuration tells the Workers platform which JavaScript class represents your Workflow, and sets a `binding` name that allows you to run the Workflow from other handlers or to call into Workflows from other Workers scripts.

## 4. Bind to your Workflow

We have a very basic Workflow definition, but now need to provide a way to call it from within our code. A Workflow can be triggered by:

1. External HTTP requests via a `fetch()` handler
2. Messages from a [Queue](/queues/)
3. A schedule via [Cron Trigger](/workers/configuration/cron-triggers/)
4. Via the [Workflows REST API](/api/resources/workflows/methods/list/) or [wrangler CLI](/workers/wrangler/commands/#workflows)

Return to the `src/index.ts` file we created in the previous step and add a `fetch` handler that _binds_ to our Workflow. This binding allows us to create new Workflow instances, fetch the status of an existing Workflow, pause and/or terminate a Workflow.

```ts title="src/index.ts"
// This is in the same file as your Workflow definition

export default {
	async fetch(req: Request, env: Env): Promise<Response> {
		let url = new URL(req.url);

		if (url.pathname.startsWith('/favicon')) {
			return Response.json({}, { status: 404 });
		}

		// Get the status of an existing instance, if provided
		let id = url.searchParams.get('instanceId');
		if (id) {
			let instance = await env.MY_WORKFLOW.get(id);
			return Response.json({
				status: await instance.status(),
			});
		}

		// Spawn a new instance and return the ID and status
		let instance = await env.MY_WORKFLOW.create();
		return Response.json({
			id: instance.id,
			details: await instance.status(),
		});
	},
};
```

The code here exposes a HTTP endpoint that generates a random ID and runs the Workflow, returning the ID and the Workflow status. It also accepts an optional `instanceId` query parameter that retrieves the status of a Workflow instance by its ID.

:::note

In a production application, you might choose to put authentication in front of your endpoint so that only authorized users can run a Workflow. Alternatively, you could pass messages to a Workflow [from a Queue consumer](/queues/reference/how-queues-works/#consumers) in order to allow for long-running tasks.

:::

### Review your Workflow code

:::note

This is the full contents of the `src/index.ts` file pulled down when you used the `cloudflare/workflows-starter` template at the beginning of this guide.

:::

Before you deploy, you can review the full Workflows code and the `fetch` handler that will allow you to trigger your Workflow over HTTP:

```ts title="src/index.ts"
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';

type Env = {
	// Add your bindings here, e.g. Workers KV, D1, Workers AI, etc.
	MY_WORKFLOW: Workflow;
};

// User-defined params passed to your workflow
type Params = {
	email: string;
	metadata: Record<string, string>;
};

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		// Can access bindings on `this.env`
		// Can access params on `event.payload`

		const files = await step.do('my first step', async () => {
			// Fetch a list of files from $SOME_SERVICE
			return {
				files: [
					'doc_7392_rev3.pdf',
					'report_x29_final.pdf',
					'memo_2024_05_12.pdf',
					'file_089_update.pdf',
					'proj_alpha_v2.pdf',
					'data_analysis_q2.pdf',
					'notes_meeting_52.pdf',
					'summary_fy24_draft.pdf',
				],
			};
		});

		const apiResponse = await step.do('some other step', async () => {
			let resp = await fetch('https://api.cloudflare.com/client/v4/ips');
			return await resp.json<any>();
		});

		await step.sleep('wait on something', '1 minute');

		await step.do(
			'make a call to write that could maybe, just might, fail',
			// Define a retry strategy
			{
				retries: {
					limit: 5,
					delay: '5 second',
					backoff: 'exponential',
				},
				timeout: '15 minutes',
			},
			async () => {
				// Do stuff here, with access to the state from our previous steps
				if (Math.random() > 0.5) {
					throw new Error('API call to $STORAGE_SYSTEM failed');
				}
			},
		);
	}
}

export default {
	async fetch(req: Request, env: Env): Promise<Response> {
		let url = new URL(req.url);

		if (url.pathname.startsWith('/favicon')) {
			return Response.json({}, { status: 404 });
		}

		// Get the status of an existing instance, if provided
		let id = url.searchParams.get('instanceId');
		if (id) {
			let instance = await env.MY_WORKFLOW.get(id);
			return Response.json({
				status: await instance.status(),
			});
		}

		// Spawn a new instance and return the ID and status
		let instance = await env.MY_WORKFLOW.create();
		return Response.json({
			id: instance.id,
			details: await instance.status(),
		});
	},
};
```

## 5. Deploy your Workflow

Deploying a Workflow is identical to deploying a Worker.

```sh
npx wrangler deploy
```
```sh output
# Note the "Workflows" binding mentioned here, showing that
# wrangler has detected your Workflow
Your worker has access to the following bindings:
- Workflows:
  - MY_WORKFLOW: MyWorkflow (defined in workflows-starter)
Uploaded workflows-starter (2.53 sec)
Deployed workflows-starter triggers (1.12 sec)
  https://workflows-starter.YOUR_WORKERS_SUBDOMAIN.workers.dev
  workflow: workflows-starter
```

A Worker with a valid Workflow definition will be automatically registered by Workflows. You can list your current Workflows using Wrangler:

```sh
npx wrangler workflows list
```
```sh output
Showing last 1 workflow:
┌───────────────────┬───────────────────┬────────────┬─────────────────────────┬─────────────────────────┐
│ Name              │ Script name       │ Class name │ Created                 │ Modified                │
├───────────────────┼───────────────────┼────────────┼─────────────────────────┼─────────────────────────┤
│ workflows-starter │ workflows-starter │ MyWorkflow │ 10/23/2024, 11:33:58 AM │ 10/23/2024, 11:33:58 AM │
└───────────────────┴───────────────────┴────────────┴─────────────────────────┴─────────────────────────┘
```

## 6. Run and observe your Workflow

With your Workflow deployed, you can now run it.

1. A Workflow can run in parallel: each unique invocation of a Workflow is an _instance_ of that Workflow.
2. An instance will run to completion (success or failure).
3. Deploying newer versions of a Workflow will cause all instances after that point to run the newest Workflow code.

:::note

Because Workflows can be long running, it is possible to have running instances that represent different versions of your Workflow code over time.

:::

To trigger our Workflow, we will use the `wrangler` CLI and pass in an optional `--payload`. The `payload` will be passed to your Workflow's `run` method handler as an `Event`.

```sh
npx wrangler workflows trigger workflows-starter '{"hello":"world"}'
```
```sh output
# Workflow instance "12dc179f-9f77-4a37-b973-709dca4189ba" has been queued successfully
```

To inspect the current status of the Workflow instance we just triggered, we can either reference it by ID or by using the keyword `latest`:

```sh
npx wrangler@latest workflows instances describe workflows-starter latest
# Or by ID:
# npx wrangler@latest workflows instances describe workflows-starter 12dc179f-9f77-4a37-b973-709dca4189ba
```
```sh output
Workflow Name:         workflows-starter
Instance Id:           f72c1648-dfa3-45ea-be66-b43d11d216f8
Version Id:            cedc33a0-11fa-4c26-8a8e-7d28d381a291
Status:                ✅ Completed
Trigger:               🌎 API
Queued:                10/15/2024, 1:55:31 PM
Success:               ✅ Yes
Start:                 10/15/2024, 1:55:31 PM
End:                   10/15/2024, 1:56:32 PM
Duration:              1 minute
Last Successful Step:  make a call to write that could maybe, just might, fail-1
Steps:

  Name:      my first step-1
  Type:      🎯 Step
  Start:     10/15/2024, 1:55:31 PM
  End:       10/15/2024, 1:55:31 PM
  Duration:  0 seconds
  Success:   ✅ Yes
  Output:    "{\"inputParams\":[{\"timestamp\":\"2024-10-15T13:55:29.363Z\",\"payload\":{\"hello\":\"world\"}}],\"files\":[\"doc_7392_rev3.pdf\",\"report_x29_final.pdf\",\"memo_2024_05_12.pdf\",\"file_089_update.pdf\",\"proj_alpha_v2.pdf\",\"data_analysis_q2.pdf\",\"notes_meeting_52.pdf\",\"summary_fy24_draft.pdf\",\"plan_2025_outline.pdf\"]}"
┌────────────────────────┬────────────────────────┬───────────┬────────────┐
│ Start                  │ End                    │ Duration  │ State      │
├────────────────────────┼────────────────────────┼───────────┼────────────┤
│ 10/15/2024, 1:55:31 PM │ 10/15/2024, 1:55:31 PM │ 0 seconds │ ✅ Success │
└────────────────────────┴────────────────────────┴───────────┴────────────┘

  Name:      some other step-1
  Type:      🎯 Step
  Start:     10/15/2024, 1:55:31 PM
  End:       10/15/2024, 1:55:31 PM
  Duration:  0 seconds
  Success:   ✅ Yes
  Output:    "{\"result\":{\"ipv4_cidrs\":[\"173.245.48.0/20\",\"103.21.244.0/22\",\"103.22.200.0/22\",\"103.31.4.0/22\",\"141.101.64.0/18\",\"108.162.192.0/18\",\"190.93.240.0/20\",\"188.114.96.0/20\",\"197.234.240.0/22\",\"198.41.128.0/17\",\"162.158.0.0/15\",\"104.16.0.0/13\",\"104.24.0.0/14\",\"172.64.0.0/13\",\"131.0.72.0/22\"],\"ipv6_cidrs\":[\"2400:cb00::/32\",\"2606:4700::/32\",\"2803:f800::/32\",\"2405:b500::/32\",\"2405:8100::/32\",\"2a06:98c0::/29\",\"2c0f:f248::/32\"],\"etag\":\"38f79d050aa027e3be3865e495dcc9bc\"},\"success\":true,\"errors\":[],\"messages\":[]}"
┌────────────────────────┬────────────────────────┬───────────┬────────────┐
│ Start                  │ End                    │ Duration  │ State      │
├────────────────────────┼────────────────────────┼───────────┼────────────┤
│ 10/15/2024, 1:55:31 PM │ 10/15/2024, 1:55:31 PM │ 0 seconds │ ✅ Success │
└────────────────────────┴────────────────────────┴───────────┴────────────┘

  Name:      wait on something-1
  Type:      💤 Sleeping
  Start:     10/15/2024, 1:55:31 PM
  End:       10/15/2024, 1:56:31 PM
  Duration:  1 minute

  Name:      make a call to write that could maybe, just might, fail-1
  Type:      🎯 Step
  Start:     10/15/2024, 1:56:31 PM
  End:       10/15/2024, 1:56:32 PM
  Duration:  1 second
  Success:   ✅ Yes
  Output:    null
┌────────────────────────┬────────────────────────┬───────────┬────────────┬───────────────────────────────────────────┐
│ Start                  │ End                    │ Duration  │ State      │ Error                                     │
├────────────────────────┼────────────────────────┼───────────┼────────────┼───────────────────────────────────────────┤
│ 10/15/2024, 1:56:31 PM │ 10/15/2024, 1:56:31 PM │ 0 seconds │ ❌ Error   │ Error: API call to $STORAGE_SYSTEM failed │
├────────────────────────┼────────────────────────┼───────────┼────────────┼───────────────────────────────────────────┤
│ 10/15/2024, 1:56:32 PM │ 10/15/2024, 1:56:32 PM │ 0 seconds │ ✅ Success │                                           │
└────────────────────────┴────────────────────────┴───────────┴────────────┴───────────────────────────────────────────┘
```

From the output above, we can inspect:

* The status (success, failure, running) of each step
* Any state emitted by the step
* Any `sleep` state, including when the Workflow will wake up
* Retries associated with each step
* Errors, including exception messages

:::note

You do not have to wait for a Workflow instance to finish executing to inspect its current status. The `wrangler workflows instances describe` sub-command will show the status of an in-progress instance, including any persisted state, if it is sleeping, and any errors or retries. This can be especially useful when debugging a Workflow during development.

:::

In the previous step, we also bound a Workers script to our Workflow. You can trigger a Workflow by visiting the (deployed) Workers script in a browser or with any HTTP client.

```sh
# This must match the URL provided in step 6
curl -s https://workflows-starter.YOUR_WORKERS_SUBDOMAIN.workers.dev/
```
```sh output
{"id":"16ac31e5-db9d-48ae-a58f-95b95422d0fa","details":{"status":"queued","error":null,"output":null}}
```

{/*

## 7. (Optional) Clean up

You can optionally delete the Workflow, which will prevent the creation of any (all) instances by using `wrangler`:

```sh
npx wrangler workflows delete my-workflow
```

Re-deploying the Workers script containing your Workflow code will re-create the Workflow.

*/}

---

## Next steps

* Learn more about [how events are passed to a Workflow](/workflows/build/events-and-parameters/).
* Learn more about binding to and triggering Workflow instances using the [Workers API](/workflows/build/workers-api/).
* Learn more about the [Rules of Workflows](/workflows/build/rules-of-workflows/) and best practices for building applications using Workflows.

If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the [Cloudflare Developers community on Discord](https://discord.cloudflare.com).

---

# Observability

URL: https://developers.cloudflare.com/workflows/observability/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Get started

URL: https://developers.cloudflare.com/workflows/get-started/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Metrics and analytics

URL: https://developers.cloudflare.com/workflows/observability/metrics-analytics/

Workflows expose metrics that allow you to inspect and measure Workflow execution, error rates, steps, and total duration across each (and all) of your Workflows.

The metrics displayed in the [Cloudflare dashboard](https://dash.cloudflare.com/) charts are queried from Cloudflare’s [GraphQL Analytics API](/analytics/graphql-api/). You can access the metrics [programmatically](#query-via-the-graphql-api) via GraphQL or HTTP client.

## Metrics

Workflows currently export the below metrics within the `workflowsAdaptiveGroups` GraphQL dataset.

| Metric             | GraphQL Field Name | Description                                                                                                                |
| ------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Read Queries (qps) | `readQueries`      | The number of read queries issued against a database. This is the raw number of read queries, and is not used for billing. |

Metrics can be queried (and are retained) for the past 31 days.

### Labels and dimensions

The `workflowsAdaptiveGroups` dataset provides the following dimensions for filtering and grouping query results:

- `workflowName` - Workflow name - e.g. `my-workflow`
- `instanceId` - Instance ID
- `stepName` - Step name
- `eventType` - Event type (see [event types](#event-types))
- `stepCount` - Step number within a given instance
- `date` - The date when the Workflow was triggered
- `datetimeFifteenMinutes` - The date and time truncated to fifteen minutes
- `datetimeFiveMinutes` - The date and time truncated to five minutes
- `datetimeHour` - The date and time truncated to the hour
- `datetimeMinute` - The date and time truncated to the minute

### Event types

The `eventType` metric allows you to filter (or groupBy) Workflows and steps based on their last observed status.

The possible values for `eventType` are documented below:

#### Workflows-level status labels

- `WORKFLOW_QUEUED` - the Workflow is queued, but not currently running. This can happen when you are at the [concurrency limit](/workflows/reference/limits/) and new instances are waiting for currently running instances to complete.
- `WORKFLOW_START` - the Workflow has started and is running.
- `WORKFLOW_SUCCESS` - the Workflow finished without errors.
- `WORKFLOW_FAILURE` - the Workflow failed due to errors (exhausting retries, errors thrown, etc).
- `WORKFLOW_TERMINATED` - the Workflow was explicitly terminated.

#### Step-level status labels

- `STEP_START` - the step has started and is running.
- `STEP_SUCCESS` - the step finished without errors.
- `STEP_FAILURE` - the step failed due to an error.
- `SLEEP_START` - the step is sleeping.
- `SLEEP_COMPLETE` - the step last finished sleeping.
- `ATTEMPT_START` - a step is retrying.
- `ATTEMPT_SUCCESS` - the retry succeeded.
- `ATTEMPT_FAILURE` - the retry attempt failed.

## View metrics in the dashboard

Per-Workflow and instance analytics for Workflows are available in the Cloudflare dashboard. To view current and historical metrics for a database:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to [**Workers & Pages** > **Workflows**](https://dash.cloudflare.com/?to=/:account/workers/workflows).
3. Select a Workflow to view its metrics.

You can optionally select a time window to query. This defaults to the last 24 hours.

## Query via the GraphQL API

You can programmatically query analytics for your Workflows via the [GraphQL Analytics API](/analytics/graphql-api/). This API queries the same datasets as the Cloudflare dashboard, and supports GraphQL [introspection](/analytics/graphql-api/features/discovery/introspection/).

Workflows GraphQL datasets require an `accountTag` filter with your Cloudflare account ID, and includes the `workflowsAdaptiveGroups` dataset.

### Examples

To query the count (number of workflow invocations) and sum of `wallTime` for a given `$workflowName` between `$datetimeStart` and `$datetimeEnd`, grouping by `date`:

```graphql graphql-api-explorer
query WorkflowInvocationsExample(
	$accountTag: string!
	$datetimeStart: Time
	$datetimeEnd: Time
	$workflowName: string
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			wallTime: workflowsAdaptiveGroups(
				limit: 10000
				filter: {
					datetimeHour_geq: $datetimeStart
					datetimeHour_leq: $datetimeEnd
					workflowName: $workflowName
				}
				orderBy: [count_DESC]
			) {
				count
				sum {
					wallTime
				}
				dimensions {
					date: datetimeHour
				}
			}
		}
	}
}
```

Here we are doing the same for `wallTime`, `instanceRuns` and `stepCount` in the same query:

```graphql graphql-api-explorer
query WorkflowInvocationsExample2(
	$accountTag: string!
	$datetimeStart: Time
	$datetimeEnd: Time
	$workflowName: string
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			instanceRuns: workflowsAdaptiveGroups(
				limit: 10000
				filter: {
					datetimeHour_geq: $datetimeStart
					datetimeHour_leq: $datetimeEnd
					workflowName: $workflowName
					eventType: "WORKFLOW_START"
				}
				orderBy: [count_DESC]
			) {
				count
				dimensions {
					date: datetimeHour
				}
			}
			stepCount: workflowsAdaptiveGroups(
				limit: 10000
				filter: {
					datetimeHour_geq: $datetimeStart
					datetimeHour_leq: $datetimeEnd
					workflowName: $workflowName
					eventType: "WORKFLOW_START"
				}
				orderBy: [count_DESC]
			) {
				count
				dimensions {
					date: datetimeHour
				}
			}
			wallTime: workflowsAdaptiveGroups(
				limit: 10000
				filter: {
					datetimeHour_geq: $datetimeStart
					datetimeHour_leq: $datetimeEnd
					workflowName: $workflowName
				}
				orderBy: [count_DESC]
			) {
				count
				sum {
					wallTime
				}
				dimensions {
					date: datetimeHour
				}
			}
		}
	}
}
```

Here lets query `workflowsAdaptive` for raw data about `$instanceId` between `$datetimeStart` and `$datetimeEnd`:

```graphql graphql-api-explorer
query WorkflowsAdaptiveExample(
	$accountTag: string!
	$datetimeStart: Time
	$datetimeEnd: Time
	$instanceId: string
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			workflowsAdaptive(
				limit: 100
				filter: {
					datetime_geq: $datetimeStart
					datetime_leq: $datetimeEnd
					instanceId: $instanceId
				}
				orderBy: [datetime_ASC]
			) {
				datetime
				eventType
				workflowName
				instanceId
				stepCount
				wallTime
			}
		}
	}
}
```

#### GraphQL query variables

Example values for the query variables:

```json
{
	"accountTag": "fedfa729a5b0ecfd623bca1f9000f0a22",
	"datetimeStart": "2024-10-20T00:00:00Z",
	"datetimeEnd": "2024-10-29T00:00:00Z",
	"workflowName": "shoppingCart",
	"instanceId": "ecc48200-11c4-22a3-b05f-88a3c1c1db81"
}
```

---

# Changelog

URL: https://developers.cloudflare.com/workflows/reference/changelog/

import { ProductReleaseNotes } from "~/components"

{/* <!-- Actual content lives in /data/changelogs/workflows.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Glossary

URL: https://developers.cloudflare.com/workflows/reference/glossary/

import { Glossary } from "~/components"

Review the definitions for terms used across Cloudflare's Workflows documentation.

<Glossary product="workflows" />

---

# Platform

URL: https://developers.cloudflare.com/workflows/reference/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Limits

URL: https://developers.cloudflare.com/workflows/reference/limits/

import { Render, WranglerConfig } from "~/components"

Limits that apply to authoring, deploying, and running Workflows are detailed below.

Many limits are inherited from those applied to Workers scripts and as documented in the [Workers limits](/workers/platform/limits/) documentation.

| Feature                                   | Workers Free            | Workers Paid          |
| ----------------------------------------- | ----------------------- | --------------------- |
| Workflow class definitions per script     | 3MB max script size per [Worker size limits](/workers/platform/limits/#account-plan-limits) | 10MB max script size per [Worker size limits](/workers/platform/limits/#account-plan-limits)
| Total scripts per account                 | 100 | 500 (shared with [Worker script limits](/workers/platform/limits/#account-plan-limits) |
| Compute time per step [^3]                | 10 seconds | 30 seconds (default) / configurable to 5 minutes of [active CPU time](/workers/platform/limits/#cpu-time) |
| Duration (wall clock) per step [^3]       | Unlimited | Unlimited - for example, waiting on network I/O calls or querying a database |
| Maximum persisted state per step          | 1MiB (2^20 bytes) | 1MiB (2^20 bytes) |
| Maximum event [payload size](/workflows/build/events-and-parameters/) | 1MiB (2^20 bytes) | 1MiB (2^20 bytes) |
| Maximum state that can be persisted per Workflow instance | 100MB | 1GB |
| Maximum `step.sleep` duration             | 365 days (1 year) | 365 days (1 year) |
| Maximum steps per Workflow [^5]           | 1024 | 1024 |
| Maximum Workflow executions               | 100,000 per day [shared with Workers daily limit](/workers/platform/limits/#worker-limits) | Unlimited |
| Concurrent Workflow instances (executions) per account   | 25 | 4500 |
| Maximum Workflow instance creation rate | 100 per 10 seconds [^6] | 100 per 10 seconds [^6] |
| Maximum number of [queued instances](/workflows/observability/metrics-analytics/#event-types) | 10,000 | 100,000 |
| Retention limit for completed Workflow state | 3 days | 30 days [^2] |
| Maximum length of a Workflow ID [^4]         | 64 characters | 64 characters |

[^2]: Workflow state and logs will be retained for 3 days on the Workers Free plan and for 7 days on the Workers Paid plan.

[^3]: A Workflow instance can run forever, as long as each step does not take more than the CPU time limit and the maximum number of steps per Workflow is not reached. 

[^4]: Match pattern: _```^[a-zA-Z0-9_][a-zA-Z0-9-_]*$```_

[^5]: `step.sleep` do not count towards the max. steps limit

[^6]: Workflows will return a HTTP 429 rate limited error if you exceed the rate of new Workflow instance creation.

<Render file="limits_increase" product="workers" />

### Increasing Workflow CPU limits

Workflows are Worker scripts, and share the same [per invocation CPU limits](/workers/platform/limits/#worker-limits) as any Workers do. Note that CPU time is active processing time: not time spent waiting on network requests, storage calls, or other general I/O, which don't count towards your CPU time or Workflows compute consumption.

By default, the maximum CPU time per Workflow invocation is set to 30 seconds, but can be increased for all invocations associated with a Workflow definition by setting `limits.cpu_ms` in your Wrangler configuration:

<WranglerConfig>

```jsonc
{
  // ...rest of your configuration...
  "limits": {
    "cpu_ms": 300000, // 300,000 milliseconds = 5 minutes
  },
  // ...rest of your configuration...
}
```

</WranglerConfig>

To learn more about CPU time and limits, [review the Workers documentation](/workers/platform/limits/#cpu-time).

---

# Pricing

URL: https://developers.cloudflare.com/workflows/reference/pricing/

import { Render } from "~/components"

:::note

Workflows is included in both the Free and Paid [Workers plans](/workers/platform/pricing/#workers).

:::

Workflows pricing is identical to [Workers Standard pricing](/workers/platform/pricing/#workers) and are billed on three dimensions:

* **CPU time**: the total amount of compute (measured in milliseconds) consumed by a given Workflow.
* **Requests** (invocations): the number of Workflow invocations. [Subrequests](/workers/platform/limits/#subrequests) made from a Workflow do not incur additional request costs.
* **Storage**: the total amount of storage (measured in GB) persisted by your Workflows.

A Workflow that is waiting on a response to an API call, paused as a result of calling `step.sleep`, or otherwise idle, does not incur CPU time.

### Workflows Pricing

| Unit | Workers Free | Workers Paid |
|------|--------------|--------------|
| Requests (millions) | 100,000 per day ([shared with Workers requests](/workers/platform/pricing/#workers)| 10 million included per month + $0.30 per additional million	|
| CPU time (ms) | 10 milliseconds of CPU time per invocation | 30 million CPU milliseconds included per month + $0.02 per additional million CPU milliseconds |
| Storage (GB-mo) | 1GB | 1GB included per month + $0.20/ GB-month |

:::note[CPU limits]

You can increase the CPU limit available to your Workflow instances up to 5 minutes per Workflow by [setting the `limits.cpu_ms` property](/workers/wrangler/configuration/#limits) in your Wrangler configuration.

:::

### Storage Usage

:::note

Storage billing for Workflows will go live on September 15th, 2025.

:::

Storage is billed using gigabyte-month (GB-month) as the billing metric, identical to [Durable Objects SQL storage](/durable-objects/platform/pricing/#sqlite-storage-backend). A GB-month is calculated by averaging the peak storage per day over a billing period (30 days).

* Storage is calculated across all instances, and includes running, errored, sleeping and completed instances.
* By default, instance state is retained for [3 days on the Free plan](/workflows/reference/limits/) and [7 days on the Paid plan](/workflows/reference/limits/).
* When creating a Workflow instance, you can set a shorter state retention period if you do not need to retain state for errored or completed Workflows.
* Deleting instances via the [Workers API](/workflows/build/workers-api/), [Wrangler CLI](/workers/wrangler/commands/#workflows), REST API, or dashboard will free up storage. Note that it may take a few minutes for storage limits to update.

An instance that attempts to store state when your have reached the storage limit on the Free plan will cause an error to be thrown.

## Frequently Asked Questions

Frequently asked questions related to Workflows pricing:

### Are there additional costs for Workflows?

No. Workflows are priced based on the same compute (CPU time), requests (invocations) as Workers, as well as storage (state from a Workflow).

### Are Workflows available on the [Workers Free](/workers/platform/pricing/#workers) plan?

Yes.

### What is a Workflow invocation?

A Workflow invocation is when you trigger a new Workflow instance: for example, via the [Workers API](/workflows/build/workers-api/), wrangler CLI, or REST API. Steps within a Workflow are not invocations.

### How do Workflows show up on my bill?

Workflows are billed as Workers, and share the same CPU time and request SKUs.

### Are there any limits to Workflows?

Refer to the published [limits](/workflows/reference/limits/) documentation.

---

# Framework guides

URL: https://developers.cloudflare.com/workers/framework-guides/

import {
	Description,
	DirectoryListing
} from "~/components";

<Description>
Create full-stack applications deployed to Cloudflare Workers.
</Description>

<DirectoryListing folder="workers/framework-guides" maxDepth={4}/>

---

# Blocking Triggers

URL: https://developers.cloudflare.com/zaraz/advanced/blocking-triggers/

Blocking Triggers are triggers that instead of being used to define when to start an action, are used to define when to _not_ start an action. You may need to block one or more actions in a tool from firing when a specific condition arises. For these cases, you can set Blocking Triggers.

Every tool action has Firing Triggers assigned to it. Blocking Triggers are optional and, if defined, will conditionally prevent the action from starting. When you add Blocking Triggers to an action, the action will not fire if any of its Blocking Triggers are true. If the tool has more than one action, other actions without these Blocking Triggers will still work.

To conditionally block all actions in a tool, you have to configure Blocking Triggers on every action that belongs to that tool. Note that when you use Blocking Triggers, Zaraz will still load on the page.

To use Blocking Triggers, start by [creating the trigger](/zaraz/custom-actions/create-trigger/) with the conditions you want to use to block an event. Then:

1. Go to [**Zaraz**](https://dash.cloudflare.com/?to=/:account/:zone/zaraz) > **Tools Configuration**.
2. Under **Third-party tools**, locate the tool with the action you want to block and select **Edit**.
3. In **Action Name**, select the action you want to block.
4. In **Blocking Triggers**, use the dropdown menu to add a trigger to block the action.
5. Select **Save**.

:::note

Blocking Triggers are useful if you wish to block specific actions, or even specific tools from firing, while keeping others active. If you wish to turn off Zaraz entirely on specific pages/domains/subdomains, or load Zaraz depending on other factors such as cookies, we recommend [loading Zaraz selectively](/zaraz/advanced/load-selectively/).

:::

---

# Context Enricher

URL: https://developers.cloudflare.com/zaraz/advanced/context-enricher/

The Zaraz Context Enricher is a tool to modify or enrich [the context](/zaraz/reference/context/) that is being used across Zaraz using a Cloudflare Worker. The Context Enricher allows you access to the client and system variables.

## Creating a Worker

To use a Context Enricher, you first need to create a new Cloudflare Worker. You can do this through the Cloudflare dashboard or by using [Wrangler](/workers/get-started/guide/).

To create a new Worker in the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/).
2. Go to **Workers & Pages** and select **Create application**.
3. Give a name to your Worker and select **Deploy**.
4. Select **Edit code**.

You have now created a basic Worker that responds with "Hello world." To make this Worker functional when using it as a Context Enricher, you need to change the code to return the context back:

```js
export default {
  async fetch(request, env, ctx) {
    const { system, client } = await request.json();

    // Here goes your modification to the system or client objects.
    /*
      For example, to change the country to a fictitious "Pirate's Island" ("PI"), use:
      system.device.location.country = 'PI';
    */

    return new Response(JSON.stringify({ system, client }));
  },
};
```

Keep reading for more complete examples of different use cases or refer to [Zaraz Context](/zaraz/reference/context/).

## Configuring your Context Enricher

Now that your Worker is published, you can select it in your Zaraz settings:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/).
2. Go to **Zaraz** > **Settings**.
3. Select your Context Enricher Worker.
4. Save your settings.

Your Context Enricher will now run on all Zaraz requests in that given zone.

## Example Context Enricher

### Adding arbitrary information using an API

You can use the Context Enricher to add information to your context. For example, you could use an API to get the current weather for the user's location and add it to the context.

```js
function getWeatherForLocation({ client, system }) {
  // Get the location from the context.
  const { city } = system.device.location;

  // Get the weather from an API.
  const response = await fetch(
    `https://wttr.in/${encodeURIComponents(city)}?format=j1`
  ).then((response) => response.json());

  // Add the weather to the context.
  client.weather = weather;

  return { client, system };
}

export default {
  async fetch(request, env, ctx) {
    const { system, client } = await request.json();

    // Add the weather to the context.
    const newContext = getWeatherForLocation({ system, client });

    // Return as JSON
    return new Response(JSON.stringify(newContext));
  },
};
```

Now, you can use the weather property anywhere in Zaraz by choosing the `Track Property` from the attributes input and entering `weather`.

### Masking sensitive information, such as emails

Let's assume we want to redact sensitive information, such as emails. For this, we're going to replace all occurrences of email addresses throughout the context. Please keep in mind that this is only an example and might not fit all edge or use cases.

For the sake of simplicity of this example, we're going to replace all strings that contain an `@` symbol:

```js
function redactEmailAddressesFromObject(context) {
  // Loop through all keys of the object.
  for (const key in context) {
    // Check if the value is a string.
    if (typeof context[key] === "string") {
      // Check if the string contains an @ symbol.
      if (context[key].includes("@")) {
        // Replace the string with a redacted version.
        context[key] = "REDACTED@example.com";
      }
    } else if (typeof context[key] === "object") {
      // Recursively call this function to redact the object.
      context[key] = redactEmailAddressesFromObject(context[key]);
    }
  }

  return context;
}

export default {
  async fetch(request, env, ctx) {
    const { system, client } = await request.json();

    // Redact email addresses from the context.
    const newContext = redactEmailAddressesFromObject({ system, client });

    // Return as JSON
    return new Response(JSON.stringify(newContext));
  },
};
```

---

# Data layer compatibility mode

URL: https://developers.cloudflare.com/zaraz/advanced/datalayer-compatibility/

Cloudflare Zaraz offers backwards compatibility with the `dataLayer` function found in tag management software, used to track events and other parameters. This way you can keep your current implementation and Cloudflare Zaraz will automatically collect your events.

To keep the Zaraz script as small and fast as possible, the data layer compatibility mode is disabled by default. To enable it:

1. Go to [**Zaraz**](https://dash.cloudflare.com/?to=/:account/:zone/zaraz) > **Settings**.
2. Enable the **Data layer compatibility mode** toggle. Refer to [Zaraz settings](/zaraz/reference/settings/) for more information.

## Using the data layer with Zaraz

After enabling the compatibility mode, Zaraz will automatically translate your `dataLayer.push()` calls to `zaraz.track()`, so you can keep using the `dataLayer.push()` function to send events from the browser to Zaraz.

:::note[Note]
Zaraz does not support automatic e-commerce mapping through the `dataLayer` compatibility mode. If you need to track e-commerce events, refer to the [E-commerce API](/zaraz/web-api/ecommerce/).
:::

Events will only be sent to Zaraz if your pushed object includes an `event` key. The `event`key is used as the name for the Zaraz event. Other keys will become part of the `eventProperties` object. The following example shows how a purchase event will be sent using the data layer to Zaraz — note that the parameters inside the object depend on what you want to track:

```js
dataLayer.push({
  event: 'purchase',
  price: '24',
  currency: 'USD',
  transactionID: '12345678',
});
```

Cloudflare Zaraz then translates the `dataLayer.push()` call to a `zaraz.track()` call. So, `dataLayer.push({event: "purchase", price: "24", "currency": "USD"})` is equivalent to `zaraz.track("purchase", {"price": "24", "currency": "USD"})`.

Because Zaraz converts the `dataLayer.push()` call to `zaraz.track()`, creating a trigger based on `dataLayer.push()` calls is the same as creating triggers for `zaraz.track()`. As an example, the trigger below will match the above `dataLayer.push()` call because it matches the event with `purchase`.

| Rule type    | Variable name | Match operation | Match string |
| ------------ | ------------- | --------------- | ------------ |
| *Match rule* | *Event Name*  | *Equals*        | `purchase`   |

We do not recommend using `dataLayer`. However, as many websites employ it, Cloudflare Zaraz has this automatic translation layer that converts it to `zaraz.track()`.

---

# Domains not proxied by Cloudflare

URL: https://developers.cloudflare.com/zaraz/advanced/domains-not-proxied/

You can load Zaraz on domains that are not proxied through Cloudflare. However, you will need to create a separate domain, or subdomain, proxied by Cloudflare (also [known as orange-clouded](https://community.cloudflare.com/t/step-3-enabling-the-orange-cloud/52715) domains), and load the script from it:

1. Create a new subdomain like `my-subdomain.example.com` and proxy it through Cloudflare. Refer to [Enabling the Orange Cloud](https://community.cloudflare.com/t/step-3-enabling-the-orange-cloud/52715) for more information.
2. Add the following script to your main website’s HTML, immediately before the `</head>` tag closes:

```html
<script src="https://my-subdomain.example.com/cdn-cgi/zaraz/i.js"></script>
```

---

# Google Consent Mode

URL: https://developers.cloudflare.com/zaraz/advanced/google-consent-mode/

## Background

[Google Consent Mode](https://developers.google.com/tag-platform/security/concepts/consent-mode) is used by Google tools to manage consent regarding the usage of private data and Personally Identifiable Information (PII). Zaraz provides automatic support for Consent Mode v2, as well as manual support for Consent Mode v1.

You can also use Google Analytics and Google Ads without cookies by selecting **Permissions** and disabling **Access client key-value store**.

***

## Consent Mode v2

Consent Mode v2 specifies a "default" consent status that is usually set when the session starts, and an "updated" status that is set when the visitor configures their consent preferences. Consent Mode v2 will turn on automatically when the correct event properties are available, meaning there is no need to change any settings in the respective tools or their actions.

### Set the default consent status

Often websites will want to set a default consent status that denies all categories. You can do that with no code at all by checking the **Set Google Consent Mode v2 state** in the Zaraz **Settings** page.

If that is not what your website needs, and instead you want to set the default consent status in a more granular way, use the reserved `google_consent_default` property:

```js
zaraz.set("google_consent_default",  {
  'ad_storage': 'denied',
  'ad_user_data': 'denied',
  'ad_personalization': 'denied',
  'analytics_storage': 'denied'
})
```

After the above code is executed, the consent status will be saved to `localStorage` and will be included with every subsequent Zaraz event.

Note that the code should be included as part of your website HTML code, usually inside a `<script>` element within the `<body>` element. It is **not recommended** to use the Custom HTML Zaraz tool for including it, as the consent preferences should be specified before Zaraz loads any other tool.

### Update the consent status

After the user has provided their consent preferences you can set the new status using the reserved `google_consent_update` property. If you are using the Zaraz Consent Management Platform, you can use the [Consent Choices Updated event](/zaraz/consent-management/api/#consent-choices-updated) to know when to update the Google Consent status.

```js
zaraz.set("google_consent_update",  {
  'ad_storage': 'granted',
  'ad_user_data': 'denied',
  'ad_personalization': 'granted',
  'analytics_storage': 'denied'
})
```

All subsequent events will include the information about both the default and the updated consent status.

### Verify if Zaraz is processing Consent Mode v2

You can verify that Zaraz is processing the Consent Mode settings by enabling the [Zaraz Debugger](/zaraz/web-api/debug-mode/). Server-side requests to Google Analytics and Google Ads should include the `gcd` parameter.

## Consent Mode v1

Consent Mode v1 was deprecated by Google in November 2023, but is still supported. Integration with Zaraz is more complex than Consent Mode v2. You do not need to use Consent Mode v1 if you have implemented Consent Mode v2.

### Set up Consent Mode v1

Configuring Consent Mode v1 is done manually for each tool. Go to the tool page and select **Settings**. Select **Add field**, and select **Consent Mode** from the drop-down menu. Then, select **Confirm**.

The value for Consent Mode must adhere to Google's defined format, which is a four-character string starting with `G1`, followed by two characters indicating consent status for Marketing and Analytics. `1` indicates consent, `0` indicates no consent, and `-` indicates no consent was required. For example, setting the value to `G111` means the user has granted consent for both Marketing and Analytics, `G101` means consent for Analytics only, and `G10-` means no consent for Marketing but no required consent for Analytics.

Since the value for Consent Mode may change per user or session, it is recommended to dynamically set this value using `zaraz.set` in your website code. For instance, use `zaraz.set("google_consent_v1", "G100")` on page load, and `zaraz.set("google_consent_v1", "G111")` after the user granted consent for Marketing and Analytics. In the **Consent Mode** field, select the **+** symbol, choose **Event Property**, and type `google_consent_v1` as the property name. Zaraz will then use the latest value of the `google_consent_v1` Event Property as the Consent Mode string.

## Supported Tools

Consent Mode v1 and v2 are both supported by Google Analytics 4 and Google Ads.

---

# Configuration Import & Export

URL: https://developers.cloudflare.com/zaraz/advanced/import-export/

Exporting your Zaraz configuration can be useful if you want to create a local backup or if you need to import it to another website. Zaraz provides an easy way to export and import your configuration.

## Export your Zaraz configuration

To export your Zaraz configuration:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Zaraz** > **Settings** > **Advanced**.
3. Click "Export" to download your configuration.

## Import your Zaraz configuration

:::caution


Importing a Zaraz configuration replaces your existing configuration, meaning that any information you did not back up could be lost. Consider exporting your existing configuration before importing a new one.


:::

To import a Zaraz configuration:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Zaraz** > **Settings** > **Advanced**.
3. Click **Browse** to select your configuration file, and **Import** to import it.

---

# Advanced options

URL: https://developers.cloudflare.com/zaraz/advanced/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Custom Managed Components

URL: https://developers.cloudflare.com/zaraz/advanced/load-custom-managed-component/

Zaraz supports loading custom third-party tools using [Managed Components](https://managedcomponents.dev/). These can be Managed Components that you have developed yourself or that were developed by others. Using Custom Managed Components with Zaraz is done by converting them into a Cloudflare Worker running in your account.

If you are new to Managed Components, we recommend you get started with [creating your own Managed Component](https://managedcomponents.dev/getting-started/quickstart) or check out [our demo Managed Component](https://github.com/managed-components/demo).

## Prepare a Managed Component

:::note

If your Managed Component requires any building, transpiling, or bundling, you must complete those steps before you can deploy it. For example, this is required for components written in TypeScript and is usually done by running `npm run build` or an equivalent.
:::

To get started, you need have a JavaScript file ready for deployment, that exports the default Managed Component function for your Managed Component.

In this guide, we will use a simple example of a Custom Managed Component that counts user visits and logs this data in the console:

```javascript
// File: index.js
export default async function (manager) {
	// Add a pageview event
	manager.addEventListener("pageview", event, () => {
		const { client } = event;

		// Get the variable "counter" from the client's cookies and increase by 1
		let counter = parseInt(client.get("counter")) || 0;
		counter += 1;

		// Log the increased number
		client.execute(`console.log('Views: ${counter}')`);

		// Store the increased number for the next visit
		client.set("counter", counter);
	});
}
```

## Deploy a Managed Component to Cloudflare

1. Open a terminal in your Managed Component’s root directory.
2. From there, run `npx managed-component-to-cloudflare-worker ./index.js my-new-counter-mc`, which will deploy the Managed Component to a specialized Cloudflare Worker. Change the path to your `index.js`. You can also rename the Component.
3. Your Managed Component should now be [visible on your account](https://dash.cloudflare.com/redirect?account=/workers-and-pages) as a Cloudflare Worker prefixed with `custom-mc-`.

## Configure a Managed Component in Cloudflare

:::note

As with regular tools, it is recommended that you [create the triggers](/zaraz/custom-actions/create-trigger/) you need first, if the Custom Managed Component you are adding needs to start actions using firing triggers different from the default `Pageview` trigger.
:::

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account and domain.
2. Select **Zaraz** > **Tools Configuration** > [**Third-party tools**](https://dash.cloudflare.com/?to=/:account/:zone/zaraz/tools-config/tools/catalog).
3. Select **Add new tool** and choose **Custom Managed Component** from the tools library page. Select **Continue** to confirm your selection.
4. In **Select Custom MC**, choose a Custom Managed Component that you have deployed to your account, such as `custom-mc-my-new-counter-mc`. Select **Continue**.
5. In **Permissions**, select the permissions you want to grant the Custom Managed Component. If you run an untrusted Managed Component, pay close attention to what permissions you are granting. Select **Continue**.
6. In **Set up**, configure the settings for your new tool. The information you need to enter will depend on the code of the Managed Component. You can add settings and default fields, as well as use [variables you have previously set up](/zaraz/variables/create-variables/).
7. Select **Save**.

While your tool is now configured, it does not have any actions associated with it yet. Adding new actions will tell Zaraz when to contact your Managed Component, and what information to send to it. When adding actions, make sure to verify the Action Type you are using. The types `pageview` and `event` are most commonly used, but you can add any action type to match the event listeners your Managed Component is using. Learn how to [create additional actions](/zaraz/custom-actions/).

If your Managed Component listens to `ecommerce` events, toggle **E-commerce tracking** in the Managed Component Settings page.

## Unsupported Features

As of now, Custom Managed Components do not support the use of the following methods yet:

- `manager.registerEmbed`
- `manager.registerWidget`
- `manager.proxy`
- `manager.serve`

---

# Load Zaraz selectively

URL: https://developers.cloudflare.com/zaraz/advanced/load-selectively/

You can use [Configuration Rules](/rules/configuration-rules/) to load Zaraz selectively on specific URLs or subdomains. Configuration Rules can also be used to block Zaraz from loading based on cookies, IP addresses or anything else related to a request.

Refer to [Configuration Rules](/rules/configuration-rules/) documentation to learn more about this feature and how you can use it with Zaraz.

:::note


If you need to block one or more actions from firing in a tool, Cloudflare recommends you use [Blocking Triggers](/zaraz/advanced/blocking-triggers/) instead of Configuration Rules.


:::

---

# Load Zaraz manually

URL: https://developers.cloudflare.com/zaraz/advanced/load-zaraz-manually/

By default, if your domain is proxied by Cloudflare, Zaraz will automatically inject itself to HTML pages in your site. This makes it easier to get up and running quickly. However, you might want to load Zaraz manually, for example to test Zaraz on specific pages first.

After you turn off the [Auto-inject script](/zaraz/reference/settings/#auto-inject-script) option, you will have to manually include the Zaraz script in your HTML, immediately before the `</head>` tag closes. The path to your script would be `/cdn-cgi/zaraz/i.js`. Your script tag should look like this:

```html
<script src="/cdn-cgi/zaraz/i.js" referrerpolicy="origin"></script>
```

With the script, your page HTML should be similar to the following:

```html
<html>
  <head>
    ….
    <script src="/cdn-cgi/zaraz/i.js" referrerpolicy="origin"></script>
  </head>
  <body>
    …
  </body>
</html>
```

Note that if your site is not proxied by Cloudflare, you should refer to the section about [Using Zaraz on domains not proxied by Cloudflare](/zaraz/advanced/domains-not-proxied/).

---

# Logpush

URL: https://developers.cloudflare.com/zaraz/advanced/logpush/

import { Plan } from "~/components";

Send Zaraz logs to an external storage provider like R2, S3, etc.

This is an Enterprise only feature.

## Setup

To configure logpush support for Zaraz please follow these steps

### 1. Create a logpush job

Navigate to your Website (Zone) and from the left sidebar find **Analytics and Logs**.

Under this **Analytics and Logs** section navigate to **Logpush**

Click on **Create a Logpush Job** and follow the steps described in the [Logpush documentation](/logs/get-started/).

When it comes to selecting a dataset please make sure to select **Zaraz Events**

### 2. Enable Logpush from Zaraz settings

Navigate to your website's [Zaraz settings](https://dash.cloudflare.com/?to=/:account/:zone/zaraz/settings)

Enable **Export Zaraz Logs**.

## Fields

Logs will have the following fields

| Field          | Type     | Description                                                                                                                                                                    |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| RequestHeaders | `JSON`   | The headers that were sent with the request.                                                                                                                                   |
| URL            | `String` | The Zaraz URL to which the request was made.                                                                                                                                |
| IP             | `String` | The originating IP.                                                                                                                                                            |
| Body           | `JSON`   | The body that was sent along with the request.                                                                                                                                 |
| Event Type     | `String` | Can be one of the following: `server_request`, `server_response`, `action_triggered`, `ecommerce_triggered`, `client_request`, `component_error`. |
| Event Details  | `JSON`   | Details about the event.                                                                                                                                                       |
| TimestampStart | `String` | The time at which the event occured.                                                                                                                                           |

---

# Using JSONata

URL: https://developers.cloudflare.com/zaraz/advanced/using-jsonata/

For advanced use cases, it is sometimes useful to be able to retrieve a value in a particular way. For instance, you might be using `zaraz.track` to send a list of products to Zaraz, but the third-party tool you want to send this data to requires the total cost of the products. Alternatively, you may want to manipulate a value, such as converting it to lowercase.

Cloudflare Zaraz uses JSONata to enable you to perform complex operations on your data. With JSONata, you can evaluate expressions against the [Zaraz Context](/zaraz/reference/context/), allowing you to access and manipulate a wide range of values. To learn more about the values available and how to access them, consult the [full reference](/zaraz/reference/context/). You can also refer to the [complete JSONata documentation](https://docs.jsonata.org/) for more information about JSONata's capabilities.

To use JSONata inside Zaraz, follow these steps:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Zaraz** > **Tools configuration** > **Tools**.
3. Select **Edit** next to a tool that you have already configured.
4. Select an action or add a new one.
5. Choose the field you want to use JSONata in, and wrap your JSONata expression with double curly brackets, like `{{ expression }}`.

JSONata can also be used inside Triggers, Tool Settings, and String Variables.

## Examples

### Converting a string to lowercase

Converting a string to lowercase is useful if you want to compare it to something else, for example a regular expression. Assuming the original string comes from a cookie named `myCookie`, turning the value lowercase can be done using `{{ $lowercase(system.cookies.myCookie) }}`.

### Sending a sum of all products in the cart

Assuming you are using `zaraz.ecommerce()` to send the cart content like this:

```js
zaraz.track('Product List Viewed',
  {  products:
    [
    {
      sku: '2671033',
      name: 'V-neck T-shirt',
      price: 14.99,
      quantity: 3
    },{
      sku: '2671034',
      name: 'T-shirt',
      price: 10.99,
      quantity: 2
    },
    ],
  }
);
```

If the field in which you want to show the sum, you will enter `{{ $sum(client.products.(price * quantity)) }}`. This will multiply the price of each product by its quantity, and then sum up the total.

---

# Consent API

URL: https://developers.cloudflare.com/zaraz/consent-management/api/

## Background

The Consent API allows you to programmatically control all aspects of the Consent Management program. This includes managing the modal, the consent status, and obtaining information about your configured purposes.

Using the Consent API, you can integrate Zaraz Consent preferences with an external Consent Management Platform, customize your consent modal, or restrict consent management to users in specific regions.

***

## Events

### `Consent API Ready`

It can be useful to know when the Consent API is fully loaded on the page so that code interacting with its methods and properties is not called prematurely.

```js
document.addEventListener("zarazConsentAPIReady", () => {
  // do things with the Consent API
});

```

### `Consent Choices Updated`

This event is fired every time the user makes changes to their consent preferences. It can be used to act on changes to the consent, for example when updating a tool with the new consent preferences.

```js
document.addEventListener("zarazConsentChoicesUpdated", () => {
  // read the new consent preferences using `zaraz.consent.getAll();` and do things with it
});

```

***

## Properties

The following are properties of the `zaraz.consent` object.



* `modal` boolean

  * Get or set the current visibility status of the consent modal dialog.

* `purposes` object read-only

  * An object containing all configured purposes, with their ID, name, description, and order.

* `APIReady` boolean read-only

  * Indicates whether the Consent API is currently available on the page.



***

## Methods

### `Get`

```js
zaraz.consent.get(purposeId);
```



* <code>get(purposeId)</code> : `boolean | undefined`



Get the current consent status for a purpose using the purpose ID.

* `true`: The consent was granted.
* `false`: The consent was not granted.
* `undefined`: The purpose does not exist.

#### Parameters



* `purposeId` string

  * The ID representing the Purpose.



### `Set`

```js
zaraz.consent.set(consentPreferences);
```



* <code>set(consentPreferences)</code> : `undefined`



Set the consent status for some purposes using the purpose ID.

#### Parameters



* `consentPreferences` object

  * a `{ purposeId: boolean }` object describing the purposes you want to set and their respective consent status.



### `Get All`

```js
zaraz.consent.getAll();
```



* <code>getAll()</code> : `{ purposeId: boolean }`



Returns an object with the consent status of all purposes.

### `Set All`

```js
zaraz.consent.setAll(consentStatus);
```



* <code>setAll(consentStatus)</code> : `undefined`



Set the consent status for all purposes at once.

#### Parameters



* `consentStatus` boolean

  * Indicates whether the consent was granted or not.



### `Get All Checkboxes`

```js
zaraz.consent.getAllCheckboxes();
```



* <code>getAllCheckboxes()</code> : `{ purposeId: boolean }`



Returns an object with the checkbox status of all purposes.

### `Set Checkboxes`

```js
zaraz.consent.setCheckboxes(checkboxesStatus);
```



* <code>setCheckboxes(checkboxesStatus)</code> : `undefined`



Set the consent status for some purposes using the purpose ID.

#### Parameters



* `checkboxesStatus` object

  * a `{ purposeId: boolean }` object describing the checkboxes you want to set and their respective checked status.



### `Set All Checkboxes`

```js
zaraz.consent.setAllCheckboxes(checkboxStatus);
```



* <code>setAllCheckboxes(checkboxStatus)</code> : `undefined`



Set the `checkboxStatus` status for all purposes in the consent modal at once.

#### Parameters



* `checkboxStatus` boolean

  * Indicates whether the purposes should be marked as checked or not.



### `Send queued events`

```js
zaraz.consent.sendQueuedEvents();
```



* <code>sendQueuedEvents()</code> : `undefined`



If some Pageview-based events were not sent due to a lack of consent, they can be sent using this method after consent was granted.

## Examples

### Restricting consent checks based on location

You can combine multiple features of Zaraz to effectively disable Consent Management for some visitors. For example, if you would like to use it only for visitors from the EU, you can disable the automatic showing of the consent modal and add a Custom HTML tool with the following script:

```html
<script>
function getCookie(name) {
  const value = `; ${document.cookie}`
  return value?.split(`; ${name}=`)[1]?.split(";")[0]
}

function handleZarazConsentAPIReady() {
  const consent_cookie = getCookie("cf_consent")
  const isEUCountry = "{{system.device.location.isEUCountry}}" === "1"
  if (!consent_cookie) {
    if (isEUCountry) {
      zaraz.consent.modal = true
    } else {
      zaraz.consent.setAll(true)
      zaraz.consent.sendQueuedEvents()
    }
  }
}

if (zaraz.consent?.APIReady) {
  handleZarazConsentAPIReady()
} else {
  document.addEventListener("zarazConsentAPIReady", handleZarazConsentAPIReady)
}
</script>
```

Note: If you've customized the cookie name for the Consent Manager, use that customized name instead of "cf\_consent"  in the snippet above.

By letting this Custom HTML tool to run without consent requirements, the modal will appear to all EU visitors, while for other visitors consent will be automatically granted. The `{{ system.device.location.isEUCountry }}` property will be `1` if the visitor is from an EU country and `0` otherwise. You can use any other property or variable to customize the Consent Management behavior in a similar manner, such as `{{ system.device.location.country }}` to restrict consent checks based on country code.

---

# Custom CSS

URL: https://developers.cloudflare.com/zaraz/consent-management/custom-css/

You can add custom CSS to the Zaraz Consent Management Platform, to make the consent modal more in-line with your website's design.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Consent**.
3. Find the **Custom CSS** section, and add your custom CSS code as you would on any other HTML editor.

---

# Enable Consent Management

URL: https://developers.cloudflare.com/zaraz/consent-management/enable-consent-management/

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Consent**.
3. Turn on **Enable Consent Management**.
4. In **Consent modal text** fill in any legal information required in your country. Use HTML code to format your information as you would in any other HTML editor.
5. Under **Purposes**, select **Add new Purpose**. Give your new purpose a name and a description. Purposes are the reasons for using third-party tools in your website.
6. In **Assign purpose to tools**, match tools to purposes by selecting one of the purposes previously created from the drop-down menu. Do this for all your tools.
7. Select **Save**.

Your Consent Management platform is ready. Your website should now display a modal asking for consent for the tools you have configured.

## Adding different languages

In your Zaraz consent settings, you can add your consent modal text and purposes in various languages.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Consent**.
3. Select a default language of your choice. The default setting is English.
4. In **Consent modal text** and **Purposes**, you can select different languages and add translations.

## Overriding the consent modal language

By default, the Zaraz Consent Management Platform will try to match the language of the consent modal with the language requested by the browser, using the `Accept-Language` HTTP header.
If, for any reason, you would like to force the consent modal language to a specific one, you can use the `zaraz.set` Web API to define the default `__zarazConsentLanguage` value.

Below is an example that forces the language shown to be American English.

```html
<script>
  zaraz.set('__zarazConsentLanguage', 'en-US')
</script>
```

## Next steps

If the default consent modal does not suit your website's design, you can use the [Custom CSS tool](/zaraz/consent-management/custom-css/) to add your own custom design.

---

# IAB TCF Compliance

URL: https://developers.cloudflare.com/zaraz/consent-management/iab-tcf-compliance/

The Zaraz Consent Management Platform is compliant with the IAB Transparency & Consent Framework. Enabling this feature [could be required](https://blog.google/products/adsense/new-consent-management-platform-requirements-for-serving-ads-in-the-eea-and-uk/) in order to serve Google Ads in the EEA and the UK.

The CMP ID of the approval is 433 and be can seen in the [IAB Europe](https://iabeurope.eu/cmp-list/) website.

Using the Zaraz Consent Management Platform in IAB TCF Compliance Mode is is opt-in.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Select **Zaraz** > **Consent**.
3. Check the **Use IAB TCF compliant modal** option.
4. Under the **Assign purposes to tools** section, add vendor details to every tool that was not automatically assigned.
5. Press **Save**.

---

# Consent management

URL: https://developers.cloudflare.com/zaraz/consent-management/

Zaraz provides a Consent Management platform (CMP) to help you address and manage required consents under the European [General Data Protection Regulation (GDPR)](https://gdpr-info.eu/) and the [Directive on privacy and electronic communications](https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:02002L0058-20091219\&from=EN#tocId7). This consent platform lets you easily create a consent modal for your website based on the tools you have configured. With Zaraz CMP, you can make sure Zaraz only loads tools under the umbrella of the specific purposes your users have agreed to.

The consent modal added to your website is concise and gives your users an easy way to opt-in to any purposes of data processing your tools need.

## Crucial vocabulary

The Zaraz Consent Management platform (CMP) has a **Purposes** section. This is where you will have to create purposes for the third-party tools your website uses. To better understand the terms involved in dealing with personal data, refer to these definitions:

* **Purpose**: The reason you are loading a given tool on your website, such as to track conversions or improve your website’s layout based on behavior tracking. One purpose can be assigned to many tools, but one tool can be assigned only to one purpose.
* **Consent**: An affirmative action that the user makes, required to store and access cookies (or other persistent data, like `LocalStorage`) on the users’ computer/browser.

:::note

All tools use consent as a legal basis. This is due to the fact that they all use cookies that are not strictly necessary for the website’s correct operation. Due to this, all purposes are opt-in. 
:::

## Purposes and tools

When you add a new tool to your website, Zaraz does not assign any purpose to it. This means that this tool will skip consent by default. Remember to check the [Consent Management settings](/zaraz/consent-management/enable-consent-management/) every time you set up a new tool. This helps ensure you avoid a situation where your tool is triggered before the user gives consent.

The user’s consent preferences are stored within a first-party cookie. This cookie is a JSON file that maps the purposes’ ID to a `true`/`false`/missing value:

* `true` value: The user gave consent.
* `false`value: The user refused consent.
* Missing value: The user has not made a choice yet.

:::caution[Important]

Cloudflare cannot recommend nor assign by default any specific purpose for your tools. It is your responsibility to properly assign tools to purposes if you need to comply with GDPR. 
:::

## Important things to note

* Purposes that have no tools assigned will not show up in the CMP modal.
* If a tool is assigned to a purpose, it will not run unless the user gives consent for the purpose the tool is assigned for.
* Once your website loads for a given user for the first time, all the triggers you have configured for tools that are waiting for consent are cached in the browser. Then, they will be fired when/if the user gives consent, so they are not lost.
* If the user visits your website for the first time, the consent modal will automatically show up. This also happens if the user has previously visited your website, but in the meantime you have enabled CMP.
* On subsequent visits, the modal will not show up. You can make the modal show up by calling the function `zaraz.showConsentModal()` — for example, by binding it to a button.

---

# Additional fields

URL: https://developers.cloudflare.com/zaraz/custom-actions/additional-fields/

Some tools supported by Zaraz let you add fields in addition to the required field. Fields can usually be added either to a specific action, or to all the action within a tool, by adding the field as a **Default Field**.

## Add an additional field to a specific action

Adding an additional field to an action will attach it to this action only, and will not affect your other actions.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Select **Zaraz** > **Tools Configuration** > **Third-party tools**.
3. Locate the third-party tool with the action you want to add the additional field to, and select **Edit**.
4. Select the action you wish to modify.
5. Select **Add Field**.
6. Choose the desired field from the drop-down menu and select **Add**.
7. Enter the value you wish to pass to the action.
8. Select **Save**.

The new field will now be used in this event.

## Add an additional field to all actions in a tool

Adding an additional field to the tool sets it as a default field for all of the tool actions. It is the same as adding it to every action in the tool.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Select **Zaraz** > **Tools**.
3. Locate the third-party tool where you want to add the field, and select **Edit**.
4. Select **Settings** > **Add Field**.
5. Choose the desired field from the drop-down menu, and select **Add**.
6. Enter the value you wish to pass to all the actions in the tool.
7. Select **Save**.

The new field will now be attached to every action that belongs to the tool.

---

# Create an action

URL: https://developers.cloudflare.com/zaraz/custom-actions/create-action/

Once you have your triggers ready, you can use them to configure your actions. An action defines a specific task that your tool will perform. 

To create an action, first [add a third-party tool](/zaraz/get-started/). If you have already added a third-party tool, follow these steps to create an action.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools Configuration**.
3. Under **Third-party tools**, locate the tool you want to configure an action for, and select **Edit**.
4. Under Custom actions select **Create action**.
5. Give the action a descriptive name.
6. In the **Firing Triggers** field, choose the relevant trigger or triggers you [previously created](/zaraz/custom-actions/create-trigger/). If you choose more than one trigger, the action will start when any of the selected triggers are matched.
7. Depending on the tool you are adding an action for, you might also have the option to choose an **Action type**. You might also need to fill in more fields in order to complete setting up the action.
8. Select **Save**.

The new action will appear under **Tool actions**. To edit or disable/enable an action, refer to [Edit tools and actions](/zaraz/custom-actions/edit-tools-and-actions/).

---

# Create a trigger

URL: https://developers.cloudflare.com/zaraz/custom-actions/create-trigger/

Triggers define the conditions under which a tool will start an action. Since a tool must have actions in order to work, and actions must have triggers, it is important to set up your website's triggers correctly. A trigger can be made out of one or more Rules. Zaraz supports [multiple types of Trigger Rules](/zaraz/reference/triggers/).

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools Configuration**.
3. Select the **Triggers** tab.
4. Select **Create trigger**.
5. In **Trigger Name** enter a descriptive name for your trigger.
6. In **Rule type**, choose from the actions available in the drop-down menu to start building your rule. Refer to [Triggers and rules](/zaraz/reference/triggers/) for more information on what each rule type means.
7. In **Variable name**, input the variable you want as the trigger. For example, use _Event Name_ if you are using [`zaraz.track()`](/zaraz/web-api/track/) in your website. If you want to use a variable you have previously [created in Variables](/zaraz/variables/create-variables/), select the `+` sign in the drop-down menu, scroll to **Variables**, and choose your variable.
8. Use the **Match operation** drop-down list to choose a comparison operator. For an expression to match, the value in **Variable name** and **Match string** must satisfy the comparison operator.
9. In **Match string**, input the string that completes the rule.
10. You can add more than one rule to your trigger. Select **Add rule** and repeat steps 5-8 to add another set of rules and conditions. If you add more than one rule, your trigger will only be valid when all conditions are true.
11. Select **Save**.

Your trigger is now complete. If you go back to the main page you will see it listed under **Triggers**, as well as which tools use it. You can also [**Edit** or **Delete** your trigger](/zaraz/custom-actions/edit-triggers/).

---

# Edit triggers

URL: https://developers.cloudflare.com/zaraz/custom-actions/edit-triggers/

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools Configuration**.
3. Under **Triggers**, locate your trigger and select **Edit**.

You can edit every field related to the trigger, as well as add new trigger rules.

## Delete a trigger

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools Configuration**.
3. Under **Triggers**, locate your trigger and select **Delete**.

---

# Edit tools and actions

URL: https://developers.cloudflare.com/zaraz/custom-actions/edit-tools-and-actions/

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools**.
3. Under **Third-party tools**, locate your tool and select **Edit**.

On this page you will be able to edit settings related to the tool, add actions, and edit existing ones. To edit an existing action, select its name.

## Enable or disable a tool

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools Configuration**.
3. Under **Third-party tools**, locate your tool and select the **Enabled** toggle.

## Enable or disable an action

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools Configuration** > **Third-party tools**.
3. Locate the tool you wan to edit and select **Edit**.
4. Find the action you want to change state, and enable or disable it with the toggle.

## Delete a tool

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools Configuration**.
3. Under **Third-party tools**, locate your tool and select **Delete**.

---

# Custom actions

URL: https://developers.cloudflare.com/zaraz/custom-actions/

Tools on Zaraz must have actions configured in order to do something. Often, using Automatic Actions is enough for configuring a tool. But you might want to use Custom Actions to create a more customized setup, or perhaps you are using a tool that does not support Automatic Actions. In these cases, you will need to configure Custom Actions manually.

Every action has firing triggers assigned to it. When the conditions of the firing triggers are met, the action will start. An action can be anything the tool can do - sending analytics information, showing a widget, adding a script and much more.

To start using actions, first [create a trigger](/zaraz/custom-actions/create-trigger/) to determine when this action will start. If you have already set up a trigger, or if you are using one of the built-in triggers, follow these steps to [create an action](/zaraz/custom-actions/create-action/).

---

# Versions & History

URL: https://developers.cloudflare.com/zaraz/history/

import { DirectoryListing } from "~/components"

Zaraz can work in real-time. In this mode, every change you make is instantly published. You can also enable [Preview & Publish mode](/zaraz/history/preview-mode/), which allows you to test your changes before you commit to them.

When enabling Preview & Publish mode, you will also have access to [Zaraz History](/zaraz/history/versions/). Zaraz History shows you a list of all the changes made to your settings, and allows you to revert to any previous settings.

<DirectoryListing />

---

# Preview mode

URL: https://developers.cloudflare.com/zaraz/history/preview-mode/

Zaraz allows you to test your configurations before publishing them. This is helpful to avoid unintended consequences when deploying a new tool or trigger.

After enabling Preview & Publish you will also have access to [Zaraz History](/zaraz/history/versions/).

## Enable Preview & Publish mode

By default, Zaraz is configured to commit changes in real time. To enable preview mode and test new features you are adding to Zaraz:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Zaraz** > **History**.
3. Enable **Preview & Publish Workflow**.

You are now working in preview mode. To commit changes and make them live, you will have to select **Publish** on your account.

### Test changes before publishing them

Now that you have Zaraz working in preview mode, you can open your website and test your settings:

1. In [Zaraz settings](https://dash.cloudflare.com/?to=/:account/:zone/zaraz/settings) copy your **Debug Key**.
2. Navigate to the website where you want to test your new settings.
3. Access the browser’s developer tools. For example, to access developer tools in Google Chrome, select **View** > **Developer** > **Developer Tools**.
4. Select the **Console** pane and enter the following command to start Zaraz’s preview mode:

   ```js
   zaraz.preview("<YOUR_DEBUG_KEY>")
   ```
5. Your website will reload along with Zaraz debugger, and Zaraz will use the most recent changes in preview mode.
6. If you are satisfied with your changes, go back to the [Zaraz dashboard](https://dash.cloudflare.com/?to=/:account/:zone/zaraz/) and select **Publish** to apply them to all users. If not, use the dashboard to continue adjusting your configuration.

To exit preview mode, close Zaraz debugger.

## Disable Preview & Publish mode

Disable Preview & Publish mode to work in real time. When you work in real time, any changes made on the dashboard are applied instantly to the domain you are working on.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Zaraz** > **History**.
3. Disable **Preview & Publish Workflow**.
4. In the modal, decide if you want to delete all unpublished changes, or if you want to publish any change made in the meantime.

Zaraz is now working in real time. Any change you make will be immediately applied the domain you are working on.

---

# Versions

URL: https://developers.cloudflare.com/zaraz/history/versions/

Version History enables you to keep track of all the Zaraz configuration changes made in your website. With Version History you can also revert changes to previous settings should there be a problem.

To access Version History you need to enable [Preview & Publish mode](/zaraz/history/preview-mode/) first. Then, you can access Version History under **Zaraz** > **History**.

## Access Version History

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Zaraz** > **History**.
3. If this is your first time using this feature, this page will be empty. Otherwise, you will have a list of changes made to your account with the following information:
   * Date of change
   * User who made the change
   * Description of the change

## Revert changes

Version History enables you to revert any changes made to your Zaraz settings.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Zaraz** > **History**.
3. Find the changes you want to revert, and select **Restore**.
4. Confirm you want to revert your changes.
5. Select **Publish** to publish your changes.

---

# Monitoring

URL: https://developers.cloudflare.com/zaraz/monitoring/

Zaraz Monitoring shows you different metrics regarding Zaraz. This helps you to detect issues when they occur. For example, if a third-party analytics provider stops collecting data, you can use the information presented by Zaraz Monitoring to find where in the workflow the problem occurred.

You can also check activity data in the **Activity last 24hr** section, when you access [tools](/zaraz/get-started/), [actions](/zaraz/custom-actions/) and [triggers](/zaraz/custom-actions/create-trigger/) in the dashboard.

To use Zaraz Monitoring:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Monitoring**.
3. Select one of the options (Loads, Events, Triggers, Actions). Zaraz Monitoring will show you how the traffic for that section evolved for the time period selected.

## Zaraz Monitoring options

- **Loads**: Counts how many times Zaraz was loaded on pages of your website. When [Single Page Application support](/zaraz/reference/settings/#single-page-application-support) is enabled, Loads will count every change of navigation as well.
- **Events**: Counts how many times a specific event was tracked by Zaraz. It includes the [Pageview event](/zaraz/get-started/), [Track events](/zaraz/web-api/track/), and [E-commerce events](/zaraz/web-api/ecommerce/).
- **Triggers**: Counts how many times a specific trigger was activated. It includes the built-in [Pageview trigger](/zaraz/custom-actions/create-trigger/) and any other trigger you set in Zaraz.
- **Actions**: Counts how many times a [specific action](/zaraz/custom-actions/) was activated. It includes the pre-configured Pageview action, and any other actions you set in Zaraz.
- **Server-side requests**: tracks the status codes returned from server-side requests that Zaraz makes to your third-party tools.

---

# Monitoring API

URL: https://developers.cloudflare.com/zaraz/monitoring/monitoring-api/

import { TabItem, Tabs } from "~/components";

The **Zaraz Monitoring API** allows users to retrieve detailed data on Zaraz events through the **GraphQL Analytics API**. Using this API, you can monitor events, pageviews, triggers, actions, and server-side request statuses, including any errors and successes. The data available through the API mirrors what is shown on the Zaraz Monitoring page in the dashboard, but with the API, you can query it programmatically to create alerts and notifications for unexpected deviations.

To get started, you'll need to generate an Analytics API token by following the [API token authentication guide](/analytics/graphql-api/getting-started/authentication/api-token-auth/).

## Key Entities

The Monitoring API includes the following core entities, which each provide distinct insights:

- **zarazTrackAdaptiveGroups**: Contains data on Zaraz events, such as event counts and timestamps.
- **zarazActionsAdaptiveGroups**: Provides information on Zaraz Actions.
- **zarazTriggersAdaptiveGroups**: Tracks data on Zaraz Triggers.
- **zarazFetchAdaptiveGroups**: Captures server-side request data, including URLs and returning status codes for third-party requests made by Zaraz.

## Example GraphQL Queries

You can construct any query you'd like using the above datasets, but here are some example queries you can use.

<Tabs syncKey="GQLExamples"><TabItem label="Events">

Query for the count of Zaraz events, grouped by time.

```graphql graphql-api-explorer='{"orderBy": "datetimeHour_ASC"}'
query ZarazEvents(
	$zoneTag: string
	$limit: uint64!
	$start: Time
	$end: Time
	$orderBy: ZoneZarazTrackAdaptiveGroupsOrderBy!
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazTrackAdaptiveGroups(
				limit: $limit
				filter: { datetimeHour_geq: $start, datetimeHour_leq: $end }
				orderBy: [$orderBy]
			) {
				count
				dimensions {
					ts: datetimeHour
				}
			}
		}
	}
}
```

</TabItem><TabItem label="Loads">

Query for the count of Zaraz loads, grouped by time.

```graphql graphql-api-explorer='{"orderBy": "date_ASC"}'
query ZarazLoads(
	$zoneTag: string
	$limit: uint64!
	$start: Date
	$end: Date
	$orderBy: ZoneZarazTriggersAdaptiveGroupsOrderBy!
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazTriggersAdaptiveGroups(
				limit: $limit
				filter: { date_geq: $start, date_leq: $end, triggerName: Pageview }
				orderBy: [$orderBy]
			) {
				count
				dimensions {
					ts: date
				}
			}
		}
	}
}
```

</TabItem> <TabItem label="Triggers">

Query for the total execution count of each trigger processed by Zaraz.

```graphql graphql-api-explorer
query ZarazTriggers(
	$zoneTag: string
	$limit: uint64!
	$start: Date
	$end: Date
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazTriggersAdaptiveGroups(
				limit: $limit
				filter: { date_geq: $start, date_leq: $end }
				orderBy: [count_DESC]
			) {
				count
				dimensions {
					name: triggerName
				}
			}
		}
	}
}
```

</TabItem><TabItem label="Erroneous responses">

Query for the count of 400 server-side responses, grouped by time and URL.

```graphql graphql-api-explorer='{"orderBy": "datetimeHour_ASC"}'
query ErroneousResponses(
	$zoneTag: string
	$limit: uint64!
	$start: Time
	$end: Time
	$orderBy: ZoneZarazFetchAdaptiveGroupsOrderBy!
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazFetchAdaptiveGroups(
				limit: $limit
				filter: {
					datetimeHour_geq: $start
					datetimeHour_leq: $end
					url_neq: ""
					status: 400
				}
				orderBy: [$orderBy]
			) {
				count
				dimensions {
					ts: datetimeHour
					name: url
				}
			}
		}
	}
}
```

 </TabItem></Tabs>

### Variables Example

```json
{
	"zoneTag": "d6dfdf32c704a77ac227243a5eb5ca61",
	"start": "2025-01-01T00:00:00Z",
	"end": "2025-01-30T00:00:00Z",
	"limit": 10000,
	"orderBy": "datetimeHour_ASC"
}
```

Be sure to customize the zoneTag to match your specific zone, along with setting the desired start and end dates

### Explanation of Parameters

- **zoneTag**: Unique identifier of your Cloudflare zone.
- **limit**: Maximum number of results to return.
- **start** and **end**: Define the date range for the query in ISO 8601 format.
- **orderBy**: Determines the sorting order, such as by ascending or descending datetime.

## Example `curl` Request

Use this `curl` command to query the Zaraz Monitoring API for the number of events processed by Zaraz. Replace `$TOKEN` with your API token, `$ZONE_TAG` with your zone tag, and adjust the start and end dates as needed.

```bash
curl -X POST https://api.cloudflare.com/client/v4/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "query": "query AllEvents($zoneTag: String!, $limit: Int!, $start: Date, $end: Date, $orderBy: [ZoneZarazTriggersAdaptiveGroupsOrderBy!]) { viewer { zones(filter: { zoneTag: $zoneTag }) { data: zarazTrackAdaptiveGroups( limit: $limit filter: { datetimeHour_geq: $start datetimeHour_leq: $end } orderBy: [$orderBy] ) { count dimensions { ts: datetimeHour } } } } }",
    "variables": {
      "zoneTag": "$ZONE_TAG",
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-01-30T00:00:00Z",
      "limit": 10000,
      "orderBy": "datetimeHour_ASC"
    }
  }'
```

### Explanation of the `curl` Components

- **Authorization**: The `Authorization` header requires a Bearer token. Replace `$TOKEN` with your actual API token.
- **Content-Type**: Set `application/json` to indicate a JSON payload.
- **Data Payload**: This payload includes the GraphQL query and variable parameters, such as `zoneTag`, `start`, `end`, `limit`, and `orderBy`.

This `curl` example will return a JSON response containing event counts and timestamps within the specified date range. Modify the `variables` values as needed for your use case.

## Additional Resources

Refer to the [full GraphQL Analytics API documentation](/analytics/graphql-api/) for more details on available fields, filters, and further customization options for Zaraz Monitoring API queries.

---

# Zaraz Context

URL: https://developers.cloudflare.com/zaraz/reference/context/

The Zaraz Context is a versatile object that provides a set of configurable properties for Zaraz, a web analytics tool for tracking user behavior on websites. These properties can be accessed and utilized across various components, including [Worker Variables](/zaraz/variables/worker-variables/) and [JSONata expressions](/zaraz/advanced/using-jsonata/).

System properties, which are automatically collected by Zaraz, provide insights into the user's environment and device, while Client properties, obtained through [Zaraz Web API](/zaraz/web-api/) calls like zaraz.track(), offer additional information on user behavior and actions.

## System properties

### Page information



| Property               | Type   | Description                                                                                                     |
| ---------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `system.page.query`    | Object | Key-Value object containing all query parameters in the current URL.                                            |
| `system.page.title`    | String | Current page title.                                                                                             |
| `system.page.url`      | URL    | [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) Object containing information about the current URL |
| `system.page.referrer` | String | Current page referrer from `document.referrer`.                                                                 |
| `system.page.encoding` | String | Current page character encoding from `document.characterSet`.                                                   |
|                        |        |                                                                                                                 |

### Cookies

| Property         | Type   | Description                                      |
| ---------------- | ------ | ------------------------------------------------ |
| `system.cookies` | Object | Key-Value object containing all present cookies. |

The keys inside the `system.cookies` are the cookies name. The property `system.cookies.foo` will return the value of the a cookie named `foo`.

### Device information



| Property                                   | Type   | Description                                                                                                              |
| ------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| `system.device.ip`                         | String | Visitor incoming IP address.                                                                                             |
| `system.device.resolution`                 | String | Screen resolution for device.                                                                                            |
| `system.device.viewport`                   | String | Visible web page area in user’s device.                                                                                  |
| `system.device.language`                   | String | Language used in user's device.                                                                                          |
| `system.device.location`                   | Object | All location-related keys from [IncomingRequestCfProperties](/workers/runtime-apis/request/#incomingrequestcfproperties) |
| `system.device.user-agent.ua`              | String | Browser user agent.                                                                                                      |
| `system.device.user-agent.browser.name`    | String | Browser name.                                                                                                            |
| `system.device.user-agent.browser.version` | String | Browser version.                                                                                                         |
| `system.device.user-agent.engine.name`     | String | Type of browser engine (for example, WebKit).                                                                            |
| `system.device.user-agent.engine.version`  | String | Version of the browser engine.                                                                                           |
| `system.device.user-agent.os.name`         | String | Operating system.                                                                                                        |
| `system.device.user-agent.os.version`      | String | Version of the operating system.                                                                                         |
| `system.device.user-agent.device`          | String | Type of device used (for example, iPhone).                                                                               |
| `system.device.user-agent.cpu`             | String | Device’s CPU.                                                                                                            |
|                                            |        |                                                                                                                          |

### Consent Management

| Property         | Type   | Description                                                                            |
| ---------------- | ------ | -------------------------------------------------------------------------------------- |
| `system.consent` | Object | Key-value object containing the current consent status from the Zaraz Consent Manager. |

The keys inside the `system.consent` object are purpose IDs, and values are `true` for consent, `false` for lack of consent.

### Managed Components

| Property          | Type   | Description                                                               |
| ----------------- | ------ | ------------------------------------------------------------------------- |
| `system.clientKV` | Object | Key-value object containing all the KV data from your Managed Components. |

The keys inside the `system.clientKV` object are formatted as Tool ID, underscore, Key name. Assuming you want to read the value of the `ga4` key used by a tool with ID `abcd`, the path would be `system.clientKV.abcd_ga4`.

### Miscellaneous



| Property                            | Type   | Description                           |
| ----------------------------------- | ------ | ------------------------------------- |
| `system.misc.random`                | Number | Random number unique to each request. |
| `system.misc.timestamp`             | Number | Unix time in seconds.                 |
| `system.misc.timestampMilliseconds` | Number | Unix time in milliseconds.            |
|                                     |        |                                       |

## Event properties



| Property              | Type   | Description                                                                                                                                                                                                                                                          |
| --------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client.__zarazTrack` | String | Returns the name of the event sent using the Track method of the Web API. Refer to [Zaraz Track](/zaraz/web-api/track/) for more information.                                                                                                                        |
| `client.<KEY_NAME>`   | String | Returns the value of a `zaraz.track()` `eventProperties` key. The key can either be directly used in `zaraz.track()` or set using `zaraz.set()`. Replace `<KEY_NAME>` with the name of your key. Refer to [Zaraz Track](/zaraz/web-api/track/) for more information. |
|                       |        |                                                                                                                                                                                                                                                                      |

---

# Reference

URL: https://developers.cloudflare.com/zaraz/reference/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Properties reference

URL: https://developers.cloudflare.com/zaraz/reference/properties-reference/

Cloudflare Zaraz offers properties that you can use when configuring the product. They are helpful to send data to a third-party tool or to create triggers as they have context about a specific user's browser session and the actions they take on the website. Below is a list of the properties you can access from the Cloudflare dashboard and their values.

## Web API

| Property               | Description                                                                                                                                                                                                                                          |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *Event Name*           | Returns the name of the event sent using the Track method of the Web API. Refer to the [Track method](/zaraz/web-api/track/) for more information.                                                                                                   |
| *Track Property name:* | Returns the value of a `zaraz.track()` `eventProperties` key. The key can either be directly used in `zaraz.track()` or set using `zaraz.set()`. Set the name of your key here. Refer to the [Set method](/zaraz/web-api/set/) for more information. |

## Page Properties

| Property                  | Description                                                                                                            |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| *Page character encoding* | Returns the document character encoding from `document.characterSet`.                                                  |
| *Page referrer*           | Returns the page referrer from `document.referrer`.                                                                    |
| *Page title*              | Returns the page title.                                                                                                |
| *Query param name:*       | Returns the value of a URL query parameter. When you choose this variable, you need to set the name of your parameter. |
| *URL*                     | Returns a string containing the entire URL.                                                                            |
| *URL base domain*         | Returns the base domain part of the URL, without any subdomains.                                                       |
| *URL host*                | Returns the domain (that is, the hostname) followed by a `:` and the port of the URL (if a port was specified).        |
| *URL hostname*            | Returns the domain of the URL.                                                                                         |
| *URL origin*              | Returns the origin of the URL — that is, its scheme, domain, and port.                                                 |
| *URL password*            | Returns the password specified before the domain name.                                                                 |
| *URL pathname*            | Returns the path of the URL, including the initial `/`. Does not include the query string or fragment.                 |
| *URL port*                | Returns the port number of the URL.                                                                                    |
| *URL protocol scheme*     | Returns the protocol scheme of the URL, including the final `:`.                                                       |
| *URL query parameters*    | Returns query parameters provided, beginning with the leading `?` character.                                           |
| *URL username*            | Returns the username specified before the domain name.                                                                 |

## Cookies

| Property       | Description                                           |
| -------------- | ----------------------------------------------------- |
| *Cookie name:* | Returns cookies obtained from the browser `document`. |

## Device properties

| Property                   | Description                                                 |
| -------------------------- | ----------------------------------------------------------- |
| *Browser engine*           | Returns the type of browser engine (for example, `WebKit`). |
| *Browser engine version*   | Returns the version of the browser’s engine.                |
| *Browser name*             | Returns the browser’s name.                                 |
| *Browser version*          | Returns the browser’s version.                              |
| *Device CPU*               | Returns the device’s CPU.                                   |
| *Device IP address*        | Returns the incoming IP address.                            |
| *Device language*          | Returns the language used.                                  |
| *Device screen resolution* | Returns the screen resolution of the device.                |
| *Device type*              | Returns the type of device used (for example, `iPhone`).    |
| *Device viewport*          | Returns the visible web page area in user’s device.         |
| *Operating system name*    | Returns the operating system.                               |
| *Operating system version* | Returns the version of the operating system.                |
| *User-agent string*        | Returns the browser’s user agent.                           |

## Device location

| Property       | Description                                                                                                                                                                       |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *City*         | Returns the city of the incoming request. For example, `Lisbon`.                                                                                                                  |
| *Continent*    | Returns the continent of the incoming request. For example, `EU`                                                                                                                  |
| *Country* code | Returns the country code of the incoming request. For example, `PT`.                                                                                                              |
| *EU* country   | Returns a `1` if the country of the incoming request is in the European Union, and a `0` if it is not.                                                                            |
| *Region*       | Returns the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) name for the first level region associated with the IP address of the incoming request. For example, `Lisbon`. |
| *Region* code  | Returns the [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) region code associated with the IP address of the incoming request. For example, `11`.                         |
| *Timezone*     | Returns the timezone of the incoming request. For example, `Europe/Lisbon`.                                                                                                       |

## Miscellaneous

| Property                   | Description                                     |
| -------------------------- | ----------------------------------------------- |
| *Random number*            | Returns a random number unique to each request. |
| *Timestamp (milliseconds)* | Returns the Unix time in milliseconds.          |
| *Timestamp (seconds)*      | Returns the Unix time in seconds.               |

---

# Third-party tools

URL: https://developers.cloudflare.com/zaraz/reference/supported-tools/

Cloudflare Zaraz supports the following third-party tools:

| Name                              | Category                          |
| --------------------------------- | --------------------------------- |
| Amplitude                         | Analytics                         |
| Bing                              | Advertising                       |
| Branch                            | Marketing automation              |
| Facebook Pixel                    | Advertising                       |
| Floodlight                        | Advertising                       |
| Google Ads                        | Advertising                       |
| Google Analytics                  | Analytics                         |
| Google Analytics 4                | Analytics                         |
| Google Conversion Linker          | Miscellaneous                     |
| Google Maps - Reserve with Google | Advertising / Miscellaneous       |
| HubSpot                           | Marketing automation              |
| iHire                             | Marketing automation / Recruiting |
| Impact Radius                     | Marketing automation              |
| Instagram                         | Embeds                            |
| Indeed                            | Recruiting                        |
| LinkedIn Insight                  | Advertising                       |
| Mixpanel                          | Analytics                         |
| Outbrain                          | Advertising                       |
| Pinterest                         | Advertising                       |
| Pinterest Conversions API         | Advertising                       |
| Pod Sights                        | Advertising / Analytics           |
| Quora                             | Advertising                       |
| Reddit                            | Advertising                       |
| Segment                           | Customer Data Platform            |
| Snapchat                          | Advertising                       |
| Snowplow                          | Analytics                         |
| Taboola                           | Advertising                       |
| Tatari                            | Advertising                       |
| TikTok                            | Advertising                       |
| Twitter Pixel                     | Advertising / Embeds              |
| Upward                            | Recruiting                        |
| ZipRecruiter                      | Recruiting                        |

For any other tool, use the custom integrations below:

| Name         | Category |
| ------------ | -------- |
| Custom HTML  | Custom   |
| Custom Image | Custom   |
| HTTP Request | Custom   |

Refer to [Add a third-party tool](/zaraz/get-started/) to learn more about this topic.

---

# Settings

URL: https://developers.cloudflare.com/zaraz/reference/settings/

import { Plan } from "~/components";

To configure Zaraz's general settings, select [**Zaraz**](https://dash.cloudflare.com/?to=/:account/:zone/zaraz) > **Settings**. Make sure you save your changes, by selecting the **Save** button after making them.

## Workflow

Allows you to choose between working in Real-time or Preview & Publish modes. By default, Zaraz instantly publishes all changes you make in your account. Choosing Preview & Publish lets you test your settings before committing to them. Refer to [Preview mode](/zaraz/history/preview-mode/) for more information.

## Web API

### Debug Key

The debug key is used to enable Debug Mode. Refer to [Debug mode](/zaraz/web-api/debug-mode/) for more information.

### E-commerce tracking

Toggle this option on to enable the Zaraz E-commerce API. Refer to [E-commerce](/zaraz/web-api/ecommerce/) for more information.

## Compatibility

### Data layer compatibility mode

Cloudflare Zaraz offers backwards compatibility with the `dataLayer` function found in tag management software, used to track events and other parameters. You can toggle this option off if you do not need it. Refer to [Data layer compatibility mode](/zaraz/advanced/datalayer-compatibility/) for more information.

### Single Page Application support

When you toggle Single Page Application support off, the `pageview` trigger will only work when loading a new web page. When enabled, Zaraz's `pageview` trigger will work every time the URL changes on a single page application. This is also known as virtual page views.

## Privacy

Zaraz offers privacy settings you can configure, such as:

* **Remove URL query parameters**: Removes all query parameters from URLs. For example, `https://example.com/?q=hello` becomes `https://example.com/`.

* **Trim IP addresses**: Trims part of the IP address before passing it to server-side loaded tools, to hide it from third-parties.

* **Clean User Agent strings**: Clear sensitive information from the User Agent string by removing information such as operating system version, extensions installed, among others.

* **Remove external referrers**: Hides the page referrers URL if the hostname is different from the website's.

* **Cookie domain**: Choose the domain on which Zaraz will set your tools' cookies. By default, Zaraz will attempt to save the cookies on the highest-level domain possible, meaning that if your website is on `foo.example.com`, the cookies will be saved on `example.com`. You can change this behavior and configure the cookies to be saved on `foo.example.com` by entering a custom domain here.

## Injection

### Auto-inject script

This option automatically injects the script needed for Zaraz to work on your website. It is turned on by default.

If you turn this option off, Zaraz will stop automatically injecting its script on your domain. If you still want Zaraz functionality, you will need to add the Zaraz script manually. Refer to [Load Zaraz manually](/zaraz/advanced/load-zaraz-manually/) for more information.

### Iframe injection

When toggled on, the Zaraz script will also be injected into `iframe` elements.

## Endpoints

Specify custom URLs for Zaraz's scripts. You need to use a valid pathname:

```txt
/<PATHNAME>/<FILE.JS>
```

This is an example of a custom pathname to host Zaraz's initialization script:

```txt
/my-server/my-scripts/start.js
```

### HTTP Events API

Refer to [HTTP Events API](/zaraz/http-events-api/) for more information on this endpoint.

## Other

### Bot Score Threshold

Choose whether to prevent Zaraz from loading on suspected bot-initiated requests. This is based on the request's [bot score](/bots/concepts/bot-score/) which is an estimate, and therefore cannot be guaranteed to be always accurate.

The options are:

* **Block none**: Load Zaraz for all requests, even if those come from bots.
* **Block automated only**: Prevent Zaraz from loading on requests from requests in the [**Automated** category](/bots/concepts/bot-score/#bot-groupings).
* **Block automated and likely automated**: Prevent Zaraz from loading on requests from requests in the [**Automated** and **Likely Automated** category](/bots/concepts/bot-score/#bot-groupings).

### Context Enricher

Refer to the [Context Enricher](/zaraz/advanced/context-enricher/) for more information on this setting.

### Logpush

<Plan type="enterprise" />

Send Zaraz events logs to an external storage service.

Refer to [Logpush](/zaraz/advanced/logpush/) for more information on this setting.

---

# Triggers and rules

URL: https://developers.cloudflare.com/zaraz/reference/triggers/

Triggers define the conditions under which [a tool will start an action](/zaraz/custom-actions/). In most cases, your objective will be to create triggers that match specific website events that are relevant to your business. A trigger can be based on an event that happened on your website, like after selecting a button or loading a specific page.

These website events can be passed to Cloudflare Zaraz in a number of ways. You can use the [Track](/zaraz/web-api/track/) method of the Web API or the [`dataLayer`](/zaraz/advanced/datalayer-compatibility/) call. Alternatively, if you do not want to write code to track events on your website, you can configure triggers to listen to browser-side website events, with different types of rules like click listeners or form submissions.

## Rule types

The exact composition of the trigger will change depending on the type of rule you choose.

### Match rule

Zaraz matches the variable you input in **Variable name** with the text under **Match string**. For a complete list of supported variables, refer to [Properties reference](/zaraz/reference/properties-reference/).

**Trigger example: Match `zaraz.track("purchase")`**

| Rule type    | Variable name | Match operation | Match string |
| ------------ | ------------- | --------------- | ------------ |
| _Match rule_ | _Event Name_  | _Equals_        | `purchase`   |

If you create a trigger with match rules using variables from Page Properties, Cookies, Device Properties, or Miscellaneous categories, you will often want to add a second rule that matches `Pageview`. Otherwise, your trigger will be valid for every other event happening on this page too. Refer to [Create a trigger](/zaraz/custom-actions/create-trigger/) to learn how to add more than one condition to a trigger.

**Trigger example: All pages under `/blog`**

| Rule type    | Variable name  | Match operation | Match string |
| ------------ | -------------- | --------------- | ------------ |
| _Match rule_ | _URL pathname_ | _Starts with_   | `/blog`      |

| Rule type    | Variable name | Match operation | Match string |
| ------------ | ------------- | --------------- | ------------ |
| _Match rule_ | _Event Name_  | _Equals_        | `Pageview`   |

**Trigger example: All logged in users**

| Rule type    | Variable name                | Match operation | Match string |
| ------------ | ---------------------------- | --------------- | ------------ |
| _Match rule_ | _Cookie: name:_ `isLoggedIn` | _Equals_        | `true`       |

| Rule type    | Variable name | Match operation | Match string |
| ------------ | ------------- | --------------- | ------------ |
| _Match rule_ | _Event Name_  | _Equals_        | `Pageview`   |

Refer to [Properties reference](/zaraz/reference/properties-reference/) for more information on the variables you can use when using Match rule.

### Click listener

Tracks clicks in a web page. You can set up click listeners using CSS selectors or XPath expressions. **Wait for actions** (in milliseconds) tells Zaraz to prevent the page from changing for the amount of time specified. This allows all requests triggered by the click listener to reach their destination.

:::note

When using CSS type rules in triggers, you have to include the CSS selector — for example, the ID (`#`) or the class (`.`) symbols. Otherwise, the click listener will not work.
:::

**Trigger example for CSS selector:**

| Rule type        | Type  | Selector     | Wait for actions |
| ---------------- | ----- | ------------ | ---------------- |
| _Click listener_ | _CSS_ | `#my-button` | `500`            |

To improve the performance of the web page, you can limit a click listener to a specific URL, by combining it with a Match rule. For example, to track button clicks on a specific page you can set up the following rules in a trigger:

| Rule type        | Type  | Selector    | Wait for actions |
| ---------------- | ----- | ----------- | ---------------- |
| _Click listener_ | _CSS_ | `#myButton` | `500`            |

| Rule type    | Variable name  | Match operation | Match string    |
| ------------ | -------------- | --------------- | --------------- |
| _Match rule_ | _URL pathname_ | _Equals_        | `/my-page-path` |

If you need to track a link of an element using CSS selectors - for example, on a clickable button - you have to create a listener for the `href` attribute of the `<a>` tag:

| Rule type        | Type  | Selector                       | Wait for actions |
| ---------------- | ----- | ------------------------------ | ---------------- |
| _Click listener_ | _CSS_ | `a[href$='/#my-css-selector']` | `500`            |

Refer to [**Create a trigger**](/zaraz/custom-actions/create-trigger/) to learn how to add more than one rule to a trigger.

---

**Trigger example for XPath:**

| Rule type        | Type    | Selector                                         | Wait for actions |
| ---------------- | ------- | ------------------------------------------------ | ---------------- |
| _Click listener_ | _XPath_ | `/html/body//*[contains(text(), 'Add To Cart')]` | `500`            |

### Element Visibility

Triggers an action when a CSS selector becomes visible in the screen.

| Rule type            | CSS Selector |
| -------------------- | ------------ |
| _Element Visibility_ | `#my-id`     |

### Scroll depth

Triggers an action when the users scrolls a predetermined amount of pixels. This can be a fixed amount of pixels or a percentage of the screen.

**Example with pixels**

| Rule type      | CSS Selector |
| -------------- | ------------ |
| _Scroll Depth_ | `100px`      |

---

**Example with a percentage of the screen**

| Rule type      | CSS Selector |
| -------------- | ------------ |
| _Scroll Depth_ | `45%`        |

### Form submission

Tracks form submissions using CSS selectors. Select the **Validate** toggle button to only fire the trigger when the form has no validation errors.

**Trigger example:**

| Rule type         | CSS Selector | Validate         |
| ----------------- | ------------ | ---------------- |
| _Form submission_ | `#my-form`   | Toggle on or off |

To improve the performance of the web page, you can limit a Form submission trigger to a specific URL, by combining it with a Match rule. For example, to track a form on a specific page you can set up the following rules in a trigger:

| Rule type         | CSS Selector | Validate         |
| ----------------- | ------------ | ---------------- |
| _Form submission_ | `#my-form`   | Toggle on or off |

| Rule type    | Variable name  | Match operation | Match string    |
| ------------ | -------------- | --------------- | --------------- |
| _Match rule_ | _URL pathname_ | _Equals_        | `/my-page-path` |

Refer to [**Create a trigger**](/zaraz/custom-actions/create-trigger/) to learn how to add more than one condition to a trigger.

### Timer

Set up a timer that will fire the trigger after each **Interval**. Set your interval time in milliseconds. In **Limit** specify the number of times the interval will run, causing the trigger to fire. If you do not specify a limit, the timer will repeat for as long as the page is on display.

**Trigger example:**

| Rule type | Interval | Limit |
| --------- | -------- | ----- |
| _Timer_   | `5000`   | `1`   |

The above Timer will fire once, after five seconds. To improve the performance of a web page, you can limit a Timer trigger to a specific URL, by combining it with a Match rule. For example, to set up a timer on a specific page you can set up the following rules in a trigger:

| Rule type | Interval | Limit |
| --------- | -------- | ----- |
| _Timer_   | `5000`   | `1`   |

| Rule type    | Variable name  | Match operation | Match string    |
| ------------ | -------------- | --------------- | --------------- |
| _Match rule_ | _URL pathname_ | _Equals_        | `/my-page-path` |

Refer to [**Create a trigger**](/zaraz/custom-actions/create-trigger/) to learn how to add more than one condition to a trigger.

---

# Create a variable

URL: https://developers.cloudflare.com/zaraz/variables/create-variables/

Variables are reusable blocks of information. They allow you to have one source of data you can reuse across tools and triggers in the dashboard. You can then update this data in a single place.

For example, instead of typing a specific user ID in multiple fields, you can create a variable with that information instead. If there is a change and you have to update the user ID, you just need to update the variable and the change will be reflected across the dashboard.

[Worker Variables](/zaraz/variables/worker-variables/) are a special type of variable that generates value dynamically.

## Create a new variable

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools Configuration** > **Variables**.
3. Select **Create variable**, and give it a name.
4. In **Variable type** select between `String`, `Masked variable` or `Worker` from the drop-down menu. Use `Masked variable` when you have a private value that you do not want to share, such as an API token.
5. In **Variable value** enter the value of your variable.
6. Select **Save**.

Your variable is now ready to be used with tools and triggers.

## Next steps

Refer to [Add a third-party tool](/zaraz/get-started/) and [Create a trigger](/zaraz/custom-actions/create-trigger/) for more information on how to add a variable to tools and triggers.

If you need to edit or delete variables, refer to [Edit variables](/zaraz/variables/edit-variables/).

---

# Edit variables

URL: https://developers.cloudflare.com/zaraz/variables/edit-variables/

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools Configuration** > **Variables**.
3. Locate the variable you want to edit, and select **Edit** to make your changes.
4. Select **Save** to save your edits.

## Delete a variable

:::caution[Important]
You cannot delete a variable being used in tools or triggers.
:::

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Tools Configuration** > **Third-party tools**.
3. Locate any tools using the variable, and delete the variable from those tools.
4. Select **Zaraz** > **Tools Configuration** > **Triggers**.
5. Locate all the triggers using the variable, and delete the variable from those triggers.
6. Navigate to **Zaraz** > **Tools Configuration** > **Variables**.
7. Locate the variable you want to delete, and select **Delete**.

---

# Variables

URL: https://developers.cloudflare.com/zaraz/variables/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Worker Variables

URL: https://developers.cloudflare.com/zaraz/variables/worker-variables/

Zaraz Worker Variables are a powerful type of variable that you can configure and then use in your actions and triggers. Unlike string and masked variables, Worker Variables are dynamic. This means you can use a Cloudflare Worker to determine the value of the variable, allowing you to use them for countless purposes. For example:

1. A Worker Variable that calculates the sum of all products in the cart
2. A Worker Variable that takes a cookie, makes a request to your backend, and returns the User ID
3. A Worker Variable that hashes a value before sending it to a third-party vendor

## Creating a Worker

To use a Worker Variable, you first need to create a new Cloudflare Worker. You can do this through the Cloudflare dashboard or by using [Wrangler](/workers/get-started/guide/).

To create a new Worker in the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/).
2. Go to **Workers & Pages** and select **Create application**.
3. Give a name to your Worker and select **Deploy**.
4. Select **Edit code**.

You have now created a basic Worker that responds with "Hello world." If you use this Worker as a Variable, your Variable will always output "Hello world." The response body coming from your Worker will be the value of your Worker Variable. To make this Worker useful, you will usually want to use information coming from Zaraz, which is known as the Zaraz Context.

Zaraz forwards the Zaraz Context object to your Worker as a JSON payload with a POST request. You can access any property like this:

```js
const { system, client } = await request.json()

/* System parameters */
system.page.url.href // URL of the current page
system.page.query.gclid // Value of the gclid query parameter
system.device.resolution // Device screen resolution
system.device.language // Browser preferred language

/* Zaraz Track values */
client.value // value from `zaraz.track("foo", {value: "bar"})`
client.products[0].name // name of the first product in an ecommerce call
```

Keep reading for more complete examples of different use cases or refer to [Zaraz Context](/zaraz/reference/context/).

## Configuring a Worker Variable

Once your Worker is published, configuring a Worker Variable is easy.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/).
2. Go to **Zaraz** > **Tools configuration** > **Variables**.
3. Click **Create variable**.
4. Give your variable a name, choose **Worker** as the Variable type, and select your newly created Worker.
5. Save your variable.

## Using your Worker Variable

Now that your Worker Variable is configured, you can use it in your actions and triggers.

To use your Worker Variable:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/), and select your account and domain.
2. Go to **Zaraz** > **Tools configuration** > **Tools**.
3. Click **Edit** next to a tool that you have already configured.
4. Select an action or add a new one.
5. Click on the plus sign at the right of the text fields.
6. Select your Worker Variable from the list.

## Example Worker Variables

### Calculates the sum of all products in the cart

Assuming we are sending a list of products in a cart, like this:

```js
zaraz.ecommerce("Cart Viewed", {
  products: [
    { name: "shirt", price: "50" },
    { name: "jacket", price: "20" },
    { name: "hat", price: "30" },
  ],
});
```

Calculating the sum can be done like this:

```js
export default {
  async fetch(request, env) {
    // Parse the Zaraz Context object
    const { system, client } = await request.json();

    // Get an array of all prices
    const productsPrices = client.products.map((p) => p.price);

    // Calculate the sum
    const sum = productsPrices.reduce((partialSum, a) => partialSum + a, 0);

    return new Response(sum);
  },
};
```

### Match a cookie with a user in your backend

Zaraz exposes all cookies automatically under the `system.cookies` object, so they are always available. Accessing the cookie and using it to query your backend might look like this:

```js
export default {
  async fetch(request, env) {
    // Parse the Zaraz Context object
    const { system, client } = await request.json();

    // Get the value of the cookie "login-cookie"
    const cookieValue = system.cookies["login-cookie"];

    const userId = await fetch("https://example.com/api/getUserIdFromCookie", {
      method: POST,
      body: cookieValue,
    });

    return new Response(userId);
  },
};
```

### Hash a value before sending it to a third-party vendor

Assuming you're sending a value that your want to hash, for example, an email address:

```js
zaraz.track("user_logged_in", { email: "user@example.com" });
```

You can access this property and hash it like this:

```js
async function digestMessage(message) {
  const msgUint8 = new TextEncoder().encode(message); // encode as (utf-8) Uint8Array
  const hashBuffer = await crypto.subtle.digest("SHA-256", msgUint8); // hash the message
  const hashArray = Array.from(new Uint8Array(hashBuffer)); // convert buffer to byte array
  const hashHex = hashArray
    .map((b) => b.toString(16).padStart(2, "0"))
    .join(""); // convert bytes to hex string
  return hashHex;
}

export default {
  async fetch(request, env) {
    // Parse the Zaraz Context object
    const { system, client } = await request.json();

    const { email } = client;

    return new Response(await digestMessage(email));
  },
};
```

---

# Debug mode

URL: https://developers.cloudflare.com/zaraz/web-api/debug-mode/

Zaraz offers a debug mode to troubleshoot the events and triggers systems. To activate debug mode you need to create a special debug cookie (`zarazDebug`) containing your debug key.
You can set this cookie manually or via the `zaraz.debug` helper function available in your console.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account and domain.
2. Go to **Zaraz** > **Settings**.
3. Copy your **Debug Key**.
4. Open a web browser and access its Developer Tools. For example, to access Developer Tools in Google Chrome, select **View** > **Developer** > **Developer Tools**.
5. Select the **Console** pane and enter the following command to create a debug cookie:

   ```js
   zaraz.debug("YOUR_DEBUG_KEY")
   ```

Zaraz’s debug mode is now enabled. A pop-up window will show up with the debugger information. To exit debug mode, remove the cookie by typing `zaraz.debug()` in the console pane of the browser.

---

# E-commerce

URL: https://developers.cloudflare.com/zaraz/web-api/ecommerce/

You can use `zaraz.ecommerce()` anywhere inside the `<body>` tag of a page.

`zaraz.ecommerce()` allows you to track common events of the e-commerce user journey, such as when a user adds a product to cart, starts the checkout funnel or completes an order on your website. It is an `async` function, so you can choose to `await` it if you would like to make sure it completed before running other code.

To start using `zaraz.ecommerce()`, you first need to enable it in your Zaraz account and enable the E-commerce action for the tool you plan to send e-commerce data to. Then, add `zaraz.ecommerce()` to the `<body>` element of your website.

Right now, Zaraz e-commerce is compatible with Google Analytics 3 (Universal Analytics), Google Analytics 4, Bing, Facebook Pixel, Amplitude, Pinterest Conversions API, TikTok and Branch.

:::note[Note]
It is crucial you follow the guidelines set by third-party tools, such as Google Analytics 3 and Google Analytics 4, to ensure compliance with their limitations on payload size and length. For instance, if your `Order Completed` call includes a large number of products, it may exceed the limitations of the selected tool.
:::

## Enable e-commerce tracking

You do not need to map e-commerce events to triggers. Zaraz automatically forwards data using the right format to the tools with e-commerce support.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account and domain.
2. Select **Zaraz** > **Settings**.
3. Enable **E-commerce tracking**.
4. Select **Save**.
5. Go to **Zaraz** > **Tools Configuration** > **Third-party tools**.
6. Locate the tool you want to use with e-commerce tracking and select **Edit**.
7. Select **Settings**.
8. Under **Advanced**, enable **E-commerce tracking**.
9. Select **Save**.

E-commerce tracking is now enabled. If you add additional tools to your website that you want to use with `zaraz.ecommerce()`, you will need to repeat steps 6-9 for that tool.

## Add e-commerce tracking to your website

After enabling e-commerce tracking on your Zaraz dashboard, you need to add `zaraz.ecommerce()` to the `<body>` element of your website:

```js
zaraz.ecommerce("Event Name", { parameters });
```

To create a complete tracking event, you need to add an event and one or more parameters. Below you will find a list of events and parameters Zaraz supports, as well as code examples for different types of events.

## List of supported events

- `Product List Viewed`
- `Products Searched`
- `Product Clicked`
- `Product Added`
- `Product Added to Wishlist`
- `Product Removed`
- `Product Viewed`
- `Cart Viewed`
- `Checkout Started`
- `Checkout Step Viewed`
- `Checkout Step Completed`
- `Payment Info Entered`
- `Order Completed`
- `Order Updated`
- `Order Refunded`
- `Order Cancelled`
- `Clicked Promotion`
- `Viewed Promotion`
- `Shipping Info Entered`

## List of supported parameters:

| Parameter                | Type   | Description                                                                                 |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------- |
| `product_id`             | String | Product ID.                                                                                 |
| `sku`                    | String | Product SKU number.                                                                         |
| `category`               | String | Product category.                                                                           |
| `name`                   | String | Product name.                                                                               |
| `brand`                  | String | Product brand name.                                                                         |
| `variant`                | String | Product variant (depending on the product, it could be product color, size, etc.).          |
| `price`                  | Number | Product price.                                                                              |
| `quantity`               | Number | Product number of units.                                                                    |
| `coupon`                 | String | Name or serial number of coupon code associated with product.                               |
| `position`               | Number | Product position in the product list (for example, `2`).                                    |
| `products`               | Array  | List of products displayed in the product list.                                             |
| `products.[].product_id` | String | Product ID displayed on the product list.                                                   |
| `products.[].sku`        | String | Product SKU displayed on the product list.                                                  |
| `products.[].category`   | String | Product category displayed on the product list.                                             |
| `products.[].name`       | String | Product name displayed on the product list.                                                 |
| `products.[].brand`      | String | Product brand displayed on the product list.                                                |
| `products.[].variant`    | String | Product variant displayed on the product list.                                              |
| `products.[].price`      | Number | Price of the product displayed on the product list.                                         |
| `products.[].quantity`   | Number | Quantity of a product displayed on the product list.                                        |
| `products.[].coupon`     | String | Name or serial number of coupon code associated with product displayed on the product list. |
| `products.[].position`   | Number | Product position in the product list (for example, `2`).                                    |
| `checkout_id`            | String | Checkout ID.                                                                                |
| `order_id`               | String | Internal ID of order/transaction/purchase.                                                  |
| `affiliation`            | String | Name of affiliate from which the order occurred.                                            |
| `total`                  | Number | Revenue with discounts and coupons added in.                                                |
| `revenue`                | Number | Revenue excluding shipping and tax.                                                         |
| `shipping`               | Number | Cost of shipping for transaction.                                                           |
| `tax`                    | Number | Total tax for transaction.                                                                  |
| `discount`               | Number | Total discount for transaction.                                                             |
| `coupon`                 | String | Name or serial number of coupon redeemed on the transaction-level.                          |
| `currency`               | String | Currency code for the transaction.                                                          |
| `value`                  | Number | Total value of the product after quantity.                                                  |
| `creative`               | String | Label for creative asset of promotion being tracked.                                        |
| `query`                  | String | Product search term.                                                                        |
| `step`                   | Number | The Number of the checkout step in the checkout process.                                    |
| `payment_type`           | String | The type of payment used.                                                                   |

## Event code examples

### Product viewed

```js
zaraz.ecommerce("Product Viewed", {
	product_id: "999555321",
	sku: "2671033",
	category: "T-shirts",
	name: "V-neck T-shirt",
	brand: "Cool Brand",
	variant: "White",
	price: 14.99,
	currency: "usd",
	value: 18.99,
});
```

### Product List Viewed

```js
zaraz.ecommerce("Product List Viewed", {
	products: [
		{
			product_id: "999555321",
			sku: "2671033",
			category: "T-shirts",
			name: "V-neck T-shirt",
			brand: "Cool Brand",
			variant: "White",
			price: 14.99,
			currency: "usd",
			value: 18.99,
			position: 1,
		},
		{
			product_id: "999555322",
			sku: "2671034",
			category: "T-shirts",
			name: "T-shirt",
			brand: "Cool Brand",
			variant: "Pink",
			price: 10.99,
			currency: "usd",
			value: 16.99,
			position: 2,
		},
	],
});
```

### Product added

```js
zaraz.ecommerce("Product Added", {
	product_id: "999555321",
	sku: "2671033",
	category: "T-shirts",
	name: "V-neck T-shirt",
	brand: "Cool Brand",
	variant: "White",
	price: 14.99,
	currency: "usd",
	quantity: 1,
	coupon: "SUMMER-SALE",
	position: 2,
});
```

### Checkout Step Viewed

```js
zaraz.ecommerce("Checkout Step Viewed", {
	step: 1,
});
```

### Order completed

```js
zaraz.ecommerce("Order Completed", {
	checkout_id: "616727740",
	order_id: "817286897056801",
	affiliation: "affiliate.com",
	total: 30.0,
	revenue: 20.0,
	shipping: 3,
	tax: 2,
	discount: 5,
	coupon: "winter-sale",
	currency: "USD",
	products: [
		{
			product_id: "999666321",
			sku: "8251511",
			name: "Boy’s shorts",
			price: 10,
			quantity: 2,
			category: "shorts",
		},
		{
			product_id: "742566131",
			sku: "7251567",
			name: "Blank T-shirt",
			price: 5,
			quantity: 2,
			category: "T-shirts",
		},
	],
});
```

---

# Web API

URL: https://developers.cloudflare.com/zaraz/web-api/

import { DirectoryListing } from "~/components"

Zaraz provides a client-side web API that you can use anywhere inside the `<body>` tag of a page.

This API allows you to send events and data to Zaraz, that you can later use when creating your triggers. Using the API lets you tailor the behavior of Zaraz to your needs: You can launch tools only when you need them, or send information you care about that is not otherwise automatically collected from your site.

<DirectoryListing />

---

# Set

URL: https://developers.cloudflare.com/zaraz/web-api/set/

You can use `zaraz.set()` anywhere inside the `<body>` tag of a page:

```js
zaraz.set(key, value, [options])
```

Set is useful if you want to make a variable available in all your events without manually setting it every time you are using `zaraz.track()`. For the purpose of this example, assume users in your system have a unique identifier that you want to send to your tools. You might have many `zaraz.track()` calls all sharing this one parameter:

```js
zaraz.track("form completed", {userId: "ABC-123"})
```

```js
zaraz.track("button clicked", {userId: "ABC-123", value: 200})
```

```js
zaraz.track("cart viewed", {items: 3, userId: "ABC-123"})
```

Here, all the events are collecting the `userId` key, and the code for setting that key repeats itself. With `zaraz.set()` you can avoid repetition by setting the key once when the page loads. Zaraz will then attach this key to all future `zaraz.track()` calls.

Using the above data as the example, if you use `zaraz.set("userId", "ABC-123")` once, before the `zaraz.track()` calls, you can remove the `userId` key from all `zaraz.track()` calls.

Another example:

```js
zaraz.set('product_name', 't-shirt', {scope: 'page'})
```

Keys that are sent using `zaraz.set()` can be used inside tool actions exactly like keys in the `eventProperties` of `zaraz.track()`. So, the above `product` key is accessible through the Cloudflare dashboard with the variable *Track Property name:*, and setting its name as `product_name`. Zaraz will then replace it with `t-shirt`.

![Example of how to create a variable with the Set method, tracking t-shirts](~/assets/images/zaraz/set.png)

The `[options]` argument is an optional object and can include a `scope` property that has a string value. This property determines the lifetime of this key, meaning for how long Zaraz should keep attaching it to `zaraz.track()` calls. Allowed values are:

* `page`: To set the key for the context of the current page only.
* `session`: To make the key last the whole session.
* `persist`: To save the key across sessions. This is the default mode and uses `localStorage` to save the value.

In the previous example, `{scope: 'page'}` makes the `product_name` property available to all `zaraz.track()` calls in the current page, but will not affect calls after visitors navigate to other pages.

To unset a variable, set it to `undefined`. The variable will then be removed from all scopes it was included in, and will not be automatically sent with future `zaraz.track` calls. For example:

```js
zaraz.set('product_name', undefined)
```

---

# Track

URL: https://developers.cloudflare.com/zaraz/web-api/track/

You can use `zaraz.track()` anywhere inside the `<body>` tag of a page.

`zaraz.track()` allows you to track custom events on your website, that might happen in real time. It is an `async` function, so you can choose to `await` it if you would like to make sure it completed before running other code.

Example of user events you might be interested in tracking are successful sign-ups, calls-to-action clicks, or purchases. Common examples for other types of events are tracking the impressions of specific elements on a page, or loading a specific widget.

To start tracking events, use the `zaraz.track()` function like this:

```js
zaraz.track(eventName, [eventProperties]);
```

The `eventName` parameter is a string, and the `eventProperties` parameter is an optional flat object of additional context you can attach to the event using your own keys of choice. For example, tracking a purchase with the value of 200 USD could look like this:

```js
zaraz.track("purchase", { value: 200, currency: "USD" });
```

Note that the name of the event (`purchase` in the above example), the names of the keys (`value` and `currency`) and the number of keys are customizable by you. You choose what variables to track and how you want to track these variables. However, picking meaningful names will help you when you configure your triggers, because the trigger configuration has to match the events your website is sending.

After using `zaraz.track()` in your website, you will usually want to create a trigger based on it, and then use the trigger in an action. Start by [creating a new trigger](/zaraz/custom-actions/create-trigger/), with _Event Name_ as your trigger's **Variable name**, and the `eventName` you are tracking in **Match string**. Following the above example, your trigger will look like this:

**Trigger example: Match `zaraz.track("purchase")`**

| Rule type    | Variable name | Match operation | Match string |
| ------------ | ------------- | --------------- | ------------ |
| _Match rule_ | _Event Name_  | _Equals_        | `purchase`   |

In every tool you want to use this trigger, add an action with this trigger [configured as a firing trigger](/zaraz/custom-actions/). Each action that uses this trigger can access the `eventProperties` you have sent. In the **Action** fields, you can use `{{ client.<KEY_NAME> }}` to get the value of `<KEY_NAME>`. In the above example, Zaraz will replace `{{ client.value }}` with `200`. If your key includes special characters or numbers, surround it with backticks like ``{{ client.`<KEY_NAME>` }}``.

For more information regarding the properties you can use with `zaraz.track()`, refer to [Properties reference](/zaraz/reference/properties-reference/).

---

# Logging

URL: https://developers.cloudflare.com/ai-gateway/observability/logging/

import { Render } from "~/components";

Logging is a fundamental building block for application development. Logs provide insights during the early stages of development and are often critical to understanding issues occurring in production.

Your AI Gateway dashboard shows logs of individual requests, including the user prompt, model response, provider, timestamp, request status, token usage, cost, and duration. These logs persist, giving you the flexibility to store them for your preferred duration and do more with valuable request data.

By default, each gateway can store up to 10 million logs. You can customize this limit per gateway in your gateway settings to align with your specific requirements. If your storage limit is reached, new logs will stop being saved. To continue saving logs, you must delete older logs to free up space for new logs.
To learn more about your plan limits, refer to [Limits](/ai-gateway/reference/limits/).

We recommend using an authenticated gateway when storing logs to prevent unauthorized access and protects against invalid requests that can inflate log storage usage and make it harder to find the data you need. Learn more about setting up an [authenticated gateway](/ai-gateway/configuration/authentication/).

## Default configuration

Logs, which include metrics as well as request and response data, are enabled by default for each gateway. This logging behavior will be uniformly applied to all requests in the gateway. If you are concerned about privacy or compliance and want to turn log collection off, you can go to settings and opt out of logs. If you need to modify the log settings for specific requests, you can override this setting on a per-request basis.

<Render file="logging" />

## Per-request logging

To override the default logging behavior set in the settings tab, you can define headers on a per-request basis.

### Collect logs (`cf-aig-collect-log`)

The `cf-aig-collect-log` header allows you to bypass the default log setting for the gateway. If the gateway is configured to save logs, the header will exclude the log for that specific request. Conversely, if logging is disabled at the gateway level, this header will save the log for that request.

In the example below, we use `cf-aig-collect-log` to bypass the default setting to avoid saving the log.

```bash
curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-collect-log: false \
  --data ' {
        "model": "gpt-4o-mini",
        "messages": [
          {
            "role": "user",
            "content": "What is the email address and phone number of user123?"
          }
        ]
      }
'
```

## Managing log storage

To manage your log storage effectively, you can:
- Set Storage Limits: Configure a limit on the number of logs stored per gateway in your gateway settings to ensure you only pay for what you need.
- Enable Automatic Log Deletion: Activate the Automatic Log Deletion feature in your gateway settings to automatically delete the oldest logs once the log limit you've set or the default storage limit of 10 million logs is reached. This ensures new logs are always saved without manual intervention.

## How to delete logs

To manage your log storage effectively and ensure continuous logging, you can delete logs using the following methods:

### Automatic Log Deletion

​To maintain continuous logging within your gateway's storage constraints, enable Automatic Log Deletion in your Gateway settings. This feature automatically deletes the oldest logs once the log limit you've set or the default storage limit of 10 million logs is reached, ensuring new logs are saved without manual intervention.

### Manual deletion

To manually delete logs through the dashboard, navigate to the Logs tab in the dashboard. Use the available filters such as status, cache, provider, cost, or any other options in the dropdown to refine the logs you wish to delete. Once filtered, select Delete logs to complete the action.

See full list of available filters and their descriptions below:

| Filter category | Filter options                                               | Filter by description                     |
| --------------- | ------------------------------------------------------------ | ----------------------------------------- |
| Status          | error, status                                                | error type or status.                     |
| Cache           | cached, not cached                                           | based on whether they were cached or not. |
| Provider        | specific providers                                           | the selected AI provider.                 |
| AI Models       | specific models                                              | the selected AI model.                    |
| Cost            | less than, greater than                                      | cost, specifying a threshold.             |
| Request type    | Universal, Workers AI Binding, WebSockets                    | the type of request.                      |
| Tokens          | Total tokens, Tokens In, Tokens Out                          | token count (less than or greater than).  |
| Duration        | less than, greater than                                      | request duration.                         |
| Feedback        | equals, does not equal (thumbs up, thumbs down, no feedback) | feedback type.                            |
| Metadata Key    | equals, does not equal                                       | specific metadata keys.                   |
| Metadata Value  | equals, does not equal                                       | specific metadata values.                 |
| Log ID          | equals, does not equal                                       | a specific Log ID.                        |
| Event ID        | equals, does not equal                                       | a specific Event ID.                      |

### API deletion

You can programmatically delete logs using the AI Gateway API. For more comprehensive information on the `DELETE` logs endpoint, check out the [Cloudflare API documentation](/api/resources/ai_gateway/subresources/logs/methods/delete/).

---

# Workers Logpush

URL: https://developers.cloudflare.com/ai-gateway/observability/logging/logpush/

import { Render, Tabs, TabItem } from "~/components";

AI Gateway allows you to securely export logs to an external storage location, where you can decrypt and process them.
You can toggle Workers Logpush on and off in the [Cloudflare dashboard](https://dash.cloudflare.com) settings. This product is available on the Workers Paid plan. For pricing information, refer to [Pricing](/ai-gateway/reference/pricing).

This guide explains how to set up Workers Logpush for AI Gateway, generate an RSA key pair for encryption, and decrypt the logs once they are received.

You can store up to 10 million logs per gateway. If your limit is reached, new logs will stop being saved and will not be exported through Workers Logpush. To continue saving and exporting logs, you must delete older logs to free up space for new logs. Workers Logpush has a limit of 4 jobs and a maximum request size of 1 MB per log.

:::note[Note]

To export logs using Workers Logpush, you must have logs turned on for the gateway.

:::

<Render file="limits-increase" product="ai-gateway" />

## How logs are encrypted

We employ a hybrid encryption model efficiency and security. Initially, an AES key is generated for each log. This AES key is what actually encrypts the bulk of your data, chosen for its speed and security in handling large datasets efficiently.

Now, for securely sharing this AES key, we use RSA encryption. Here's what happens: the AES key, although lightweight, needs to be transmitted securely to the recipient. We encrypt this key with the recipient's RSA public key. This step leverages RSA's strength in secure key distribution, ensuring that only someone with the corresponding RSA private key can decrypt and use the AES key.

Once encrypted, both the AES-encrypted data and the RSA-encrypted AES key are sent together. Upon arrival, the recipient's system uses the RSA private key to decrypt the AES key. With the AES key now accessible, it is straightforward to decrypt the main data payload.

This method combines the best of both worlds: the efficiency of AES for data encryption with the secure key exchange capabilities of RSA, ensuring data integrity, confidentiality, and performance are all optimally maintained throughout the data lifecycle.

## Setting up Workers Logpush

To configure Workers Logpush for AI Gateway, follow these steps:

## 1. Generate an RSA key pair locally

You need to generate a key pair to encrypt and decrypt the logs. This script will output your RSA privateKey and publicKey. Keep the private key secure, as it will be used to decrypt the logs. Below is a sample script to generate the keys using Node.js and OpenSSL.

<Tabs syncKey="JSPlusSSL"> <TabItem label="JavaScript">

```js title="JavaScript"
const crypto = require("crypto");

const { privateKey, publicKey } = crypto.generateKeyPairSync("rsa", {
	modulusLength: 4096,
	publicKeyEncoding: {
		type: "spki",
		format: "pem",
	},
	privateKeyEncoding: {
		type: "pkcs8",
		format: "pem",
	},
});

console.log(publicKey);
console.log(privateKey);
```

Run the script by executing the below code on your terminal. Replace `file name` with the name of your JavaScript file.

```bash
node {file name}
```

</TabItem> <TabItem label="OpenSSL">

1. Generate private key:
   Use the following command to generate a RSA private key:

   ```bash
   openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096
   ```

2. Generate public key:
   After generating the private key, you can extract the corresponding public key using:

   ```bash
   openssl rsa -pubout -in private_key.pem -out public_key.pem
   ```

</TabItem> </Tabs>

## 2. Upload public key to gateway settings

Once you have generated the key pair, upload the public key to your AI Gateway settings. This key will be used to encrypt your logs. In order to enable Workers Logpush, you will need logs enabled for that gateway.

## 3. Set up Logpush

To set up Logpush, refer to [Logpush Get Started](/logs/get-started/).

## 4. Receive encrypted logs

After configuring Workers Logpush, logs will be sent encrypted using the public key you uploaded. To access the data, you will need to decrypt it using your private key. The logs will be sent to the object storage provider that you have selected.

## 5. Decrypt logs

To decrypt the encrypted log bodies and metadata from AI Gateway, you can use the following Node.js script or OpenSSL:

<Tabs syncKey="JSPlusSSL"> <TabItem label="JavaScript">

To decrypt the encrypted log bodies and metadata from AI Gateway, download the logs to a folder, in this case its named `my_log.log.gz`.

Then copy this JavaScript file into the same folder and place your private key in the top variable.

```js title="JavaScript"
const privateKeyStr = `-----BEGIN RSA PRIVATE KEY-----
....
-----END RSA PRIVATE KEY-----`;

const crypto = require("crypto");
const privateKey = crypto.createPrivateKey(privateKeyStr);

const fs = require("fs");
const zlib = require("zlib");
const readline = require("readline");

async function importAESGCMKey(keyBuffer) {
	try {
		// Ensure the key length is valid for AES
		if ([128, 192, 256].includes(256)) {
			return await crypto.webcrypto.subtle.importKey(
				"raw",
				keyBuffer,
				{
					name: "AES-GCM",
					length: 256,
				},
				true, // Whether the key is extractable (true in this case to allow for export later if needed)
				["encrypt", "decrypt"], // Use for encryption and decryption
			);
		} else {
			throw new Error("Invalid AES key length. Must be 128, 12, or 256 bits.");
		}
	} catch (error) {
		console.error("Failed to import key:", error);
		throw error;
	}
}

async function decryptData(encryptedData, aesKey, iv) {
	const decryptedData = await crypto.subtle.decrypt(
		{ name: "AES-GCM", iv: iv },
		aesKey,
		encryptedData,
	);
	return new TextDecoder().decode(decryptedData);
}

async function decryptBase64(privateKey, data) {
	if (data.key === undefined) {
		return data;
	}

	const aesKeyBuf = crypto.privateDecrypt(
		{
			key: privateKey,
			oaepHash: "SHA256",
		},
		Buffer.from(data.key, "base64"),
	);
	const aesKey = await importAESGCMKey(aesKeyBuf);

	const decryptedData = await decryptData(
		Buffer.from(data.data, "base64"),
		aesKey,
		Buffer.from(data.iv, "base64"),
	);

	return decryptedData.toString();
}

async function run() {
	let lineReader = readline.createInterface({
		input: fs.createReadStream("my_log.log.gz").pipe(zlib.createGunzip()),
	});

	lineReader.on("line", async (line) => {
		line = JSON.parse(line);

		const { Metadata, RequestBody, ResponseBody, ...remaining } = line;

		console.log({
			...remaining,
			Metadata: await decryptBase64(privateKey, Metadata),
			RequestBody: await decryptBase64(privateKey, RequestBody),
			ResponseBody: await decryptBase64(privateKey, ResponseBody),
		});
		console.log("--");
	});
}

run();
```

Run the script by executing the below code on your terminal. Replace `file name` with the name of your JavaScript file.

```bash
node {file name}
```

The script reads the encrypted log file `(my_log.log.gz)`, decrypts the metadata, request body, and response body, and prints the decrypted data.
Ensure you replace the `privateKey` variable with your actual private RSA key that you generated in step 1.

</TabItem> <TabItem label="OpenSSL">

1. Decrypt the encrypted log file using the private key.

Assuming that the logs were encrypted with the public key (for example `public_key.pem`), you can use the private key (`private_key.pem`) to decrypt the log file.

For example, if the encrypted logs are in a file named `encrypted_logs.bin`, you can decrypt it like this:

```bash
openssl rsautl -decrypt -inkey private_key.pem -in encrypted_logs.bin -out decrypted_logs.txt
```

- `-decrypt` tells OpenSSL that we want to decrypt the file.
- `-inkey private_key.pem` specifies the private key that will be used to decrypt the logs.
- `-in encrypted_logs.bin` is the encrypted log file.
- `-out decrypted_logs.txt`decrypted logs will be saved into this file.

2. View the decrypted logs
   Once decrypted, you can view the logs by simply running:

```bash
cat decrypted_logs.txt
```

This command will output the decrypted logs to the terminal.

</TabItem> </Tabs>

---

# Examples

URL: https://developers.cloudflare.com/analytics/analytics-engine/recipes/

import { DirectoryListing } from "~/components"

Example implementations of common use cases for Workers Analytics Engine:

<DirectoryListing />

---

# Usage-based billing

URL: https://developers.cloudflare.com/analytics/analytics-engine/recipes/usage-based-billing-for-your-saas-product/

Many Cloudflare customers run software-as-a-service products with multiple customers. A big concern for such companies is understanding the cost of each customer, and understanding customer behaviour more widely.

Keeping data on every web request used by a customer can be expensive, as can attributing page views to customers. At Cloudflare we have solved this problem with the same in-house technologies now available to you through Analytics Engine.

## Recording data on usage

Analytics Engine is designed for use with Cloudflare Workers. If you already use Cloudflare Workers to serve requests, you can start sending data into Analytics Engine in just a few lines of code:

```javascript
  [...]

  // This examples assumes you give a unique ID to each of your SaaS customers, and the Worker has
  // assigned it to the variable named `customer_id`
  const { pathname } = new URL(request.url);
  env.USAGE_INDEXED_BY_CUSTOMER_ID.writeDataPoint({
    "indexes": [customer_id],
    "blobs": [pathname]
  });
```

SaaS customer activity often follows an exponential pattern: one customer may do 100 million requests per second, while another does 100 requests a day. If all data is sampled together, the usage of bigger customers can cause smaller customers data to be sampled to zero. Analytics Engine allows you to prevent that: in the example code above we supply the customer's unique ID as the index, causing Analytics Engine to sample your customers' individual activity.

## Viewing usage

You can start viewing customer data either using Grafana (for visualisations) or as JSON (for your own tools). Other areas of the Analytics Engine documentation explain this in-depth.

Look at customer usage over all endpoints:

```sql
SELECT
  index1 AS customer_id,
  sum(_sample_interval) AS count
FROM
  usage_indexed_by_customer_id
GROUP BY customer_id
```

If run in Grafana, this query returns a graph summarising the usage of each customer. The `sum(_sample_interval)` accounts for the sampling - refer to other Analytics Engine documentation. This query gives you an answer to "which customers are most active?"

The example `writeDataPoint` call above writes an endpoint name. If you do that, you can break down customer activity by endpoint:

```sql
SELECT
  index1 AS customer_id,
  blob1 AS request_endpoint,
  sum(_sample_interval) AS count
FROM
  usage_indexed_by_customer_id
GROUP BY customer_id, request_endpoint
```

This can give you insights into what endpoints different customers are using. This can be useful for business purposes (for example, understanding customer needs) as well for for your engineers to see activity and behaviour (observability).

## Billing customers

Analytics Engine can be used to bill customers based on a reliable approximation of usage. In order to get the best approximation, when generating bills we suggest executing one query per customer. This can result in less sampling than querying multiple customers at once.

```sql
SELECT
  index1 AS customer_id,
  blob1 AS request_endpoint,
  sum(_sample_interval) AS usage_count
FROM
  usage_indexed_by_customer_id
WHERE
  customer_id = 'substitute_customer_id_here'
  AND timestamp >= toDateTime('2023-03-01 00:00:00')
  AND timestamp < toDateTime('2023-04-01 00:00:00')
GROUP BY customer_id, request_endpoint
```

Running this query once for each customer at the end of each month could give you the data to produce a bill. This is just an example: most likely you'll want to adjust this example to how you want to bill.

When producing a bill, most likely you will also want to provide the daily costs. The following query breaks down usage by day:

```sql
SELECT
  index1 AS customer_id,
  toStartOfInterval(timestamp, INTERVAL '1' DAY) AS date,
  blob1 AS request_endpoint,
  sum(_sample_interval) AS request_count
FROM
  usage_indexed_by_customer_id
WHERE
  customer_id = 'x'
  AND timestamp >= toDateTime('2023-03-01 00:00:00')
  AND timestamp < toDateTime('2023-04-01 00:00:00')
GROUP BY customer_id, date, request_endpoint
```

You will want to take the usage queries above, adapt them for how you charge customers, and make a backend system run those queries and calculate the customer charges based on the data returned.

---

# Argo Smart Routing for SaaS

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/performance/argo-for-saas/

Argo Smart Routing uses real-time global network information to route traffic on the fastest possible path across the Internet. Regardless of geographic location, this allows Cloudflare to optimize routing to make it faster, more reliable, and more secure. As a SaaS provider, you may want to emphasize the quickest traffic delivery for your end customers. To do so, [enable Argo Smart Routing](/argo-smart-routing/get-started/).

---

# Cache for SaaS

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/performance/cache-for-saas/

Cloudflare makes customer websites faster by storing a copy of the website’s content on the servers of our globally distributed data centers. Content can be either static or dynamic: static content is “cacheable” or eligible for caching, and dynamic content is “uncacheable” or ineligible for caching. The cached copies of content are stored physically closer to users, optimized to be fast, and do not require recomputing.

As a SaaS provider, enabling caching reduces latency on your custom domains. For more information, refer to [Cache](/cache/). If you would like to enable caching, review [Getting Started with Cache](/cache/get-started/).

---

# Early Hints for SaaS

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/performance/early-hints-for-saas/

import { APIRequest } from "~/components";

[Early Hints](/cache/advanced-configuration/early-hints/) allows the browser to begin loading resources while the origin server is compiling the full response. This improves webpage’s loading speed for the end user. As a SaaS provider, you may prioritize speed for some of your custom hostnames. Using custom metadata, you can [enable Early Hints](/cache/advanced-configuration/early-hints/#enable-early-hints) per custom hostname.

***

## Prerequisites

Before you can employ Early Hints for SaaS, you need to create a custom hostname. Review [Get Started with Cloudflare for SaaS](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/) if you have not already done so.

***

## Enable Early Hints per custom hostname via the API

1. [Locate your zone ID](/fundamentals/account/find-account-and-zone-ids/), available in the Cloudflare dashboard.

2. Locate your Authentication Key by selecting **My Profile** > **API tokens** > **Global API Key**.

3. If you are [creating a new custom hostname](/api/resources/custom_hostnames/methods/create/), make an API call such as the example below, specifying `"early_hints": "on"`:

<APIRequest
  path="/zones/{zone_id}/custom_hostnames"
  method="POST"
  json={{
		"hostname": "<CUSTOM_HOSTNAME>",
		"ssl": {
			"method": "http",
			"type": "dv",
			"settings": {
				"http2": "on",
				"min_tls_version": "1.2",
				"tls_1_3": "on",
				"early_hints": "on"
				},
				"bundle_method": "ubiquitous",
				"wildcard": false
			},
	}}
/>

4. For an existing custom hostname, locate the `id` of that hostname via a `GET` call:

<APIRequest
  path="/zones/{zone_id}/custom_hostnames"
  method="GET"
  parameters={{
		hostname:"{hostname}"
	}}
/>

5. Then make an API call such as the example below, specifying `"early_hints": "on"`:

<APIRequest
  path="/zones/{zone_id}/custom_hostnames/{custom_hostname_id}"
  method="PATCH"
  json={{
		"ssl": {
			"method": "http",
			"type": "dv",
			"settings": {
				"http2": "on", // Note: These settings will be set to default if not included when updating early hints
				"min_tls_version": "1.2",
				"tls_1_3": "on",
				"early_hints": "on"
				}
			},
	}}
/>

Currently, all options within `settings` are required in order to prevent those options from being set to default. You can pull the current settings state prior to updating Early Hints by leveraging the output that returns the `id` for the hostname.

---

# Performance

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/performance/

Cloudflare for SaaS allows you to deliver the best performance to your end customers by helping enable you to reduce latency through:

* [Argo Smart Routing for SaaS](/cloudflare-for-platforms/cloudflare-for-saas/performance/argo-for-saas/) calculates and optimizes the fastest path for requests to travel to your origin.
* [Early Hints for SaaS](/cloudflare-for-platforms/cloudflare-for-saas/performance/early-hints-for-saas/) provides faster loading speeds for individual custom hostnames by allowing the browser to begin loading responses while the origin server is compiling the full response.
* [Cache for SaaS](/cloudflare-for-platforms/cloudflare-for-saas/performance/cache-for-saas/) makes customer websites faster by storing a copy of the website’s content on the servers of our globally distributed data centers.
* By using Cloudflare for SaaS, your customers automatically inherit the benefits of Cloudflare's vast [anycast network](https://www.cloudflare.com/network/).

---

# Connection request details

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/reference/connection-details/

When forwarding connections to your origin server, Cloudflare will set request parameters according to the following:

## Host header

Cloudflare will not alter the Host header by default, and will forward exactly as sent by the client. If you wish to change the value of the Host header you can utilise [Page-Rules](/workers/configuration/workers-with-page-rules/) or [Workers](/workers/) using the steps outlined in [certificate management](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/).

## SNI

When establishing a TLS connection to your origin server, if the request is being sent to your configured Fallback Host then the value of the SNI sent by Cloudflare will match the value of the Host header sent by the client (i.e. the custom hostname).

If however the request is being forwarded to a Custom Origin, then the value of the SNI will be that of the Custom Origin.

---

# Reference

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/reference/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Token validity periods

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/reference/token-validity-periods/

import { Render } from "~/components"

When you perform [TXT](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/txt/) domain control validation, you will need to share these tokens with your customers.

However, these tokens expire after a certain amount of time, depending on your chosen certificate authority.

| Certificate authority | Token validity |
| --------------------- | -------------- |
| Let's Encrypt         | 7 days         |
| Google Trust Services | 14 days        |
| SSL.com | 14 days        |

:::caution
 <Render file="dcv-invalid-token-situations" product="ssl" />
:::

---

# Troubleshooting

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/reference/troubleshooting/

import { Details } from "~/components";

## Rate limits

By default, you may issue up to 15 certificates per minute. Only successful submissions (POSTs that return 200) are counted towards your limit. If you exceed your limit, you will be prevented from issuing new certificates for 30 seconds.

If you require a higher rate limit, contact your Customer Success Manager.

***

## Purge cache

To remove specific files from Cloudflare’s cache, [purge the cache](/cache/how-to/purge-cache/purge-by-single-file/) while specifying one or more hosts.

***

## Resolution error 1016 (Origin DNS error) when accessing the custom hostname

Cloudflare returns a 1016 error when the custom hostname cannot be routed or proxied.

There are three main causes of error 1016:

1. Custom Hostname ownership validation is not complete. To check validation status, run an API call to [search for a certificate by hostname](/cloudflare-for-platforms/cloudflare-for-saas/start/common-api-calls/) and check the verification error field: `"verification_errors": ["custom hostname does not CNAME to this zone."]`.
2. Fallback Origin is not [correctly set](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/#1-create-fallback-origin). Confirm that you have created a DNS record for the fallback origin and also set the fallback origin.
3. A Wildcard Custom Hostname has been created, but the requested hostname is associated with a domain that exists in Cloudflare as a standalone zone. In this case, the [hostname priority](/ssl/reference/certificate-and-hostname-priority/#hostname-priority) for the standalone zone will take precedence over the wildcard custom hostname. This behavior applies even if there is no DNS record for this standalone zone hostname.

In this scenario each hostname that needs to be served by the Cloudflare for SaaS parent zone needs to be added as an individual Custom Hostname.

:::note


If you encounter other 1XXX errors, refer to [Troubleshooting Cloudflare 1XXX Errors](/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/).


:::

***

## Custom hostname in Moved status

To move a custom hostname back to an Active status, send a [PATCH request](/api/resources/custom_hostnames/methods/edit/) to restart the hostname validation. A Custom Hostname in a Moved status is deleted after 7 days.

In some circumstances, custom hostnames can also enter a **Moved** state if your customer changes their DNS records pointing to your SaaS service. For more details, refer to [Remove custom hostnames](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/remove-custom-hostnames/).

***

## CAA Errors

The `caa_error` in the status of a custom hostname means that the CAA records configured on the domain prevented the Certificate Authority to issue the certificate.

You can check which CAA records are configured on a domain using the `dig` command:
`dig CAA example.com`

You will need to ensure that the required CAA records for the selected Certificate Authority are configured.
For example, here are the records required to issue [Let's Encrypt](https://letsencrypt.org/docs/caa/) and [Google Trust Services](https://pki.goog/faq/#caa) certificates:

```
example.com CAA 0 issue "pki.goog; cansignhttpexchanges=yes"
example.com CAA 0 issuewild "pki.goog; cansignhttpexchanges=yes"

example.com CAA 0 issue "letsencrypt.org"
example.com CAA 0 issuewild "letsencrypt.org"

example.com CAA 0 issue "ssl.com"
example.com CAA 0 issuewild "ssl.com"
```

More details can be found on the [CAA records FAQ](/ssl/edge-certificates/troubleshooting/caa-records/).

## Older devices have issues connecting

As Let's Encrypt - one of the [certificate authorities (CAs)](/ssl/reference/certificate-authorities/) used by Cloudflare - has announced changes in its [chain of trust](/ssl/concepts/#chain-of-trust), starting September 9, 2024, there may be issues with older devices trying to connect to your custom hostname certificate.

Consider the following solutions:

- Use the [Edit Custom Hostname](/api/resources/custom_hostnames/methods/edit/) endpoint to set the `certificate_authority` parameter to an empty string (`""`): this sets the custom hostname certificate to "default CA", leaving the choice up to Cloudflare. Cloudflare will always attempt to issue the certificate from a more compatible CA, such as [Google Trust Services](/ssl/reference/certificate-authorities/#google-trust-services), and will only fall back to using Let’s Encrypt if there is a [CAA record](/ssl/edge-certificates/caa-records/) in place that blocks Google from issuing a certificate.

    <Details header="Example API call">

    ```sh
    curl --request PATCH \\
    https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id} \\
    --header "X-Auth-Email: <EMAIL>" \\
    --header "X-Auth-Key: <API_KEY>" \\
    --header "Content-Type: application/json" \\
    --data '{
      "ssl": {
          "method": "txt",
          "type": "dv",
          "certificate_authority": ""
      }
    }'

    ```

    </Details>

- Use the [Edit Custom Hostname](/api/resources/custom_hostnames/methods/edit/) endpoint to set the `certificate_authority` parameter to `google`: this sets Google Trust Services as the CA for your custom hostnames. In your API call, make sure to also include `method` and `type` in the `ssl` object.
- If you are using a custom certificate for your custom hostname, refer to the [custom certificates troubleshooting](/ssl/edge-certificates/custom-certificates/troubleshooting/#lets-encrypt-chain-update).

## Custom hostname fails to verify because the zone is held

The [zone hold feature](/fundamentals/account/account-security/zone-holds/) is a toggle that will prevent their zone from being activated on other Cloudflare account.
When the option `Also prevent subdomains` is enabled, this prevents the verification of custom hostnames for this domain. The custom hostname will remain in the `Blocked` status, with the following error message: `The hostname is associated with a held zone. Please contact the owner of this domain to have the hold removed.` In this case, the owner of the zone needs to [release the hold](/fundamentals/account/account-security/zone-holds/#release-zone-holds) before the custom hostname can become activated.

## Hostnames over 64 characters

The Common Name (CN) restriction establishes a limit of 64 characters ([RFC 5280](https://www.rfc-editor.org/rfc/rfc5280.html)). If you have a hostname that exceeds this length, you may find the following error:

```txt
Since no host is 64 characters or fewer, Cloudflare Branding is required. Please check your input and try again. (1469)
```

To solve this, you can set `cloudflare_branding` to `true` when [creating your custom hostnames](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/create-custom-hostnames/#hostnames-over-64-characters) via API.

Cloudflare branding means that `sni.cloudflaressl.com` will be added as the certificate Common Name (CN) and the long hostname will be included as a part of the Subject Alternative Name (SAN).

---

# Deprecation - Version 1

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/reference/versioning/

The first version of SSL for SaaS will be deprecated on September 1, 2021.

## Why is SSL for SaaS changing?

In SSL for SaaS v1, traffic for Custom Hostnames is proxied to the origin based on the IP addresses assigned to the zone with SSL for SaaS enabled. This IP-based routing introduces complexities that prevented customers from making changes with zero downtime.

SSL for SaaS v2 removes IP-based routing and its associated problems. Instead, traffic is proxied to the origin based on the custom hostname of the SaaS zone. This means that Custom Hostnames will now need to pass a **hostname verification** step after Custom Hostname creation and in addition to SSL certificate validation. This adds a layer of security from SSL for SaaS v1 by ensuring that only verified hostnames are proxied to your origin.

## What action is needed?

To ensure that your service is not disrupted, you need to perform an additional ownership check on every new Custom Hostname. There are three methods to verify ownership: TXT, HTTP, and CNAME. Use TXT and HTTP for pre-validation to validate the Custom Hostname before traffic is proxied by Cloudflare’s edge.

### Recommended validation methods

Using a [TXT](#dns-txt-record) or [HTTP](#http-token) validation method helps you avoid downtime during your migration. If you choose to use [CNAME validation](#cname-validation), your domain might fall behind on its [backoff schedule](/ssl/edge-certificates/changing-dcv-method/validation-backoff-schedule/).

#### DNS TXT Record

When creating a Custom Hostname with the TXT method through the [API](/api/resources/custom_hostnames/methods/create/), a TXT ownership\_verification record is provided for your customer to add to their DNS for the ownership validation check. When the TXT record is added, the Custom Hostname will be marked as **Active** in the Cloudflare SSL/TLS app under the Custom Hostnames tab.

#### HTTP Token

When creating a Custom Hostname with the HTTP through the [API](/api/resources/custom_hostnames/methods/create/), an HTTP ownership\_verification token is provided. HTTP verification is used mainly by organizations with a large deployed base of custom domains with HTTPS support. Serving the HTTP token from your origin web server allows hostname verification before proxying domain traffic through Cloudflare.

Cloudflare sends GET requests to the http\_url using `User-Agent: Cloudflare Custom Hostname Verification`.

If you validated a hostname that is not proxying traffic through Cloudflare, the Custom Hostname will be marked as **Active** in the Cloudflare SSL/TLS app when the HTTP token is verified (under the **Custom Hostnames** tab).

If your hostname is already proxying traffic through Cloudflare, then HTTP validation is not enough by itself and the hostname will only go active when DNS-based validation is complete.

### Other validation methods

Though you can use [CNAME validation](#cname-validation), we recommend you either use a [TXT](#dns-txt-record) or [HTTP](#http-token) validation method.

#### CNAME Validation

Custom Hostnames can also be validated once Cloudflare detects that the Custom Hostname is a CNAME record pointing to the fallback record configured for the SSL for SaaS domain. Though this is the simplest validation method, it increases the risk of errors. Since a CNAME record would also route traffic to Cloudflare’s edge, traffic may reach our edge before the Custom Hostname has completed validation or the SSL certificate has issued.

Once you have tested and added the hostname validation step to your Custom Hostname creation process, please contact your Cloudflare Account Team to schedule a date to migrate your SSL for SaaS v1 zones. Your Cloudflare Account Team will work with you to validate your existing Custom Hostnames without downtime.

## If you are using BYOIP or Apex Proxying:

Both BYOIP addresses and IP addresses configured for Apex Proxying allow for hostname validation to complete successfully by having either a BYOIP address or an Apex Proxy IP address as the target of a DNS A record for a custom hostname.

## What is available in the new version of SSL for SaaS?

SSL for SaaS v2 is functionally equivalent to SSL for SaaS v1, but removes the requirements to use specific anycast IP addresses at Cloudflare’s edge and Cloudflare’s Universal SSL product with the SSL for SaaS zone.

:::note

SSL for SaaS v2 is now called Cloudflare for SaaS.
:::

## What happens during the migration?

Once the migration has been started for your zone(s), Cloudflare will require every Custom Hostname to pass a hostname verification check. Existing Custom Hostnames that are proxying to Cloudflare with a DNS CNAME record will automatically re-validate and migrate to the new version with no downtime. Any Custom Hostnames created after the start of the migration will need to pass the hostname validation check using one of the validation methods mentioned above.

:::note


You can revert the migration at any time.


:::

### Before the migration

Before your migration, you should:

1. To test validation methods, set up a test zone and ask your Solutions Engineer (SE) to enable SSL for SaaS v2.
2. Wait for your SE to run our pre-migration tool. This tool groups your hostnames into one of the following statuses:
   * `test_pending`: In the process of being verified or was unable to be verified and re-queued for verification. A custom hostname will be re-queued 25 times before moving to the `test_failed` status.
   * `test_active`: Passed CNAME verification
   * `test_active_apex`: Passed Apex Proxy verification
   * `test_blocked`: Hostname will be blocked during the migration because hostname belongs to a banned zone. Contact your CSM to verify banned custom hostnames and proceed with the migration.
   * `test_failed`: Failed hostname verification 25 times
3. Review the results of our pre-migration tool (run by your Solutions Engineer) using one of the following methods:
   * Via the API: `https://api.cloudflare.com/client/v4/zones/{zone_tag}/custom_hostnames?hostname_status={status}`
   * Via a CSV file (provided by your SE)
   * Via the Cloudflare dashboard:
     ![Review SSL migration status in the dashboard](~/assets/images/cloudflare-for-platforms/ssl-migration-status.png)
4. Approve the migration. Your Cloudflare account team will work with you to schedule a migration window for each of your SSL for SaaS zones.

## During the migration

After the migration has started and has had some time to progress, Cloudflare will generate a list of Custom Hostnames that failed to migrate and ask for your approval to complete the migration. When you give your approval, the migration will be complete, SSL for SaaS v1 will be disabled for the zone, and any Custom Hostname that has not completed hostname validation will no longer function.

The migration timeline depends on the number of Custom Hostnames. For example, if a zone has fewer than 10,000 Custom Hostnames, the list can be generated around an hour after beginning the migration. If a zone has millions of Custom Hostnames, it may take up to 24 hours to identify instances that failed to successfully migrate.

When your Cloudflare Account Team asks for approval to complete the migration, please respond in a timely manner. You will have **two weeks** to validate any remaining Custom Hostnames before they are systematically deleted.

## When is the migration?

The migration process starts on March 31, 2021 and will continue until final deprecation on September 1, 2021.

If you would like to begin the migration process before March 31, 2021, please contact your Cloudflare Account Team and they will work with you to expedite the process. Otherwise, your Cloudflare Account Team will reach out to you with a time for a migration window so that your zones are migrated before **September 1, 2021** end-of-life date.

## What if I have additional questions?

If you have any questions, please contact your Cloudflare Account Team or [SaaSv2@cloudflare.com](mailto:saasv2@cloudflare.com).

---

# How it works

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/

import { Example } from "~/components";

Orange-to-Orange (O2O) is a specific traffic routing configuration where traffic routes through two Cloudflare zones: the first Cloudflare zone is owned by customer 1 and the second Cloudflare zone is owned by customer 2, who is considered a SaaS provider.

If one or more hostnames are onboarded to a SaaS Provider that uses Cloudflare products as part of their platform - specifically the [Cloudflare for SaaS product](/cloudflare-for-platforms/cloudflare-for-saas/) - those hostnames will be created as [custom hostnames](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/) in the SaaS Provider's zone.

To give the SaaS provider permission to route traffic through their zone, any custom hostname must be activated by you (the SaaS customer) by placing a [CNAME record](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/#3-have-customer-create-cname-record) on your authoritative DNS. If your authoritative DNS is Cloudflare, you have the option to [proxy](/fundamentals/concepts/how-cloudflare-works/#application-services) your CNAME record, achieving an Orange-to-Orange setup.


## With O2O

If you have your own Cloudflare zone (`example.com`) and your zone contains a [proxied DNS record](/dns/proxy-status/) matching the custom hostname (`mystore.example.com`) with a **CNAME** target defined by the SaaS Provider, then O2O will be enabled.

<Example>

DNS management for **example.com**

| **Type** | **Name**     | **Target**                  | **Proxy status** |
| -------- | ------------ | --------------------------------- | ---------------- |
| `CNAME`  | `mystore`    | `customers.saasprovider.com` | Proxied          |

</Example>

With O2O enabled, the settings configured in your Cloudflare zone will be applied to the traffic first, and then the settings configured in the SaaS provider's zone will be applied to the traffic second.

```mermaid
flowchart TD
accTitle: O2O-enabled traffic flow diagram

A[Website visitor]

subgraph Cloudflare
  B[Customer-owned zone]
  C[SaaS Provider-owned zone]
end

D[SaaS Provider Origin]

A --> B
B --> C
C --> D
```
## Without O2O

If you do not have your own Cloudflare zone and have only onboarded one or more of your hostnames to a SaaS Provider, then O2O will not be enabled.

Without O2O enabled, the settings configured in the SaaS Provider's zone will be applied to the traffic.

```mermaid
flowchart TD
accTitle: Your zone using a SaaS provider, but without O2O

A[Website visitor]

subgraph Cloudflare
    B[SaaS Provider-owned zone]
end

C[SaaS Provider Origin]

A --> B
B --> C
```

---

# SaaS customers

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/

import { DirectoryListing } from "~/components"

Cloudflare partners with many [SaaS providers](/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/provider-guides/) to extend our performance and security benefits to your website.

If you are a SaaS customer, you can take this process a step further by managing your own zone on Cloudflare. This setup - known as **Orange-to-Orange (O2O)** - allows you to benefit from your provider's setup but still customize how Cloudflare treats incoming traffic to your zone.

## Related resources

<DirectoryListing />

---

# Product compatibility

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/product-compatibility/

As a general rule, settings on the customer zone will override settings on the SaaS zone. In addition, [Orange-to-Orange](/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/) does not permit traffic directed to a custom hostname zone into another custom hostname zone.

The following table provides a list of compatibility guidelines for various Cloudflare products and features.

:::note


This is not an exhaustive list of Cloudflare products and features.


:::

| Product                                                                                             | Customer zone | SaaS provider zone | Notes                                                                                                                                                                                                                                                                                                                                                             |
| --------------------------------------------------------------------------------------------------- | ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Access](/cloudflare-for-platforms/cloudflare-for-saas/security/secure-with-access/)                | Yes           | Yes                |                                                                                                                                                                                                                                                                                                                                                                   |
| [API Shield](/api-shield/)                                                                          | Yes           | No                 |                                                                                                                                                                                                                                                                                                                                                                   |
| [Argo Smart Routing](/argo-smart-routing/)                                                          | No            | Yes                | Customer zones can still use Smart Routing for non-O2O traffic.                                                                                                                                                                                                                                                                                                   |
| [Bot Management](/bots/plans/bm-subscription/)                                                      | Yes         | Yes              |                                                                                                                                                                                                                                                                                       |
| [Browser Integrity Check](/waf/tools/browser-integrity-check/)                                      | Yes           | Yes                |                                                                                                                                                                                                                                                                                                                                                                   |
| [Cache](/cache/)                                                                                    | Yes\*         | Yes                | Though caching is possible on a customer zone, it is generally discouraged (especially for HTML).<br/><br/>Your SaaS provider likely performs its own caching outside of Cloudflare and caching on your zone might lead to out-of-sync or stale cache states.<br/><br/>Customer zones can still cache content that are not routed through a SaaS provider's zone. |
| [China Network](/china-network/)                                                                    | No            | No                 |                                                                                                                                                                                                                                                                                                                                                                   |
| [DNS](/dns/)                                                                                        | Yes\*         | Yes                | As a SaaS customer, do not remove the records related to your Cloudflare for SaaS setup.<br/><br/>Otherwise, your traffic will begin routing away from your SaaS provider.                                                                                                                                                                                        |
| [HTTP/2 prioritization](https://blog.cloudflare.com/better-http-2-prioritization-for-a-faster-web/) | Yes           | Yes\*              | This feature must be enabled on the customer zone to function.                                                                                                                                                                                                                                                                                                    |
| [Image resizing](/images/transform-images/)                                                         | Yes           | Yes                |                                                                                                                                                                                                                                                                                                                                                                   |
| IPv6                                                                                                | Yes           | Yes                |                                                                                                                                                                                                                                                                                                                                                                   |
| [IPv6 Compatibility](/network/ipv6-compatibility/)                                                  | Yes           | Yes\*              | If the customer zone has **IPv6 Compatibility** enabled, generally the SaaS zone should as well.<br/><br/>If not, make sure the SaaS zone enables [Pseudo IPv4](/network/pseudo-ipv4/).                                                                                                                                                                           |
| [Load Balancing](/load-balancing/)                                                                  | No            | Yes                | Customer zones can still use Load Balancing for non-O2O traffic.                                                                                                                                                                                                                                                                                                  |
| [Page Rules](/rules/page-rules/)                                                                    | Yes\*         | Yes                | Page Rules that match the subdomain used for O2O may block or interfere with the flow of visitors to your website.                                                                                                                                                                                                                                                |
| [Mirage](/speed/optimization/images/mirage/)                                                        | Yes           | Yes                |                                                                                                                                                                                                                                                                                                                                                                   |
| [Origin Rules](/rules/origin-rules/)                                                                | Yes           | Yes                | Enterprise zones can configure Origin Rules, by setting the Host Header and DNS Overrides to direct traffic to a SaaS zone.                                                                                                                                                                                                                                       |
| [Page Shield](/page-shield/)                                                                        | Yes           | Yes                | |
| [Polish](/images/polish/)                                                                           | Yes\*         | Yes                | Polish only runs on cached assets. If the customer zone is bypassing cache for SaaS zone destined traffic, then images optimized by Polish will not be loaded from origin.                                                                                                                                                                                        |
| [Rate Limiting](/waf/rate-limiting-rules/)                                                          | Yes\*         | Yes                | Rate Limiting rules that match the subdomain used for O2O may block or interfere with the flow of visitors to your website.                                                                                                                                                                                                                                       |
| [Rocket Loader](/speed/optimization/content/rocket-loader/)                                         | No            | No                 |                                                                                                                                                                                                                                                                                                                                                                   |
| [Security Level](/waf/tools/security-level/)                                                        | Yes           | Yes                |                                                                                                                                                                                                                                                                                                                                                                   |
| [Spectrum](/spectrum/)                                                                              | No            | No                 |                                                                                                                                                                                                                                                                                                                                                                   |
| [Transform Rules](/rules/transform/)                                                                | Yes\*         | Yes                | Transform Rules that match the subdomain used for O2O may block or interfere with the flow of visitors to your website.                                                                                                                                                                                                                                           |
| [WAF custom rules](/waf/custom-rules/)                                                              | Yes           | Yes                | WAF custom rules that match the subdomain used for O2O may block or interfere with the flow of visitors to your website.                                                                                                                                                                                                                                          |
| [WAF managed rules](/waf/managed-rules/)                                                            | Yes           | Yes                |                                                                                                                                                                                                                                                                                                                                                                   |
| [Waiting Room](/waiting-room/)                                                                      | Yes           | Yes                |                                                                                                                                                                                                                                                                                                                                                                   |
| [Websockets](/network/websockets/)                                                                  | No            | No                 |                                                                                                                                                                                                                                                                                                                                                                   |
| [Workers](/workers/)                                                                                | Yes\*         | Yes                | Similar to Page Rules, Workers that match the subdomain used for O2O may block or interfere with the flow of visitors to your website.                                                                                                                                                                                                                            |
| [Zaraz](/zaraz/)                                                                                    | Yes           | No                 |                                                                                                                                                                                                                                                                                                                                                                   |

---

# Remove domain

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/remove-domain/

import { Render } from "~/components"

<Render file="saas-customer-churn" />

---

# Security

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/

Cloudflare for SaaS provides increased security per custom hostname through:

* [Certificate management](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/)
  * [Issue certificates through Cloudflare](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/)
  * [Upload your own certificates](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/custom-certificates/)
* Control your traffic's level of encryption with [TLS settings](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/enforce-mtls/)
* Create and deploy WAF custom rules, rate limiting rules, and managed rulesets using [WAF for SaaS](/cloudflare-for-platforms/cloudflare-for-saas/security/waf-for-saas/)

---

# Secure with Cloudflare Access

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/secure-with-access/

Cloudflare Access provides visibility and control over who has access to your [custom hostnames](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/). You can allow or block users based on identity, device posture, and other [Access rules](/cloudflare-one/policies/access/).

## Prerequisites

* You must have an active custom hostname. For setup instructions, refer to [Configuring Cloudflare for SaaS](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/).
* You must have a Cloudflare Zero Trust plan in your SaaS provider account. Learn more about [getting started with Zero Trust](/cloudflare-one/setup/).
* You can only run Access on custom hostnames if they are managed externally to Cloudflare or in a separate Cloudflare account. If the custom hostname zone is in the same account as the SaaS zone, the Access application will not be applied.

## Setup

1. At your SaaS provider account, select [Zero Trust](https://one.dash.cloudflare.com).
2. Go to **Access** > **Applications**.
3. Select **Add an application** and, for type of application, select **Self-hosted**.
4. Enter a name for your Access application and, in **Session Duration**, choose how often the user's [application token](/cloudflare-one/identity/authorization-cookie/application-token/) should expire.
5. Select **Add public hostname**.
6. For **Input method**, select _Custom_.
7. In **Hostname**, enter your custom hostname (for example, `mycustomhostname.com`).
8. Follow the remaining [self-hosted application creation steps](/cloudflare-one/applications/configure-apps/self-hosted-public-app/) to publish the application.

---

# Common API Calls

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/common-api-calls/

As a SaaS provider, you may want to configure and manage Cloudflare for SaaS [via the API](/api/) rather than the [Cloudflare dashboard](https://dash.cloudflare.com/). Below are relevant API calls for creating, editing, and deleting custom hostnames, as well as monitoring, updating, and deleting fallback origins. Further details can be found in the [Cloudflare API documentation](/api/).

***

## Custom hostnames

| Endpoint                                                                                                                         | Notes                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| [List custom hostnames](/api/resources/custom_hostnames/methods/list/)                                        | Use the `page` parameter to pull additional pages. Add a `hostname` parameter to search for specific hostnames.                         |
| [Create custom hostname](/api/resources/custom_hostnames/methods/create/)                                      | In the `validation_records` object of the response, use the `txt_name` and `txt_record` listed  to validate the custom hostname.        |
| [Custom hostname details](/api/resources/custom_hostnames/methods/get/)                                    |                                                                                                                                         |
| [Edit custom hostname](/api/resources/custom_hostnames/methods/edit/)                                          | When sent with an `ssl` object that matches the existing value, indicates that hostname should restart domain control validation (DCV). |
| [Delete custom hostname](/api/resources/custom_hostnames/methods/delete/) | Also deletes any associated SSL/TLS certificates.                                                                                       |

## Fallback origins

Our API includes the following endpoints related to the [fallback origin](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/#1-create-fallback-origin) of a custom hostname:

* [Get fallback origin](/api/resources/custom_hostnames/subresources/fallback_origin/methods/get/)
* [Update fallback origin](/api/resources/custom_hostnames/subresources/fallback_origin/methods/update/)
* [Remove fallback origin](/api/resources/custom_hostnames/subresources/fallback_origin/methods/delete/)

---

# Enable

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/enable/

To enable Cloudflare for SaaS for your account:

1. Log into the [Cloudflare dashboard](https://dash.cloudflare.com).
2. Select your account and zone.
3. Go to **SSL/TLS** > **Custom Hostnames**.
4. Select **Enable**.
5. The next step depends on the zone's plan:
   * **Enterprise**: Can preview this product as a [non-contract service](/billing/preview-services/), which provide full access, free of metered usage fees, limits, and certain other restrictions.
   * **Non-enterprise**: Will have to enter payment information.

:::note


Different zone plan levels have access to different features. For more details, refer to [Plans](/cloudflare-for-platforms/cloudflare-for-saas/plans/).


:::

---

# Configuring Cloudflare for SaaS

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/

import { Example, Render } from "~/components"

***

<Render file="get-started-prereqs" params={{ one: "on a Free plan." }} />

***

## Initial setup

<Render file="get-started-initial-setup-preamble" /> <br/>

### 1. Create fallback origin

<Render file="get-started-fallback-origin" />

### 2. (Optional) Create CNAME target

The CNAME target — optional, but highly encouraged — provides a friendly and more flexible place for customers to [route their traffic](#3-have-customer-create-cname-record). You may want to use a subdomain such as `customers.<SAAS_PROVIDER>.com`.

[Create](/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records) a proxied CNAME that points your CNAME target to your fallback origin (can be a wildcard such as `*.customers.saasprovider.com`).

<Example>

| **Type** | **Name**     | **Target**                  | **Proxy status** |
| -------- | ------------ | --------------------------------- | ---------------- |
| `CNAME`  | `.customers` | `proxy-fallback.saasprovider.com` | Proxied          |

</Example>

***

## Per-hostname setup

<Render file="get-started-per-hostname" />

### 3. Have customer create CNAME record

To finish the custom hostname setup, your customer needs to set up a CNAME record at their authoritative DNS that points to your [CNAME target](#2-optional-create-cname-target) [^1].

<Render file="get-started-check-statuses" />

Your customer's CNAME record might look like the following:

```txt
mystore.example.com CNAME customers.saasprovider.com
```

This record would route traffic in the following way:

```mermaid
flowchart TD
accTitle: How traffic routing works with a CNAME target
A[Request to <code>mystore.example.com</code>] --> B[<code>customers.saasprovider.com</code>]
B --> C[<code>proxy-fallback.saasprovider.com</code>]
```

<br/>

Requests to `mystore.example.com` would go to your CNAME target (`customers.saasprovider.com`), which would then route to your fallback origin (`proxy-fallback.saasprovider.com`).

[^1]: <Render file="regional-services" />

:::caution
If your customer needs to use an A record to point to the SaaS target, you will need to get [apex proxying](/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/apex-proxying/). By default, using an A record to point to the target is not a supported setup.
:::

#### Service continuation

<Render file="get-started-service-continuation" />

---

# Custom limits

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/configuration/custom-limits/

Custom limits allow you to programmatically enforce limits on your customers' Workers' resource usage. You can set limits for the maximum CPU time and number of subrequests per invocation. If a user Worker hits either of these limits, the user Worker will immediately throw an exception.

## Set Custom limits

Custom limits can be set in the dynamic dispatch Worker:

```js
export default {
 async fetch(request, env) {
   try {
     // parse the URL, read the subdomain
     let workerName = new URL(request.url).host.split('.')[0];
     let userWorker = env.dispatcher.get(
       workerName,
       {},
       {// set limits
         limits: {cpuMs: 10, subRequests: 5}
       }
     );
     return await userWorker.fetch(request);
   } catch (e) {
     if (e.message.startsWith('Worker not found')) {
       // we tried to get a worker that doesn't exist in our dispatch namespace
       return new Response('', { status: 404 });
     }
      return new Response(e.message, { status: 500 });
   }
 },
};
```

---

# Configuration

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/configuration/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Get started

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Observability

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/configuration/observability/

Workers for Platforms provides you with logs and analytics that can be used to share data with end users.

## Logs

Learn how to access logs with Workers for Platforms.

### Workers Trace Events Logpush

Workers Trace Events logpush is used to get raw Workers execution logs. Refer to [Logpush](/workers/observability/logs/logpush/) for more information.

Logpush can be enabled for an entire dispatch namespace or a single user Worker. To capture logs for all of the user Workers in a dispatch namespace:

1. Create a [Logpush job](/workers/observability/logs/logpush/#create-a-logpush-job).
2. Enable [logging](/workers/observability/logs/logpush/#enable-logging-on-your-worker) on your dispatch Worker.

Enabling logging on your dispatch Worker collects logs for both the dispatch Worker and for any user Workers in the dispatch namespace. Logs are automatically collected for all new Workers added to a dispatch namespace. To enable logging for an individual user Worker rather than an entire dispatch namespace, skip step 1 and complete step 2 on your user Worker.

All logs are forwarded to the Logpush job that you have setup for your account. Logpush filters can be used on the `Outcome` or `Script Name` field to include or exclude specific values or send logs to different destinations.

### Tail Workers

A [Tail Worker](/workers/observability/logs/tail-workers/) receives information about the execution of other Workers (known as producer Workers), such as HTTP statuses, data passed to `console.log()` or uncaught exceptions.

Use [Tail Workers](/workers/observability/logs/tail-workers/) instead of Logpush if you want granular control over formatting before logs are sent to their destination to receive [diagnostics channel events](/workers/runtime-apis/nodejs/diagnostics-channel), or if you want logs delivered in real-time.

Adding a Tail Worker to  your dispatch Worker collects logs for both the dispatch Worker and for any user Workers in the dispatch namespace. Logs are automatically collected for all new Workers added to a dispatch namespace. To enable logging for an individual user Worker rather than an entire dispatch namespace, add the [Tail Worker configuration](/workers/observability/logs/tail-workers/#configure-tail-workers) directly to the user Worker.

## Analytics

There are two ways for you to review your Workers for Platforms analytics.

### Workers Analytics Engine

[Workers Analytics Engine](/analytics/analytics-engine/) can be used with Workers for Platforms to provide analytics to end users. It can be used to expose events relating to a Workers invocation or custom user-defined events. Platforms can write/query events by script tag to get aggregates over a user’s usage.

### GraphQL Analytics API

Use Cloudflare’s [GraphQL Analytics API](/analytics/graphql-api) to get metrics relating to your Dispatch Namespaces. Use the `dispatchNamespaceName` dimension in the `workersInvocationsAdaptive` node to query usage by namespace.

---

# Outbound Workers

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/

import { WranglerConfig } from "~/components";

Outbound Workers sit between your customer's Workers and the public Internet. They give you visibility into all outgoing `fetch()` requests from user Workers.

![Outbound Workers diagram information](~/assets/images/cloudflare-for-platforms/outbound-worker-diagram.png)

## General Use Cases

Outbound Workers can be used to:

* Log all subrequests to identify malicious domains or usage patterns.
* Create, allow, or block lists for hostnames requested by user Workers.
* Configure authentication to your APIs behind the scenes (without end developers needing to set credentials).

## Use Outbound Workers

To use Outbound Workers:

1. Create a Worker intended to serve as your Outbound Worker.
2. Outbound Worker can be specified as an optional parameter in the [dispatch namespaces](/cloudflare-for-platforms/workers-for-platforms/get-started/configuration/#2-create-a-dispatch-namespace) binding in a project's [Wrangler configuration file](/workers/wrangler/configuration/). Optionally, to pass data from your dynamic dispatch Worker to the Outbound Worker, the variable names can be specified under **parameters**.

Make sure that you have `wrangler@3.3.0` or later [installed](/workers/wrangler/install-and-update/).

<WranglerConfig>

```toml
[[dispatch_namespaces]]
binding = "dispatcher"
namespace = "<NAMESPACE_NAME>"
outbound = {service = "<SERVICE_NAME>", parameters = ["params_object"]}
```

</WranglerConfig>

3. Edit your dynamic dispatch Worker to call the Outbound Worker and declare variables to pass on `dispatcher.get()`.

```js
export default {
	async fetch(request, env) {
	  try {

    // parse the URL, read the subdomain
		let workerName = new URL(request.url).host.split('.')[0];

		let context_from_dispatcher = {
			'customer_name': workerName,
			'url': request.url,
		  }

		let userWorker = env.dispatcher.get(
		  workerName,
		  {},
		  {// outbound arguments. object name must match parameters in the binding
			outbound: {
			 params_object: context_from_dispatcher,
			   }
			 }
		);
		return await userWorker.fetch(request);
	  } catch (e) {
		if (e.message.startsWith('Worker not found')) {
		  // we tried to get a worker that doesn't exist in our dispatch namespace
		  return new Response('', { status: 404 });
		}
		 return new Response(e.message, { status: 500 });
	  }
	}
}
```

4. The Outbound Worker will now be invoked on any `fetch()` requests from a user Worker. The user Worker will trigger a [FetchEvent](/workers/runtime-apis/handlers/fetch/) on the Outbound Worker. The variables declared in the binding can be accessed in the Outbound Worker through `env.<VAR_NAME>`.

The following is an example of an Outbound Worker that logs the fetch request from user Worker and creates a JWT if the fetch request matches `api.example.com`.

```js
export default {
  // this event is fired when the dispatched Workers make a subrequest
  async fetch(request, env, ctx) {
    // env contains the values we set in `dispatcher.get()`
    const customer_name = env.customer_name;
    const original_url = env.url;

    // log the request
    ctx.waitUntil(fetch(
      'https://logs.example.com',
      {
        method: 'POST',
        body: JSON.stringify({
          customer_name,
          original_url,
        }),
      },
    ));

    const url = new URL(original_url);
    if (url.host === 'api.example.com') {
      // pre-auth requests to our API
      const jwt = make_jwt_for_customer(customer_name);

      let headers = new Headers(request.headers);
      headers.set('Authorization', `Bearer ${jwt}`);

      // clone the request to set new headers using existing body
      let new_request = new Request(request, {headers});

      return fetch(new_request)
    }

    return fetch(request)
  }
};
```

:::note


Outbound Workers do not intercept fetch requests made from [Durable Objects](/durable-objects/) or [mTLS certificate bindings](/workers/runtime-apis/bindings/mtls/).


:::

---

# Static assets

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/configuration/static-assets/

import { Aside } from "@astrojs/starlight/components";

Workers for Platforms lets you deploy front-end applications at scale. By hosting static assets on Cloudflare's global network, you can deliver faster load times worldwide and eliminate the need for external infrastructure. You can also combine these static assets with dynamic logic in Cloudflare Workers, providing a full-stack experience for your customers.

### What you can build

#### Static sites

Host and serve HTML, CSS, JavaScript, and media files directly from Cloudflare's network, ensuring fast loading times worldwide. This is ideal for blogs, landing pages, and documentation sites.

#### Full-stack applications

Combine asset hosting with Cloudflare Workers to power dynamic, interactive applications. Store and retrieve data using Cloudflare KV, D1, and R2 Storage, allowing you to serve both front-end assets and backend logic from a single Worker.

### Benefits

#### Global caching for faster performance

Cloudflare automatically caches static assets at data centers worldwide, reducing latency and improving load times by up to 2x for users everywhere.

#### Scalability without infrastructure management

Your applications scale automatically to handle high traffic without requiring you to provision or manage infrastructure. Cloudflare dynamically adjusts to demand in real time.

#### Unified deployment for static and dynamic content

Deploy front-end assets alongside server-side logic, all within Cloudflare Workers. This eliminates the need for a separate hosting provider and ensures a streamlined deployment process.

---

## Deploy static assets to User Workers

It is common that, as the Platform, you will be responsible for uploading static assets on behalf of your end users. This often looks like this:

1. Your user uploads files (HTML, CSS, images) through your interface.
2. Your platform interacts with the Workers for Platforms APIs to attach the static assets to the User Worker script.

Once you receive the static files from your users (for a new or updated site), complete the following steps to attach the files to the corresponding User Worker:

1. Create an Upload Session
2. Upload file contents
3. Deploy/Update the Worker

After these steps are completed, the User Worker's static assets will be live on the Cloudflare's global network.

### 1. Create an Upload Session

Before sending any file data, you need to tell Cloudflare which files you intend to upload. That list of files is called a manifest. Each item in the manifest includes:

- A file path (for example, `"/index.html"` or `"/assets/logo.png"`)
- A hash (32-hex characters) representing the file contents
- The file size in bytes

<Aside type="note" title="Asset Isolation Considerations">
Static assets uploaded to Workers for Platforms are associated with the namespace rather than with individual User Worker. If multiple User Workers exist under the same namespace, assets with identical hashes may be shared across them. **JWTs should therefore only be shared with trusted platform services and should never be distributed to end-users.**

If strict isolation of assets is required, we recommend either salting with a random value each time, or incorporating an end-user identifier (for example, account ID or Worker script ID) within the hashing process, to ensure uniqueness. For example, `hash = slice(sha256(accountID + fileContents), 32)`.

</Aside>

#### Example manifest (JSON)

```json
{
	"/index.html": {
		"hash": "08f1dfda4574284ab3c21666d1ee8c7d4",
		"size": 1234
	},
	"/styles.css": {
		"hash": "36b8be012ee77df5f269b11b975611d3",
		"size": 5678
	}
}
```

To start the upload process, send a POST request to the Create Assets Upload Session [API endpoint](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/asset_upload/methods/create/).

```bash
POST /accounts/{account_id}/workers/dispatch/namespaces/{namespace}/scripts/{script_name}/assets-upload-session
```

Path Parameters:

- `namespace`: Name of the Workers for Platforms dispatch namespace
- `script_name`: Name of the User Worker

In the request body, include a JSON object listing each file path along with its hash and size. This helps Cloudflare identify which files you intend to upload and allows Cloudflare to check if any of them are already stored.

#### Sample request

```bash
curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME/assets-upload-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  --data '{
    "manifest": {
      "/index.html": {
        "hash": "08f1dfda4574284ab3c21666d1ee8c7d4",
        "size": 1234
      },
      "/styles.css": {
        "hash": "36b8be012ee77df5f269b11b975611d3",
        "size": 5678
      }
    }
  }'
```

#### Generating the hash

You can compute a SHA-256 digest of the file contents, then truncate or otherwise represent it consistently as a 32-hex-character string. Make sure to do it the same way each time so Cloudflare can reliably match files across uploads.

#### API Response

If all the files are already stored on Cloudflare, the response will only return the JWT token. If new or updated files are needed, the response will return:

- `jwt`: An upload token (valid for 1 hour) which will be used in the API request to upload the file contents (Step 2).
- `buckets`: An array of file-hash groups indicating which files to upload together. Files that have been recently uploaded will not appear in buckets, since Cloudflare already has them.

:::note
This step alone does not store files on Cloudflare. You must upload the actual file data in the next step.
:::

### 2. Upload File Contents

If the response to the Upload Session API returns `buckets`, that means you have new or changed files that need to be uploaded to Cloudflare.

Use the [Workers Assets Upload API](/api/resources/workers/subresources/assets/subresources/upload/) to transmit the raw file bytes in base64-encoded format for any missing or changed files. Once uploaded, Cloudflare will store these files so they can then be attached to a User Worker.

<Aside type="caution">
	Asset uniqueness is determined by the provided hash and are associated globally to their namespace rather than with each specific User Worker. If an asset has already been uploaded for that namespace earlier, Cloudflare will automatically omit sending this asset hash back in the `buckets` response to save you from re-uploading the same thing twice. This means that an asset can be shared between multiple User Workers if it shares the same hash unless you **explicitly make the hash unique**. If you require full isolation between assets across User Workers, incorporate a unique identifier within your asset hashing process (either salting it with something entirely random each time, or by including the end-user account ID or their Worker name to retain per-customer re-use).
</Aside>

#### API Request Authentication

Unlike most Cloudflare API calls that use an account-wide API token in the Authorization header, uploading file contents requires using the short-lived JWT token returned in the `jwt` field of the `assets-upload-session` response.

Include it as a Bearer token in the header:

```bash
Authorization: Bearer <upload-session-token>
```

This token is valid for one hour and must be supplied for each upload request to the Workers Assets Upload API.

#### File fields (multipart/form-data)

You must send the files as multipart/form-data with base64-encoded content:

- Field name: The file hash (for example, `36b8be012ee77df5f269b11b975611d3`)
- Field value: A Base64-encoded string of the file's raw bytes

#### Example: Uploading multiple files within a single bucket

If your Upload Session response listed a single "bucket" containing two file hashes:

```json
"buckets": [
  [
    "08f1dfda4574284ab3c21666d1ee8c7d4",
    "36b8be012ee77df5f269b11b975611d3"
  ]
]
```

You can upload both files in one request, each as a form-data field:

```bash
curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/assets/upload?base64=true" \
  -H "Authorization: Bearer <upload-session-token>" \
  -F "08f1dfda4574284ab3c21666d1ee8c7d4=<BASE64_OF_INDEX_HTML>" \
  -F "36b8be012ee77df5f269b11b975611d3=<BASE64_OF_STYLES_CSS>"
```

- `<upload-session-token>` is the token from step 1's assets-upload-session response
- `<BASE64_OF_INDEX_HTML>` is the Base64-encoded content of index.html
- `<BASE64_OF_STYLES_CSS>` is the Base64-encoded content of styles.css

If you have multiple buckets (for example, `[["hashA"], ["hashB"], ["hashC"]]`), you might need to repeat this process for each bucket, making one request per bucket group.

Once every file in the manifest has been uploaded, a status code of `201` will be returned, with the `jwt` field present. This JWT is a final "completion" token which can be used to create a deployment of a Worker with this set of assets. This completion token is valid for 1 hour.

```json
{
	"success": true,
	"errors": [],
	"messages": [],
	"result": {
		"jwt": "<completion-token>"
	}
}
```

`<completion-token>` indicates that Cloudflare has successfully received and stored the file contents specified by your manifest. You will use this `<completion-token>` in Step 3 to finalize the attachment of these files to the Worker.

### 3. Deploy the User Worker with static assets

Now that Cloudflare has all the files it needs (from the previous upload steps), you must attach them to the User Worker by making a PUT request to the [Upload User Worker API](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/methods/update/). This final step links the static assets to the User Worker using the completion token you received after uploading file contents.

You can also specify any optional settings under the `assets.config` field to customize how your files are served (for example, to handle trailing slashes in HTML paths).

#### API request example

```bash
curl -X PUT \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/dispatch/namespaces/$NAMESPACE_NAME/scripts/$SCRIPT_NAME" \
  -H "Content-Type: multipart/form-data" \
  -H "Authorization: Bearer $API_TOKEN" \
  -F 'metadata={
    "main_module": "index.js",
    "assets": {
      "jwt": "<completion-token>",
      "config": {
        "html_handling": "auto-trailing-slash"
      }
    },
    "compatibility_date": "2025-01-24"
  };type=application/json' \
  -F 'index.js=@/path/to/index.js;type=application/javascript'
```

- The `"jwt": "<completion-token>"` links the newly uploaded files to the Worker
- Including "html_handling" (or other fields under "config") is optional and can customize how static files are served
- If the user's Worker code has not changed, you can omit the code file or re-upload the same index.js

Once this PUT request succeeds, the files are served on the User Worker. Requests routed to that Worker will serve the new or updated static assets.

---

## Deploying static assets with Wrangler

If you prefer a CLI-based approach and your platform setup allows direct publishing, you can use Wrangler to deploy both your Worker code and static assets. Wrangler bundles and uploads static assets (from a specified directory) along with your Worker script, so you can manage everything in one place.

Create or update your [Wrangler configuration file](/workers/wrangler/configuration/) to specify where Wrangler should look for static files:

import { WranglerConfig } from "~/components";

<WranglerConfig>

```toml
name = "my-static-site"
main = "./src/index.js"
compatibility_date = "2025-01-29"

[assets]
directory = "./public"
binding = "ASSETS"
```

</WranglerConfig>

- `directory`: The local folder containing your static files (for example, `./public`).
- `binding`: The binding name used to reference these assets within your Worker code.

### 1. Organize your files

Place your static files (HTML, CSS, images, etc.) in the specified directory (in this example, `./public`). Wrangler will detect and bundle these files when you publish your Worker.

If you need to reference these files in your Worker script to serve them dynamically, you can use the `ASSETS` binding like this:

```js
export default {
	async fetch(request, env, ctx) {
		return env.ASSETS.fetch(request);
	},
};
```

### 2. Deploy the User Worker with the static assets

Run Wrangler to publish both your Worker code and the static assets:

```bash
npx wrangler deploy --name <USER_WORKER_NAME> --dispatch-namespace <NAMESPACE_NAME>
```

Wrangler will automatically detect your static files, bundle them, and upload them to Cloudflare along with your Worker code.

---

# Tags

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/configuration/tags/

To help you manage your customers’ Workers, use tags to better perform create, read, update, delete (CRUD) operations at scale. Tag user Worker scripts based on user ID, account ID, project ID, and environment. After you tag user Workers, when a user deletes their project, you will be able to delete all Workers associated with that project simultaneously.

```bash
curl --request PUT \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts/{script_name}/tags" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: application/javascript" \
--data "['TAG1', 'TAG2', 'TAG3']"
```

:::note


You can set a maximum of eight tags per script. Avoid special characters like `,` and `&` when naming your tag.


:::

You can include script tags and bindings on multipart script uploads in the metadata blob.

```bash
curl --request PUT \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts/{script_name}" \
--header "Authorization: Bearer <API_TOKEN>" \
--header "Content-Type: multipart/form-data" \
--form 'metadata="{\"main_module\": \"worker.js\", \"bindings\": [{\"name\": \"KV\", \"type\": \"kv_namespace\", \"namespace_id\": \"<KV_NAMESPACE_ID>\"}], \"tags\": [\"customer-123\", \"staging\", \"free-user\"]}"' \
--form 'worker.js=@"/path/to/worker.js";type=application/javascript+module'
```

### Tags API reference

| Method and endpoint                                                                                                                                    | Description                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts/{script_name}/tags`               | Lists tags through a response body of a list of tag strings.                                                                                                                                                     |
| `GET https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts/{script_name}/tags?tags={filter}` | Returns true or false where `filter` is a comma separated pairs of tag names to a yes or no value (for example, `my-tag-value:yes`).                                                                             |
| `GET https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts?tags={filter}`                    | Gets all Worker scripts that have tags that match the filter specified. The filter must be comma separated pairs of tag names to a yes or no value depending if the tag should act as an allowlist or blocklist. |
| `PUT https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts/{script_name}/tags`               | Sets the tags associated with the worker to match the tags specified in the body. If there are tags already associated with the Worker script that are not in the request, they will be removed.                 |
| `PUT https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts/{script_name}/tags/{tag}`         | Adds the single specified tag to the list of tags associated with the Worker script.                                                                                                                             |
| `DELETE https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts/{script_name}/tags/{tag}`      | Deletes the single specified tag from the list of tags associated with the Worker script.                                                                                                                        |
| `DELETE https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/dispatch/namespaces/{namespace_name}/scripts?tags={filter}`                 | Deletes all Worker scripts matching the filter. For example, `tags=testing:yes` would delete all scripts tagged with `testing`.                                                                                  |

---

# Configure Workers for Platforms

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/get-started/configuration/

import { Render, PackageManagers, WranglerConfig } from "~/components";

## Prerequisites:

### Enable Workers for Platforms

To enable Workers for Platforms, you will need to purchase the [Workers for Platforms Paid plan](/cloudflare-for-platforms/workers-for-platforms/platform/pricing/).

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers-for-platforms), and select your account.
2. Complete the payment process for the Workers for Platforms Paid plan.

If you are an Enterprise customer, contact your Cloudflare account team to enable Workers for Platforms.

### Learn about Workers for Platforms

Refer to [How Workers for Platforms works](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/) to learn more about Workers for Platforms terminology and architecture.

---

This guide will instruct you on setting up Workers for Platforms. You will configure a [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace), a [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) and a [user Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers) to test a request end to end.

### 1. Create a user Worker

First, create a [user Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers). User Workers are Workers that your end users (end developers) will be uploading.

User Workers can be created using C3. C3 (create-cloudflare-cli) is a command-line tool designed to help you setup and deploy Workers to Cloudflare as fast as possible.

Open a terminal window and run C3 to create your Worker project. This example creates a user Worker called `customer-worker-1`.

```sh
npm create cloudflare@latest customer-worker-1 -- --type=hello-world
```

When following the interactive prompts, answer the questions as below:

- Select `no` to using TypeScript.
- **Select `no` to deploying your application.**

### 2. Create a dispatch namespace

Create a [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace). A dispatch namespace is made up of a collection of [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers).

This example creates a dispatch namespace called `testing`. To create a dispatch namespace, run:

```sh
npx wrangler dispatch-namespace create testing
```

### 3. Upload a user Worker to the dispatch namespace

Make sure you are in your user Worker's project directory:

```sh
cd customer-worker-1
```

To upload and deploy the user Worker to the dispatch namespace, running the following command:

```sh
npx wrangler deploy --dispatch-namespace testing
```

### 4. Create a dynamic dispatch Worker

A [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) is a specialized routing Worker that directs incoming requests to the appropriate user Workers in your dispatch namespace. Instead of using [Workers Routes](/workers/configuration/routing/routes/), dispatch Workers let you programmatically control request routing through code.

#### Why use a dynamic dispatch Worker?

* **Scale**: Perfect for routing thousands or millions of hostnames to different Workers, without needing to rely on [Workers Routes](/workers/configuration/routing/routes/)
* **Custom routing logic**: Write code to determine exactly how requests should be routed. For example:
   * Map hostnames directly to specific Workers
   * Route requests based on subdomains
   * Use request metadata or headers for routing decisions

* **Add platform functionality**: Build in additional features at the routing layer.
   * Run authentication checks before requests reach user Workers
   * Sanitize incoming requests
   * Attach useful context like user IDs or account information
   * Transform requests or responses as needed

**To create your dynamic dispatch Worker:**

Navigate up a level from your user Worker's project directory:

```sh
cd ..
```

Create your dynamic dispatch Worker. In this example, the dispatch Worker is called `my-dispatcher`.

<PackageManagers type="create" pkg="cloudflare@latest" args={"my-dispatcher"} />

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Change to your project's directory:

```sh
cd my-dispatcher
```

Open the Wrangler file in your project directory, and add the dispatch namespace binding:

<WranglerConfig>

```toml
[[dispatch_namespaces]]
binding = "DISPATCHER"
namespace = "testing"
```

</WranglerConfig>

Add the following to the index.js file:

```js
export default {
	async fetch(req, env) {
		const worker = env.DISPATCHER.get("customer-worker-1");
		return await worker.fetch(req);
	},
};
```

This example shows a simple dynamic dispatch Worker that routes all requests to a single user Worker. For more advanced routing patterns, you could route based on hostname, path, custom metadata, or other request properties.

Deploy your dynamic dispatch Worker:

```sh
npx wrangler deploy
```

### 5. Test a request

You will now send a request to the route your dynamic dispatch Worker is on. You should receive the response (`Hello world`) you created in your user Worker (`customer-worker-1`) that you call from your dynamic dispatch Worker (`my-dispatcher`).

Preview the response to your Workers for Platforms project at `https://my-dispatcher.<YOUR_WORKER_SUBDOMAIN>.workers.dev/`.

By completing this guide, you have successfully set up a dispatch namespace, dynamic dispatch Worker and user Worker to test a request end to end.

## Related resources

- [Workers for Platforms example project](https://github.com/cloudflare/workers-for-platforms-example) - An end to end example project using Workers for Platforms

---

# Local development

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/get-started/developing-with-wrangler/

import { Render, PackageManagers, WranglerConfig } from "~/components";

To test your [Dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker), [user Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers) and [Outbound Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/) before deploying to production, you can use [Wrangler](/workers/wrangler) for development and testing.

:::note

Support for Workers for Platforms with `wrangler dev` in local mode is experimental and may change in the future. Use the prerelease branch: `wrangler@dispatch-namespaces-dev` to try Workers for Platforms locally.
:::

## 1. Create a user worker

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"customer-worker-1"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Then, move into the newly created directory:

```sh
cd customer-worker-1
```

Update the `src/index.js` file for customer-worker-1:

```javascript
export default {
	async fetch(request) {
		// make a subrequest to the internet
		const response = await fetch("https://example.com");
		return new Response(
			`user worker got "${await response.text()}" from fetch`,
		);
	},
};
```

Update the Wrangler file for customer-worker-1 and add the dispatch namespace:

<WranglerConfig>

```toml
# ... other content above ...

dispatch_namespace = "my-namespace"
```

</WranglerConfig>

## 2. Create a dispatch worker

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"dispatch-worker"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Then, move into the newly created directory:

```sh
cd dispatch-worker
```

Update the `src/index.js` file for dispatch-worker:

```javascript
export default {
	async fetch(request, env) {
		// get the user Worker, specifying parameters that the Outbound Worker will see when it intercepts a user worker's subrequest
		const customerScript = env.DISPATCH_NAMESPACE.get(
			"customer-worker-1",
			{},
			{
				outbound: {
					paramCustomerName: "customer-1",
				},
			},
		);
		// invoke user Worker
		return await customerScript.fetch(request);
	},
};
```

Update the Wrangler file for dispatch-worker and add the dispatch namespace binding:

<WranglerConfig>

```toml
# ... other content above ...

[[dispatch_namespaces]]
binding = "DISPATCH_NAMESPACE"
namespace = "my-namespace"
outbound = { service = "outbound-worker", parameters = ["paramCustomerName"] }
```

</WranglerConfig>

## 3. Create an Outbound Worker

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"outbound-worker"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Then, move into the newly created directory:

```sh
cd outbound-worker
```

Update the `src/index.js` file for outbound-worker:

```javascript
export default {
	async fetch(request, env) {
		const { paramCustomerName } = env;
		// use the parameters passed by the dispatcher to know what this user this request is for
		// and return custom content back to the user worker
		return new Response(
			`intercepted a request for ${paramCustomerName} by the outbound`,
		);
	},
};
```

## 4. Start local dev session for your Workers

In separate terminals, start a local dev session for each of your Workers.

For your dispatcher Worker:

```sh
cd dispatch-worker
npx wrangler@dispatch-namespaces-dev dev --port 8600
```

For your outbound Worker:

```sh
cd outbound-worker
npx wrangler@dispatch-namespaces-dev dev --port 8601
```

And for your user Worker:

```sh
cd customer-worker-1
npx wrangler@dispatch-namespaces-dev dev --port 8602
```

## 5. Test your requests

Send a request to your dispatcher Worker:

```sh
curl http://localhost:8600
```

```sh output
# -> user worker got "intercepted a request for customer-1 by the outbound" from fetch
```

## Remote dispatch namespaces

You can configure dispatch namespace bindings to connect to remote dispatch namespaces during local development by setting [`experimental_remote = true`](/workers/development-testing/#remote-bindings):

<WranglerConfig>
```jsonc title="wrangler.jsonc"
{
  "dispatch_namespaces": [
    {
      "binding": "DISPATCH_NAMESPACE",
      "namespace": "testing",
      "experimental_remote": true
		}
  ]
}
```
</WranglerConfig>

This allows you to run your [dynamic dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) locally, while connecting it to your remote dispatch namespace binding. You can then test changes to your core dispatching logic against real, deployed [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers).

For more information about remote bindings during local development, refer to [remote bindings documentation](/workers/development-testing/#remote-bindings).

---

# Create a dynamic dispatch Worker

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/get-started/dynamic-dispatch/

After you have created a dispatch namespace, you can fetch any user Workers in the namespace using a dynamic dispatch Worker. The dynamic dispatch Worker has a namespace binding.

Use any method of routing to a namespaced Worker (reading the subdomain, request header, or lookup in a database). Ultimately you need the name of the user Worker.

In the following example, routing to a user Worker is done through reading the subdomain `<USER_WORKER_NAME>.example.com/*`. For example, `my-customer.example.com` will run the script uploaded to `PUT accounts/<ACCOUNT_ID>/workers/dispatch/namespaces/my-dispatch-namespace/scripts/my-customer`.

```js
export default {
	async fetch(request, env) {
		try {
			// parse the URL, read the subdomain
			let workerName = new URL(request.url).host.split('.')[0];
			let userWorker = env.dispatcher.get(workerName);
			return await userWorker.fetch(request);
		} catch (e) {
			if (e.message.startsWith('Worker not found')) {
				// we tried to get a worker that doesn't exist in our dispatch namespace
				return new Response('', { status: 404 });
			}

			// this could be any other exception from `fetch()` *or* an exception
			// thrown by the called worker (e.g. if the dispatched worker has
			// `throw MyException()`, you could check for that here).
			return new Response(e.message, { status: 500 });
		}
	},
};
```

---

# Get started

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/get-started/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Uploading User Workers

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/get-started/user-workers/

[User Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers) contain code written by your end users (end developers).

## Upload User Workers

You can upload user Workers to a namespace via Wrangler or the Cloudflare API. Workers uploaded to a namespace will not appear on the **Workers & Pages** section of the Cloudflare dashboard. Instead, they will appear in a namespace under the [Workers for Platforms](https://dash.cloudflare.com/?to=/:account/workers-for-platforms) tab.

To run Workers uploaded to a namespace, you will need to first create a [dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker)
with a [dispatch namespace binding](/workers/wrangler/configuration/#dispatch-namespace-bindings-workers-for-platforms).

### Upload user Workers via Wrangler

Uploading user Workers is supported through [wrangler](/workers/wrangler/) by running the following command:

```sh
npx wrangler deploy --dispatch-namespace <NAMESPACE_NAME>
```

For simplicity, start with wrangler when [getting started](/cloudflare-for-platforms/workers-for-platforms/get-started/configuration/).

### Upload user Workers via the API

Since you will be deploying Workers on behalf of your users, you will likely want to use the [Workers for Platforms script upload APIs](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/content/methods/update/) directly instead of Wrangler to have more control over the upload process. The Workers for Platforms script upload API is the same as the [Worker upload API](/api/resources/workers/subresources/scripts/methods/update/), but it will upload the Worker to a [dispatch namespace](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dispatch-namespace) instead of to your account directly. See an example of the REST API [here](/workers/platform/infrastructure-as-code#workers-for-platforms).

## Bindings

You can use any Workers [bindings](/workers/runtime-apis/bindings/) with the dynamic dispatch Worker or any user Workers.

Bindings for your user Workers can be defined on [multipart script uploads](/api/resources/workers_for_platforms/subresources/dispatch/subresources/namespaces/subresources/scripts/subresources/content/methods/update/) in the [metadata](/workers/configuration/multipart-upload-metadata/) part.

---

# Changelog

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/platform/changelog/

import { ProductReleaseNotes } from "~/components";

Workers for Platforms users might also be interested in [the Workers changelog](/workers/platform/changelog/) which has detailed changes to the Workers runtime and the various configuration options available to your dispatch and user Workers.

{/* <!-- Actual content lives in /src/content/release-notes/workers-for-platforms.yaml. --> */}

<ProductReleaseNotes />

---

# Limits

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/platform/limits/

import { Render } from "~/components"

## Script limits

Cloudflare provides an unlimited number of scripts for Workers for Platforms customers.

## `cf` object

The [`cf` object](/workers/runtime-apis/request/#the-cf-property-requestinitcfproperties) contains Cloudflare-specific properties of a request. This field is not accessible in [user Workers](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers) because some fields in this object are sensitive and can be used to manipulate Cloudflare features (for example, `cacheKey`, `resolveOverride`, `scrapeShield`.)

## Durable Object namespace limits

Workers for Platforms do not have a limit for the number of Durable Object namespaces.

## Cache API

For isolation, `caches.default` is disabled for namespaced scripts. To learn more about the cache, refer to [How the cache Works](/workers/reference/how-the-cache-works/).

## ​Tags

You can set a maximum of eight tags per script. Avoid special characters like `,` and `&` when naming your tag.

<Render file="limits_increase" product="workers" />

## Gradual Deployments

[Gradual Deployments](/workers/configuration/versions-and-deployments/gradual-deployments/) is not supported yet for user Workers. Changes made to user Workers create a new version that deployed all-at-once to 100% of traffic.

## API Rate Limits

<Render file="api-rate-limits" product="fundamentals" />

---

# Platform

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/platform/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Pricing

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/platform/pricing/

The Workers for Platforms Paid plan is **$25 monthly**. Workers for Platforms can be purchased through the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers-for-platforms).

Workers for Platforms comes with the following usage allotments and overage pricing.



|   | Requests<sup>1</sup> <sup>2</sup>                                                 | Duration                        | CPU time<sup>2</sup>                                                                                                                                                                                                                                                                                                                             | Scripts                                                |
| - | --------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
|   | 20 million requests included per month <br /><br /> +$0.30 per additional million | No charge or limit for duration | 60 million CPU milliseconds included per month<br /><br /> +$0.02 per additional million CPU milliseconds<br /><br/> Max of 30 seconds of CPU time per invocation <br /> Max of 15 minutes of CPU time per [Cron Trigger](/workers/configuration/cron-triggers/) or [Queue Consumer](/queues/configuration/javascript-apis/#consumer) invocation | 1000 scripts <br /> <br />+$0.02 per additional script |

 <sup>1</sup>  Inbound requests to your Worker. Cloudflare does not bill for [subrequests](/workers/platform/limits/#subrequests) you make from your Worker. <br /> <sup>2</sup>  Workers for Platforms only charges for 1 request across the chain of [dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#dynamic-dispatch-worker) -> [user Worker](/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/#user-workers) -> [outbound Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/outbound-workers/). CPU time is charged across these Workers.

## Example pricing:

A Workers for Platforms project that serves 100 million requests per month, uses an average of 10 milliseconds (ms) of CPU time per request and uses 1200 scripts would have the following estimated costs:

|                  | Monthly Costs | Formula                                                                                                     |
| ---------------- | ------------- | ----------------------------------------------------------------------------------------------------------- |
| **Subscription** | $25.00        |                                                                                                             |
| **Requests**     | $24.00        | (100,000,000 requests - 20,000,000 included requests) / 1,000,000 \* $0.30                                  |
| **CPU time**     | $18.80        | ((10 ms of CPU time per request \* 100,000,000 requests) - 60,000,000 included CPU ms) / 1,000,000 \* $0.02 |
| **Scripts**      | $4.00         | 1200 scripts - 1000 included scripts \* $0.02                                                               |
| **Total**        | $71.80        |                                                                                                             |

:::note[Custom limits]


Set [custom limits](/cloudflare-for-platforms/workers-for-platforms/configuration/custom-limits/) for user Workers to get control over your Cloudflare bill, prevent accidental runaway bills or denial-of-wallet attacks. Configure the maximum amount of CPU time that can be used per invocation by [defining custom limits in your dispatch Worker](/cloudflare-for-platforms/workers-for-platforms/configuration/custom-limits/#set-custom-limits).


:::

---

# How Workers for Platforms works

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/reference/how-workers-for-platforms-works/

Workers for Platforms is built on top of [Cloudflare Workers](/workers/). The same [security and performance models used by Workers](/workers/reference/security-model/) apply to applications that use Workers for Platforms.

The Workers configuration API was initially built around managing a relatively small number of Workers on each account. This leads to some difficulties when using Workers as a platform for your own users, including:

* Frequently needing to increase script limits.
* Adding an ever-increasing number of routes.
* Managing logic in a central place if your own logic is supposed to come before your customers' logic.

Workers for Platforms extends the capabilities of Workers for SaaS businesses that want to deploy Worker scripts on behalf of their customers or that want to let their users write Worker scripts directly.

## Architecture

Workers for Platforms introduces a new architecture model as outlined on this page.

### Dispatch namespace

A dispatch namespace is composed of a collection of user Workers. With dispatch namespaces, a dynamic dispatch Worker can be used to call any user Worker in a namespace.

:::note[Best practice]


Having a production and staging namespace is useful to test changes that you have made to your dynamic dispatch Worker.

If you have multiple distinct services you are providing your customers, you should split these out into different dispatch workers and namespaces. We discourage creating a new namespace for each customer.


:::

### Dynamic dispatch Worker

A dynamic dispatch Worker is written by Cloudflare’s platform customers to run their own logic before dispatching (routing) the request to user Workers. In addition to routing, it can be used to run authentication, create boilerplate functions and sanitize responses.

The dynamic dispatch Worker calls user Workers from the dispatch namespace and executes them. The dynamic dispatch Worker is configured with a [dispatch namespace binding](/cloudflare-for-platforms/workers-for-platforms/get-started/configuration/#4-create-a-dynamic-dispatch-worker). The binding is the entrypoint for all requests to user Workers.

### User Workers

User Workers are written by your end users (end developers). End developers deploy user Workers to script automated actions, create integrations or modify response payloads to return custom content.

### Request lifecycle

Below you will find an example request lifecycle in the Workers for Platforms architecture.

![The request lifecycle is described below.](~/assets/images/cloudflare-for-platforms/workers-for-platforms.png)

In the above diagram:

1. Request for `customer-a.example.com/api` will first hit the dynamic dispatch Worker (`api-prod`).
2. The dispatcher (`env.dispatcher.get(customer-a)`) configured in your dynamic dispatch Worker code will handle routing logic to user Workers.
3. The subdomain (`customer-a.example.com`) of the incoming request is used to route to the user Worker with the same name (`customer-a`).

## ​Workers for Platforms versus Service bindings

Both Workers for Platforms and Service bindings enable Worker-to-Worker communication.

Service bindings explicitly link two Workers together. They are meant for use cases where you know exactly which Workers need to communicate with each other. Service bindings do not work in the Workers for Platforms model because user Workers are uploaded as needed by your end users.

In the Workers for Platforms model, a dynamic dispatch Worker can be used to call any user Worker (similar to how Service bindings work) in a dispatch namespace but without needing to explicitly pre-define the relationship.

Service bindings and Workers for Platforms can be used simultaneously when building applications.

## [Cache API](/workers/runtime-apis/cache/)

Workers for Platforms user Workers have access to namespaced cache through the [cache API](/workers/runtime-apis/cache/). Namespaced cache is isolated across user Workers. For isolation, `caches.default` is disabled for namespaced scripts.

To learn more about the cache, refer to [How the cache Works](/workers/reference/how-the-cache-works/).

---

# Reference

URL: https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/reference/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Build a Comments API

URL: https://developers.cloudflare.com/d1/tutorials/build-a-comments-api/

import { Render, PackageManagers, Stream, WranglerConfig } from "~/components";

In this tutorial, you will learn how to use D1 to add comments to a static blog site. To do this, you will construct a new D1 database, and build a JSON API that allows the creation and retrieval of comments.

## Prerequisites

Use [C3](https://developers.cloudflare.com/learning-paths/workers/get-started/c3-and-wrangler/#c3), the command-line tool for Cloudflare's developer products, to create a new directory and initialize a new Worker project:

<PackageManagers type="create" pkg="cloudflare@latest" args={"d1-example"} />

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

To start developing your Worker, `cd` into your new project directory:

```sh
cd d1-example
```

## Video Tutorial

<Stream
	id="8d20dd6cf5679f3272ca44a9fa01728c"
	title="Build a Comments API with D1"
	thumbnail="22s"
/>

## 1. Install Hono

In this tutorial, you will use [Hono](https://github.com/honojs/hono), an Express.js-style framework, to build your API. To use Hono in this project, install it using `npm`:

<PackageManagers pkg="hono" />

## 2. Initialize your Hono application

In `src/worker.js`, initialize a new Hono application, and define the following endpoints:

- `GET /api/posts/:slug/comments`.
- `POST /api/posts/:slug/comments`.

```js
import { Hono } from "hono";

const app = new Hono();

app.get("/api/posts/:slug/comments", async (c) => {
	// Do something and return an HTTP response
	// Optionally, do something with `c.req.param("slug")`
});

app.post("/api/posts/:slug/comments", async (c) => {
	// Do something and return an HTTP response
	// Optionally, do something with `c.req.param("slug")`
});

export default app;
```

## 3. Create a database

You will now create a D1 database. In Wrangler, there is support for the `wrangler d1` subcommand, which allows you to create and query your D1 databases directly from the command line. Create a new database with `wrangler d1 create`:

```sh
npx wrangler d1 create d1-example
```

Reference your created database in your Worker code by creating a [binding](/workers/runtime-apis/bindings/) inside of your [Wrangler configuration file](/workers/wrangler/configuration/). Bindings allow us to access Cloudflare resources, like D1 databases, KV namespaces, and R2 buckets, using a variable name in code. In the Wrangler configuration file, set up the binding `DB` and connect it to the `database_name` and `database_id`:

<WranglerConfig>

```toml
[[ d1_databases ]]
binding = "DB" # available in your Worker on `env.DB`
database_name = "d1-example"
database_id = "4e1c28a9-90e4-41da-8b4b-6cf36e5abb29"
```

</WranglerConfig>

With your binding configured in your Wrangler file, you can interact with your database from the command line, and inside your Workers function.

## 4. Interact with D1

Interact with D1 by issuing direct SQL commands using `wrangler d1 execute`:

```sh
npx wrangler d1 execute d1-example --remote --command "SELECT name FROM sqlite_schema WHERE type ='table'"
```

```sh output

Executing on d1-example:

┌───────┐
│ name  │
├───────┤
│ d1_kv │
└───────┘
```

You can also pass a SQL file - perfect for initial data seeding in a single command. Create `schemas/schema.sql`, which will create a new `comments` table for your project:

```sql
DROP TABLE IF EXISTS comments;
CREATE TABLE IF NOT EXISTS comments (
  id integer PRIMARY KEY AUTOINCREMENT,
  author text NOT NULL,
  body text NOT NULL,
  post_slug text NOT NULL
);
CREATE INDEX idx_comments_post_slug ON comments (post_slug);

-- Optionally, uncomment the below query to create data

-- INSERT INTO COMMENTS (author, body, post_slug) VALUES ('Kristian', 'Great post!', 'hello-world');
```

With the file created, execute the schema file against the D1 database by passing it with the flag `--file`:

```sh
npx wrangler d1 execute d1-example --remote --file schemas/schema.sql
```

## 5. Execute SQL

In earlier steps, you created a SQL database and populated it with initial data. Now, you will add a route to your Workers function to retrieve data from that database. Based on your Wrangler configuration in previous steps, your D1 database is now accessible via the `DB` binding. In your code, use the binding to prepare SQL statements and execute them, for example, to retrieve comments:

```js
app.get("/api/posts/:slug/comments", async (c) => {
	const { slug } = c.req.param();
	const { results } = await c.env.DB.prepare(
		`
    select * from comments where post_slug = ?
  `,
	)
		.bind(slug)
		.all();
	return c.json(results);
});
```

The above code makes use of the `prepare`, `bind`, and `all` functions on a D1 binding to prepare and execute a SQL statement. Refer to [D1 Workers Binding API](/d1/worker-api/) for a list of all methods available.

In this function, you accept a `slug` URL query parameter and set up a new SQL statement where you select all comments with a matching `post_slug` value to your query parameter. You can then return it as a JSON response.

## 6. Insert data

The previous steps grant read-only access to your data. To create new comments by inserting data into the database, define another endpoint in `src/worker.js`:

```js
app.post("/api/posts/:slug/comments", async (c) => {
	const { slug } = c.req.param();
	const { author, body } = await c.req.json();

	if (!author) return c.text("Missing author value for new comment");
	if (!body) return c.text("Missing body value for new comment");

	const { success } = await c.env.DB.prepare(
		`
    insert into comments (author, body, post_slug) values (?, ?, ?)
  `,
	)
		.bind(author, body, slug)
		.run();

	if (success) {
		c.status(201);
		return c.text("Created");
	} else {
		c.status(500);
		return c.text("Something went wrong");
	}
});
```

## 7. Deploy your Hono application

With your application ready for deployment, use Wrangler to build and deploy your project to the Cloudflare network.

Begin by running `wrangler whoami` to confirm that you are logged in to your Cloudflare account. If you are not logged in, Wrangler will prompt you to login, creating an API key that you can use to make authenticated requests automatically from your local machine.

After you have logged in, confirm that your Wrangler file is configured similarly to what is seen below. You can change the `name` field to a project name of your choice:

<WranglerConfig>

```toml
name = "d1-example"
main = "src/worker.js"
compatibility_date = "2022-07-15"

[[ d1_databases ]]
binding = "DB" # available in your Worker on env.DB
database_name = "<YOUR_DATABASE_NAME>"
database_id = "<YOUR_DATABASE_UUID>"
```

</WranglerConfig>

Now, run `npx wrangler deploy` to deploy your project to Cloudflare.

```sh
npx wrangler deploy
```

When it has successfully deployed, test the API by making a `GET` request to retrieve comments for an associated post. Since you have no posts yet, this response will be empty, but it will still make a request to the D1 database regardless, which you can use to confirm that the application has deployed correctly:

```sh
# Note: Your workers.dev deployment URL may be different
curl https://d1-example.signalnerve.workers.dev/api/posts/hello-world/comments
[
  {
    "id": 1,
    "author": "Kristian",
    "body": "Hello from the comments section!",
    "post_slug": "hello-world"
  }
]
```

## 8. Test with an optional frontend

This application is an API back-end, best served for use with a front-end UI for creating and viewing comments. To test this back-end with a prebuild front-end UI, refer to the example UI in the [example-frontend directory](https://github.com/cloudflare/workers-sdk/tree/main/templates/worker-d1-api/example-frontend). Notably, the [`loadComments` and `submitComment` functions](https://github.com/cloudflare/workers-sdk/tree/main/templates/worker-d1-api/example-frontend/src/views/PostView.vue#L57-L82) make requests to a deployed version of this site, meaning you can take the frontend and replace the URL with your deployed version of the codebase in this tutorial to use your own data.

Interacting with this API from a front-end will require enabling specific Cross-Origin Resource Sharing (or _CORS_) headers in your back-end API. Hono allows you to enable Cross-Origin Resource Sharing for your application. Import the `cors` module and add it as middleware to your API in `src/worker.js`:

```typescript null {5}
import { Hono } from "hono";
import { cors } from "hono/cors";

const app = new Hono();
app.use("/api/*", cors());
```

Now, when you make requests to `/api/*`, Hono will automatically generate and add CORS headers to responses from your API, allowing front-end UIs to interact with it without erroring.

## Conclusion

In this example, you built a comments API for powering a blog. To see the full source for this D1-powered comments API, you can visit [cloudflare/workers-sdk/templates/worker-d1-api](https://github.com/cloudflare/workers-sdk/tree/main/templates/worker-d1-api).

---

# Build a Staff Directory Application

URL: https://developers.cloudflare.com/d1/tutorials/build-a-staff-directory-app/

import { WranglerConfig } from "~/components";

In this tutorial, you will learn how to use D1 to build a staff directory. This application will allow users to access information about an organization's employees and give admins the ability to add new employees directly within the app.
To do this, you will first need to set up a [D1 database](/d1/get-started/) to manage data seamlessly, then you will develop and deploy your application using the [HonoX Framework](https://github.com/honojs/honox) and [Cloudflare Pages](/pages).

## Prerequisites

Before moving forward with this tutorial, make sure you have the following:

- A Cloudflare account, if you do not have one, [sign up](https://dash.cloudflare.com/sign-up/workers-and-pages) before continuing.
- A recent version of [npm](https://docs.npmjs.com/getting-started) installed.

If you do not want to go through with the setup now, [view the completed code](https://github.com/lauragift21/staff-directory) on GitHub.

## 1. Install HonoX

In this tutorial, you will use [HonoX](https://github.com/honojs/honox), a meta-framework for creating full-stack websites and Web APIs to build your application. To use HonoX in your project, run the `hono-create` command.

To get started, run the following command:

```sh
npm create hono@latest
```

During the setup process, you will be asked to provide a name for your project directory and to choose a template. When making your selection, choose the `x-basic` template.

## 2. Initialize your HonoX application

Once your project is set up, you can see a list of generated files as below. This is a typical project structure for a HonoX application:

```
.
├── app
│   ├── global.d.ts // global type definitions
│   ├── routes
│   │   ├── _404.tsx // not found page
│   │   ├── _error.tsx // error page
│   │   ├── _renderer.tsx // renderer definition
│   │   ├── about
│   │   │   └── [name].tsx // matches `/about/:name`
│   │   └── index.tsx // matches `/`
│   └── server.ts // server entry file
├── package.json
├── tsconfig.json
└── vite.config.ts
```

The project includes directories for app code, routes, and server setup, alongside configuration files for package management, TypeScript, and Vite.

## 3. Create a database

To create a database for your project, use the Cloudflare CLI tool, [Wrangler](/workers/wrangler), which supports the `wrangler d1` command for D1 database operations. Create a new database named `staff-directory` with the following command:

```sh
npx wrangler d1 create staff-directory
```

After creating your database, you will need to set up a [binding](/workers/runtime-apis/bindings/) in the [Wrangler configuration file](/workers/wrangler/configuration/) to integrate your database with your application.

This binding enables your application to interact with Cloudflare resources such as D1 databases, KV namespaces, and R2 buckets. To configure this, create a Wrangler file in your project's root directory and input the basic setup information:

<WranglerConfig>

```toml
name = "staff-directory"
compatibility_date = "2023-12-01"
```

</WranglerConfig>

Next, add the database binding details to your Wrangler file. This involves specifying a binding name (in this case, `DB`), which will be used to reference the database within your application, along with the `database_name` and `database_id` provided when you created the database:



<WranglerConfig>

```toml
[[d1_databases]]
binding = "DB"
database_name = "staff-directory"
database_id = "f495af5f-dd71-4554-9974-97bdda7137b3"
```

</WranglerConfig>

You have now configured your application to access and interact with your D1 database, either through the command line or directly within your codebase.

You will also need to make adjustments to your Vite config file in `vite.config.js`. Add the following config settings to ensure that Vite is properly set up to work with Cloudflare bindings in local environment:

```ts
import adapter from "@hono/vite-dev-server/cloudflare";

export default defineConfig(({ mode }) => {
	if (mode === "client") {
		return {
			plugins: [client()],
		};
	} else {
		return {
			plugins: [
				honox({
					devServer: {
						adapter,
					},
				}),
				pages(),
			],
		};
	}
});
```

## 4. Interact with D1

To interact with your D1 database, you can directly issue SQL commands using the `wrangler d1 execute` command:

```sh
wrangler d1 execute staff-directory --command "SELECT name FROM sqlite_schema WHERE type ='table'"
```

The command above allows you to run queries or operations directly from the command line.

For operations such as initial data seeding or batch processing, you can pass a SQL file with your commands. To do this, create a `schema.sql` file in the root directory of your project and insert your SQL queries into this file:

```sql
CREATE TABLE locations (
    location_id INTEGER PRIMARY KEY AUTOINCREMENT,
    location_name VARCHAR(255) NOT NULL
);

CREATE TABLE departments (
    department_id INTEGER PRIMARY KEY AUTOINCREMENT,
    department_name VARCHAR(255) NOT NULL
);

CREATE TABLE employees (
    employee_id INTEGER PRIMARY KEY AUTOINCREMENT,
    name VARCHAR(255) NOT NULL,
    position VARCHAR(255) NOT NULL,
    image_url VARCHAR(255) NOT NULL,
    join_date DATE NOT NULL,
    location_id INTEGER REFERENCES locations(location_id),
    department_id INTEGER REFERENCES departments(department_id)
);

INSERT INTO locations (location_name) VALUES ('London, UK'), ('Paris, France'), ('Berlin, Germany'), ('Lagos, Nigeria'), ('Nairobi, Kenya'), ('Cairo, Egypt'), ('New York, NY'), ('San Francisco, CA'), ('Chicago, IL');

INSERT INTO departments (department_name) VALUES ('Software Engineering'), ('Product Management'), ('Information Technology (IT)'), ('Quality Assurance (QA)'), ('User Experience (UX)/User Interface (UI) Design'), ('Sales and Marketing'), ('Human Resources (HR)'), ('Customer Support'), ('Research and Development (R&D)'), ('Finance and Accounting');
```

The above queries will create three tables: `Locations`, `Departments`, and `Employees`. To populate these tables with initial data, use the `INSERT INTO` command. After preparing your schema file with these commands, you can apply it to the D1 database. Do this by using the `--file` flag to specify the schema file for execution:

```sh
wrangler d1 execute staff-directory --file=./schema.sql
```

To execute the schema locally and seed data into your local directory, pass the `--local` flag to the above command.

## 5. Create SQL statements

After setting up your D1 database and configuring the Wrangler file as outlined in previous steps, your database is accessible in your code through the `DB` binding. This allows you to directly interact with the database by preparing and executing SQL statements. In the following step, you will learn how to use this binding to perform common database operations such as retrieving data and inserting new records.

### Retrieve data from database

```ts
export const findAllEmployees = async (db: D1Database) => {
	const query = `
      SELECT employees.*, locations.location_name, departments.department_name
      FROM employees
      JOIN locations ON employees.location_id = locations.location_id
      JOIN departments ON employees.department_id = departments.department_id
      `;
	const { results } = await db.prepare(query).all();
	const employees = results;
	return employees;
};
```

### Insert data into the database

```ts
export const createEmployee = async (db: D1Database, employee: Employee) => {
	const query = `
      INSERT INTO employees (name, position, join_date, image_url, department_id, location_id)
      VALUES (?, ?, ?, ?, ?, ?)`;

	const results = await db
		.prepare(query)
		.bind(
			employee.name,
			employee.position,
			employee.join_date,
			employee.image_url,
			employee.department_id,
			employee.location_id,
		)
		.run();
	const employees = results;
	return employees;
};
```

For a complete list of all the queries used in the application, refer to the [db.ts](https://github.com/lauragift21/staff-directory/blob/main/app/db.ts) file in the codebase.

## 6. Develop the UI

The application uses `hono/jsx` for rendering. You can set up a Renderer in `app/routes/_renderer.tsx` using the JSX-rendered middleware, serving as the entry point for your application:

```ts
import { jsxRenderer } from 'hono/jsx-renderer'
import { Script } from 'honox/server'

export default jsxRenderer(({ children, title }) => {
  return (
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>{title}</title>
        <Script src="/app/client.ts" async />
      </head>
      <body>{children}</body>
    </html>
  )
})
```

Add the bindings defined earlier in `global.d.ts` file where the global type definitions for TypeScript is defined ensuring type consistency across your application:

```ts
declare module "hono" {
	interface Env {
		Variables: {};
		Bindings: {
			DB: D1Database;
		};
	}
}
```

This application uses [Tailwind CSS](https://tailwindcss.com/) for styling. To use Tailwind CSS, refer to the [TailwindCSS documentation](https://v2.tailwindcss.com/docs), or follow the steps [provided on GitHub](https://github.com/honojs/honox?tab=readme-ov-file#using-tailwind-css).

To display a list of employees, invoke the `findAllEmployees` function from your `db.ts` file and call that within the `routes/index.tsx` file. The `createRoute()` function present in the file serves as a helper function for defining routes that handle different HTTP methods like `GET`, `POST`, `PUT`, or `DELETE`.

```ts
import { css } from 'hono/css'
import { createRoute } from 'honox/factory'
import Counter from '../islands/counter'

const className = css`
  font-family: sans-serif;
`

export default createRoute((c) => {
  const name = c.req.query('name') ?? 'Hono'
  return c.render(
    <div class={className}>
      <h1>Hello, {name}!</h1>
      <Counter />
    </div>,
    { title: name }
  )
})
```

The existing code within the file includes a placeholder that uses the Counter component. You should replace this section with the following code block:

```ts null {2-4,19-21}
import { createRoute } from 'honox/factory'
import type { FC } from 'hono/jsx'
import type { Employee } from '../db'
import { findAllEmployees, findAllDepartments, findAllLocations } from '../db'

const EmployeeCard: FC<{ employee: Employee }> = ({ employee }) => {
  const { employee_id, name, image_url, department_name, location_name } = employee;
  return (
    <div className="max-w-sm bg-white border border-gray-200 rounded-lg shadow-md">
      <a href={`/employee/${employee_id}`}>
        <img className="bg-indigo-600 p-4 rounded-t-lg" src={image_url} alt={name} />
        //...
      </a>
    </div>
  );
};

export const GET = createRoute(async (c) => {
  const employees = await findAllEmployees(c.env.DB)
  const locations = await findAllLocations(c.env.DB)
  const departments = await findAllDepartments(c.env.DB)
  return c.render(
    <section className="flex-grow">
      <h1 className="mb-4 text-3xl font-extrabold text-gray-900 dark:text-white md:text-5xl lg:text-6xl mt-12">
        <span className="text-transparent bg-clip-text bg-gradient-to-r to-blue-600 from-sky-400">{`Directory `}</span>
      </h1>
      //...
      </section>
      <section className="flex flex-wrap -mx-4">
        {employees.map((employee) => (
          <div className="w-full sm:w-1/2 md:w-1/3 lg:w-1/4 px-2 mb-4">
            <EmployeeCard employee={employee} />
          </div>
        ))}
      </section>
    </section>
  )
})
```

The code snippet demonstrates how to import the `findAllEmployees`, `findAllLocations`, and `findAllDepartments` functions from the `db.ts` file, and how to use the binding `c.env.DB` to invoke these functions. With these, you can retrieve and display the fetched data on the page.

### Add an employee

Use the `export POST` route to create a new employee through the `/admin` page:

```ts null {26}
import { createRoute } from "honox/factory";
import type { Employee } from "../../db";
import { getFormDataValue, getFormDataNumber } from "../../utils/formData";
import { createEmployee } from "../../db";

export const POST = createRoute(async (c) => {
	try {
		const formData = await c.req.formData();
		const imageFile = formData.get("image_file");
		let imageUrl = "";

		// TODO: process image url with R2

		const employeeData: Employee = {
			employee_id: getFormDataValue(formData, "employee_id"),
			name: getFormDataValue(formData, "name"),
			position: getFormDataValue(formData, "position"),
			image_url: imageUrl,
			join_date: getFormDataValue(formData, "join_date"),
			department_id: getFormDataNumber(formData, "department_id"),
			location_id: getFormDataNumber(formData, "location_id"),
			location_name: "",
			department_name: "",
		};

		await createEmployee(c.env.DB, employeeData);
		return c.redirect("/", 303);
	} catch (error) {
		return new Response("Error processing your request", { status: 500 });
	}
});
```

### Store images in R2

During the process of creating a new employee, the image uploaded can be stored in an R2 bucket prior to being added to the database.

To store an image in an R2 bucket:

1. Create an R2 bucket.
2. Upload the image to this bucket.
3. Obtain a public URL for the image from the bucket. This URL is then saved in your database, linking to the image stored in the R2 bucket.

Use the `wrangler r2 bucket create` command to create a bucket:

```sh
wrangler r2 bucket create employee-avatars
```

Once the bucket is created, add the R2 bucket binding to your Wrangler file:



<WranglerConfig>

```toml
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "employee-avatars"
```

</WranglerConfig>

Pass the R2 binding to the `global.d.ts` file:

```ts
declare module "hono" {
	interface Env {
		Variables: {};
		Bindings: {
			DB: D1Database;
			MY_BUCKET: R2Bucket;
		};
	}
}
```

To store the uploaded image in the R2 bucket, you can use the `put()` method provided by R2. This method allows you to upload the image file to your bucket:

```ts
if (imageFile instanceof File) {
	const key = `${new Date().getTime()}-${imageFile.name}`;
	const fileBuffer = await imageFile.arrayBuffer();

	await c.env.MY_BUCKET.put(key, fileBuffer, {
		httpMetadata: {
			contentType: imageFile.type || "application/octet-stream",
		},
	});
	console.log(`File uploaded successfully: ${key}`);
	imageUrl = `https://pub-8d936184779047cc96686a631f318fce.r2.dev/${key}`;
}
```

[Refer to GitHub](https://github.com/lauragift21/staff-directory) for the full codebase.

## 7. Deploy your HonoX application

With your application ready for deployment, you can use Wrangler to build and deploy your project to the Cloudflare Network. Ensure you are logged in to your Cloudflare account by running the `wrangler whoami` command. If you are not logged in, Wrangler will prompt you to login by creating an API key that you can use to make authenticated requests automatically from your computer.

After successful login, confirm that your Wrangler file is configured similarly to the code block below:



<WranglerConfig>

```toml
name = "staff-directory"
compatibility_date = "2023-12-01"

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "employee-avatars"

[[d1_databases]]
binding = "DB"
database_name = "staff-directory"
database_id = "f495af5f-dd71-4554-9974-97bdda7137b3"
```

</WranglerConfig>

Run `wrangler deploy` to deploy your project to Cloudflare. After deployment you can test your application is working by accessing the deployed URL provided for you. Your browser should display your application with the base frontend you created. If you do not have any data populated in your database, go to the `/admin` page to add a new employee, and this should return a new employee in your home page.

## Conclusion

In this tutorial, you built a staff directory application where users can view all employees within an organization. Refer to the [Staff directory repository](https://github.com/lauragift21/staff-directory) for the full source code.

![staff directory demo](https://github.com/lauragift21/staff-directory/raw/main/demo.gif)

---

# Build an API to access D1 using a proxy Worker

URL: https://developers.cloudflare.com/d1/tutorials/build-an-api-to-access-d1/

import { Render, PackageManagers, Steps, Details, WranglerConfig } from "~/components";

In this tutorial, you will learn how to create an API that allows you to securely run queries against a D1 database.

This is useful if you want to access a D1 database outside of a Worker or Pages project, customize access controls and/or limit what tables can be queried.

D1's built-in [REST API](/api/resources/d1/subresources/database/methods/create/) is best suited for administrative use as the global [Cloudflare API rate limit](/fundamentals/api/reference/limits) applies.

To access a D1 database outside of a Worker project, you need to create an API using a Worker. Your application can then securely interact with this API to run D1 queries.

:::note

D1 uses parameterized queries. This prevents SQL injection. To make your API more secure, validate the input using a library like [zod](https://zod.dev/).

:::

## Prerequisites

1. Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages).
2. Install [`Node.js`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
3. Have an existing D1 database. Refer to [Get started tutorial for D1](/d1/get-started/).

<Details header="Node.js version manager">
	Use a Node version manager like [Volta](https://volta.sh/) or
	[nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change
	Node.js versions. [Wrangler](/workers/wrangler/install-and-update/), discussed
	later in this guide, requires a Node version of `16.17.0` or later.
</Details>

## 1. Create a new project

Create a new Worker to create and deploy your API.

<Steps>
1. Create a Worker named `d1-http` by running:

    <PackageManagers type="create" pkg="cloudflare@latest" args={"d1-http"} />

    <Render
    	file="c3-post-run-steps"
    	product="workers"
    	params={{
    	category: "hello-world",
    	type: "Worker only",
    	lang: "TypeScript",
    	}}
    />

2.  Change into your new project directory to start developing:

    ```sh frame="none"
    cd d1-http
    ```

</Steps>

## 2. Install Hono

In this tutorial, you will use [Hono](https://github.com/honojs/hono), an Express.js-style framework, to build the API.

<Steps>
1. To use Hono in this project, install it using `npm`:

    <PackageManagers type="add" pkg="hono" frame="none" />

</Steps>

## 3. Add an API_KEY

You need an API key to make authenticated calls to the API. To ensure that the API key is secure, add it as a [secret](/workers/configuration/secrets).

<Steps>
1. For local development, create a `.dev.vars` file in the root directory of `d1-http`.
2. Add your API key in the file as follows.

    ```bash title=".dev.vars"
    API_KEY="YOUR_API_KEY"
    ```

    Replace `YOUR_API_KEY` with a valid string value. You can also generate this value using the following command.

    ```sh
    openssl rand -base64 32
    ```

</Steps>

:::note
In this step, we have defined the name of the API key to be `API_KEY`.
:::

## 4. Initialize the application

To initialize the application, you need to import the required packages, initialize a new Hono application, and configure the following middleware:

- [Bearer Auth](https://hono.dev/docs/middleware/builtin/bearer-auth): Adds authentication to the API.
- [Logger](https://hono.dev/docs/middleware/builtin/logger): Allows monitoring the flow of requests and responses.
- [Pretty JSON](https://hono.dev/docs/middleware/builtin/pretty-json): Enables "JSON pretty print" for JSON response bodies.

<Steps>
1. Replace the contents of the `src/index.ts` file with the code below.

    ```ts title="src/index.ts"
    import { Hono } from "hono";
    import { bearerAuth } from "hono/bearer-auth";
    import { logger } from "hono/logger";
    import { prettyJSON } from "hono/pretty-json";

    type Bindings = {
    	API_KEY: string;
    };

    const app = new Hono<{ Bindings: Bindings }>();

    app.use("*", prettyJSON(), logger(), async (c, next) => {
    	const auth = bearerAuth({ token: c.env.API_KEY });
    	return auth(c, next);
    });
    ```

</Steps>

## 5. Add API endpoints

<Steps>
1. Add the following snippet into your `src/index.ts`.

    ```ts title="src/index.ts"

    // Paste this code at the end of the src/index.ts file

    app.post("/api/all", async (c) => {
    	return c.text("/api/all endpoint");
    });

    app.post("/api/exec", async (c) => {
    	return c.text("/api/exec endpoint");
    });

    app.post("/api/batch", async (c) => {
    	return c.text("/api/batch endpoint");
    });

    export default app;
    ```

    This adds the following endpoints:

    - POST `/api/all`
    - POST `/api/exec`
    - POST `/api/batch`

2. Start the development server by running the following command:

   <PackageManagers type="run" args={"dev"} frame="none" />

3. To test the API locally, open a second terminal.

4. In the second terminal, execute the below cURL command. Replace `YOUR_API_KEY` with the value you set in the `.dev.vars` file.

   ```sh frame="none"
   curl -H "Authorization: Bearer YOUR_API_KEY" "http://localhost:8787/api/all" --data '{}'
   ```

   You should get the following output:

   ```txt
   /api/all endpoint
   ```

5. Stop the local server from running by pressing `x` in the first terminal.

</Steps>

The Hono application is now set up. You can test the other endpoints and add more endpoints if needed. The API does not yet return any information from your database. In the next steps, you will create a database, add its bindings, and update the endpoints to interact with the database.

## 6. Create a database

If you do not have a D1 database already, you can create a new database with `wrangler d1 create`.

<Steps>

1.  In your terminal, run:

    ```sh frame="none"
    npx wrangler d1 create d1-http-example
    ```

    You may be asked to login to your Cloudflare account. Once logged in, the command will create a new D1 database. You should see a similar output in your terminal.

    ```sh output
    ✅ Successfully created DB 'd1-http-example' in region EEUR
    Created your new D1 database.

    [[d1_databases]]
    binding = "DB" # i.e. available in your Worker on env.DB
    database_name = "d1-http-example"
    database_id = "1234567890"
    ```

</Steps>

Make a note of the displayed `database_name` and `database_id`. You will use this to reference the database by creating a [binding](/workers/runtime-apis/bindings/).

## 7. Add a binding

<Steps>
1. From your `d1-http` folder, open the Wrangler file, Wrangler's configuration file.
2. Add the following binding in the file. Make sure that the `database_name` and the `database_id` are correct.

    <WranglerConfig>

    ```toml
    [[d1_databases]]
    binding = "DB" # i.e. available in your Worker on env.DB
    database_name = "d1-http-example"
    database_id = "1234567890"
    ```

    </WranglerConfig>

3.  In your `src/index.ts` file, update the `Bindings` type by adding `DB: D1Database`.

    ```ts ins={2}
    type Bindings = {
    	DB: D1Database;
    	API_KEY: string;
    };
    ```

</Steps>

You can now access the database in the Hono application.

## 8. Create a table

To create a table in your newly created database:

<Steps>

1.  Create a new folder called `schemas` inside your `d1-http` folder.
2.  Create a new file called `schema.sql`, and paste the following SQL statement into the file.

    ```sql title="schema.sql"
    DROP TABLE IF EXISTS posts;
    CREATE TABLE IF NOT EXISTS posts (
    	id integer PRIMARY KEY AUTOINCREMENT,
    	author text NOT NULL,
    	title text NOT NULL,
    	body text NOT NULL,
    	post_slug text NOT NULL
    );
    INSERT INTO posts (author, title, body, post_slug) VALUES ('Harshil', 'D1 HTTP API', 'Learn to create an API to query your D1 database.','d1-http-api');
    ```

    The code drops any table named `posts` if it exists, then creates a new table `posts` with the field `id`, `author`, `title`, `body`, and `post_slug`. It then uses an INSERT statement to populate the table.

3.  In your terminal, execute the following command to create this table:

    ```sh frame="none"
    npx wrangler d1 execute d1-http-example --file=./schemas/schema.sql
    ```

</Steps>

Upon successful execution, a new table will be added to your database.

:::note
The table will be created in the local instance of the database. If you want to add this table to your production database, append the above command by adding the `--remote` flag.
:::

## 9. Query the database

Your application can now access the D1 database. In this step, you will update the API endpoints to query the database and return the result.

<Steps>
1. In your `src/index.ts` file, update the code as follow.

    ```ts title="src/index.ts" ins={10-21,31-37,47-62} del={9,30,46}
    // Update the API routes

    /**
    * Executes the `stmt.run()` method.
    * https://developers.cloudflare.com/d1/worker-api/prepared-statements/#run
    */

    app.post('/api/all', async (c) => {
    		return c.text("/api/all endpoint");
    	try {
    		let { query, params } = await c.req.json();
    		let stmt = c.env.DB.prepare(query);
    		if (params) {
    			stmt = stmt.bind(params);
    		}

    		const result = await stmt.run();
    		return c.json(result);
    	} catch (err) {
    		return c.json({ error: `Failed to run query: ${err}` }, 500);
    	}
    });

    /**
    * Executes the `db.exec()` method.
    * https://developers.cloudflare.com/d1/worker-api/d1-database/#exec
    */

    app.post('/api/exec', async (c) => {
    		return c.text("/api/exec endpoint");
    	try {
    		let { query } = await c.req.json();
    		let result = await c.env.DB.exec(query);
    		return c.json(result);
    	} catch (err) {
    		return c.json({ error: `Failed to run query: ${err}` }, 500);
    	}
    });

    /**
    * Executes the `db.batch()` method.
    * https://developers.cloudflare.com/d1/worker-api/d1-database/#batch
    */

    app.post('/api/batch', async (c) => {
    		return c.text("/api/batch endpoint");
    	try {
    		let { batch } = await c.req.json();
    		let stmts = [];
    		for (let query of batch) {
    			let stmt = c.env.DB.prepare(query.query);
    			if (query.params) {
    				stmts.push(stmt.bind(query.params));
    			} else {
    				stmts.push(stmt);
    			}
    		}
    		const results = await c.env.DB.batch(stmts);
    		return c.json(results);
    	} catch (err) {
    		return c.json({ error: `Failed to run query: ${err}` }, 500);
    	}
    });
    ...
    ```

</Steps>

In the above code, the endpoints are updated to receive `query` and `params`. These queries and parameters are passed to the respective functions to interact with the database.

- If the query is successful, you receive the result from the database.
- If there is an error, the error message is returned.

## 10. Test the API

Now that the API can query the database, you can test it locally.

<Steps>
1. Start the development server by executing the following command:

    <PackageManagers type="run" args={"dev"} frame="none" />

2.  In a new terminal window, execute the following cURL commands. Make sure to replace `YOUR_API_KEY` with the correct value.

    ```sh title="/api/all"
    curl -H "Authorization: Bearer YOUR_API_KEY" "http://localhost:8787/api/all" --data '{"query": "SELECT title FROM posts WHERE id=?", "params":1}'
    ```

    ```sh title="/api/batch"
    curl -H "Authorization: Bearer YOUR_API_KEY" "http://localhost:8787/api/batch" --data '{"batch": [ {"query": "SELECT title FROM posts WHERE id=?", "params":1},{"query": "SELECT id FROM posts"}]}'
    ```

    ```sh title="/api/exec"
    curl -H "Authorization: Bearer YOUR_API_KEY" "localhost:8787/api/exec" --data '{"query": "INSERT INTO posts (author, title, body, post_slug) VALUES ('\''Harshil'\'', '\''D1 HTTP API'\'', '\''Learn to create an API to query your D1 database.'\'','\''d1-http-api'\'')" }'
    ```

</Steps>

If everything is implemented correctly, the above commands should result successful outputs.

## 11. Deploy the API

Now that everything is working as expected, the last step is to deploy it to the Cloudflare network. You will use Wrangler to deploy the API.

<Steps>
1. To use the API in production instead of using it locally, you need to add the table to your remote (production) database. To add the table to your production database, run the following command:

    ```sh frame="none"
    npx wrangler d1 execute d1-http-example --file=./schemas/schema.sql --remote
    ```

    You should now be able to view the table on the [Cloudflare dashboard > **Storage & Databases** > **D1**.](https://dash.cloudflare.com/?to=/:account/workers/d1/)

2.  To deploy the application to the Cloudflare network, run the following command:

    ```sh frame="none"
    npx wrangler deploy
    ```

    ```sh output
     ⛅️ wrangler 3.78.4 (update available 3.78.5)
    -------------------------------------------------------

    Total Upload: 53.00 KiB / gzip: 13.16 KiB
    Your worker has access to the following bindings:
    - D1 Databases:
      - DB: d1-http-example (DATABASE_ID)
    Uploaded d1-http (4.29 sec)
    Deployed d1-http triggers (5.57 sec)
      [DEPLOYED_APP_LINK]
    Current Version ID: [BINDING_ID]
    ```

    Upon successful deployment, you will get the link of the deployed app in the terminal (`DEPLOYED_APP_LINK`). Make a note of it.

3.  Generate a new API key to use in production.

    ```sh
    openssl rand -base64 32
    ```

    ```sh output
    [YOUR_API_KEY]
    ```

4.  Execute the `wrangler secret put` command to add an API to the deployed project.

    ```sh frame="none"
    npx wrangler secret put API_KEY
    ```

    ```sh output
    ✔ Enter a secret value:
    ```

    The terminal will prompt you to enter a secret value.

5.  Enter the value of your API key (`YOUR_API_KEY`). Your API key will now be added to your project. Using this value you can make secure API calls to your deployed API.

    ```sh
    ✔ Enter a secret value: [YOUR_API_KEY]
    ```

    ```sh output
    🌀 Creating the secret for the Worker "d1-http"
    ✨ Success! Uploaded secret API_KEY
    ```

6.  To test it, run the following cURL command with the correct `YOUR_API_KEY` and `DEPLOYED_APP_LINK`.

    - Use the `YOUR_API_KEY` you have generated as the secret API key.
    - You can also find your `DEPLOYED_APP_LINK` from the Cloudflare dashboard > **Workers & Pages** > **`d1-http`** > **Settings** > **Domains & Routes**.

    ```sh frame="none"
    curl -H "Authorization: Bearer YOUR_API_KEY" "https://DEPLOYED_APP_LINK/api/exec" --data '{"query": "SELECT 1"}'
    ```

</Steps>

## Summary

In this tutorial, you have:

1. Created an API that interacts with your D1 database.
2. Deployed this API to the Workers. You can use this API in your external application to execute queries against your D1 database. The full code for this tutorial can be found on [GitHub](https://github.com/harshil1712/d1-http-example/tree/main).

## Next steps

You can check out a similar implementation that uses Zod for validation in [this GitHub repository](https://github.com/elithrar/http-api-d1-example). If you want to build an OpenAPI compliant API for your D1 database, you should use the [Cloudflare Workers OpenAPI 3.1 template](https://github.com/cloudflare/workers-sdk/tree/main/templates/worker-openapi).

---

# Query D1 using Prisma ORM

URL: https://developers.cloudflare.com/d1/tutorials/d1-and-prisma-orm/

import { WranglerConfig, FileTree, PackageManagers, GitHubCode } from "~/components";

## What is Prisma ORM?

[Prisma ORM](https://www.prisma.io/orm) is a next-generation JavaScript and TypeScript ORM that unlocks a new level of developer experience when working with databases thanks to its intuitive data model, automated migrations, type-safety and auto-completion.

To learn more about Prisma ORM, refer to the [Prisma documentation](https://www.prisma.io/docs).

## Query D1 from a Cloudflare Worker using Prisma ORM

This tutorial shows you how to set up and deploy a Cloudflare Worker that is accessing a D1 database from scratch.

## Quick start

If you want to skip the steps and get started quickly, select **Deploy to Cloudflare** below.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/docs-examples/tree/d1-prisma/d1/query-d1-using-prisma)

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers. Use this option if you are familiar with Cloudflare Workers, and wish to skip the step-by-step guidance.

You may wish to manually follow the steps if you are new to Cloudflare Workers.

## Prerequisites

- [`Node.js`](https://nodejs.org/en/) and [`npm`](https://docs.npmjs.com/getting-started) installed on your machine.
- A [Cloudflare account](https://dash.cloudflare.com).

## 1. Create a Cloudflare Worker

Open your terminal, and run the following command to create a Cloudflare Worker using Cloudflare's [`hello-world`](https://github.com/cloudflare/workers-sdk/tree/4fdd8987772d914cf50725e9fa8cb91a82a6870d/packages/create-cloudflare/templates/hello-world) template:

```sh
npm create cloudflare@latest prisma-d1-example -- --type hello-world
```

In your terminal, you will be asked a series of questions related your project:

1. Answer `yes` to using TypeScript.
2. Answer `no` to deploying your Worker.

## 2. Initialize Prisma ORM

:::note

D1 is supported in Prisma ORM as of [v5.12.0](https://github.com/prisma/prisma/releases/tag/5.12.0).

:::

To set up Prisma ORM, go into your project directory, and install the Prisma CLI:

```sh
cd prisma-d1-example
```

<PackageManagers pkg="prisma" dev />

Next, install the Prisma Client package and the driver adapter for D1:

<PackageManagers pkg="@prisma/client @prisma/adapter-d1" />

Finally, bootstrap the files required by Prisma ORM using the following command:

<PackageManagers
	type="exec"
	pkg="prisma"
	args="init --datasource-provider sqlite"
/>

The command above:

1. Creates a new directory called `prisma` that contains your [Prisma schema](https://www.prisma.io/docs/orm/prisma-schema/overview) file.
2. Creates a `.env` file used to configure environment variables that will be read by the Prisma CLI.

In this tutorial, you will not need the `.env` file since the connection between Prisma ORM and D1 will happen through a [binding](/workers/runtime-apis/bindings/). The next steps will instruct you through setting up this binding.

Since you will use the [driver adapter](https://www.prisma.io/docs/orm/overview/databases/database-drivers#driver-adapters) feature which is currently in Preview, you need to explicitly enable it via the `previewFeatures` field on the `generator` block.

Open your `schema.prisma` file and adjust the `generator` block to reflect as follows:

```prisma title="schema.prisma"
generator client {
  provider        = "prisma-client-js"
  output          = "../src/generated/prisma"
  previewFeatures = ["driverAdapters"]
}
```

## 3. Create your D1 database

In this step, you will set up your D1 database. You can create a D1 database via the [Cloudflare dashboard](https://dash.cloudflare.com), or via `wrangler`. This tutorial will use the `wrangler` CLI.

Open your terminal and run the following command:

```sh
npx wrangler d1 create prisma-demo-db
```

You should receive the following output on your terminal:

```
✅ Successfully created DB 'prisma-demo-db' in region WEUR
Created your new D1 database.

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "prisma-demo-db",
      "database_id": "<D1_DATABASE_ID>"
    }
  ]
}
```

You now have a D1 database in your Cloudflare account with a binding to your Cloudflare Worker.

Copy the last part of the command output and paste it into your Wrangler file. It should look similar to this:

<WranglerConfig>

```toml
name = "prisma-d1-example"
main = "src/index.ts"
compatibility_date = "2024-03-20"
compatibility_flags = ["nodejs_compat"]
[observability]
enabled = true

[[d1_databases]]
binding = "DB" # i.e. available in your Worker on env.DB
database_name = "prisma-demo-db"
database_id = "<D1_DATABASE_ID>"
```

</WranglerConfig>

Replace `<D1_DATABASE_ID>` with the database ID of your D1 instance. If you were not able to fetch this ID from the terminal output, you can also find it in the [Cloudflare dashboard](https://dash.cloudflare.com/), or by running `npx wrangler d1 info prisma-demo-db` in your terminal.

Next, you will create a database table in the database to send queries to D1 using Prisma ORM.

## 4. Create a table in the database

[Prisma Migrate](https://www.prisma.io/docs/orm/prisma-migrate/understanding-prisma-migrate/overview) does not support D1 yet, so you cannot follow the default migration workflows using `prisma migrate dev` or `prisma db push`.

:::note

Prisma Migrate for D1 is currently in Early Access. If you want to try it out, you can follow the instructions on the [Prisma documentation](https://www.prisma.io/docs/orm/overview/databases/cloudflare-d1#using-prisma-migrate-via-a-driver-adapter-in-prismaconfigts-early-access).

:::

D1 uses [migrations](/d1/reference/migrations) for managing schema changes, and the Prisma CLI can help generate the necessary SQL for those updates. In the steps below, you will use both tools to create and apply a migration to your database.

First, create a new migration using `wrangler`:

```sh
npx wrangler d1 migrations create prisma-demo-db create_user_table
```

Answer `yes` to creating a new folder called `migrations`.

The command has now created a new directory called `migrations` and an empty file called `0001_create_user_table.sql` inside of it:

<FileTree>

- prisma-d1-example
  - migrations
    - **0001_create_user_table.sql**

</FileTree>

Next, you need to add the SQL statement that will create a `User` table to that file.

Open the `schema.prisma` file and add the following `User` model to your schema:

<GitHubCode
    repo="cloudflare/docs-examples"
    file="d1/query-d1-using-prisma/prisma/schema.prisma"
    commit="c49d24f86dc2eb06a07b1c0b3ede871a1d8e7e92"
    lines="15-19"
		lang="prisma"
    code={{
     title: "schema.prisma"
   }}
/>

Now, run the following command in your terminal to generate the SQL statement that creates a `User` table equivalent to the `User` model above:

```sh
npx prisma migrate diff --from-empty --to-schema-datamodel ./prisma/schema.prisma --script --output migrations/0001_create_user_table.sql
```

This stores a SQL statement to create a new `User` table in your migration file from before, here is what it looks like:

<GitHubCode
    repo="cloudflare/docs-examples"
    file="d1/query-d1-using-prisma/migrations/0001_create_user_table.sql"
    commit="c49d24f86dc2eb06a07b1c0b3ede871a1d8e7e92"
    lang="sql"
    lines="1-9"
    code={{
     title: "0001_create_user_table.sql"
   }}
/>

`UNIQUE INDEX` on `email` was created because the `User` model in your Prisma schema is using the [`@unique`](https://www.prisma.io/docs/orm/reference/prisma-schema-reference#unique) attribute on its `email` field.

You now need to use the `wrangler d1 migrations apply` command to send this SQL statement to D1. This command accepts two options:

- `--local`: Executes the statement against a _local_ version of D1. This local version of D1 is a SQLite database file that will be located in the `.wrangler/state` directory of your project. Use this approach when you want to develop and test your Worker on your local machine. Refer to [Local development](/d1/best-practices/local-development/) to learn more.
- `--remote`: Executes the statement against your _remote_ version of D1. This version is used by your _deployed_ Cloudflare Workers. Refer to [Remote development](/d1/best-practices/remote-development/) to learn more.

In this tutorial, you will do both local and remote development. You will test the Worker locally, then deploy your Worker afterwards.

Open your terminal, and run both commands:

```sh
# For the local database
npx wrangler d1 migrations apply prisma-demo-db --local
```

```sh
# For the remote database
npx wrangler d1 migrations apply prisma-demo-db --remote
```

Choose `Yes` both times when you are prompted to confirm that the migration should be applied.

Next, create some data that you can query once the Worker is running. This time, you will run the SQL statement without storing it in a file:

```sh
# For the local database
npx wrangler d1 execute prisma-demo-db --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Local)');" --local
```

```sh
# For the remote database
npx wrangler d1 execute prisma-demo-db --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Remote)');" --remote
```

:::note
If you receive an error to the effect of `Unknown arguments: (\email\,, \name\)...`, you may need to escape the double quotes with backticks (`) instead of backslashes (\\).

Your Wrangler command will then look like:

```sh
# Escape with ` instead of \
npx wrangler d1 execute prisma-demo-db --command "INSERT INTO  `"User`" (`"email`", `"name`") VALUES
('jane@prisma.io', 'Jane Doe (Local)');" --<FLAG>
```

:::

## 5. Query your database from the Worker

To query your database from the Worker using Prisma ORM, you need to:

1. Add `DB` to the `Env` interface.
2. Instantiate `PrismaClient` using the `PrismaD1` driver adapter.
3. Send a query using Prisma Client and return the result.

Open `src/index.ts` and replace the entire content with the following:

<GitHubCode
    repo="cloudflare/docs-examples"
    file="d1/query-d1-using-prisma/src/index.ts"
    commit="c49d24f86dc2eb06a07b1c0b3ede871a1d8e7e92"
    lang="ts"
    code={{
     title: "index.ts"
   }}
    useTypeScriptExample={true}
/>

Before running the Worker, generate Prisma Client with the following command:

```sh
npx prisma generate
```

## 6. Run the Worker locally

Now that you have the database query in place and Prisma Client generated, run the Worker locally:

```sh
npm run dev
```

Open your browser at [`http://localhost:8787`](http://localhost:8787/) to check the result of the database query:

```json
[{ "id": 1, "email": "jane@prisma.io", "name": "Jane Doe (Local)" }]
```

## 7. Deploy the Worker

To deploy the Worker, run the following command:

```sh
npm run deploy
```

Access your Worker at `https://prisma-d1-example.USERNAME.workers.dev`. Your browser should display the following data queried from your remote D1 database:

```json
[{ "id": 1, "email": "jane@prisma.io", "name": "Jane Doe (Remote)" }]
```

By finishing this tutorial, you have deployed a Cloudflare Worker using D1 as a database and querying it via Prisma ORM.

## Related resources

- [Prisma documentation](https://www.prisma.io/docs/getting-started).
- To get help, open a new [GitHub Discussion](https://github.com/prisma/prisma/discussions/), or [ask the AI bot in the Prisma docs](https://www.prisma.io/docs).
- [Ready-to-run examples using Prisma ORM](https://github.com/prisma/prisma-examples/).
- Check out the [Prisma community](https://www.prisma.io/community), follow [Prisma on X](https://www.x.com/prisma) and join the [Prisma Discord](https://pris.ly/discord).
- [Developer Experience Redefined: Prisma & Cloudflare Lead the Way to Data DX](https://www.prisma.io/blog/cloudflare-partnership-qerefgvwirjq).

---

# Bulk import to D1 using REST API

URL: https://developers.cloudflare.com/d1/tutorials/import-to-d1-with-rest-api/

import { Render, Steps, PackageManagers } from "~/components";

In this tutorial, you will learn how to import a database into D1 using the [REST API](/api/resources/d1/subresources/database/methods/import/).

## Prerequisites

<Render file="prereqs" product="workers" />

## 1. Create a D1 API token

To use REST APIs, you need to generate an API token to authenticate your API requests. You can do this through the Cloudflare dashboard.

<Render file="generate-d1-api-token" product="d1" />

## 2. Create the target table

You must have an existing D1 table which matches the schema of the data you wish to import.

This tutorial uses the following:

- A database called `d1-import-tutorial`.
- A table called `TargetD1Table`
- Within `TargetD1Table`, three columns called `id`, `text`, and `date_added`.

To create the table, follow these steps:

<Steps>

1. Go to **Storage & Databases** > **D1**.
2. Select **Create**.
3. Name your database. For this tutorial, name your D1 database `d1-import-tutorial`.
4. (Optional) Provide a location hint. Location hint is an optional parameter you can provide to indicate your desired geographical location for your database. Refer to [Provide a location hint](/d1/configuration/data-location/#provide-a-location-hint) for more information.
5. Select **Create**.
6. Go to **Console**, then paste the following SQL snippet. This creates a table named `TargetD1Table`.

   ```sql
   DROP TABLE IF EXISTS TargetD1Table;
   CREATE TABLE IF NOT EXISTS TargetD1Table (id INTEGER PRIMARY KEY, text TEXT, date_added TEXT);
   ```

   Alternatively, you can use the [Wrangler CLI](/workers/wrangler/install-and-update/).

   ```bash
   # Create a D1 database
   npx wrangler d1 create d1-import-tutorial

   # Create a D1 table
   npx wrangler d1 execute d1-import-tutorial --command="DROP TABLE IF EXISTS TargetD1Table; CREATE TABLE IF NOT EXISTS TargetD1Table (id INTEGER PRIMARY KEY, text TEXT, date_added TEXT);" --remote

   ```

</Steps>

## 3. Create an `index.js` file

<Steps>

1. Create a new directory and initialize a new Node.js project.

   ```bash
   mkdir d1-import-tutorial
   cd d1-import-tutorial
   npm init -y
   ```

2. In this repository, create a new file called `index.js`. This file will contain the code which uses REST API to import your data to your D1 database.

3. In your `index.js` file, define the following variables:

   - `TARGET_TABLE`: The target table name
   - `ACCOUNT_ID`: The account ID (you can find this in the Cloudflare dashboard > **Workers & Pages**)
   - `DATABASE_ID`: The D1 database ID (you can find this in the Cloudflare dashboard > **Storage & Databases** > **D1 SQL Database** > your database)
   - `D1_API_KEY`: The D1 API token generated in [step 1](/d1/tutorials/import-to-d1-with-rest-api#1-create-a-d1-api-token)

   :::caution
   In production, you should use environment variables to store sensitive information.
   :::

   ```js title="index.js"
   const TARGET_TABLE = " "; // for the tutorial, `TargetD1Table`
   const ACCOUNT_ID = " ";
   const DATABASE_ID = " ";
   const D1_API_KEY = " ";
   const D1_URL = `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/d1/database/${DATABASE_ID}/import`;
   const filename = crypto.randomUUID(); // create a random filename
   const uploadSize = 500;
   const headers = {
   	"Content-Type": "application/json",
   	Authorization: `Bearer ${D1_API_KEY}`,
   };
   ```

</Steps>

## 4. Generate example data (optional)

In practice, you may already have the data you wish to import to a D1 database.

This tutorial generates example data to demonstrate the import process.

<Steps>

1. Install the `@faker-js/faker` module.

   <PackageManagers pkg="@faker-js/faker" />

2. Add the following code at the beginning of the `index.js` file. This code creates an array called `data` with 2500 (`uploadSize`) array elements, where each array element contains an object with `id`, `text`, and `date_added`. Each array element corresponds to a table row.

   ```js title="index.js"
   import crypto from "crypto";
   import { faker } from "@faker-js/faker";

   // Generate Fake data
   const data = Array.from({ length: uploadSize }, () => ({
   	id: Math.floor(Math.random() * 1000000),
   	text: faker.lorem.paragraph(),
   	date_added: new Date().toISOString().slice(0, 19).replace("T", " "),
   }));
   ```

</Steps>

## 5. Generate the SQL command

<Steps>

1. Create a function that will generate the SQL command to insert the data into the target table. This function uses the `data` array generated in the previous step.

   ```js title="index.js"
   function makeSqlInsert(data, tableName, skipCols = []) {
   	const columns = Object.keys(data[0]).join(",");
   	const values = data
   		.map((row) => {
   			return (
   				"(" +
   				Object.values(row)
   					.map((val) => {
   						if (skipCols.includes(val) || val === null || val === "") {
   							return "NULL";
   						}
   						return `'${String(val).replace(/'/g, "").replace(/"/g, "'")}'`;
   					})
   					.join(",") +
   				")"
   			);
   		})
   		.join(",");

   	return `INSERT INTO ${tableName} (${columns}) VALUES ${values};`;
   }
   ```

</Steps>

## 6. Import the data to D1

The import process consists of four steps:

1. **Init upload**: This step initializes the upload process. It sends the hash of the SQL command to the D1 API and receives an upload URL.
2. **Upload to R2**: This step uploads the SQL command to the upload URL.
3. **Start ingestion**: This step starts the ingestion process.
4. **Polling**: This step polls the import process until it completes.

<Steps>

1. Create a function called `uploadToD1` which executes the four steps of the import process.

   ```js title="index.js"
   async function uploadToD1() {
   	// 1. Init upload
   	const hashStr = crypto.createHash("md5").update(sqlInsert).digest("hex");

   	try {
   		const initResponse = await fetch(D1_URL, {
   			method: "POST",
   			headers,
   			body: JSON.stringify({
   				action: "init",
   				etag: hashStr,
   			}),
   		});

   		const uploadData = await initResponse.json();
   		const uploadUrl = uploadData.result.upload_url;
   		const filename = uploadData.result.filename;

   		// 2. Upload to R2
   		const r2Response = await fetch(uploadUrl, {
   			method: "PUT",
   			body: sqlInsert,
   		});

   		const r2Etag = r2Response.headers.get("ETag").replace(/"/g, "");

   		// Verify etag
   		if (r2Etag !== hashStr) {
   			throw new Error("ETag mismatch");
   		}

   		// 3. Start ingestion
   		const ingestResponse = await fetch(D1_URL, {
   			method: "POST",
   			headers,
   			body: JSON.stringify({
   				action: "ingest",
   				etag: hashStr,
   				filename,
   			}),
   		});

   		const ingestData = await ingestResponse.json();
   		console.log("Ingestion Response:", ingestData);

   		// 4. Polling
   		await pollImport(ingestData.result.at_bookmark);

   		return "Import completed successfully";
   	} catch (e) {
   		console.error("Error:", e);
   		return "Import failed";
   	}
   }
   ```

   In the above code:

   - An `md5` hash of the SQL command is generated.
   - `initResponse` initializes the upload process and receives the upload URL.
   - `r2Response` uploads the SQL command to the upload URL.
   - Before starting ingestion, the ETag is verified.
   - `ingestResponse` starts the ingestion process.
   - `pollImport` polls the import process until it completes.

2. Add the `pollImport` function to the `index.js` file.

   ```js title="index.js"
   async function pollImport(bookmark) {
   	const payload = {
   		action: "poll",
   		current_bookmark: bookmark,
   	};

   	while (true) {
   		const pollResponse = await fetch(D1_URL, {
   			method: "POST",
   			headers,
   			body: JSON.stringify(payload),
   		});

   		const result = await pollResponse.json();
   		console.log("Poll Response:", result.result);

   		const { success, error } = result.result;

   		if (
   			success ||
   			(!success && error === "Not currently importing anything.")
   		) {
   			break;
   		}

   		await new Promise((resolve) => setTimeout(resolve, 1000));
   	}
   }
   ```

   The code above does the following:

   - Sends a `poll` action to the D1 API.
   - Polls the import process until it completes.

3. Finally, add the `runImport` function to the `index.js` file to run the import process.

   ```js title="index.js"
   async function runImport() {
   	const result = await uploadToD1();
   	console.log(result);
   }

   runImport();
   ```

</Steps>

## 7. Write the final code

In the previous steps, you have created functions to execute various processes involved in importing data into D1. The final code executes those functions to import the example data into the target D1 table.

<Steps>

1. Copy the final code of your `index.js` file as shown below, with your variables defined at the top of the code.

   ```js
   import crypto from "crypto";
   import { faker } from "@faker-js/faker";

   const TARGET_TABLE = "";
   const ACCOUNT_ID = "";
   const DATABASE_ID = "";
   const D1_API_KEY = "";
   const D1_URL = `https://api.cloudflare.com/client/v4/accounts/${ACCOUNT_ID}/d1/database/${DATABASE_ID}/import`;
   const uploadSize = 500;
   const headers = {
   	"Content-Type": "application/json",
   	Authorization: `Bearer ${D1_API_KEY}`,
   };

   // Generate Fake data
   const data = Array.from({ length: uploadSize }, () => ({
   	id: Math.floor(Math.random() * 1000000),
   	text: faker.lorem.paragraph(),
   	date_added: new Date().toISOString().slice(0, 19).replace("T", " "),
   }));

   // Make SQL insert statements
   function makeSqlInsert(data, tableName, skipCols = []) {
   	const columns = Object.keys(data[0]).join(",");
   	const values = data
   		.map((row) => {
   			return (
   				"(" +
   				Object.values(row)
   					.map((val) => {
   						if (skipCols.includes(val) || val === null || val === "") {
   							return "NULL";
   						}
   						return `'${String(val).replace(/'/g, "").replace(/"/g, "'")}'`;
   					})
   					.join(",") +
   				")"
   			);
   		})
   		.join(",");

   	return `INSERT INTO ${tableName} (${columns}) VALUES ${values};`;
   }

   const sqlInsert = makeSqlInsert(data, TARGET_TABLE);

   async function pollImport(bookmark) {
   	const payload = {
   		action: "poll",
   		current_bookmark: bookmark,
   	};

   	while (true) {
   		const pollResponse = await fetch(D1_URL, {
   			method: "POST",
   			headers,
   			body: JSON.stringify(payload),
   		});

   		const result = await pollResponse.json();
   		console.log("Poll Response:", result.result);

   		const { success, error } = result.result;

   		if (
   			success ||
   			(!success && error === "Not currently importing anything.")
   		) {
   			break;
   		}

   		await new Promise((resolve) => setTimeout(resolve, 1000));
   	}
   }

   // Upload to D1
   async function uploadToD1() {
   	// 1. Init upload
   	const hashStr = crypto.createHash("md5").update(sqlInsert).digest("hex");

   	try {
   		const initResponse = await fetch(D1_URL, {
   			method: "POST",
   			headers,
   			body: JSON.stringify({
   				action: "init",
   				etag: hashStr,
   			}),
   		});

   		const uploadData = await initResponse.json();
   		const uploadUrl = uploadData.result.upload_url;
   		const filename = uploadData.result.filename;

   		// 2. Upload to R2
   		const r2Response = await fetch(uploadUrl, {
   			method: "PUT",
   			body: sqlInsert,
   		});

   		const r2Etag = r2Response.headers.get("ETag").replace(/"/g, "");

   		// Verify etag
   		if (r2Etag !== hashStr) {
   			throw new Error("ETag mismatch");
   		}

   		// 3. Start ingestion
   		const ingestResponse = await fetch(D1_URL, {
   			method: "POST",
   			headers,
   			body: JSON.stringify({
   				action: "ingest",
   				etag: hashStr,
   				filename,
   			}),
   		});

   		const ingestData = await ingestResponse.json();
   		console.log("Ingestion Response:", ingestData);

   		// 4. Polling
   		await pollImport(ingestData.result.at_bookmark);

   		return "Import completed successfully";
   	} catch (e) {
   		console.error("Error:", e);
   		return "Import failed";
   	}
   }

   async function runImport() {
   	const result = await uploadToD1();
   	console.log(result);
   }

   runImport();
   ```

</Steps>

## 8. Run the code

<Steps>

1. Run your code.

   ```sh
   node index.js
   ```

</Steps>

You will now see your target D1 table populated with the example data.

:::note
If you encounter the `statement too long` error, you would need to break your SQL command into smaller chunks and upload them in batches. You can learn more about this error in the [D1 documentation](/d1/best-practices/import-export-data/#resolve-statement-too-long-error).
:::

## Summary

By completing this tutorial, you have

1. Created an API token.
2. Created a target database and table.
3. Generated example data.
4. Created SQL command for the example data.
5. Imported your example data into the D1 target table using REST API.

---

# Using D1 Read Replication for your e-commerce website

URL: https://developers.cloudflare.com/d1/tutorials/using-read-replication-for-e-com/

import {
	Render,
	Steps,
	PackageManagers,
	WranglerConfig,
	Details,
} from "~/components";

[D1 Read Replication](/d1/best-practices/read-replication/) is a feature that allows you to replicate your D1 database to multiple regions. This is useful for your e-commerce website, as it reduces read latencies and improves read throughput. In this tutorial, you will learn how to use D1 read replication for your e-commerce website.

While this tutorial uses a fictional e-commerce website, the principles can be applied to any use-case that requires low read latencies and scaling reads, such as a news website, a social media platform, or a marketing website.

## Quick start

If you want to skip the steps and get started quickly, click on the below button:

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/harshil1712/e-com-d1-hono)

This will create a repository in your GitHub account and deploy the application to Cloudflare Workers. It will also create and bind a D1 database, create the required tables, add some sample data. During deployment, tick the `Enable read replication` box to activate read replication.

You can then visit the deployed application.

## Prerequisites

<Render file="prereqs" product="workers" />

## Step 1: Create a Workers project

Create a new Workers project by running the following command:

<PackageManagers type="create" pkg="cloudflare@latest" args={"fast-commerce"} />

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "SSR / full-stack app",
		lang: "TypeScript",
	}}
/>

For creating the API routes, you will use [Hono](https://hono.dev/). You need to install Hono by running the following command:

<PackageManagers pkg="hono" />

## Step 2: Update the frontend

The above step creates a new Workers project with a default frontend and installs Hono. You will update the frontend to list the products. You will also add a new page to the frontend to display a single product.

Navigate to the newly created Worker project folder.

```sh
cd fast-commerce
```

Update the `public/index.html` file to list the products. Use the below code as a reference.

<Details open={false} header="public/index.html">
```html
<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<title>E-commerce Store</title>
		<style>
			* {
				margin: 0;
				padding: 0;
				box-sizing: border-box;
				font-family: Arial, sans-serif;
			}

    		body {
    			background-color: #f9fafb;
    			min-height: 100vh;
    			display: flex;
    			flex-direction: column;
    		}

    		header {
    			background-color: white;
    			padding: 1rem 2rem;
    			display: flex;
    			justify-content: space-between;
    			align-items: center;
    			border-bottom: 1px solid #e5e7eb;
    		}

    		.store-title {
    			font-weight: bold;
    			font-size: 1.25rem;
    		}

    		.cart-button {
    			padding: 0.5rem 1rem;
    			cursor: pointer;
    			background: none;
    			border: none;
    		}

    		.products-grid {
    			display: grid;
    			grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
    			gap: 1.5rem;
    			padding: 2rem;
    		}

    		.product-card {
    			background-color: white;
    			border-radius: 0.5rem;
    			overflow: hidden;
    			box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
    		}

    		.product-info {
    			padding: 1rem;
    		}

    		.product-title {
    			font-size: 1.125rem;
    			font-weight: 600;
    			margin-bottom: 0.5rem;
    		}

    		.product-description {
    			color: #4b5563;
    			font-size: 0.875rem;
    			margin-bottom: 1rem;
    		}

    		.product-price {
    			font-size: 1.25rem;
    			font-weight: bold;
    			margin-bottom: 0.5rem;
    		}

    		.product-stock {
    			color: #4b5563;
    			font-size: 0.875rem;
    			margin-bottom: 1rem;
    		}

    		.view-details-btn {
    			display: block;
    			width: 100%;
    			padding: 0.5rem 0;
    			background-color: #2563eb;
    			color: white;
    			border: none;
    			border-radius: 0.375rem;
    			cursor: pointer;
    			text-align: center;
    			text-decoration: none;
    			font-size: 0.875rem;
    		}

    		.view-details-btn:hover {
    			background-color: #1d4ed8;
    		}

    		footer {
    			background-color: white;
    			padding: 1rem 2rem;
    			text-align: center;
    			border-top: 1px solid #e5e7eb;
    			color: #4b5563;
    			font-size: 0.875rem;
    		}

    		/* Basic Responsiveness */
    		@media (max-width: 768px) {
    			.products-grid {
    				grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
    			}
    		}

    		@media (max-width: 480px) {
    			.products-grid {
    				grid-template-columns: 1fr;
    			}
    		}
    	</style>
    </head>
    <body>
    	<header>
    		<h1 class="store-title">E-commerce Store</h1>
    		<button class="cart-button">Cart</button>
    	</header>

    	<main class="products-grid" id="products-container">
    		<!-- Products will be loaded here by JavaScript -->
    	</main>

    	<footer>
    		<p>© 2025 E-commerce Store. All rights reserved.</p>
    	</footer>

    	<script>
    		document.addEventListener('DOMContentLoaded', () => {
    			let products = [];
    			let d1Duration,
    				queryDuration = 0;
    			let dbLocation;
    			let isPrimary = true;

    			// Function to create product HTML
    			function createProductCard(product) {
    				return `
                <div class="product-card" data-category="${product.category}">
                    <div class="product-info">
                        <h3 class="product-title">${product.name}</h3>
                        <p class="product-description">${product.description}</p>
                        <p class="product-price">$${product.price.toFixed(2)}</p>
                        <p class="product-stock">${product.inventory} in stock</p>
                        <a href="product-details.html?id=${product.id}" class="view-details-btn">View Details</a>
                    </div>
                </div>
            `;
    			}

    			// Function to render content
    			function renderContent() {
    				try {
    					const productsContainer = document.getElementById('products-container');
    					if (!productsContainer) return;
    					productsContainer.innerHTML = '';

    					products.forEach((product) => {
    						productsContainer.innerHTML += createProductCard(product);
    					});
    				} catch (error) {
    					console.error('Error rendering content:', error);
    				}
    			}

    			// Fetch products
    			fetch('/api/products')
    				.then((response) => response.json())
    				.then((data) => {
    					products = data;
    					renderContent();
    				})
    				.catch((error) => console.error('Error fetching products:', error));
    		});
    	</script>
    </body>

</html>
```
</Details>

Create a new `public/product-details.html` file to display a single product.

<Details open={false} header="public/product-details.html">

```html
<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<title>Product Details - E-commerce Store</title>
		<style>
			* {
				margin: 0;
				padding: 0;
				box-sizing: border-box;
				font-family: Arial, sans-serif;
			}

			body {
				background-color: #f9fafb;
				min-height: 100vh;
				display: flex;
				flex-direction: column;
			}

			header {
				background-color: white;
				padding: 1rem 2rem;
				display: flex;
				justify-content: space-between;
				align-items: center;
				border-bottom: 1px solid #e5e7eb;
			}

			.store-title {
				font-weight: bold;
				font-size: 1.25rem;
				text-decoration: none;
				color: black;
			}

			.cart-button {
				padding: 0.5rem 1rem;
				cursor: pointer;
				background: none;
				border: none;
			}

			.product-container {
				max-width: 800px;
				margin: 2rem auto;
				background-color: white;
				border-radius: 0.5rem;
				box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
				padding: 2rem;
			}

			.product-title {
				font-size: 1.875rem;
				font-weight: bold;
				margin-bottom: 0.5rem;
			}

			.product-description {
				color: #4b5563;
				margin-bottom: 1.5rem;
			}

			.product-price {
				font-size: 1.875rem;
				font-weight: bold;
				margin-bottom: 0.5rem;
			}

			.product-stock {
				font-size: 0.875rem;
				color: #4b5563;
				text-align: right;
			}

			.add-to-cart-btn {
				display: block;
				width: 100%;
				padding: 0.75rem;
				background-color: #2563eb;
				color: white;
				border: none;
				border-radius: 0.375rem;
				cursor: pointer;
				text-align: center;
				font-size: 1rem;
				margin-top: 1.5rem;
			}

			.add-to-cart-btn:hover {
				background-color: #1d4ed8;
			}

			.price-stock-container {
				display: flex;
				justify-content: space-between;
				align-items: center;
				margin-bottom: 1rem;
			}

			footer {
				background-color: white;
				padding: 1rem 2rem;
				text-align: center;
				border-top: 1px solid #e5e7eb;
				color: #4b5563;
				font-size: 0.875rem;
				margin-top: auto;
			}

			/* Back button */
			.back-button {
				display: inline-block;
				margin-bottom: 1.5rem;
				color: #2563eb;
				text-decoration: none;
				font-size: 0.875rem;
			}

			.back-button:hover {
				text-decoration: underline;
			}

			/* Notification */
			.notification {
				position: fixed;
				top: 1rem;
				right: 1rem;
				background-color: #10b981;
				color: white;
				padding: 0.75rem 1rem;
				border-radius: 0.375rem;
				box-shadow: 0 2px 5px rgba(0, 0, 0, 0.2);
				transform: translateX(150%);
				transition: transform 0.3s ease;
			}

			.notification.show {
				transform: translateX(0);
			}
		</style>
	</head>
	<body>
		<header>
			<a href="index.html" class="store-title">E-commerce Store</a>
			<button class="cart-button">Cart</button>
		</header>

		<main class="product-container">
			<a href="index.html" class="back-button">← Back to products</a>
			<h1 class="product-title" id="product-title">Product Name</h1>
			<p class="product-description" id="product-description">
				Product description goes here.
			</p>

			<div class="price-stock-container">
				<p class="product-price" id="product-price">$0.00</p>
				<p class="product-stock" id="product-stock">0 in stock</p>
			</div>

			<button class="add-to-cart-btn" id="add-to-cart">Add to Cart</button>
		</main>

		<div class="notification" id="notification">Added to cart!</div>

		<footer>
			<p>© 2025 E-commerce Store. All rights reserved.</p>
		</footer>

		<script>
			// Get query parameter from URL
			const url = new URL(window.location.href);
			const searchParams = new URLSearchParams(url.search);
			const productId = searchParams.get("id");

			// Fetch product details
			fetch(`/api/products/${productId}`)
				.then((response) => response.json())
				.then((product) => displayContent(product))
				.catch((error) =>
					console.error("Error fetching product details:", error),
				);

			// Function to display product details
			function displayContent(product) {
				document.title = `${product[0].name} - E-commerce Store`;
				document.getElementById("product-title").textContent = product[0].name;
				document.getElementById("product-description").textContent =
					product[0].description;
				document.getElementById("product-price").textContent =
					`$${product[0].price.toFixed(2)}`;
				document.getElementById("product-stock").textContent =
					`${product[0].inventory} in stock`;
			}
		</script>
	</body>
</html>
```

</Details>

You now have a frontend that lists products and displays a single product. However, the frontend is not yet connected to the D1 database. If you start the development server now, you will see no products. In the next steps, you will create a D1 database and create APIs to fetch products and display them on the frontend.

## Step 3: Create a D1 database and enable read replication

Create a new D1 database by running the following command:

```sh
npx wrangler d1 create fast-commerce
```

Add the D1 bindings returned in the terminal to the `wrangler` file:

<WranglerConfig>

```toml
[[d1_databases]]
binding = "DB"
database_name = "fast-commerce"
database_id = "YOUR_DATABASE_ID"
```

</WranglerConfig>

Run the following command to update the `Env` interface in the `worker-congifuration.d.ts` file.

```sh
npm run cf-typegen
```

Next, enable read replication for the D1 database. Navigate to [**Workers & Pages** > **D1**](https://dash.cloudflare.com/?to=/:account/workers/d1), then select an existing database > **Settings** > **Enable Read Replication**.

## Step 4: Create the API routes

Update the `src/index.ts` file to import the Hono library and create the API routes.

```ts
import { Hono } from "hono";
// Set db session bookmark in the cookie
import { getCookie, setCookie } from "hono/cookie";

const app = new Hono<{ Bindings: Env }>();

// Get all products
app.get("/api/products", async (c) => {
	return c.json({ message: "get list of products" });
});

// Get a single product
app.get("/api/products/:id", async (c) => {
	return c.json({ message: "get a single product" });
});

// Upsert a product
app.post("/api/product", async (c) => {
	return c.json({ message: "create or update a product" });
});

export default app;
```

The above code creates three API routes:

- `GET /api/products`: Returns a list of products.
- `GET /api/products/:id`: Returns a single product.
- `POST /api/product`: Creates or updates a product.

However, the API routes are not connected to the D1 database yet. In the next steps, you will create a products table in the D1 database, and update the API routes to connect to the D1 database.

## Step 5: Create local D1 database schema

Create a products table in the D1 database by running the following command:

```sh
npx wrangler d1 execute fast-commerce --command "CREATE TABLE IF NOT EXISTS products (id INTEGER PRIMARY KEY, name TEXT NOT NULL, description TEXT, price DECIMAL(10, 2) NOT NULL, inventory INTEGER NOT NULL DEFAULT 0, category TEXT NOT NULL, created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, last_updated TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP)"
```

Next, create an index on the products table by running the following command:

```sh
npx wrangler d1 execute fast-commerce --command "CREATE INDEX IF NOT EXISTS idx_products_id ON products (id)"
```

For development purposes, you can also execute the insert statements on the local D1 database by running the following command:

```sh
npx wrangler d1 execute fast-commerce --command "INSERT INTO products (id, name, description, price, inventory, category) VALUES (1, 'Fast Ergonomic Chair', 'A comfortable chair for your home or office', 100.00, 10, 'Furniture'), (2, 'Fast Organic Cotton T-shirt', 'A comfortable t-shirt for your home or office', 20.00, 100, 'Clothing'), (3, 'Fast Wooden Desk', 'A wooden desk for your home or office', 150.00, 5, 'Furniture'), (4, 'Fast Leather Sofa', 'A leather sofa for your home or office', 300.00, 3, 'Furniture'), (5, 'Fast Organic Cotton T-shirt', 'A comfortable t-shirt for your home or office', 20.00, 100, 'Clothing')"
```

## Step 6: Add retry logic

To make the application more resilient, you can add retry logic to the API routes. Create a new file called `retry.ts` in the `src` directory.

```ts
export interface RetryConfig {
	maxRetries: number;
	initialDelay: number;
	maxDelay: number;
	backoffFactor: number;
}

const shouldRetry = (error: unknown): boolean => {
	const errMsg = error instanceof Error ? error.message : String(error);
	return (
		errMsg.includes("Network connection lost") ||
		errMsg.includes("storage caused object to be reset") ||
		errMsg.includes("reset because its code was updated")
	);
};

// Helper function for sleeping
const sleep = (ms: number): Promise<void> => {
	return new Promise((resolve) => setTimeout(resolve, ms));
};

export const defaultRetryConfig: RetryConfig = {
	maxRetries: 3,
	initialDelay: 100,
	maxDelay: 1000,
	backoffFactor: 2,
};

export async function withRetry<T>(
	operation: () => Promise<T>,
	config: Partial<RetryConfig> = defaultRetryConfig,
): Promise<T> {
	const maxRetries = config.maxRetries ?? defaultRetryConfig.maxRetries;
	const initialDelay = config.initialDelay ?? defaultRetryConfig.initialDelay;
	const maxDelay = config.maxDelay ?? defaultRetryConfig.maxDelay;
	const backoffFactor =
		config.backoffFactor ?? defaultRetryConfig.backoffFactor;

	let lastError: Error | unknown;
	let delay = initialDelay;

	for (let attempt = 0; attempt <= maxRetries; attempt++) {
		try {
			const result = await operation();
			return result;
		} catch (error) {
			lastError = error;

			if (!shouldRetry(error) || attempt === maxRetries) {
				throw error;
			}

			// Add randomness to avoid synchronizing retries
			// Wait for a random delay between delay and delay*2
			await sleep(delay * (1 + Math.random()));

			// Calculate next delay with exponential backoff
			delay = Math.min(delay * backoffFactor, maxDelay);
		}
	}

	throw lastError;
}
```

The `withRetry` function is a utility function that retries a given operation with exponential backoff. It takes a configuration object as an argument, which allows you to customize the number of retries, initial delay, maximum delay, and backoff factor. It will only retry the operation if the error is due to a network connection loss, storage reset, or code update.

:::caution

In a distrubed system, retry mechanisms can have certain risks. Read the article [Retry Strategies in Distributed Systems: Identifying and Addressing Key Pitfalls](https://www.computer.org/publications/tech-news/trends/retry-strategies-avoiding-pitfalls) to learn more about the risks of retry mechanisms and how to avoid them.

Retries can sometimes lead to data inconsistency. Make sure to handle the retry logic carefully.

:::

Next, update the `src/index.ts` file to import the `withRetry` function and use it in the API routes.

```ts
import { withRetry } from "./retry";
```

## Step 7: Update the API routes

Update the API routes to connect to the D1 database.

### 1. POST /api/product

```ts
app.post("/api/product", async (c) => {
	const product = await c.req.json();

	if (!product) {
		return c.json({ message: "No data passed" }, 400);
	}

	const db = c.env.DB;
	const session = db.withSession("first-primary");

	const { id } = product;

	try {
		return await withRetry(async () => {
			// Check if the product exists
			const { results } = await session
				.prepare("SELECT * FROM products where id = ?")
				.bind(id)
				.run();
			if (results.length === 0) {
				const fields = [...Object.keys(product)];
				const values = [...Object.values(product)];
				// Insert the product
				await session
					.prepare(
						`INSERT INTO products (${fields.join(", ")}) VALUES (${fields.map(() => "?").join(", ")})`,
					)
					.bind(...values)
					.run();
				const latestBookmark = session.getBookmark();
				latestBookmark &&
					setCookie(c, "product_bookmark", latestBookmark, {
						maxAge: 60 * 60, // 1 hour
					});
				return c.json({ message: "Product inserted" });
			}

			// Update the product
			const updates = Object.entries(product)
				.filter(([_, value]) => value !== undefined)
				.map(([key, _]) => `${key} = ?`)
				.join(", ");

			if (!updates) {
				throw new Error("No valid fields to update");
			}

			const values = Object.entries(product)
				.filter(([_, value]) => value !== undefined)
				.map(([_, value]) => value);

			await session
				.prepare(`UPDATE products SET ${updates} WHERE id = ?`)
				.bind(...[...values, id])
				.run();
			const latestBookmark = session.getBookmark();
			latestBookmark &&
				setCookie(c, "product_bookmark", latestBookmark, {
					maxAge: 60 * 60, // 1 hour
				});
			return c.json({ message: "Product updated" });
		});
	} catch (e) {
		console.error(e);
		return c.json({ message: "Error upserting product" }, 500);
	}
});
```

In the above code:

- You get the product data from the request body.
- You then check if the product exists in the database.
  - If it does, you update the product.
  - If it doesn't, you insert the product.
- You then set the bookmark in the cookie.
- Finally, you return the response.

Since you want to start the session with the latest data, you use the `first-primary` constraint. Even if you use the `first-unconstrained` constraint or pass a bookmark, the write request will always be routed to the primary database.

The bookmark set in the cookie can be used to guarantee that a new session reads a database version that is at least as up-to-date as the provided bookmark.

If you are using an external platform to manage your products, you can connect this API to the external platform, such that, when a product is created or updated in the external platform, the D1 database automatically updates the product details.

### 2. GET /api/products

```ts
app.get("/api/products", async (c) => {
	const db = c.env.DB;

	// Get bookmark from the cookie
	const bookmark = getCookie(c, "product_bookmark") || "first-unconstrained";

	const session = db.withSession(bookmark);

	try {
		return await withRetry(async () => {
			const { results } = await session.prepare("SELECT * FROM products").all();

			const latestBookmark = session.getBookmark();

			// Set the bookmark in the cookie
			latestBookmark &&
				setCookie(c, "product_bookmark", latestBookmark, {
					maxAge: 60 * 60, // 1 hour
				});

			return c.json(results);
		});
	} catch (e) {
		console.error(e);
		return c.json([]);
	}
});
```

In the above code:

- You get the database session bookmark from the cookie.
  - If the bookmark is not set, you use the `first-unconstrained` constraint.
- You then create a database session with the bookmark.
- You fetch all the products from the database and get the latest bookmark.
- You then set this bookmark in the cookie.
- Finally, you return the results.

### 3. GET /api/products/:id

```ts
app.get("/api/products/:id", async (c) => {
	const id = c.req.param("id");

	if (!id) {
		return c.json({ message: "Invalid id" }, 400);
	}

	const db = c.env.DB;

	// Get bookmark from the cookie
	const bookmark = getCookie(c, "product_bookmark") || "first-unconstrained";

	const session = db.withSession(bookmark);

	try {
		return await withRetry(async () => {
			const { results } = await session
				.prepare("SELECT * FROM products where id = ?")
				.bind(id)
				.run();

			const latestBookmark = session.getBookmark();

			// Set the bookmark in the cookie
			latestBookmark &&
				setCookie(c, "product_bookmark", latestBookmark, {
					maxAge: 60 * 60, // 1 hour
				});

			console.log(results);

			return c.json(results);
		});
	} catch (e) {
		console.error(e);
		return c.json([]);
	}
});
```

In the above code:

- You get the product ID from the request parameters.
- You then create a database session with the bookmark.
- You fetch the product from the database and get the latest bookmark.
- You then set this bookmark in the cookie.
- Finally, you return the results.

## Step 8: Test the application

You have now updated the API routes to connect to the D1 database. You can now test the application by starting the development server and navigating to the frontend.

```sh
npm run dev
```

Navigate to `http://localhost:8787. You should see the products listed. Click on a product to view the product details.

To insert a new product, use the following command (while the development server is running):

```sh
curl -X POST http://localhost:8787/api/product \
     -H "Content-Type: application/json" \
     -d '{"id": 6, "name": "Fast Computer", "description": "A computer for your home or office", "price": 1000.00, "inventory": 10, "category": "Electronics"}'
```

Navigate to `http://localhost:8787/product-details?id=6`. You should see the new product.

Update the product using the following command, and navigate to `http://localhost:8787/product-details?id=6` again. You will see the updated product.

```sh
curl -X POST http://localhost:8787/api/product \
     -H "Content-Type: application/json" \
     -d '{"id": 6, "name": "Fast Computer", "description": "A computer for your home or office", "price": 1050.00, "inventory": 10, "category": "Electronics"}'
```

:::note
Read replication is only used when the application has been [deployed](/d1/tutorials/using-read-replication-for-e-com/#step-9-deploy-the-application). D1 does not create read replicas when you develop locally. To test it locally, you can start the development server with the `--remote` flag.
:::

## Step 9: Deploy the application

Since the database you used in the previous steps is local, you need to create the products table in the remote database. Execute the following D1 commands to create the products table in the remote database.

```sh
npx wrangler d1 execute fast-commerce --remote --command "CREATE TABLE IF NOT EXISTS products (id INTEGER PRIMARY KEY, name TEXT NOT NULL, description TEXT, price DECIMAL(10, 2) NOT NULL, inventory INTEGER NOT NULL DEFAULT 0, category TEXT NOT NULL, created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, last_updated TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP)"
```

Next, create an index on the products table by running the following command:

```sh
npx wrangler d1 execute fast-commerce --remote --command "CREATE INDEX IF NOT EXISTS idx_products_id ON products (id)"
```

Optionally, you can insert the products into the remote database by running the following command:

```sh
npx wrangler d1 execute fast-commerce --remote --command "INSERT INTO products (id, name, description, price, inventory, category) VALUES (1, 'Fast Ergonomic Chair', 'A comfortable chair for your home or office', 100.00, 10, 'Furniture'), (2, 'Fast Organic Cotton T-shirt', 'A comfortable t-shirt for your home or office', 20.00, 100, 'Clothing'), (3, 'Fast Wooden Desk', 'A wooden desk for your home or office', 150.00, 5, 'Furniture'), (4, 'Fast Leather Sofa', 'A leather sofa for your home or office', 300.00, 3, 'Furniture'), (5, 'Fast Organic Cotton T-shirt', 'A comfortable t-shirt for your home or office', 20.00, 100, 'Clothing')"
```

Now, you can deploy the application with the following command:

```sh
npm run deploy
```

This will deploy the application to Workers and the D1 database will be replicated to the remote regions. If a user requests the application from any region, the request will be redirected to the nearest region where the database is replicated.

## Conclusion

In this tutorial, you learned how to use D1 Read Replication for your e-commerce website. You created a D1 database and enabled read replication for it. You then created an API to create and update products in the database. You also learned how to use the bookmark to get the latest data from the database.

You then created the products table in the remote database and deployed the application.

You can use the same approach for your existing read heavy application to reduce read latencies and improve read throughput. If you are using an external platform to manage the content, you can connect the external platform to the D1 database, so that the content is automatically updated in the database.

You can find the complete code for this tutorial in the [GitHub repository](https://github.com/harshil1712/e-com-d1-hono).

---

# Create custom hostnames

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/create-custom-hostnames/

import { Render, TabItem, Tabs } from "~/components";

There are several required steps before a custom hostname can become active. For more details, refer to our [Get started guide](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/).

To create a custom hostname:

<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">

<Render file="create-custom-hostname" />

<Render file="create-custom-hostname-limitations" />

</TabItem> <TabItem label="API">

<Render file="create-custom-hostname-api" />

<Render file="create-custom-hostname-limitations" />

</TabItem> </Tabs>

<Render file="issue-certs-preamble" />


## Hostnames over 64 characters

The Common Name (CN) restriction establishes a limit of 64 characters ([RFC 5280](https://www.rfc-editor.org/rfc/rfc5280.html)). If you have a hostname that exceeds this length, you can set `cloudflare_branding` to `true` when creating your custom hostnames [via API](/api/resources/custom_hostnames/methods/create/).

```txt

"ssl": {
    "cloudflare_branding": true
  }

```

Cloudflare branding means that `sni.cloudflaressl.com` will be added as the certificate Common Name (CN) and the long hostname will be included as a part of the Subject Alternative Name (SAN).

---

# Custom metadata

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/custom-metadata/

import { Render, APIRequest } from "~/components";

You may wish to configure per-hostname (customer) settings beyond the scale of Page Rules or Rate Limiting, which have a maximum of 125 rules each.

To do this, you will first need to reach out to your account team to enable access to Custom Metadata. After configuring custom metadata, you can use it in the following ways:

- Read the metadata JSON from [Cloudflare Workers](/workers/) (requires access to Workers) to define per-hostname behavior.
- Use custom metadata values in [rule expressions](/ruleset-engine/rules-language/expressions/) of different Cloudflare security products to define the rule scope.

<Render file="ssl-for-saas-plan-limitation" />

---

## Examples

- Per-customer URL rewriting — for example, customers 1-10,000 fetch assets from server A, 10,001-20,000 from server B, etc.
- Adding custom headers — for example, `X-Customer-ID: $number` based on the metadata you provided
- Setting HTTP Strict Transport Security (“HSTS”) headers on a per-customer basis

Please speak with your Solutions Engineer to discuss additional logic and requirements.

## Submitting custom metadata

You may add custom metadata to Cloudflare via the Custom Hostnames API. This data can be added via a [`PATCH` request](/api/resources/custom_hostnames/methods/edit/) to the specific hostname ID to set metadata for that hostname, for example:


<APIRequest
  path="/zones/{zone_id}/custom_hostnames/{custom_hostname_id}"
  method="PATCH"
  json={{
		"ssl": {
    "method": "http",
    "type": "dv"
  },
  "custom_metadata": {
    "customer_id": "12345",
    "redirect_to_https": true,
    "security_tag": "low"
  },
	}}
/>

Changes to metadata will propagate across Cloudflare's edge within 30 seconds.

---

## Accessing custom metadata from a Cloudflare Worker

The metadata object will be accessible on each request using the `request.cf.hostMetadata` property. You can then read the data, and customize any behavior on it using the Worker.

In the example below we will use the user_id in the Worker that was submitted using the API call above `"custom_metadata":{"customer_id":"12345","redirect_to_https": true,"security_tag":"low"}`, and set a request header to send the `customer_id` to the origin:

```js
export default {
  /**
   * Fetch and add a X-Customer-Id header to the origin based on hostname
   * @param {Request} request
   */
  async fetch(request, env, ctx): Promise<Response> {
    const customer_id = request.cf.hostMetadata.customer_id;
    const newHeaders = new Headers(request.headers);
    newHeaders.append('X-Customer-Id', customer_id);

    const init = {
      headers: newHeaders,
      method: request.method,
    };
    return fetch(request.url, init);
  },
} satisfies ExportedHandler<Env>;
```

## Accessing custom metadata in a rule expression

Use the [`cf.hostname.metadata`](/ruleset-engine/rules-language/fields/reference/cf.hostname.metadata/) field to access the metadata object in rule expressions. To obtain the different values from the JSON object, use the [`lookup_json_string`](/ruleset-engine/rules-language/functions/#lookup_json_string) function.

The following rule expression defines that there will be a rule match if the `security_tag` value in custom metadata contains the value `low`:

```txt
lookup_json_string(cf.hostname.metadata, "security_tag") eq "low"
```

---

## Best practices

- Ensure that the JSON schema used is fixed: changes to the schema without corresponding Cloudflare Workers changes will potentially break websites, or fall back to any defined “default” behavior
- Prefer a flat JSON structure
- Use string keys in snake_case (rather than camelCase or PascalCase)
- Use proper booleans (true/false rather than `true` or `1` or `0`)
- Use numbers to represent integers instead of strings (`1` or `2` instead of `"1"` or `"2"`)
- Define fallback behaviour in the non-presence of metadata
- Define fallback behaviour if a key or value in the metadata are unknown

General guidance is to follow [Google's JSON Style guide](https://google.github.io/styleguide/jsoncstyleguide.xml) where appropriate.

---

## Limitations

There are some limitations to the metadata that can be provided to Cloudflare:

- It must be valid JSON.
- Any origin resolution — for example, directing requests for a given hostname to a specific backend — must be provided as a hostname that exists within Cloudflare's DNS (even for non-authoritative setups). Providing an IP address directly will cause requests to error.
- The total payload must not exceed 4 KB.
- It requires a Cloudflare Worker that knows how to process the schema and trigger logic based on the contents.
- Custom metadata cannot be set on custom hostnames that contain wildcards.

:::note

Be careful when modifying the schema. Adding, removing, or changing keys and possible values may cause the Cloudflare Worker to either ignore the data or return an error for requests that trigger it.
:::

### Terraform support

[Terraform](/terraform/) only allows maps of a single type, so Cloudflare's Terraform support for custom metadata for custom hostnames is limited to string keys and values.

---

# Custom hostnames

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/

import { DirectoryListing } from "~/components";

Cloudflare for SaaS allows you, as a SaaS provider, to extend the benefits of Cloudflare products to custom domains by adding them to your zone as custom hostnames. We support adding hostnames that are a subdomain of your zone (for example, `sub.serviceprovider.com`) and vanity domains (for example, `customer.com`) to your SaaS zone.

## Resources

<DirectoryListing />

---

# Move hostnames

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/migrating-custom-hostnames/

As a SaaS provider, you may want, or have, multiple zones to manage hostnames. Each zone can have different configurations or origins, as well as correlate to varying products. You might shift custom hostnames between zones to enable or disable certain features. Cloudflare allows migration within the same account through the steps below:

***

## CNAME

If your custom hostname uses a CNAME record, add the custom hostname to the new zone and [update your DNS record](/dns/manage-dns-records/how-to/create-dns-records/#edit-dns-records) to point to the new zone.

:::note

If you would like to migrate the custom hostname without end customers changing the DNS target, use [apex proxying](/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/apex-proxying/).

:::

1. [Add custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/) to your new zone.

2. Direct your customer to [change the DNS record](/dns/manage-dns-records/how-to/create-dns-records/#edit-dns-records) so that it points to the new zone.

3. Confirm that the custom hostname has validated in the new zone.

4. Wait for the certificate to validate automatically through Cloudflare or [validate it using Domain Control Validation (DCV)](/ssl/edge-certificates/changing-dcv-method/methods/#perform-dcv).

5. Remove custom hostname from the old zone.

Once these steps are complete, the custom hostname's traffic will route to the second SaaS zone and will use its configuration.

## A record

Through [Apex Proxying](/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/apex-proxying/) or [BYOIP](/byoip/), you can migrate the custom hostname without action from your end customer.

1. Verify with the account team that your apex proxying IPs have been assigned to both SaaS zones.

2. [Add custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/) to the new zone.

3. Confirm that the custom hostname has validated in the new zone.

4. Wait for the certificate to validate automatically through Cloudflare or [validate it using DCV](/ssl/edge-certificates/changing-dcv-method/methods/#perform-dcv).

5. Remove custom hostname from the old zone.

:::note

The most recently edited custom hostname will be active. For instance, `example.com` exists on `SaaS Zone 1`. It is added to `SaaS Zone 2`. Because it was activated more recently on `SaaS Zone 2`, that is where it will be active. However, if edits are made to example.com on `SaaS Zone 1`, it will reactivate on that zone instead of `SaaS Zone 2`.

:::

## Wildcard certificate

If you are migrating custom hostnames that rely on a Wildcard certificate, Cloudflare cannot automatically complete Domain Control Validation (DCV).

1. [Add custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/) to the new zone.

2. Direct your customer to [change the DNS record](/dns/manage-dns-records/how-to/create-dns-records/#edit-dns-records) so that it points to the new zone.

3. [Validate the certificate](/ssl/edge-certificates/changing-dcv-method/methods/#perform-dcv) on the new zone through DCV.

The custom hostname can activate on the new zone even if the certificate is still active on the old zone. This ensures a valid certificate exists during migration. However, it is important to validate the certificate on the new zone as soon as possible.

:::note

Verify that the custom hostname successfully activated after the migration in the Cloudflare dashboard by selecting **SSL/TLS** > **Custom hostnames** > **`{your custom hostname}`**.

:::

---

# Remove custom hostnames

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/remove-custom-hostnames/

import { Render, TabItem, Tabs } from "~/components";

As a SaaS provider, your customers may decide to no longer participate in your service offering. If that happens, you need to stop routing traffic through those custom hostnames.

## Domains using Cloudflare

If your customer's domain is also using Cloudflare, they can stop routing their traffic through your custom hostname by updating their Cloudflare DNS.

If they update their [`CNAME` record](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/#3-have-customer-create-cname-record) so that it no longer points to your `CNAME` target:

- The domain's traffic will not route through your custom hostname.
- The custom hostname will enter into a **Moved** state.

If the custom hostname is in a **Moved** state for seven days, it will transition into a **Deleted** state.

## Domains not using Cloudflare

If your customer's domain is not using Cloudflare, you must remove a customer's custom hostname from your zone if they decide to churn.

This is especially important if your end customers are using Cloudflare because if the custom hostname changes the DNS target to point away from your SaaS zone, the custom hostname will continue to route to your service. This is a result of the [custom hostname priority logic](/ssl/reference/certificate-and-hostname-priority/#hostname-priority).

<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">

<Render file="delete-custom-hostname-dash" />

</TabItem> <TabItem label="API">

To delete a custom hostname and any issued certificates using the API, send a [`DELETE` request](/api/resources/custom_hostnames/methods/delete/).

</TabItem> </Tabs>

## For end customers

<Render file="saas-customer-churn" />

---

# Build a seat booking app with SQLite in Durable Objects

URL: https://developers.cloudflare.com/durable-objects/tutorials/build-a-seat-booking-app/

import { Render, PackageManagers, Details, WranglerConfig } from "~/components";

In this tutorial, you will learn how to build a seat reservation app using Durable Objects. This app will allow users to book a seat for a flight. The app will be written in TypeScript and will use the new [SQLite storage backend in Durable Object](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend) to store the data.

Using Durable Objects, you can write reusable code that can handle coordination and state management for multiple clients. Moreover, writing data to SQLite in Durable Objects is synchronous and uses local disks, therefore all queries are executed with great performance. You can learn more about SQLite storage in Durable Objects in the [SQLite in Durable Objects blog post](https://blog.cloudflare.com/sqlite-in-durable-objects).

:::note[SQLite in Durable Objects]

SQLite in Durable Objects is currently in beta. You can learn more about the limitations of SQLite in Durable Objects in the [SQLite in Durable Objects documentation](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend).

:::

The application will function as follows:

- A user navigates to the application with a flight number passed as a query parameter.
- The application will create a new Durable Object for the flight number, if it does not already exist.
- If the Durable Object already exists, the application will retrieve the seats information from the SQLite database.
- If the Durable Object does not exist, the application will create a new Durable Object and initialize the SQLite database with the seats information. For the purpose of this tutorial, the seats information is hard-coded in the application.
- When a user selects a seat, the application asks for their name. The application will then reserve the seat and store the name in the SQLite database.
- The application also broadcasts any changes to the seats to all clients.

Let's get started!

## Prerequisites

1. Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages).
2. Install [`Node.js`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).

<Details header="Node.js version manager">
	Use a Node version manager like [Volta](https://volta.sh/) or
	[nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change
	Node.js versions. [Wrangler](/workers/wrangler/install-and-update/), discussed
	later in this guide, requires a Node version of `16.17.0` or later.
</Details>

## 1. Create a new project

Create a new Worker project to create and deploy your app.

1.  Create a Worker named `seat-booking` by running:

    <PackageManagers
    	type="create"
    	pkg="cloudflare@latest"
    	args={"seat-booking"}
    />

    <Render
    	file="c3-post-run-steps"
    	product="workers"
    	params={{
    		category: "hello-world",
    		type: "Worker + Durable Objects",
    		lang: "TypeScript",
    	}}
    />

2.  Change into your new project directory to start developing:

```sh frame="none"
cd seat-booking
```

## 2. Create the frontend

The frontend of the application is a simple HTML page that allows users to select a seat and enter their name. The application uses [Workers Static Assets](/workers/static-assets/binding/) to serve the frontend.

1. Create a new directory named `public` in the project root.

2. Create a new file named `index.html` in the `public` directory.

3. Add the following HTML code to the `index.html` file:

<Details header="public/index.html">
```html title="public/index.html"
<!doctype html>
<html lang="en">
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
		<title>Flight Seat Booking</title>
		<style>
			body {
				font-family: Arial, sans-serif;
				display: flex;
				justify-content: center;
				align-items: center;
				height: 100vh;
				margin: 0;
				background-color: #f0f0f0;
			}
			.booking-container {
				background-color: white;
				padding: 20px;
				border-radius: 8px;
				box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
			}
			.seat-grid {
				display: grid;
				grid-template-columns: repeat(7, 1fr);
				gap: 10px;
				margin-top: 20px;
			}
			.aisle {
				grid-column: 4;
			}
			.seat {
				width: 40px;
				height: 40px;
				display: flex;
				justify-content: center;
				align-items: center;
				border: 1px solid #ccc;
				cursor: pointer;
			}
			.seat.available {
				background-color: #5dbf61ba;
				color: white;
			}
			.seat.unavailable {
				background-color: #f4433673;
				color: white;
				cursor: not-allowed;
			}
			.airplane {
				display: flex;
				flex-direction: column;
				align-items: center;
				background-color: #f0f0f0;
				padding: 20px;
				border-radius: 20px;
			}
		</style>
	</head>
	<body>
		<div class="booking-container">
			<h2 id="title"></h2>
			<div class="airplane">
				<div id="seatGrid" class="seat-grid"></div>
			</div>
		</div>

    	<script>
    		const seatGrid = document.getElementById("seatGrid");
    		const title = document.getElementById("title");

    		const flightId = window.location.search.split("=")[1];

        const hostname = window.location.hostname;

    		if (flightId === undefined) {
    			title.textContent = "No Flight ID provided";
    			seatGrid.innerHTML = "<p>Add `flightId` to the query string</p>";
    		} else {
    			handleBooking();
    		}

    		function handleBooking() {
    			let ws;
    			if (hostname === 'localhost') {
            const port = window.location.port;
    				ws = new WebSocket(`ws://${hostname}:${port}/ws?flightId=${flightId}`);
    			} else {
    				ws = new WebSocket(`wss://${hostname}/ws?flightId=${flightId}`);
    			}

    			title.textContent = `Book seat for flight ${flightId}`;

    			ws.onopen = () => {
    				console.log("Connected to WebSocket server");
    			};

    			function createSeatGrid(seats) {
    				seatGrid.innerHTML = "";
    				for (let row = 1; row <= 10; row++) {
    					for (let col = 0; col < 6; col++) {
    						if (col === 3) {
    							const aisle = document.createElement("div");
    							aisle.className = "aisle";
    							seatGrid.appendChild(aisle);
    						}

    						const seatNumber = `${row}${String.fromCharCode(65 + col)}`;
    						const seat = seats.find((s) => s.seatNumber === seatNumber);
    						const seatElement = document.createElement("div");
    						seatElement.className = `seat ${seat && seat.occupant ? "unavailable" : "available"}`;
    						seatElement.textContent = seatNumber;
    						seatElement.onclick = () => bookSeat(seatNumber);
    						seatGrid.appendChild(seatElement);
    					}
    				}
    			}

    			async function fetchSeats() {
    				const response = await fetch(`/seats?flightId=${flightId}`);
    				const seats = await response.json();
    				createSeatGrid(seats);
    			}

    			async function bookSeat(seatNumber) {
    				const name = prompt("Please enter your name:");
    				if (!name) {
    					return; // User canceled the prompt
    				}

    				const response = await fetch(`book-seat?flightId=${flightId}`, {
    					method: "POST",
    					headers: { "Content-Type": "application/json" },
    					body: JSON.stringify({ seatNumber, name }),
    				});
    				const result = await response.text();
    				fetchSeats();
    			}

    			ws.onmessage = (event) => {
    				try {
    					const seats = JSON.parse(event.data);
    					createSeatGrid(seats);
    				} catch (error) {
    					console.error("Error parsing WebSocket message:", error);
    				}
    			};

    			ws.onerror = (error) => {
    				console.error("WebSocket error:", error);
    			};

    			ws.onclose = (event) => {
    				console.log("WebSocket connection closed:", event);
    			};

    			fetchSeats();
    		}
    	</script>
    </body>

</html>
```

</Details>

- The frontend makes an HTTP `GET` request to the `/seats` endpoint to retrieve the available seats for the flight.
- It also uses a WebSocket connection to receive updates about the available seats.
- When a user clicks on a seat, the `bookSeat()` function is called that prompts the user to enter their name and then makes a `POST` request to the `/book-seat` endpoint.

4. Update the bindings in the [Wrangler configuration file](/workers/wrangler/configuration/) to configure `assets` to serve the `public` directory.

<WranglerConfig>

```toml
[assets]
directory = "public"
```

</WranglerConfig>

5. If you start the development server using the following command, the frontend will be served at `http://localhost:8787`. However, it will not work because the backend is not yet implemented.

```bash frame=none
npm run dev
```

:::note[Workers Static Assets]

[Workers Static Assets](/workers/static-assets/binding/) is currently in beta. You can also use Cloudflare Pages to serve the frontend. However, you will need a separate Worker for the backend.

:::

## 3. Create table for each flight

The application already has the binding for the Durable Objects class configured in the [Wrangler configuration file](/workers/wrangler/configuration/). If you update the name of the Durable Objects class in `src/index.ts`, make sure to also update the binding in the [Wrangler configuration file](/workers/wrangler/configuration/).

1. Update the binding to use the SQLite storage in Durable Objects. In the [Wrangler configuration file](/workers/wrangler/configuration/), replace `new_classes=["Flight"]` with `new_sqlite_classes=["Flight"]`, `name = "FLIGHT"` with `name = "FLIGHT"`, and `class_name = "MyDurableObject"` with `class_name = "Flight"`. your [Wrangler configuration file](/workers/wrangler/configuration/) should look similar to this:

<WranglerConfig>

```toml {9}
[[durable_objects.bindings]]
name = "FLIGHT"
class_name = "Flight"

# Durable Object migrations.
# Docs: https://developers.cloudflare.com/workers/wrangler/configuration/#migrations
[[migrations]]
tag = "v1"
new_sqlite_classes = ["Flight"]
```

</WranglerConfig>

Your application can now use the SQLite storage in Durable Objects.

2. Add the `initializeSeats()` function to the `Flight` class. This function will be called when the Durable Object is initialized. It will check if the table exists, and if not, it will create it. It will also insert seats information in the table.

For this tutorial, the function creates an identical seating plan for all the flights. However, in production, you would want to update this function to insert seats based on the flight type.

Replace the `Flight` class with the following code:

```ts title="src/index.ts"
import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
	sql = this.ctx.storage.sql;

	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		this.initializeSeats();
	}

	private initializeSeats() {
		const cursor = this.sql.exec(`PRAGMA table_list`);

		// Check if a table exists.
		if ([...cursor].find((t) => t.name === "seats")) {
			console.log("Table already exists");
			return;
		}

		this.sql.exec(`
				  CREATE TABLE IF NOT EXISTS seats (
					seatId TEXT PRIMARY KEY,
					occupant TEXT
				  )
				`);

		// For this demo, we populate the table with 60 seats.
		// Since SQLite in DOs is fast, we can do a query per INSERT instead of batching them in a transaction.
		for (let row = 1; row <= 10; row++) {
			for (let col = 0; col < 6; col++) {
				const seatNumber = `${row}${String.fromCharCode(65 + col)}`;
				this.sql.exec(`INSERT INTO seats VALUES (?, null)`, seatNumber);
			}
		}
	}
}
```

3. Add a `fetch` handler to the `Flight` class. This handler will return a text response. In [Step 5](#5-handle-websocket-connections) You will update the `fetch` handler to handle the WebSocket connection.

```ts title="src/index.ts" {3-5}
import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
  ...
  async fetch(request: Request): Promise<Response> {
    return new Response("Hello from Durable Object!", { status: 200 });
  }
}
```

4. Next, update the Worker's fetch handler to create a unique Durable Object for each flight.

```ts title="src/index.ts"
export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Get flight id from the query parameter
		const url = new URL(request.url);
		const flightId = url.searchParams.get("flightId");

		if (!flightId) {
			return new Response(
				"Flight ID not found. Provide flightId in the query parameter",
				{ status: 404 },
			);
		}

		const id = env.FLIGHT.idFromName(flightId);
		const stub = env.FLIGHT.get(id);
		return stub.fetch(request);
	},
} satisfies ExportedHandler<Env>;
```

Using the flight ID, from the query parameter, a unique Durable Object is created. This Durable Object is initialized with a table if it does not exist.

## 4. Add methods to the Durable Object

1. Add the `getSeats()` function to the `Flight` class. This function returns all the seats in the table.

```ts title="src/index.ts" {8-22}
import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
    ...

	private initializeSeats() {
		...
	}

	// Get all seats.
	getSeats() {
		let results = [];

		// Query returns a cursor.
		let cursor = this.sql.exec(`SELECT seatId, occupant FROM seats`);

		// Cursors are iterable.
		for (let row of cursor) {
			// Each row is an object with a property for each column.
			results.push({ seatNumber: row.seatId, occupant: row.occupant });
		}

		return results;
	}
}
```

2. Add the `assignSeat()` function to the `Flight` class. This function will assign a seat to a passenger. It takes the seat number and the passenger name as parameters.

```ts title="src/index.ts" {13-48}
import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
	...

	private initializeSeats() {
		...
	}

	// Get all seats.
	getSeats() {
		...
	}

	// Assign a seat to a passenger.
	assignSeat(seatId: string, occupant: string) {
		// Check that seat isn't occupied.
		let cursor = this.sql.exec(
			`SELECT occupant FROM seats WHERE seatId = ?`,
			seatId,
		);
		let result = cursor.toArray()[0]; // Get the first result from the cursor.

		if (!result) {
			return {message: 'Seat not available',  status: 400 };
		}
		if (result.occupant !== null) {
			return {message: 'Seat not available',  status: 400 };
		}

		// If the occupant is already in a different seat, remove them.
		this.sql.exec(
			`UPDATE seats SET occupant = null WHERE occupant = ?`,
			occupant,
		);

		// Assign the seat. Note: We don't have to worry that a concurrent request may
		// have grabbed the seat between the two queries, because the code is synchronous
		// (no `await`s) and the database is private to this Durable Object. Nothing else
		// could have changed since we checked that the seat was available earlier!
		this.sql.exec(
			`UPDATE seats SET occupant = ? WHERE seatId = ?`,
			occupant,
			seatId,
		);

		// Broadcast the updated seats.
		this.broadcastSeats();
		return {message: `Seat ${seatId} booked successfully`, status: 200 };
	}
}
```

The above function uses the `broadcastSeats()` function to broadcast the updated seats to all the connected clients. In the next section, we will add the `broadcastSeats()` function.

## 5. Handle WebSocket connections

All the clients will connect to the Durable Object using WebSockets. The Durable Object will broadcast the updated seats to all the connected clients. This allows the clients to update the UI in real time.

1. Add the `handleWebSocket()` function to the `Flight` class. This function handles the WebSocket connections.

```ts title="src/index.ts" {18-26}
import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
	...

	private initializeSeats() {
		...
	}

	// Get all seats.
	getSeats() {
		...
	}

	// Assign a seat to a passenger.
	assignSeat(seatId: string, occupant: string) {
		...
	}

  private handleWebSocket(request: Request) {
		console.log('WebSocket connection requested');
		const [client, server] = Object.values(new WebSocketPair());

		this.ctx.acceptWebSocket(server);
		console.log('WebSocket connection established');

		return new Response(null, { status: 101, webSocket: client });
	}
}
```

2. Add the `broadcastSeats()` function to the `Flight` class. This function will broadcast the updated seats to all the connected clients.

```ts title="src/index.ts" {22-24}
import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
	...

	private initializeSeats() {
		...
	}

	// Get all seats.
	getSeats() {
		...
	}

	// Assign a seat to a passenger.
	assignSeat(seatId: string, occupant: string) {
		...
	}

  private handleWebSocket(request: Request) {
		...
	}

  private broadcastSeats() {
		this.ctx.getWebSockets().forEach((ws) => ws.send(this.getSeats()));
	}
}
```

3. Next, update the `fetch` handler in the `Flight` class. This handler will handle all the incoming requests from the Worker and handle the WebSocket connections using the `handleWebSocket()` method.

```ts title="src/index.ts" {26-28}
import { DurableObject } from "cloudflare:workers";

export class Flight extends DurableObject {
	...

	private initializeSeats() {
		...
	}

	// Get all seats.
	getSeats() {
		...
	}

	// Assign a seat to a passenger.
	assignSeat(seatId: string, occupant: string) {
		...
	}

  private handleWebSocket(request: Request) {
		...
	}

  private broadcastSeats() {
		...
	}

  async fetch(request: Request) {
		return this.handleWebSocket(request);
	}
}
```

4. Finally, update the `fetch` handler of the Worker.

```ts title="src/index.ts" {8-23}
export default {
	...

	async fetch(request, env, ctx): Promise<Response> {
		// Get flight id from the query parameter
		...

		if (request.method === "GET" && url.pathname === "/seats") {
			return new Response(JSON.stringify(await stub.getSeats()), {
				headers: { 'Content-Type': 'application/json' },
			});
		} else if (request.method === "POST" && url.pathname === "/book-seat") {
			const { seatNumber, name } = (await request.json()) as {
				seatNumber: string;
				name: string;
			};
			const result = await stub.assignSeat(seatNumber, name);
			return new Response(JSON.stringify(result));
		} else if (request.headers.get("Upgrade") === "websocket") {
			return stub.fetch(request);
		}

		return new Response("Not found", { status: 404 });
	},
} satisfies ExportedHandler<Env>;
```

The `fetch` handler in the Worker now calls appropriate Durable Object function to handle the incoming request. If the request is a `GET` request to `/seats`, the Worker returns the seats from the Durable Object. If the request is a `POST` request to `/book-seat`, the Worker calls the `bookSeat` method of the Durable Object to assign the seat to the passenger. If the request is a WebSocket connection, the Durable Object handles the WebSocket connection.

## 6. Test the application

You can test the application locally by running the following command:

```sh frame="none"
npm run dev
```

This starts a local development server that runs the application. The application is served at `http://localhost:8787`.

Navigate to the application at `http://localhost:8787` in your browser. Since the flight ID is not specified, the application displays an error message.

Update the URL with the flight ID as `http://localhost:8787?flightId=1234`. The application displays the seats for the flight with the ID `1234`.

## 7. Deploy the application

To deploy the application, run the following command:

```sh frame="none"
npm run deploy
```

```sh output
 ⛅️ wrangler 3.78.8
-------------------

🌀 Building list of assets...
🌀 Starting asset upload...
🌀 Found 1 new or modified file to upload. Proceeding with upload...
+ /index.html
Uploaded 1 of 1 assets
✨ Success! Uploaded 1 file (1.93 sec)

Total Upload: 3.45 KiB / gzip: 1.39 KiB
Your worker has access to the following bindings:
- Durable Objects:
  - FLIGHT: Flight
Uploaded seat-book (12.12 sec)
Deployed seat-book triggers (5.54 sec)
  [DEPLOYED_APP_LINK]
Current Version ID: [BINDING_ID]
```

Navigate to the `[DEPLOYED_APP_LINK]` to see the application. Again, remember to pass the flight ID as a query string parameter.

## Summary

In this tutorial, you have:

- used the SQLite storage backend in Durable Objects to store the seats for a flight.
- created a Durable Object class to manage the seat booking.
- deployed the application to Cloudflare Workers!

The full code for this tutorial is available on [GitHub](https://github.com/harshil1712/seat-booking-app).

---

# Serve images

URL: https://developers.cloudflare.com/images/manage-images/serve-images/

import { DirectoryListing } from "~/components"

<DirectoryListing />

---

# Serve images from custom domains

URL: https://developers.cloudflare.com/images/manage-images/serve-images/serve-from-custom-domains/

Image delivery is supported from all customer domains under the same Cloudflare account. To serve images through custom domains, an image URL should be adjusted to the following format:

```txt
https://example.com/cdn-cgi/imagedelivery/<ACCOUNT_HASH>/<IMAGE_ID>/<VARIANT_NAME>
```

Example with a custom domain:

```txt
https://example.com/cdn-cgi/imagedelivery/ZWd9g1K7eljCn_KDTu_MWA/083eb7b2-5392-4565-b69e-aff66acddd00/public
```

In this example, `<ACCOUNT_HASH>`, `<IMAGE_ID>` and `<VARIANT_NAME>` are the same, but the hostname and prefix path is different:

- `example.com`: Cloudflare proxied domain under the same account as the Cloudflare Images.
- `/cdn-cgi/imagedelivery`: Path to trigger `cdn-cgi` image proxy.
- `ZWd9g1K7eljCn_KDTu_MWA`: The Images account hash. This can be found in the Cloudflare Images Dashboard.
- `083eb7b2-5392-4565-b69e-aff66acddd00`: The image ID.
- `public`: The variant name.

## Custom paths

By default, Images are served from the `/cdn-cgi/imagedelivery/` path. You can use Transform Rules to rewrite URLs and serve images from custom paths.

### Basic version

Free and Pro plans support string matching rules (including wildcard operations) that do not require regular expressions.

This example lets you rewrite a request from `example.com/images` to `example.com/cdn-cgi/imagedelivery/<ACCOUNT_HASH>`.

To create a rule:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account and website.
2. Go to **Rules** > **Overview**.
3. Next to **URL Rewrite Rules**, select **Create rule**.
4. Under **If incoming requests match**, select **Wildcard pattern** and enter the following **Request URL** (update with your own domain):

   ```txt
   https://example.com/images/*
   ```

5. Under **Then rewrite the path and/or query** > **Path**, enter the following values (using your account hash):

   - **Target path**: [`/`] `images/*`
   - **Rewrite to**: [`/`] `cdn-cgi/imagedelivery/<ACCOUNT_HASH>/${1}`

6. Select **Deploy** when you are done.

### Advanced version

:::note
This feature requires a Business or Enterprise plan to enable regular expressions in Transform Rules. Refer to Cloudflare [Transform Rules Availability](/rules/transform/#availability) for more information.
:::

This example lets you rewrite a request from `example.com/images/some-image-id/w100,h300` to `example.com/cdn-cgi/imagedelivery/<ACCOUNT_HASH>/some-image-id/width=100,height=300` and assumes Flexible variants feature is turned on.

To create a rule:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account and website.
2. Go to **Rules** > **Overview**.
3. Next to **URL Rewrite Rules**, select **Create rule**.
4. Under **If incoming requests match**, select **Custom filter expression** and then select **Edit expression**.
5. In the text field, enter `(http.request.uri.path matches "^/images/.*$")`.
6. Under **Path**, select **Rewrite to**.
7. Select _Dynamic_ and enter the following in the text field.

```txt
regex_replace(
  http.request.uri.path,
  "^/images/(.*)\\?w([0-9]+)&h([0-9]+)$",
  "/cdn-cgi/imagedelivery/<ACCOUNT_HASH>/${1}/width=${2},height=${3}"
)
```

## Limitations

When using a custom domain, it is not possible to directly set up WAF rules that act on requests hitting the `/cdn-cgi/imagedelivery/` path. If you need to set up WAF rules, you can use a Cloudflare Worker to access your images and a Route using your domain to execute the worker. For an example worker, refer to [Serve private images using signed URL tokens](/images/manage-images/serve-images/serve-private-images/).

---

# Serve private images

URL: https://developers.cloudflare.com/images/manage-images/serve-images/serve-private-images/

You can serve private images by using signed URL tokens. When an image requires a signed URL, the image cannot be accessed without a token unless it is being requested for a variant set to always allow public access.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
2. Select **Images** > **Keys**.
3. Copy your key and use it to generate an expiring tokenized URL.

:::note

Private images do not currently support custom paths.

:::

The example below uses a Worker that takes in a regular URL without a signed token and returns a tokenized URL that expires after one day. You can, however, set this expiration period to whatever you need, by changing the const `EXPIRATION` value.

```js
const KEY = 'YOUR_KEY_FROM_IMAGES_DASHBOARD';
const EXPIRATION = 60 * 60 * 24; // 1 day

const bufferToHex = buffer =>
  [...new Uint8Array(buffer)].map(x => x.toString(16).padStart(2, '0')).join('');

async function generateSignedUrl(url) {
  // `url` is a full imagedelivery.net URL
  // e.g. https://imagedelivery.net/cheeW4oKsx5ljh8e8BoL2A/bc27a117-9509-446b-8c69-c81bfeac0a01/mobile

  const encoder = new TextEncoder();
  const secretKeyData = encoder.encode(KEY);
  const key = await crypto.subtle.importKey(
    'raw',
    secretKeyData,
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );

  // Attach the expiration value to the `url`
  const expiry = Math.floor(Date.now() / 1000) + EXPIRATION;
  url.searchParams.set('exp', expiry);
  // `url` now looks like
  // https://imagedelivery.net/cheeW4oKsx5ljh8e8BoL2A/bc27a117-9509-446b-8c69-c81bfeac0a01/mobile?exp=1631289275

  const stringToSign = url.pathname + '?' + url.searchParams.toString();
  // for example, /cheeW4oKsx5ljh8e8BoL2A/bc27a117-9509-446b-8c69-c81bfeac0a01/mobile?exp=1631289275

  // Generate the signature
  const mac = await crypto.subtle.sign('HMAC', key, encoder.encode(stringToSign));
  const sig = bufferToHex(new Uint8Array(mac).buffer);

  // And attach it to the `url`
  url.searchParams.set('sig', sig);

  return new Response(url);
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const url = new URL(event.request.url);
    const imageDeliveryURL = new URL(
      url.pathname.slice(1).replace('https:/imagedelivery.net', 'https://imagedelivery.net')
    );
    return generateSignedUrl(imageDeliveryURL);
  },
} satisfies ExportedHandler<Env>;
```

---

# Serve uploaded images

URL: https://developers.cloudflare.com/images/manage-images/serve-images/serve-uploaded-images/

To serve images uploaded to Cloudflare Images, you must have:

* Your Images account hash
* Image ID
* Variant or flexible variant name

Assuming you have at least one image uploaded to Images, you will find the basic URL format from the Images dashboard under Developer Resources.

![Developer Resources section within the Images product form the Cloudflare Dashboard.](~/assets/images/images/image-delivery-url.png)

A typical image delivery URL looks similar to the example below.

`https://imagedelivery.net/<ACCOUNT_HASH>/<IMAGE_ID>/<VARIANT_NAME>`

In the example, you need to replace `<ACCOUNT_HASH>` with your Images account hash, along with the `<IMAGE_ID>` and `<VARIANT_NAME>`, to begin serving images.

You can select **Preview** next to the image you want to serve to preview the image with an Image URL you can copy. The link will have a fully formed **Images URL** and will look similar to the example below.

In this example:

* `ZWd9g1K7eljCn_KDTu_MWA` is the Images account hash.
* `083eb7b2-5392-4565-b69e-aff66acddd00` is the image ID. You can also use Custom IDs instead of the generated ID.
* `public` is the variant name.

When a user requests an image, Cloudflare Images chooses the optimal format, which is determined by client headers and the image type.

## Optimize format

Cloudflare Images automatically transcodes uploaded PNG, JPEG and GIF files to the more efficient AVIF and WebP formats. This happens whenever the customer browser supports them. If the browser does not support AVIF, Cloudflare Images will fall back to WebP. If there is no support for WebP, then Cloudflare Images will serve compressed files in the original format.

Uploaded SVG files are served as [sanitized SVGs](/images/upload-images/).

---

# Credentials

URL: https://developers.cloudflare.com/images/upload-images/sourcing-kit/credentials/

To migrate images from Amazon S3, Sourcing Kit requires access permissions to your bucket. While you can use any AWS Identity and Access Management (IAM) user credentials with the correct permissions to create a Sourcing Kit source, Cloudflare recommends that you create a user with a narrow set of permissions.

To create the correct Sourcing Kit permissions:

1. Log in to your AWS IAM account.

2. Create a policy with the following format (replace `<BUCKET_NAME>` with the bucket you want to grant access to):

   ```json
   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "s3:Get*",
                   "s3:List*"
               ],
               "Resource": [
                   "arn:aws:s3:::<BUCKET_NAME>",
                   "arn:aws:s3:::<BUCKET_NAME>/*"
               ]
           }
       ]
   }
   ```

3. Next, create a new user and attach the created policy to that user.

You can now use both the Access Key ID and Secret Access Key to create a new source in Sourcing Kit. Refer to [Enable Sourcing Kit](/images/upload-images/sourcing-kit/enable/) to learn more.

---

# Edit sources

URL: https://developers.cloudflare.com/images/upload-images/sourcing-kit/edit/

The Sourcing Kit main page has a list of all the import jobs and sources you have defined. This is where you can edit details for your sources or abort running import jobs.

## Source details

You can learn more about your sources by selecting the **Sources** tab on the Sourcing Kit dashboard. Use this option to rename or delete your sources.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account.
2. Go to **Images** > **Sourcing Kit**.
3. Select **Sources** and choose the source you want to change.
4. In this page you have the option to rename or delete your source. Select **Rename source** or **Delete source** depending on what you want to do.

## Abort import jobs

While Cloudflare Images is still running a job to import images into your account, you can abort it before it finishes.

1. Log in to the [ Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account.
2. Go to **Images** > **Sourcing Kit**.
3. In **Imports** select the import job you want to abort.
4. The next page shows you a summary of the import. Select **Abort**.
5. Confirm that you want to abort your import job by selecting **Abort** on the dialog box.

---

# Enable Sourcing Kit

URL: https://developers.cloudflare.com/images/upload-images/sourcing-kit/enable/

Enabling Sourcing Kit will set it up with the necessary information to start importing images from your Amazon S3 account.

## Create your first import job

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account.
2. Go to **Images** > **Sourcing Kit**.
3. Select **Import images** to create an import job.
4. In **Source name** give your source an appropriate name.
5. In **Amazon S3 bucket information** enter the S3's bucket name where your images are stored.
6. In **Required credentials**, enter your Amazon S3 credentials. This is required to connect Cloudflare Images to your source and import your images. Refer to [Credentials](/images/upload-images/sourcing-kit/credentials/) to learn more about how to set up credentials.
7. Select **Next**.
8. In **Basic rules** define the Amazon S3 path to import your images from, and the path you want to copy your images to in your Cloudflare Images account. This is optional, and you can leave these fields blank.
9. On the same page, in **Overwrite images**, you need to choose what happens when the files in your source change. The recommended action is to copy the new images and overwrite the old ones on your Cloudflare Images account. You can also choose to skip the import, and keep what you already have on your Cloudflare Images account.
10. Select **Next**.
11. Review and confirm the information regarding the import job you created. Select **Import images** to start importing images from your source.

Your import job is now created. You can review the job status on the Sourcing Kit main page. It will show you information such as how many objects it found, how many images were imported, and any errors that might have occurred.

:::note

Sourcing Kit will warn you when you are about to reach the limit for your plan space quota. When you exhaust the space available in your plan, the importing jobs will be aborted. If you see this warning on Sourcing Kit’s main page, select **View plan** to change your plan’s limits.
:::

## Define a new source

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account.
2. Go to **Images** > **Sourcing Kit**.
3. Select **Import images** > **Define a new source**.

Repeat steps 4-11 in [Create your first import job](#create-your-first-import-job) to finish setting up your new source.

## Define additional import jobs

You can have many import jobs from the same or different sources. If you select an existing source to create a new import job, you will not need to enter your credentials again.

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login), and select your account.
2. Go to **Images** > **Sourcing Kit**.
3. Select **Import images**.
4. Choose from one of the sources already configured.

Repeat steps 8-11 in [Create your first import job](#create-your-first-import-job) to finish setting up your new import job.

## Next steps

Refer to [Edit source details](/images/upload-images/sourcing-kit/edit/) to learn more about editing details for import jobs you have already created, or to learn how to abort running import jobs.

---

# Upload via Sourcing Kit

URL: https://developers.cloudflare.com/images/upload-images/sourcing-kit/

With Sourcing Kit you can define one or multiple repositories of images to bulk import from Amazon S3. Once you have these set up, you can reuse those sources and import only new images to your Cloudflare Images account. This helps you make sure that only usable images are imported, and skip any other objects or files that might exist in that source.

Sourcing Kit also lets you target paths, define prefixes for imported images, and obtain error logs for bulk operations.

Sourcing Kit is available in beta. If you have any comments, questions, or bugs to report, contact the Images team on our [Discord channel](https://discord.cloudflare.com). You can also engage with other users and the Images team on the [Cloudflare Community](https://community.cloudflare.com/c/developers/images/63).

## When to use Sourcing Kit

Sourcing Kit can be a good choice if the Amazon S3 bucket you are importing consists primarily of images stored using non-archival storage classes, as images stored using [archival storage classes](https://aws.amazon.com/s3/storage-classes/#Archive) will be skipped and need to be imported separately. Specifically:

* Images stored using S3 Glacier tiers (not including Glacier Instant Retrieval) will be skipped and logged in the migration log.
* Images stored using S3 Intelligent Tiering and placed in Deep Archive tier will be skipped and logged in the migration log.

---

# Connect to MySQL

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-mysql/

import { TabItem, Tabs, Render, WranglerConfig } from "~/components";

Hyperdrive supports MySQL and MySQL-compatible databases, [popular drivers](#supported-drivers), and Object Relational Mapper (ORM) libraries that use those drivers.

## Create a Hyperdrive

:::note

New to Hyperdrive? Refer to the [Get started guide](/hyperdrive/get-started/) to learn how to set up your first Hyperdrive.

:::

To create a Hyperdrive that connects to an existing MySQL database, use the [Wrangler](/workers/wrangler/install-and-update/) CLI or the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive).

When using Wrangler, replace the placeholder value provided to `--connection-string` with the connection string for your database:

```sh
# wrangler v3.11 and above required
npx wrangler hyperdrive create my-first-hyperdrive --connection-string="mysql://user:password@database.host.example.com:3306/databasenamehere"
```

The command above will output the ID of your Hyperdrive, which you will need to set in the [Wrangler configuration file](/workers/wrangler/configuration/) for your Workers project:

<Render file="hyperdrive-node-compatibility-requirement" product="hyperdrive" />

This will allow Hyperdrive to generate a dynamic connection string within your Worker that you can pass to your existing database driver. Refer to [Driver examples](#driver-examples) to learn how to set up a database driver with Hyperdrive.

Refer to the [Examples documentation](/hyperdrive/examples/) for step-by-step guides on how to set up Hyperdrive with several popular database providers.

## Supported drivers

Hyperdrive uses Workers [TCP socket support](/workers/runtime-apis/tcp-sockets/#connect) to support TCP connections to databases. The following table lists the supported database drivers and the minimum version that works with Hyperdrive:

| Driver                   | Documentation                                                    | Minimum Version Required | Notes                                                                                                                                                                                             |
| ------------------------ | ---------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mysql2 (**recommended**) | [mysql2 documentation](https://github.com/sidorares/node-mysql2) | `mysql2@3.13.0`          | Supported in both Workers & Pages. Using the Promise API is recommended.                                                                                                                          |
| mysql                    | [mysql documentation](https://github.com/mysqljs/mysql)          | `mysql@2.18.0`           | Requires `compatibility_flags = ["nodejs_compat"]` and `compatibility_date = "2024-09-23"` - refer to [Node.js compatibility](/workers/runtime-apis/nodejs). Requires wrangler `3.78.7` or later. |
| Drizzle                  | [Drizzle documentation](https://orm.drizzle.team/)               | Requires `mysql2@3.13.0` |                                                                                                                                                                                                   |
| Kysely                   | [Kysely documentation](https://kysely.dev/)                      | Requires `mysql2@3.13.0` |                                                                                                                                                                                                   |

^ _The marked libraries can use either mysql or mysql2 as a dependency._

Other drivers and ORMs not listed may also be supported: this list is not exhaustive.

### Database drivers and Node.js compatibility

[Node.js compatibility](/workers/runtime-apis/nodejs/) is required for database drivers, including mysql and mysql2, and needs to be configured for your Workers project.

<Render file="nodejs_compat" product="workers" />

## Supported TLS (SSL) modes

Hyperdrive supports the following MySQL TLS/SSL connection modes when connecting to your origin database:

| Mode              | Supported                       | Details                                                                                                            |
| ----------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `DISABLED`        | No                              | Hyperdrive does not support insecure plain text connections.                                                       |
| `PREFERRED`       | No (use `required`)             | Hyperdrive will always use TLS.                                                                                    |
| `REQUIRED`        | Yes (default)                   | TLS is required, and server certificates are validated (based on WebPKI).                                          |
| `VERIFY_CA`       | Not currently supported in beta | Verifies the server's TLS certificate is signed by a root CA on the client.                                        |
| `VERIFY_IDENTITY` | Not currently supported in beta | Identical to `VERIFY_CA`, but also requires that the database hostname matches the certificate's Common Name (CN). |

:::note

Hyperdrive does not currently support `VERIFY_CA` or `VERIFY_IDENTITY` for MySQL (beta).

:::

## Driver examples

The following examples show you how to:

1. Create a database client with a database driver.
2. Pass the Hyperdrive connection string and connect to the database.
3. Query your database via Hyperdrive.

### `mysql2`

The following Workers code shows you how to use [mysql2](https://github.com/sidorares/node-mysql2) with Hyperdrive using the Promise API.

<Render file="use-mysql2-to-make-query" product="hyperdrive" />

### `mysql`

The following Workers code shows you how to use [mysql](https://github.com/mysqljs/mysql) with Hyperdrive.

<Render file="use-mysql-to-make-query" product="hyperdrive" />

## Identify connections from Hyperdrive

To identify active connections to your MySQL database server from Hyperdrive:

- Hyperdrive's connections to your database will show up with `Cloudflare Hyperdrive` in the `PROGRAM_NAME` column in the `performance_schema.threads` table.
- Run `SELECT DISTINCT USER, HOST, PROGRAM_NAME FROM performance_schema.threads WHERE PROGRAM_NAME = 'Cloudflare Hyperdrive'` to show whether Hyperdrive is currently holding a connection (or connections) open to your database.

## Next steps

- Refer to the list of [supported database integrations](/workers/databases/connecting-to-databases/) to understand other ways to connect to existing databases.
- Learn more about how to use the [Socket API](/workers/runtime-apis/tcp-sockets) in a Worker.
- Understand the [protocols supported by Workers](/workers/reference/protocols/).

---

# Connect to PostgreSQL

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/

import { TabItem, Tabs, Render, WranglerConfig } from "~/components";

Hyperdrive supports PostgreSQL and PostgreSQL-compatible databases, [popular drivers](#supported-drivers) and Object Relational Mapper (ORM) libraries that use those drivers.

## Create a Hyperdrive

:::note

New to Hyperdrive? Refer to the [Get started guide](/hyperdrive/get-started/) to learn how to set up your first Hyperdrive.

:::

To create a Hyperdrive that connects to an existing PostgreSQL database, use the [wrangler](/workers/wrangler/install-and-update/) CLI or the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive).

When using wrangler, replace the placeholder value provided to `--connection-string` with the connection string for your database:

```sh
# wrangler v3.11 and above required
npx wrangler hyperdrive create my-first-hyperdrive --connection-string="postgres://user:password@database.host.example.com:5432/databasenamehere"
```

The command above will output the ID of your Hyperdrive, which you will need to set in the [Wrangler configuration file](/workers/wrangler/configuration/) for your Workers project:

<Render file="hyperdrive-node-compatibility-requirement" product="hyperdrive" />

This will allow Hyperdrive to generate a dynamic connection string within your Worker that you can pass to your existing database driver. Refer to [Driver examples](#driver-examples) to learn how to set up a database driver with Hyperdrive.

Refer to the [Examples documentation](/hyperdrive/examples/) for step-by-step guides on how to set up Hyperdrive with several popular database providers.

## Supported drivers

Hyperdrive uses Workers [TCP socket support](/workers/runtime-apis/tcp-sockets/#connect) to support TCP connections to databases. The following table lists the supported database drivers and the minimum version that works with Hyperdrive:

| Driver                                                     | Documentation                                                            | Minimum Version Required | Notes                                                                                                                                                                                                                                                                                |
| ---------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| node-postgres - `pg`      (recommended)                                 | [node-postgres - `pg` documentation](https://node-postgres.com/)         | `pg@8.13.0`              | `8.11.4` introduced a bug with URL parsing and will not work. `8.11.5` fixes this. Requires `compatibility_flags = ["nodejs_compat"]` and `compatibility_date = "2024-09-23"` - refer to [Node.js compatibility](/workers/runtime-apis/nodejs). Requires wrangler `3.78.7` or later. |
| Postgres.js                                                | [Postgres.js documentation](https://github.com/porsager/postgres)        | `postgres@3.4.4`         | Supported in both Workers & Pages.                                                                                                                                                                                                                                                   |
| Drizzle                                                    | [Drizzle documentation](https://orm.drizzle.team/)                       | `0.26.2`^                |                                                                                                                                                                                                                                                                                      |
| Kysely                                                     | [Kysely documentation](https://kysely.dev/)                              | `0.26.3`^                |                                                                                                                                                                                                                                                                                      |
| [rust-postgres](https://github.com/sfackler/rust-postgres) | [rust-postgres documentation](https://docs.rs/postgres/latest/postgres/) | `v0.19.8`                | Use the [`query_typed`](https://docs.rs/postgres/latest/postgres/struct.Client.html#method.query_typed) method for best performance.                                                                                                                                                 |

^ _The marked libraries use `node-postgres` as a dependency._

Other drivers and ORMs not listed may also be supported: this list is not exhaustive.

### Database drivers and Node.js compatibility

[Node.js compatibility](/workers/runtime-apis/nodejs/) is required for database drivers, including Postgres.js, and needs to be configured for your Workers project.

<Render file="nodejs_compat" product="workers" />

## Driver examples

The following examples show you how to:

1. Create a database client with a database driver.
2. Pass the Hyperdrive connection string and connect to the database.
3. Query your database via Hyperdrive.

### node-postgres / pg

Install the `node-postgres` driver:

<Render file="use-node-postgres-to-make-query" product="hyperdrive" />

### Postgres.js

The following Workers code shows you how to use [Postgres.js](https://github.com/porsager/postgres) with Hyperdrive.

<Render file="use-postgres-js-to-make-query" product="hyperdrive" />

## Identify connections from Hyperdrive

To identify active connections to your Postgres database server from Hyperdrive:

- Hyperdrive's connections to your database will show up with `Cloudflare Hyperdrive` as the `application_name` in the `pg_stat_activity` table.
- Run `SELECT DISTINCT usename, application_name FROM pg_stat_activity WHERE application_name = 'Cloudflare Hyperdrive'` to show whether Hyperdrive is currently holding a connection (or connections) open to your database.

## Next steps

- Refer to the list of [supported database integrations](/workers/databases/connecting-to-databases/) to understand other ways to connect to existing databases.
- Learn more about how to use the [Socket API](/workers/runtime-apis/tcp-sockets) in a Worker.
- Understand the [protocols supported by Workers](/workers/reference/protocols/).

---

# Create a serverless, globally distributed time-series API with Timescale

URL: https://developers.cloudflare.com/hyperdrive/tutorials/serverless-timeseries-api-with-timescale/

import { Render, PackageManagers, WranglerConfig } from "~/components";

In this tutorial, you will learn to build an API on Workers which will ingest and query time-series data stored in [Timescale](https://www.timescale.com/) (they make PostgreSQL faster in the cloud).

You will create and deploy a Worker function that exposes API routes for ingesting data, and use [Hyperdrive](https://developers.cloudflare.com/hyperdrive/) to proxy your database connection from the edge and maintain a connection pool to prevent us having to make a new database connection on every request.

You will learn how to:

- Build and deploy a Cloudflare Worker.
- Use Worker secrets with the Wrangler CLI.
- Deploy a Timescale database service.
- Connect your Worker to your Timescale database service with Hyperdrive.
- Query your new API.

You can learn more about Timescale by reading their [documentation](https://docs.timescale.com/getting-started/latest/services/).

---

## 1. Create a Worker project

Run the following command to create a Worker project from the command line:

<PackageManagers type="create" pkg="cloudflare@latest" args={"timescale-api"} />

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

Make note of the URL that your application was deployed to. You will be using it when you configure your GitHub webhook.

Change into the directory you just created for your Worker project:

```sh
cd timescale-api
```

## 2. Prepare your Timescale Service

:::note

If you have not signed up for Timescale, go to the [signup page](https://timescale.com/signup) where you can start a free 30 day trial with no credit card.
:::

If you are creating a new service, go to the [Timescale Console](https://console.cloud.timescale.com/) and follow these steps:

1. Select **Create Service** by selecting the black plus in the upper right.
2. Choose **Time Series** as the service type.
3. Choose your desired region and instance size. 1 CPU will be enough for this tutorial.
4. Set a service name to replace the randomly generated one.
5. Select **Create Service**.
6. On the right hand side, expand the **Connection Info** dialog and copy the **Service URL**.
7. Copy the password which is displayed. You will not be able to retrieve this again.
8. Select **I stored my password, go to service overview**.

If you are using a service you created previously, you can retrieve your service connection information in the [Timescale Console](https://console.cloud.timescale.com/):

1. Select the service (database) you want Hyperdrive to connect to.
2. Expand **Connection info**.
3. Copy the **Service URL**. The Service URL is the connection string that Hyperdrive will use to connect. This string includes the database hostname, port number and database name.

:::note

If you do not have your password stored, you will need to select **Forgot your password?** and set a new **SCRAM** password. Save this password, as Timescale will only display it once.

You should ensure that you do not break any existing clients if when you reset the password.
:::

Insert your password into the **Service URL** as follows (leaving the portion after the @ untouched):

```txt
postgres://tsdbadmin:YOURPASSWORD@...
```

This will be referred to as **SERVICEURL** in the following sections.

## 3. Create your Hypertable

Timescale allows you to convert regular PostgreSQL tables into [hypertables](https://docs.timescale.com/use-timescale/latest/hypertables/), tables used to deal with time-series, events, or analytics data. Once you have made this change, Timescale will seamlessly manage the hypertable's partitioning, as well as allow you to apply other features like compression or continuous aggregates.

Connect to your Timescale database using the Service URL you copied in the last step (it has the password embedded).

If you are using the default PostgreSQL CLI tool [**psql**](https://www.timescale.com/blog/how-to-install-psql-on-mac-ubuntu-debian-windows/) to connect, you would run psql like below (substituting your **Service URL** from the previous step). You could also connect using a graphical tool like [PgAdmin](https://www.pgadmin.org/).

```sh
psql <SERVICEURL>
```

Once you are connected, create your table by pasting the following SQL:

```sql
CREATE TABLE readings(
  ts timestamptz DEFAULT now() NOT NULL,
  sensor UUID NOT NULL,
  metadata jsonb,
  value numeric NOT NULL
 );

SELECT create_hypertable('readings', 'ts');
```

Timescale will manage the rest for you as you ingest and query data.

## 4. Create a database configuration

To create a new Hyperdrive instance you will need:

- Your **SERVICEURL** from [step 2](/hyperdrive/tutorials/serverless-timeseries-api-with-timescale/#2-prepare-your-timescale-service).
- A name for your Hyperdrive service. For this tutorial, you will use **hyperdrive**.

Hyperdrive uses the `create` command with the `--connection-string` argument to pass this information. Run it as follows:

```sh
npx wrangler hyperdrive create hyperdrive --connection-string="SERVICEURL"
```

:::note

Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](/hyperdrive/observability/troubleshooting/) to debug possible causes.

:::

This command outputs your Hyperdrive ID. You can now bind your Hyperdrive configuration to your Worker in your Wrangler configuration by replacing the content with the following:

<WranglerConfig>

```toml
name = "timescale-api"
main = "src/index.ts"
compatibility_date = "2024-09-23"
compatibility_flags = [ "nodejs_compat"]

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "your-id-here"
```

</WranglerConfig>

Install the Postgres driver into your Worker project:

<PackageManagers pkg="pg" />

Now copy the below Worker code, and replace the current code in `./src/index.ts`. The code below:

1. Uses Hyperdrive to connect to Timescale using the connection string generated from `env.HYPERDRIVE.connectionString` directly to the driver.
2. Creates a `POST` route which accepts an array of JSON readings to insert into Timescale in one transaction.
3. Creates a `GET` route which takes a `limit` parameter and returns the most recent readings. This could be adapted to filter by ID or by timestamp.

```ts
import { Client } from "pg";

export interface Env {
	HYPERDRIVE: Hyperdrive;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const client = new Client({
			connectionString: env.HYPERDRIVE.connectionString,
		});
		await client.connect();

		const url = new URL(request.url);
		// Create a route for inserting JSON as readings
		if (request.method === "POST" && url.pathname === "/readings") {
			// Parse the request's JSON payload
			const productData = await request.json();

			// Write the raw query. You are using jsonb_to_recordset to expand the JSON
			// to PG INSERT format to insert all items at once, and using coalesce to
			// insert with the current timestamp if no ts field exists
			const insertQuery = `
      INSERT INTO readings (ts, sensor, metadata, value)
      SELECT coalesce(ts, now()), sensor, metadata, value FROM jsonb_to_recordset($1::jsonb)
      AS t(ts timestamptz, sensor UUID, metadata jsonb, value numeric)
  `;

			const insertResult = await client.query(insertQuery, [
				JSON.stringify(productData),
			]);

			// Collect the raw row count inserted to return
			const resp = new Response(JSON.stringify(insertResult.rowCount), {
				headers: { "Content-Type": "application/json" },
			});

			ctx.waitUntil(client.end());
			return resp;

			// Create a route for querying within a time-frame
		} else if (request.method === "GET" && url.pathname === "/readings") {
			const limit = url.searchParams.get("limit");

			// Query the readings table using the limit param passed
			const result = await client.query(
				"SELECT * FROM readings ORDER BY ts DESC LIMIT $1",
				[limit],
			);

			// Return the result as JSON
			const resp = new Response(JSON.stringify(result.rows), {
				headers: { "Content-Type": "application/json" },
			});

			ctx.waitUntil(client.end());
			return resp;
		}
	},
} satisfies ExportedHandler<Env>;
```

## 5. Deploy your Worker

Run the following command to redeploy your Worker:

```sh
npx wrangler deploy
```

Your application is now live and accessible at `timescale-api.<YOUR_SUBDOMAIN>.workers.dev`. The exact URI will be shown in the output of the wrangler command you just ran.

After deploying, you can interact with your Timescale IoT readings database using your Cloudflare Worker. Connection from the edge will be faster because you are using Cloudflare Hyperdrive to connect from the edge.

You can now use your Cloudflare Worker to insert new rows into the `readings` table. To test this functionality, send a `POST` request to your Worker’s URL with the `/readings` path, along with a JSON payload containing the new product data:

```json
[
	{ "sensor": "6f3e43a4-d1c1-4cb6-b928-0ac0efaf84a5", "value": 0.3 },
	{ "sensor": "d538f9fa-f6de-46e5-9fa2-d7ee9a0f0a68", "value": 10.8 },
	{ "sensor": "5cb674a0-460d-4c80-8113-28927f658f5f", "value": 18.8 },
	{ "sensor": "03307bae-d5b8-42ad-8f17-1c810e0fbe63", "value": 20.0 },
	{ "sensor": "64494acc-4aa5-413c-bd09-2e5b3ece8ad7", "value": 13.1 },
	{ "sensor": "0a361f03-d7ec-4e61-822f-2857b52b74b3", "value": 1.1 },
	{ "sensor": "50f91cdc-fd19-40d2-b2b0-c90db3394981", "value": 10.3 }
]
```

This tutorial omits the `ts` (the timestamp) and `metadata` (the JSON blob) so they will be set to `now()` and `NULL` respectively.

Once you have sent the `POST` request you can also issue a `GET` request to your Worker’s URL with the `/readings` path. Set the `limit` parameter to control the amount of returned records.

If you have **curl** installed you can test with the following commands (replace `<YOUR_SUBDOMAIN>` with your subdomain from the deploy command above):

```bash title="Ingest some data"
curl --request POST --data @- 'https://timescale-api.<YOUR_SUBDOMAIN>.workers.dev/readings' <<EOF
[
  { "sensor": "6f3e43a4-d1c1-4cb6-b928-0ac0efaf84a5", "value":0.3},
  { "sensor": "d538f9fa-f6de-46e5-9fa2-d7ee9a0f0a68", "value":10.8},
  { "sensor": "5cb674a0-460d-4c80-8113-28927f658f5f", "value":18.8},
  { "sensor": "03307bae-d5b8-42ad-8f17-1c810e0fbe63", "value":20.0},
  { "sensor": "64494acc-4aa5-413c-bd09-2e5b3ece8ad7", "value":13.1},
  { "sensor": "0a361f03-d7ec-4e61-822f-2857b52b74b3", "value":1.1},
  { "sensor": "50f91cdc-fd19-40d2-b2b0-c90db3394981", "metadata": {"color": "blue" }, "value":10.3}
]
EOF
```

```sh title="Query some data"
curl "https://timescale-api.<YOUR_SUBDOMAIN>.workers.dev/readings?limit=10"
```

In this tutorial, you have learned how to create a working example to ingest and query readings from the edge with Timescale, Workers, Hyperdrive, and TypeScript.

## Next steps

- Learn more about [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/).
- Learn more about [Timescale](https://timescale.com).
- Refer to the [troubleshooting guide](/hyperdrive/observability/troubleshooting/) to debug common issues.

---

# GitHub integration

URL: https://developers.cloudflare.com/pages/configuration/git-integration/github-integration/

You can connect each Cloudflare Pages project to a GitHub repository, and Cloudflare will automatically deploy your code every time you push a change to a branch.

## Features

Beyond automatic deployments, the Cloudflare GitHub integration lets you monitor, manage, and preview deployments directly in GitHub, keeping you informed without leaving your workflow.

### Custom branches

Pages will default to setting your [production environment](/pages/configuration/branch-build-controls/#production-branch-control) to the branch you first push. If a branch other than the default branch (e.g. `main`) represents your project's production branch, then go to **Settings** > **Builds** > **Branch control**, change the production branch by clicking the **Production branch** dropdown menu and choose any other branch.

You can also use [preview deployments](/pages/configuration/preview-deployments/) to preview versions of your project before merging your production branch, and deploying to production. Pages allows you to configure which of your preview branches are automatically deployed using [branch build controls](/pages/configuration/branch-build-controls/). To configure, go to **Settings** > **Builds** > **Branch control** and select an option under **Preview branch**. Use [**Custom branches**](/pages/configuration/branch-build-controls/) to specify branches you wish to include or exclude from automatic preview deployments.

### Preview URLs

Every time you open a new pull request on your GitHub repository, Cloudflare Pages will create a unique preview URL, which will stay updated as you continue to push new commits to the branch. Note that preview URLs will not be created for pull requests created from forks of your repository. Learn more in [Preview Deployments](/pages/configuration/preview-deployments/).

![GitHub Preview URLs](~/assets/images/pages/configuration/ghpreviewurls.png)

### Skipping a build via a commit message

Without any configuration required, you can choose to skip a deployment on an ad hoc basis. By adding the `[CI Skip]`, `[CI-Skip]`, `[Skip CI]`, `[Skip-CI]`, or `[CF-Pages-Skip]` flag as a prefix in your commit message, and Pages will omit that deployment. The prefixes are not case sensitive.

### Check runs

If you have one or multiple projects connected to a repository (i.e. a [monorepo](/pages/configuration/monorepos/)), you can check on the status of each build within GitHub via [GitHub check runs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks#checks).

You can see the checks by selecting the status icon next to a commit within your GitHub repository. In the example below, you can select the green check mark to see the results of the check run.

![GitHub status](~/assets/images/workers/platform/ci-cd/gh-status-check-runs.png)

Check runs will appear like the following in your repository.

![GitHub check runs](~/assets/images/pages/configuration/ghcheckrun.png)

If a build skips for any reason (i.e. CI Skip, build watch paths, or branch deployment controls), the check run/commit status will not appear.

## Manage access

You can deploy projects to Cloudflare Workers from your company or side project on GitHub using the [Cloudflare Workers & Pages GitHub App](https://github.com/apps/cloudflare-workers-and-pages).

### Organizational access

You can deploy projects to Cloudflare Pages from your company or side project on both GitHub and GitLab.

When authorizing Cloudflare Pages to access a GitHub account, you can specify access to your individual account or an organization that you belong to on GitHub. In order to be able to add the Cloudflare Pages installation to that organization, your user account must be an owner or have the appropriate role within the organization (that is, the GitHub Apps Manager role). More information on these roles can be seen on [GitHub's documentation](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#github-app-managers).

:::caution[GitHub security consideration]

A GitHub account should only point to one Cloudflare account. If you are setting up Cloudflare with GitHub for your organization, Cloudflare recommends that you limit the scope of the application to only the repositories you intend to build with Pages. To modify these permissions, go to the [Applications page](https://github.com/settings/installations) on GitHub and select **Switch settings context** to access your GitHub organization settings. Then, select **Cloudflare Workers & Pages** > For **Repository access**, select **Only select repositories** > select your repositories.

:::

### Remove access

You can remove Cloudflare Pages' access to your GitHub repository or account by going to the [Applications page](https://github.com/settings/installations) on GitHub (if you are in an organization, select Switch settings context to access your GitHub organization settings). The GitHub App is named Cloudflare Workers and Pages, and it is shared between Workers and Pages projects.

#### Remove Cloudflare access to a GitHub repository

To remove access to an individual GitHub repository, you can navigate to **Repository access**. Select the **Only select repositories** option, and configure which repositories you would like Cloudflare to have access to.

![GitHub Repository Access](~/assets/images/workers/platform/ci-cd/github-repository-access.png)

#### Remove Cloudflare access to the entire GitHub account

To remove Cloudflare Workers and Pages access to your entire Git account, you can navigate to **Uninstall "Cloudflare Workers and Pages"**, then select **Uninstall**. Removing access to the Cloudflare Workers and Pages app will revoke Cloudflare's access to _all repositories_ from that GitHub account. If you want to only disable automatic builds and deployments, follow the [Disable Build](/workers/ci-cd/builds/#disconnecting-builds) instructions.

Note that removing access to GitHub will disable new builds for Workers and Pages project that were connected to those repositories, though your previous deployments will continue to be hosted by Cloudflare Workers.

### Reinstall the Cloudflare GitHub app

If you see errors where Cloudflare Pages cannot access your git repository, you should attempt to uninstall and reinstall the GitHub application associated with the Cloudflare Pages installation.

1. Go to the installation settings page on GitHub:
   - Navigate to **Settings > Builds** for the Pages project and select **Manage** under Git Repository.
   - Alternatively, visit these links to find the Cloudflare Workers and Pages installation and select **Configure**:

|                  |                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------- |
| **Individual**   | `https://github.com/settings/installations`                                        |
| **Organization** | `https://github.com/organizations/<YOUR_ORGANIZATION_NAME>/settings/installations` |

2. In the Cloudflare Workers and Pages GitHub App settings page, navigate to **Uninstall "Cloudflare Workers and Pages"** and select **Uninstall**.
3. Go back to the [**Workers & Pages** overview](https://dash.cloudflare.com) page. Select **Create application** > **Pages** > **Connect to Git**.
4. Select the **+ Add account** button, select the GitHub account you want to add, and then select **Install & Authorize**.
5. You should be redirected to the create project page with your GitHub account or organization in the account list.
6. Attempt to make a new deployment with your project which was previously broken.

---

# GitLab integration

URL: https://developers.cloudflare.com/pages/configuration/git-integration/gitlab-integration/

You can connect each Cloudflare Pages project to a GitLab repository, and Cloudflare will automatically deploy your code every time you push a change to a branch.

## Features

Beyond automatic deployments, the Cloudflare GitLab integration lets you monitor, manage, and preview deployments directly in GitLab, keeping you informed without leaving your workflow.

### Custom branches

Pages will default to setting your [production environment](/pages/configuration/branch-build-controls/#production-branch-control) to the branch you first push. If a branch other than the default branch (e.g. `main`) represents your project's production branch, then go to **Settings** > **Builds** > **Branch control**, change the production branch by clicking the **Production branch** dropdown menu and choose any other branch.

You can also use [preview deployments](/pages/configuration/preview-deployments/) to preview versions of your project before merging your production branch, and deploying to production. Pages allows you to configure which of your preview branches are automatically deployed using [branch build controls](/pages/configuration/branch-build-controls/). To configure, go to **Settings** > **Builds** > **Branch control** and select an option under **Preview branch**. Use [**Custom branches**](/pages/configuration/branch-build-controls/) to specify branches you wish to include or exclude from automatic preview deployments.

### Skipping a specific build via a commit message

Without any configuration required, you can choose to skip a deployment on an ad hoc basis. By adding the `[CI Skip]`, `[CI-Skip]`, `[Skip CI]`, `[Skip-CI]`, or `[CF-Pages-Skip]` flag as a prefix in your commit message, Pages will omit that deployment. The prefixes are not case sensitive.

### Check runs and preview URLs

If you have one or multiple projects connected to a repository (i.e. a [monorepo](/workers/ci-cd/builds/advanced-setups/#monorepos)), you can check on the status of each build within GitLab via [GitLab commit status](https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html).

You can see the statuses by selecting the status icon next to a commit or by going to **Build** > **Pipelines** within your GitLab repository. In the example below, you can select the green check mark to see the results of the check run.

![GitLab Status](~/assets/images/workers/platform/ci-cd/gl-status-checks.png)

Check runs will appear like the following in your repository. You can select one of the statuses to view the [preview URL](/pages/configuration/preview-deployments/) for that deployment.

![GitLab Commit Status](~/assets/images/pages/configuration/glcommitstatus.png)

If a build skips for any reason (i.e. CI Skip, build watch paths, or branch deployment controls), the check run/commit status will not appear.

## Manage access

You can deploy projects to Cloudflare Workers from your company or side project on GitLab using the Cloudflare Pages app.

### Organizational access

You can deploy projects to Cloudflare Pages from your company or side project on both GitHub and GitLab.

When you authorize Cloudflare Pages to access your GitLab account, you automatically give Cloudflare Pages access to organizations, groups, and namespaces accessed by your GitLab account. Managing access to these organizations and groups is handled by GitLab.

### Remove access

You can remove Cloudflare Workers' access to your GitLab account by navigating to [Authorized Applications page](https://gitlab.com/-/profile/applications) on GitLab. Find the applications called Cloudflare Workers and select the **Revoke** button to revoke access.

Note that the GitLab application Cloudflare Workers is shared between Workers and Pages projects, and removing access to GitLab will disable new builds for Workers and Pages, though your previous deployments will continue to be hosted by Cloudflare Pages.

### Reinstall the Cloudflare GitLab app

When encountering Git integration related issues, one potential troubleshooting step is attempting to uninstall and reinstall the GitHub or GitLab application associated with the Cloudflare Pages installation.

1. Go to your application settings page on GitLab located here: [https://gitlab.com/-/profile/applications](https://gitlab.com/-/profile/applications)
2. Select the **Revoke** button on your Cloudflare Pages installation if it exists.
3. Go back to the **Workers & Pages** overview page at `https://dash.cloudflare.com/[YOUR_ACCOUNT_ID]/workers-and-pages`. Select **Create application** > **Pages** > **Connect to Git**.
4. Select the **GitLab** tab at the top, select the **+ Add account** button, select the GitLab account you want to add, and then select **Authorize** on the modal titled "Authorize Cloudflare Pages to use your account?".
5. You will be redirected to the create project page with your GitLab account or organization in the account list.
6. Attempt to make a new deployment with your project which was previously broken.

---

# Git integration

URL: https://developers.cloudflare.com/pages/configuration/git-integration/

You can connect each Cloudflare Pages project to a [GitHub](/pages/configuration/git-integration/github-integration) or [GitLab](/pages/configuration/git-integration/gitlab-integration) repository, and Cloudflare will automatically deploy your code every time you push a change to a branch.

:::note
Cloudflare Workers now also supports Git integrations to automatically build and deploy Workers from your connected Git repository. Learn more in [Workers Builds](/workers/ci-cd/builds/).
:::

When you connect a git repository to your Cloudflare Pages project, Cloudflare will also:

- **Preview deployments for custom branches**, generating preview URLs for a commit to any branch in the repository without affecting your production deployment.
- **Preview URLs in pull requests** (PRs) to the repository.
- **Build and deployment status checks** within the Git repository.
- **Skipping builds using a commit message**.

These features allow you to manage your deployments directly within GitHub or GitLab without leaving your team's regular development workflow.

:::caution[You cannot switch to Direct Upload later]
If you deploy using the Git integration, you cannot switch to [Direct Upload](/pages/get-started/direct-upload/) later. However, if you already use a Git-integrated project and do not want to trigger deployments every time you push a commit, you can [disable automatic deployments](/pages/configuration/git-integration/#disable-automatic-deployments) on all branches. Then, you can use Wrangler to deploy directly to your Pages projects and make changes to your Git repository without automatically triggering a build.

:::

## Supported Git providers

Cloudflare supports connecting Cloudflare Pages to your GitHub and GitLab repositories. Pages does not currently support connecting self-hosted instances of GitHub or GitLab.

If you using a different Git provider (e.g. Bitbucket) or a self-hosted instance, you can start with a Direct Upload project and deploy using a CI/CD provider (e.g. GitHub Actions) with [Wrangler CLI](/pages/how-to/use-direct-upload-with-continuous-integration/).

## Add a Git integration

If you do not have a Git account linked to your Cloudflare account, you will be prompted to set up an installation to GitHub or GitLab when [connecting to Git](/pages/get-started/git-integration/) for the first time, or when adding a new Git account. Follow the prompts and authorize the Cloudflare Git integration.

You can check the following pages to see if your Git integration has been installed:

- [GitHub Applications page](https://github.com/settings/installations) (if you're in an organization, select **Switch settings context** to access your GitHub organization settings)
- [GitLab Authorized Applications page](https://gitlab.com/-/profile/applications)

For details on providing access to organization accounts, see the [GitHub](/pages/configuration/git-integration/github-integration/#organizational-access) and [GitLab](/pages/configuration/git-integration/gitlab-integration/#organizational-access) guides.

## Manage a Git integration

You can manage the Git installation associated with your repository connection by navigating to the Pages project, then going to **Settings** > **Builds** and selecting **Manage** under **Git Repository**.

This can be useful for managing repository access or troubleshooting installation issues by reinstalling. For more details, see the [GitHub](/pages/configuration/git-integration/github-integration/#managing-access) and [GitLab](/pages/configuration/git-integration/gitlab-integration/#managing-access) guides.

## Disable automatic deployments

If you are using a Git-integrated project and do not want to trigger deployments every time you push a commit, you can use [branch control](/pages/configuration/branch-build-controls/) to disable/pause builds:

1. Go to the **Settings** of your **Pages project** in the [Cloudflare dashboard](https://dash.cloudflare.com).
2. Navigate to **Build** > edit **Branch control** > turn off **Enable automatic production branch deployments**.
3. You can also change your Preview branch to **None (Disable automatic branch deployments)** to pause automatic preview deployments.

Then, you can use Wrangler to deploy directly to your Pages project and make changes to your Git repository without automatically triggering a build.

---

# Troubleshooting builds

URL: https://developers.cloudflare.com/pages/configuration/git-integration/troubleshooting/

If your git integration is experiencing issues, you may find the following banners in the Deployment page of your Pages project.

## Project creation

#### `This repository is being used for a Cloudflare Pages project on a different Cloudflare account.`

Using the same GitHub/GitLab repository across separate Cloudflare accounts is disallowed. To use the repository for a Pages project in that Cloudflare account, you should delete any Pages projects using the repository in other Cloudflare accounts.

## Deployments

If you run into any issues related to deployments or failing, check your project dashboard to see if there are any SCM installation warnings listed as shown in the screenshot below.

![Pausing a deployment in the Settings of your Pages project](~/assets/images/pages/platform/git.dashboard-error.png)

To resolve any errors displayed in the Cloudflare Pages dashboard, follow the steps listed below.

#### `This project is disconnected from your Git account, this may cause deployments to fail.`

To resolve this issue, follow the steps provided above in the [Reinstalling a Git installation section](/pages/configuration/git-integration/#reinstall-a-git-installation) for the applicable SCM provider. If the issue persists even after uninstalling and reinstalling, contact support.

#### `Cloudflare Pages is not properly installed on your Git account, this may cause deployments to fail.`

To resolve this issue, follow the steps provided above in the [Reinstalling a Git installation section](/pages/configuration/git-integration/#reinstall-a-git-installation) for the applicable SCM provider. If the issue persists even after uninstalling and reinstalling, contact support.

#### `The Cloudflare Pages installation has been suspended, this may cause deployments to fail.`

Go to your GitHub installation settings:

- `https://github.com/settings/installations` for individual accounts
- `https://github.com/organizations/<YOUR_ORGANIZATION_NAME>/settings/installations` for organizational accounts

Click **Configure** on the Cloudflare Pages application. Scroll down to the bottom of the page and click **Unsuspend** to allow Cloudflare Pages to make future deployments.

#### `The project is linked to a repository that no longer exists, this may cause deployments to fail.`

You may have deleted or transferred the repository associated with this Cloudflare Pages project. For a deleted repository, you will need to create a new Cloudflare Pages project with a repository that has not been deleted. For a transferred repository, you can either transfer the repository back to the original Git account or you will need to create a new Cloudflare Pages project with the transferred repository.

#### `The repository cannot be accessed, this may cause deployments to fail.`

You may have excluded this repository from your installation's repository access settings. Go to your GitHub installation settings:

- `https://github.com/settings/installations` for individual accounts
- `https://github.com/organizations/<YOUR_ORGANIZATION_NAME>/settings/installations` for organizational accounts

Click **Configure** on the Cloudflare Pages application. Under **Repository access**, ensure that the repository associated with your Cloudflare Pages project is included in the list.

#### `There is an internal issue with your Cloudflare Pages Git installation.`

This is an internal error in the Cloudflare Pages SCM system. You can attempt to [reinstall your Git installation](/pages/configuration/git-integration/#reinstall-a-git-installation), but if the issue persists, [contact support](/support/contacting-cloudflare-support/).

#### `GitHub/GitLab is having an incident and push events to Cloudflare are operating in a degraded state. Check their status page for more details.`

This indicates that GitHub or GitLab may be experiencing an incident affecting push events to Cloudflare. It is recommended to monitor their status page ([GitHub](https://www.githubstatus.com/), [GitLab](https://status.gitlab.com/)) for updates and try deploying again later.

---

# Static site

URL: https://developers.cloudflare.com/pages/framework-guides/nextjs/deploy-a-static-nextjs-site/

import { PagesBuildPreset, Render } from "~/components";

:::note

Do not use this guide unless you have a specific use case for static exports. Cloudflare recommends using the [Deploy a Next.js site](/pages/framework-guides/nextjs/ssr/get-started/) guide.

:::

[Next.js](https://nextjs.org) is an open-source React framework for creating websites and applications. In this guide, you will create a new Next.js application and deploy it using Cloudflare Pages.

This guide will instruct you how to deploy a static site Next.js project with [static exports](https://nextjs.org/docs/app/building-your-application/deploying/static-exports).

<Render file="tutorials-before-you-start" />

## Select your Next.js project

If you already have a Next.js project that you wish to deploy, ensure that it is [configured for static exports](https://nextjs.org/docs/app/building-your-application/deploying/static-exports), change to its directory, and proceed to the next step. Otherwise, use `create-next-app` to create a new Next.js project.

```sh
npx create-next-app --example with-static-export my-app
```

After creating your project, a new `my-app` directory will be generated using the official [`with-static-export`](https://github.com/vercel/next.js/tree/canary/examples/with-static-export) example as a template. Change to this directory to continue.

```sh
cd my-app
```

### Create a GitHub repository

Create a new GitHub repository by visiting [repo.new](https://repo.new). After creating a new repository, prepare and push your local application to GitHub by running the following commands in your terminal:

```sh
git remote add origin https://github.com/<GH_USERNAME>/<REPOSITORY_NAME>.git
git branch -M main
git push -u origin main
```

### Deploy your application to Cloudflare Pages

<Render
	file="deploy-to-pages-steps-with-preset"
	params={{ name: "Next.js (Static HTML Export)" }}
/>

<PagesBuildPreset framework="next-js-static" />

After configuring your site, you can begin your first deploy. Cloudflare Pages will install `next`, your project dependencies, and build your site before deploying it.

## Preview your site

After deploying your site, you will receive a unique subdomain for your project on `*.pages.dev`.

Every time you commit new code to your Next.js site, Cloudflare Pages will automatically rebuild your project and deploy it. You will also get access to [preview deployments](/pages/configuration/preview-deployments/) on new pull requests, so you can preview how changes look to your site before deploying them to production.

For the complete guide to deploying your first site to Cloudflare Pages, refer to the [Get started guide](/pages/get-started/).

---

# Next.js

URL: https://developers.cloudflare.com/pages/framework-guides/nextjs/

import { DirectoryListing, Stream } from "~/components";

[Next.js](https://nextjs.org) is an open-source React framework for creating websites and applications.

### Video Tutorial

<Stream
	id="20dcfaa7ec7caa714b2c916d4a430069"
	title="Deploy NextJS to your Workers Application"
	thumbnail="https://pub-d9bf66e086fb4b639107aa52105b49dd.r2.dev/Deploy-NextJS-Workers.png"
/>

<DirectoryListing />

---

# Resources

URL: https://developers.cloudflare.com/pages/framework-guides/nextjs/resources/

import { ResourcesBySelector, ExternalResources } from "~/components";

## Demo apps

For demo applications using Next.js, refer to the following resources:

<ExternalResources tags={["NextJS"]} type="apps" />

---

# Migrating from Netlify to Pages

URL: https://developers.cloudflare.com/pages/migrations/migrating-from-netlify/

In this tutorial, you will learn how to migrate your Netlify application to Cloudflare Pages.

## Finding your build command and build directory

To move your application to Cloudflare Pages, find your build command and build directory. Cloudflare Pages will use this information to build and deploy your application.

In your Netlify Dashboard, find the project that you want to deploy. It should be configured to deploy from a GitHub repository.

![Selecting a site in the Netlify Dashboard](~/assets/images/pages/migrations/netlify-deploy-1.png)

Inside of your site dashboard, select **Site Settings**, and then **Build & Deploy**.

![Selecting Site Settings in site dashboard](~/assets/images/pages/migrations/netlify-deploy-2.png)

![Selecting Build and Deploy in sidebar](~/assets//images/pages/migrations/netlify-deploy-3.png)

In the **Build & Deploy** tab, find the **Build settings** panel, which will have the **Build command** and **Publish directory** fields. Save these for deploying to Cloudflare Pages. In the below image, **Build command** is `yarn build`, and **Publish directory** is `build/`.

![Finding the Build command and Publish directory fields](~/assets/images/pages/migrations/netlify-deploy-4.png)

## Migrating redirects and headers

If your site includes a `_redirects` file in your publish directory, you can use the same file in Cloudflare Pages and your redirects will execute successfully. If your redirects are in your `netlify.toml` file, you will need to add them to the `_redirects` folder. Cloudflare Pages currently offers limited [supports for advanced redirects](/pages/configuration/redirects/). In the case where you have over 2000 static and/or 100 dynamic redirects rules, it is recommended to use [Bulk Redirects](/rules/url-forwarding/bulk-redirects/create-dashboard/).

Your header files can also be moved into a `_headers` folder in your publish directory. It is important to note that custom headers defined in the `_headers` file are not currently applied to responses from functions, even if the function route matches the URL pattern. To learn more about how to [handle headers, refer to Headers](/pages/configuration/headers/).

:::note

Redirects execute before headers. In the case of a request matching rules in both files, the redirect will take precedence.

:::

## Forms

In your form component, remove the `data-netlify = "true"` attribute or the Netlify attribute from the `<form>` tag. You can now put your form logic as a Pages Function and collect the entries to a database or an Airtable. Refer to the [handling form submissions with Pages Functions](/pages/tutorials/forms/) tutorial for more information.

## Serverless functions

Netlify functions and Pages Functions share the same filesystem convention using a `functions` directory in the base of your project to handle your serverless functions. However, the syntax and how the functions are deployed differs. Pages Functions run on Cloudflare Workers, which by default operate on the Cloudflare global network, and do not require any additional code or configuration for deployment.

Cloudflare Pages Functions also provides middleware that can handle any logic you need to run before and/or after your function route handler.

### Functions syntax

Netlify functions export an async event handler that accepts an event and a context as arguments. In the case of Pages Functions, you will have to export a single `onRequest` function that accepts a `context` object. The `context` object contains all the information for the request such as `request`, `env`, `params`, and returns a new Response. Learn more about [writing your first function](/pages/functions/get-started/)

Hello World with Netlify functions:

```js
exports.handler = async function (event, context) {
	return {
		statusCode: 200,
		body: JSON.stringify({ message: "Hello World" }),
	};
};
```

Hello World with Pages Functions:

```js
export async function onRequestPost(request) {
	return new Response(`Hello world`);
}
```

## Other Netlify configurations

Your `netlify.toml` file might have other configurations that are supported by Pages, such as, preview deployment, specifying publish directory, and plugins. You can delete the file after migrating your configurations.

## Access management

You can migrate your access management to [Cloudflare Zero Trust](/cloudflare-one/) which allows you to manage user authentication for your applications, event logging and requests.

## Creating a new Pages project

Once you have found your build directory and build command, you can move your project to Cloudflare Pages.

The [Get started guide](/pages/get-started/) will instruct you how to add your GitHub project to Cloudflare Pages.

If you choose to use a custom domain for your Pages, you can set it to the same custom domain as your currently deployed Netlify application. To assign a custom domain to your Pages project, refer to [Custom Domains](/pages/configuration/custom-domains/).

## Cleaning up your old application and assigning the domain

In the Cloudflare dashboard, go to **DNS** > **Records** and review that you have updated the CNAME record for your domain from Netlify to Cloudflare Pages. With your DNS record updated, requests will go to your Pages application.

In **DNS**, your record's **Content** should be your `<SUBDOMAIN>.pages.dev` subdomain.

With the above steps completed, you have successfully migrated your Netlify project to Cloudflare Pages.

---

# Migrating from Vercel to Pages

URL: https://developers.cloudflare.com/pages/migrations/migrating-from-vercel/

import { Render } from "~/components";

In this tutorial, you will learn how to deploy your Vercel application to Cloudflare Pages.

You should already have an existing project deployed on Vercel that you would like to host on Cloudflare Pages. Features such as Vercel's serverless functions are currently not supported in Cloudflare Pages.

## Find your build command and build directory

To move your application to Cloudflare Pages, you will need to find your build command and build directory. Cloudflare Pages will use this information to build your application and deploy it.

In your Vercel Dashboard, find the project that you want to deploy. It should be configured to deploy from a GitHub repository.

![Selecting a site in the Vercel Dashboard](~/assets/images/pages/migrations/vercel-deploy-1.png)

Inside of your site dashboard, select **Settings**, then **General**.

![Selecting Site Settings in site dashboard](~/assets/images/pages/migrations/vercel-deploy-2.png)

Find the **Build & Development settings** panel, which will have the **Build Command** and **Output Directory** fields. If you are using a framework, these values may not be filled in, but will show the defaults used by the framework. Save these for deploying to Cloudflare Pages. In the below image, the **Build Command** is `npm run build`, and the **Output Directory** is `build`.

![Finding the Build Command and Output Directory fields](~/assets/images/pages/migrations/vercel-deploy-3.png)

## Create a new Pages project

After you have found your build directory and build command, you can move your project to Cloudflare Pages.

The [Get started guide](/pages/get-started/) will instruct you how to add your GitHub project to Cloudflare Pages.

## Add a custom domain

Next, connect a [custom domain](/pages/configuration/custom-domains/) to your Pages project. This domain should be the same one as your currently deployed Vercel application.

### Change domain nameservers

In most cases, you will want to [add your domain to Cloudflare](/dns/zone-setups/full-setup/setup/).

This does involve changing your domain nameservers, but simplifies your Pages setup and allows you to use an apex domain for your project (like `example.com`).

If you want to take a different approach, read more about [custom domains](/pages/configuration/custom-domains/).

### Set up custom domain

<Render file="custom-domain-steps" />

The next steps vary based on if you [added your domain to Cloudflare](#change-domain-nameservers):

- **Added to Cloudflare**: Cloudflare will set everything up for you automatically and your domain will move to an `Active` status.
- **Not added to Cloudflare**: You need to [update some DNS records](/pages/configuration/custom-domains/#add-a-custom-subdomain) at your DNS provider to finish your setup.

## Delete your Vercel app

Once your custom domain is set up and sending requests to Cloudflare Pages, you can safely delete your Vercel application.

## Troubleshooting

Cloudflare does not provide IP addresses for your Pages project because we do not require `A` or `AAAA` records to link your domain to your project. Instead, Cloudflare uses `CNAME` records.

For more details, refer to [Custom domains](/pages/configuration/custom-domains/).

---

# Migrating from Workers Sites to Pages

URL: https://developers.cloudflare.com/pages/migrations/migrating-from-workers/

In this tutorial, you will learn how to migrate an existing [Cloudflare Workers Sites](/workers/configuration/sites/) application to Cloudflare Pages.

As a prerequisite, you should have a Cloudflare Workers Sites project, created with [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler).

Cloudflare Pages provides built-in defaults for every aspect of serving your site. You can port custom behavior in your Worker — such as custom caching logic — to your Cloudflare Pages project using [Functions](/pages/functions/). This enables an easy-to-use, file-based routing system. You can also migrate your custom headers and redirects to Pages.

You may already have a reasonably complex Worker and/or it would be tedious to splice it up into Pages' file-based routing system. For these cases, Pages offers developers the ability to define a `_worker.js` file in the output directory of your Pages project.

:::note

When using a `_worker.js` file, the entire `/functions` directory is ignored - this includes its routing and middleware characteristics. Instead, the `_worker.js` file is deployed as is and must be written using the [Module Worker syntax](/workers/reference/migrate-to-module-workers/).

:::

By migrating to Cloudflare Pages, you will be able to access features like [preview deployments](/pages/configuration/preview-deployments/) and automatic branch deploys with no extra configuration needed.

## Remove unnecessary code

Workers Sites projects consist of the following pieces:

1. An application built with a [static site tool](/pages/how-to/) or a static collection of HTML, CSS and JavaScript files.
2. If using a static site tool, a build directory (called `bucket` in the [Wrangler configuration file](/pages/functions/wrangler-configuration/)) where the static project builds your HTML, CSS, and JavaScript files.
3. A Worker application for serving that build directory. For most projects, this is likely to be the `workers-site` directory.

When moving to Cloudflare Pages, remove the Workers application and any associated Wrangler configuration files or build output. Instead, note and record your `build` command (if you have one), and the `bucket` field, or build directory, from the Wrangler file in your project's directory.

## Migrate headers and redirects

You can migrate your redirects to Pages, by creating a `_redirects` file in your output directory. Pages currently offers limited support for advanced redirects. More support will be added in the future. For a list of support types, refer to the [Redirects documentation](/pages/configuration/redirects/).

:::note

A project is limited to 2,000 static redirects and 100 dynamic redirects, for a combined total of 2,100 redirects. Each redirect declaration has a 1,000-character limit. Malformed definitions are ignored. If there are multiple redirects for the same source path, the topmost redirect is applied.

Make sure that static redirects are before dynamic redirects in your `_redirects` file.

:::

In addition to a `_redirects` file, Cloudflare also offers [Bulk Redirects](/pages/configuration/redirects/#surpass-_redirects-limits), which handles redirects that surpasses the 2,100 redirect rules limit set by Pages.

Your custom headers can also be moved into a `_headers` file in your output directory. It is important to note that custom headers defined in the `_headers` file are not currently applied to responses from Functions, even if the Function route matches the URL pattern. To learn more about handling headers, refer to [Headers](/pages/configuration/headers/).

## Create a new Pages project

### Connect to your git provider

After you have recorded your **build command** and **build directory** in a separate location, remove everything else from your application, and push the new version of your project up to your git provider. Follow the [Get started guide](/pages/get-started/) to add your project to Cloudflare Pages, using the **build command** and **build directory** that you saved earlier.

If you choose to use a custom domain for your Pages project, you can set it to the same custom domain as your currently deployed Workers application. Follow the steps for [adding a custom domain](/pages/configuration/custom-domains/#add-a-custom-domain) to your Pages project.

:::note

Before you deploy, you will need to delete your old Workers routes to start sending requests to Cloudflare Pages.

:::

### Using Direct Upload

If your Workers site has its custom build settings, you can bring your prebuilt assets to Pages with [Direct Upload](/pages/get-started/direct-upload/). In addition, you can serve your website's assets right to the Cloudflare global network by either using the [Wrangler CLI](/workers/wrangler/install-and-update/) or the drag and drop option.

These options allow you to create and name a new project from the CLI or dashboard. After your project deployment is complete, you can set the custom domain by following the [adding a custom domain](/pages/configuration/custom-domains/#add-a-custom-domain) steps to your Pages project.

## Cleaning up your old application and assigning the domain

After you have deployed your Pages application, to delete your Worker:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. Go to **Workers & Pages** and in **Overview**, select your Worker.
3. Go to **Manage** > **Delete Worker**.

With your Workers application removed, requests will go to your Pages application. You have successfully migrated your Workers Sites project to Cloudflare Pages by completing this guide.

---

# A/B testing with middleware

URL: https://developers.cloudflare.com/pages/functions/examples/ab-testing/

```js
const cookieName = "ab-test-cookie";
const newHomepagePathName = "/test";

const abTest = async (context) => {
	const url = new URL(context.request.url);
	// if homepage
	if (url.pathname === "/") {
		// if cookie ab-test-cookie=new then change the request to go to /test
		// if no cookie set, pass x% of traffic and set a cookie value to "current" or "new"

		let cookie = request.headers.get("cookie");
		// is cookie set?
		if (cookie && cookie.includes(`${cookieName}=new`)) {
			// pass the request to /test
			url.pathname = newHomepagePathName;
			return context.env.ASSETS.fetch(url);
		} else {
			const percentage = Math.floor(Math.random() * 100);
			let version = "current"; // default version
			// change pathname and version name for 50% of traffic
			if (percentage < 50) {
				url.pathname = newHomepagePathName;
				version = "new";
			}
			// get the static file from ASSETS, and attach a cookie
			const asset = await context.env.ASSETS.fetch(url);
			let response = new Response(asset.body, asset);
			response.headers.append("Set-Cookie", `${cookieName}=${version}; path=/`);
			return response;
		}
	}
	return context.next();
};

export const onRequest = [abTest];
```

---

# Adding CORS headers

URL: https://developers.cloudflare.com/pages/functions/examples/cors-headers/

This example is a snippet from our Cloudflare Pages Template repo.

```ts
// Respond to OPTIONS method
export const onRequestOptions: PagesFunction = async () => {
	return new Response(null, {
		status: 204,
		headers: {
			"Access-Control-Allow-Origin": "*",
			"Access-Control-Allow-Headers": "*",
			"Access-Control-Allow-Methods": "GET, OPTIONS",
			"Access-Control-Max-Age": "86400",
		},
	});
};

// Set CORS to all /api responses
export const onRequest: PagesFunction = async (context) => {
	const response = await context.next();
	response.headers.set("Access-Control-Allow-Origin", "*");
	response.headers.set("Access-Control-Max-Age", "86400");
	return response;
};
```

---

# Examples

URL: https://developers.cloudflare.com/pages/functions/examples/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Cloudflare Access

URL: https://developers.cloudflare.com/pages/functions/plugins/cloudflare-access/

import { PackageManagers } from "~/components";

The Cloudflare Access Pages Plugin is a middleware to validate Cloudflare Access JWT assertions. It also includes an API to lookup additional information about a given user's JWT.

## Installation

<PackageManagers pkg="@cloudflare/pages-plugin-cloudflare-access" />

## Usage

```typescript
import cloudflareAccessPlugin from "@cloudflare/pages-plugin-cloudflare-access";

export const onRequest: PagesFunction = cloudflareAccessPlugin({
	domain: "https://test.cloudflareaccess.com",
	aud: "4714c1358e65fe4b408ad6d432a5f878f08194bdb4752441fd56faefa9b2b6f2",
});
```

The Plugin takes an object with two properties: the `domain` of your Cloudflare Access account, and the policy `aud` (audience) to validate against. Any requests which fail validation will be returned a `403` status code.

### Access the JWT payload

If you need to use the JWT payload in your application (for example, you need the user's email address), this Plugin will make this available for you at `data.cloudflareAccess.JWT.payload`.

For example:

```typescript
import type { PluginData } from "@cloudflare/pages-plugin-cloudflare-access";

export const onRequest: PagesFunction<unknown, any, PluginData> = async ({
	data,
}) => {
	return new Response(
		`Hello, ${data.cloudflareAccess.JWT.payload.email || "service user"}!`,
	);
};
```

The [entire JWT payload](/cloudflare-one/identity/authorization-cookie/application-token/#payload) will be made available on `data.cloudflareAccess.JWT.payload`. Be aware that the fields available differ between identity authorizations (for example, a user in a browser) and non-identity authorizations (for example, a service token).

### Look up identity

In order to get more information about a given user's identity, use the provided `getIdentity` API function:

```typescript
import { getIdentity } from "@cloudflare/pages-plugin-cloudflare-access/api";

export const onRequest: PagesFunction = async ({ data }) => {
	const identity = await getIdentity({
		jwt: "eyJhbGciOiJIUzI1NiIsImtpZCI6IjkzMzhhYmUxYmFmMmZlNDkyZjY0NmE3MzZmMjVhZmJmN2IwMjVlMzVjNjI3YmU0ZjYwYzQxNGQ0YzczMDY5YjgiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOlsiOTdlMmFhZTEyMDEyMWY5MDJkZjhiYzk5ZmMzNDU5MTNhYjE4NmQxNzRmMzA3OWVhNzI5MjM2NzY2YjJlN2M0YSJdLCJlbWFpbCI6ImFkbWluQGV4YW1wbGUuY29tIiwiZXhwIjoxNTE5NDE4MjE0LCJpYXQiOjE1MTkzMzE4MTUsImlzcyI6Imh0dHBzOi8vdGVzdC5jbG91ZGZsYXJlYWNjZXNzLmNvbSIsIm5vbmNlIjoiMWQ4MDgzZjcwOGE0Nzk4MjI5NmYyZDk4OTZkNzBmMjA3YTI3OTM4ZjAyNjU0MGMzOTJiOTAzZTVmZGY0ZDZlOSIsInN1YiI6ImNhNjM5YmI5LTI2YWItNDJlNS1iOWJmLTNhZWEyN2IzMzFmZCJ9.05vGt-_0Mw6WEFJF3jpaqkNb88PUMplsjzlEUvCEfnQ",
		domain: "https://test.cloudflareaccess.com",
	});

	return new Response(`Hello, ${identity.name || "service user"}!`);
};
```

The `getIdentity` function takes an object with two properties: a `jwt` string, and a `domain` string. It returns a `Promise` of [the object returned by the `/cdn-cgi/access/get-identity` endpoint](/cloudflare-one/identity/authorization-cookie/application-token/#user-identity). This is particularly useful if you want to use a user's group membership for something like application permissions.

For convenience, this same information can be fetched for the current request's JWT with the `data.cloudflareAccess.JWT.getIdentity` function, (assuming you have already validated the request with the Plugin as above):

```typescript
import type { PluginData } from "@cloudflare/pages-plugin-cloudflare-access";

export const onRequest: PagesFunction<unknown, any, PluginData> = async ({
	data,
}) => {
	const identity = await data.cloudflareAccess.JWT.getIdentity();

	return new Response(`Hello, ${identity.name || "service user"}!`);
};
```

### Login and logout URLs

If you want to force a login or logout, use these utility functions to generate URLs and redirect a user:

```typescript
import { generateLoginURL } from "@cloudflare/pages-plugin-cloudflare-access/api";

export const onRequest = () => {
	const loginURL = generateLoginURL({
		redirectURL: "https://example.com/greet",
		domain: "https://test.cloudflareaccess.com",
		aud: "4714c1358e65fe4b408ad6d432a5f878f08194bdb4752441fd56faefa9b2b6f2",
	});

	return new Response(null, {
		status: 302,
		headers: { Location: loginURL },
	});
};
```

```typescript
import { generateLogoutURL } from "@cloudflare/pages-plugin-cloudflare-access/api";

export const onRequest = () =>
	new Response(null, {
		status: 302,
		headers: {
			Location: generateLogoutURL({
				domain: "https://test.cloudflareaccess.com",
			}),
		},
	});
```

---

# Community Plugins

URL: https://developers.cloudflare.com/pages/functions/plugins/community-plugins/

The following are some of the community-maintained Pages Plugins. If you have created a Pages Plugin and would like to share it with developers, create a PR to add it to this alphabeticallly-ordered list using the link in the footer.

- [pages-plugin-asset-negotiation](https://github.com/Cherry/pages-plugin-asset-negotiation)

  Given a folder of assets in multiple formats, this Plugin will automatically negotiate with a client to serve an optimized version of a requested asset.

- [proxyflare-for-pages](https://github.com/flaregun-net/proxyflare-for-pages)

  Move traffic around your Cloudflare Pages domain with ease. Proxyflare is a reverse-proxy that enables you to:

  - Port forward, redirect, and reroute HTTP and websocket traffic anywhere on the Internet.
  - Mount an entire website on a subpath (for example, `mysite.com/docs`) on your apex domain.
  - Serve static text (like `robots.txt` and other structured metadata) from any endpoint.

  Refer to [Proxyflare](https://proxyflare.works) for more information.

- [cloudflare-pages-plugin-rollbar](https://github.com/hckr-studio/cloudflare-pages-plugin-rollbar)

  The [Rollbar](https://rollbar.com/) Pages Plugin captures and logs all exceptions which occur below it in the execution chain
  of your [Pages Functions](/pages/functions/). Discover, predict, and resolve errors in real-time.

- [cloudflare-pages-plugin-trpc](https://github.com/toyamarinyon/cloudflare-pages-plugin-trpc)

  Allows developers to quickly create a tRPC server with a Cloudflare Pages Function.

- [pages-plugin-twind](https://github.com/helloimalastair/twind-plugin)

  Automatically injects Tailwind CSS styles into HTML pages after analyzing which classes are used.

---

# Google Chat

URL: https://developers.cloudflare.com/pages/functions/plugins/google-chat/

import { PackageManagers } from "~/components";

The Google Chat Pages Plugin creates a Google Chat bot which can respond to messages. It also includes an API for interacting with Google Chat (for example, for creating messages) without the need for user input. This API is useful for situations such as alerts.

## Installation

<PackageManagers pkg="@cloudflare/pages-plugin-google-chat" />

## Usage

```typescript
import googleChatPlugin from "@cloudflare/pages-plugin-google-chat";

export const onRequest: PagesFunction = googleChatPlugin(async (message) => {
	if (message.text.includes("ping")) {
		return { text: "pong" };
	}

	return { text: "Sorry, I could not understand your message." };
});
```

The Plugin takes a function, which in turn takes an incoming message, and returns a `Promise` of a response message (or `void` if there should not be any response).

The Plugin only exposes a single route, which is the URL you should set in the Google Cloud Console when creating the bot.

![Google Cloud Console's Connection Settings for the Google Chat API showing 'App URL' selected and 'https://example.com/google-chat' entered into the 'App URL' text input.](~/assets/images/pages/platform/functions/google-chat.png)

### API

The Google Chat API can be called directly using the `GoogleChatAPI` class:

```typescript
import { GoogleChatAPI } from "@cloudflare/pages-plugin-google-chat/api";

export const onRequest: PagesFunction = () => {
	// Initialize a GoogleChatAPI with your service account's credentials
	const googleChat = new GoogleChatAPI({
		credentials: {
			client_email: "SERVICE_ACCOUNT_EMAIL_ADDRESS",
			private_key: "SERVICE_ACCOUNT_PRIVATE_KEY",
		},
	});

	// Post a message
	// https://developers.google.com/chat/api/reference/rest/v1/spaces.messages/create
	const message = await googleChat.createMessage(
		{ parent: "spaces/AAAAAAAAAAA" },
		undefined,
		{
			text: "I'm an alert!",
		},
	);

	return new Response("Alert sent.");
};
```

We recommend storing your service account's credentials in KV rather than in plain text as above.

The following functions are available on a `GoogleChatAPI` instance. Each take up to three arguments: an object of path parameters, an object of query parameters, and an object of the request body; as described in the [Google Chat API's documentation](https://developers.google.com/chat/api/reference/rest).

- [`downloadMedia`](https://developers.google.com/chat/api/reference/rest/v1/media/download)
- [`getSpace`](https://developers.google.com/chat/api/reference/rest/v1/spaces/get)
- [`listSpaces`](https://developers.google.com/chat/api/reference/rest/v1/spaces/list)
- [`getMember`](https://developers.google.com/chat/api/reference/rest/v1/spaces.members/get)
- [`listMembers`](https://developers.google.com/chat/api/reference/rest/v1/spaces.members/list)
- [`createMessage`](https://developers.google.com/chat/api/reference/rest/v1/spaces.messages/create)
- [`deleteMessage`](https://developers.google.com/chat/api/reference/rest/v1/spaces.messages/delete)
- [`getMessage`](https://developers.google.com/chat/api/reference/rest/v1/spaces.messages/get)
- [`updateMessage`](https://developers.google.com/chat/api/reference/rest/v1/spaces.messages/update)
- [`getAttachment`](https://developers.google.com/chat/api/reference/rest/v1/spaces.messages.attachments/get)

---

# GraphQL

URL: https://developers.cloudflare.com/pages/functions/plugins/graphql/

import { PackageManagers } from "~/components";

The GraphQL Pages Plugin creates a GraphQL server which can respond to `application/json` and `application/graphql` `POST` requests. It responds with [the GraphQL Playground](https://github.com/graphql/graphql-playground) for `GET` requests.

## Installation

<PackageManagers pkg="@cloudflare/pages-plugin-graphql" />

## Usage

```typescript
import graphQLPlugin from "@cloudflare/pages-plugin-graphql";
import {
	graphql,
	GraphQLSchema,
	GraphQLObjectType,
	GraphQLString,
} from "graphql";

const schema = new GraphQLSchema({
	query: new GraphQLObjectType({
		name: "RootQueryType",
		fields: {
			hello: {
				type: GraphQLString,
				resolve() {
					return "Hello, world!";
				},
			},
		},
	}),
});

export const onRequest: PagesFunction = graphQLPlugin({
	schema,
	graphql,
});
```

This Plugin only exposes a single route, so wherever it is mounted is wherever it will be available. In the above example, because it is mounted in `functions/graphql.ts`, the server will be available on `/graphql` of your Pages project.

---

# hCaptcha

URL: https://developers.cloudflare.com/pages/functions/plugins/hcaptcha/

import { Render, PackageManagers } from "~/components";

The hCaptcha Pages Plugin validates hCaptcha tokens.

## Installation

<PackageManagers pkg="@cloudflare/pages-plugin-hcaptcha" />

## Usage

```typescript
import hCaptchaPlugin from "@cloudflare/pages-plugin-hcaptcha";

export const onRequestPost: PagesFunction[] = [
	hCaptchaPlugin({
		secret: "0x0000000000000000000000000000000000000000",
		sitekey: "10000000-ffff-ffff-ffff-000000000001",
	}),
	async (context) => {
		// Request has been validated as coming from a human

		const formData = await context.request.formData();

		// Store user credentials

		return new Response("Successfully registered!");
	},
];
```

This Plugin only exposes a single route. It will be available wherever it is mounted. In the above example, because it is mounted in `functions/register.ts`, it will validate requests to `/register`. The Plugin is mounted with a single object parameter with the following properties.

[`secret`](https://dashboard.hcaptcha.com/settings) (mandatory) and [`sitekey`](https://dashboard.hcaptcha.com/sites) (optional) can both be found in your hCaptcha dashboard.

`response` and `remoteip` are optional strings. `response` the hCaptcha token to verify (defaults to extracting `h-captcha-response` from a `multipart/form-data` request). `remoteip` should be requester's IP address (defaults to the `CF-Connecting-IP` header of the request).

`onError` is an optional function which takes the Pages Function context object and returns a `Promise` of a `Response`. By default, it will return a human-readable error `Response`.

`data.hCaptcha` will be populated in subsequent Pages Functions (including for the `onError` function) with [the hCaptcha response object](https://docs.hcaptcha.com/#verify-the-user-response-server-side).

---

# Honeycomb

URL: https://developers.cloudflare.com/pages/functions/plugins/honeycomb/

import { PackageManagers } from "~/components";

The Honeycomb Pages Plugin automatically sends traces to Honeycomb for analysis and observability.

## Installation

<PackageManagers pkg="@cloudflare/pages-plugin-honeycomb" />

## Usage

The following usage example uses environment variables you will need to set in your Pages project settings.

```typescript
import honeycombPlugin from "@cloudflare/pages-plugin-honeycomb";

export const onRequest: PagesFunction<{
	HONEYCOMB_API_KEY: string;
	HONEYCOMB_DATASET: string;
}> = (context) => {
	return honeycombPlugin({
		apiKey: context.env.HONEYCOMB_API_KEY,
		dataset: context.env.HONEYCOMB_DATASET,
	})(context);
};
```

Alternatively, you can hard-code (not advisable for API key) your settings the following way:

```typescript
import honeycombPlugin from "@cloudflare/pages-plugin-honeycomb";

export const onRequest = honeycombPlugin({
	apiKey: "YOUR_HONEYCOMB_API_KEY",
	dataset: "YOUR_HONEYCOMB_DATASET_NAME",
});
```

This Plugin is based on the `@cloudflare/workers-honeycomb-logger` and accepts the same [configuration options](https://github.com/cloudflare/workers-honeycomb-logger#config).

Ensure that you enable the option to **Automatically unpack nested JSON** and set the **Maximum unpacking depth** to **5** in your Honeycomb dataset settings.

![Follow the instructions above to toggle on Automatically unpack nested JSON and set the Maximum unpacking depth option to 5 in the Honeycomb dashboard](~/assets/images/pages/platform/functions/honeycomb.png)

### Additional context

`data.honeycomb.tracer` has two methods for attaching additional information about a given trace:

- `data.honeycomb.tracer.log` which takes a single argument, a `String`.
- `data.honeycomb.tracer.addData` which takes a single argument, an object of arbitrary data.

More information about these methods can be seen on [`@cloudflare/workers-honeycomb-logger`'s documentation](https://github.com/cloudflare/workers-honeycomb-logger#adding-logs-and-other-data).

For example, if you wanted to use the `addData` method to attach user information:

```typescript
import type { PluginData } from "@cloudflare/pages-plugin-honeycomb";

export const onRequest: PagesFunction<unknown, any, PluginData> = async ({
	data,
	next,
	request,
}) => {
	// Authenticate the user from the request and extract user's email address
	const email = await getEmailFromRequest(request);

	data.honeycomb.tracer.addData({ email });

	return next();
};
```

---

# Pages Plugins

URL: https://developers.cloudflare.com/pages/functions/plugins/

import { DirectoryListing, Render } from "~/components";

Cloudflare maintains a number of official Pages Plugins for you to use in your Pages projects:

<DirectoryListing />

---

## Author a Pages Plugin

A Pages Plugin is a Pages Functions distributable which includes built-in routing and functionality. Developers can include a Plugin as a part of their Pages project wherever they chose, and can pass it some configuration options. The full power of Functions is available to Plugins, including middleware, parameterized routes, and static assets.

For example, a Pages Plugin could:

- Intercept HTML pages and inject in a third-party script.
- Proxy a third-party service's API.
- Validate authorization headers.
- Provide a full admin web app experience.
- Store data in KV or Durable Objects.
- Server-side render (SSR) webpages with data from a CMS.
- Report errors and track performance.

A Pages Plugin is essentially a library that developers can use to augment their existing Pages project with a deep integration to Functions.

## Use a Pages Plugin

Developers can enhance their projects by mounting a Pages Plugin at a route of their application. Plugins will provide instructions of where they should typically be mounted (for example, an admin interface might be mounted at `functions/admin/[[path]].ts`, and an error logger might be mounted at `functions/_middleware.ts`). Additionally, each Plugin may take some configuration (for example, with an API token).

---

## Static form example

In this example, you will build a Pages Plugin and then include it in a project.

The first Plugin should:

- intercept HTML forms.
- store the form submission in [KV](/kv/api/).
- respond to submissions with a developer's custom response.

### 1. Create a new Pages Plugin

Create a `package.json` with the following:

```json
{
	"name": "@cloudflare/static-form-interceptor",
	"main": "dist/index.js",
	"types": "index.d.ts",
	"files": ["dist", "index.d.ts", "tsconfig.json"],
	"scripts": {
		"build": "npx wrangler pages functions build --plugin --outdir=dist",
		"prepare": "npm run build"
	}
}
```

:::note

The `npx wrangler pages functions build` command supports a number of arguments, including:

- `--plugin` which tells the command to build a Pages Plugin, (rather than Pages Functions as part of a Pages project)
- `--outdir` which allows you to specify where to output the built Plugin
- `--external` which can be used to avoid bundling external modules in the Plugin
- `--watch` argument tells the command to watch for changes to the source files and rebuild the Plugin automatically

For more information about the available arguments, run `npx wrangler pages functions build --help`.

:::

In our example, `dist/index.js` will be the entrypoint to your Plugin. This is a generated file built by Wrangler with the `npm run build` command. Add the `dist/` directory to your `.gitignore`.

Next, create a `functions` directory and start coding your Plugin. The `functions` folder will be mounted at some route by the developer, so consider how you want to structure your files. Generally:

- if you want your Plugin to run on a single route of the developer's choice (for example, `/foo`), create a `functions/index.ts` file.
- if you want your Plugin to be mounted and serve all requests beyond a certain path (for example, `/admin/login` and `/admin/dashboard`), create a `functions/[[path]].ts` file.
- if you want your Plugin to intercept requests but fallback on either other Functions or the project's static assets, create a `functions/_middleware.ts` file.

:::note[Do not include the mounted path in your Plugin]

Your Plugin should not use the mounted path anywhere in the file structure (for example, `/foo` or `/admin`). Developers should be free to mount your Plugin wherever they choose, but you can make recommendations of how you expect this to be mounted in your `README.md`.

:::

You are free to use as many different files as you need. The structure of a Plugin is exactly the same as Functions in a Pages project today, except that the handlers receive a new property of their parameter object, `pluginArgs`. This property is the initialization parameter that a developer passes when mounting a Plugin. You can use this to receive API tokens, KV/Durable Object namespaces, or anything else that your Plugin needs to work.

Returning to your static form example, if you want to intercept requests and override the behavior of an HTML form, you need to create a `functions/_middleware.ts`. Developers could then mount your Plugin on a single route, or on their entire project.

```typescript
class FormHandler {
	element(element) {
		const name = element.getAttribute("data-static-form-name");
		element.setAttribute("method", "POST");
		element.removeAttribute("action");
		element.append(
			`<input type="hidden" name="static-form-name" value="${name}" />`,
			{ html: true },
		);
	}
}

export const onRequestGet = async (context) => {
	// We first get the original response from the project
	const response = await context.next();

	// Then, using HTMLRewriter, we transform `form` elements with a `data-static-form-name` attribute, to tell them to POST to the current page
	return new HTMLRewriter()
		.on("form[data-static-form-name]", new FormHandler())
		.transform(response);
};

export const onRequestPost = async (context) => {
	// Parse the form
	const formData = await context.request.formData();
	const name = formData.get("static-form-name");
	const entries = Object.fromEntries(
		[...formData.entries()].filter(([name]) => name !== "static-form-name"),
	);

	// Get the arguments given to the Plugin by the developer
	const { kv, respondWith } = context.pluginArgs;

	// Store form data in KV under key `form-name:YYYY-MM-DDTHH:MM:SSZ`
	const key = `${name}:${new Date().toISOString()}`;
	context.waitUntil(kv.put(name, JSON.stringify(entries)));

	// Respond with whatever the developer wants
	const response = await respondWith({ formData });
	return response;
};
```

### 2. Type your Pages Plugin

To create a good developer experience, you should consider adding TypeScript typings to your Plugin. This allows developers to use their IDE features for autocompletion, and also ensure that they include all the parameters you are expecting.

In the `index.d.ts`, export a function which takes your `pluginArgs` and returns a `PagesFunction`. For your static form example, you take two properties, `kv`, a KV namespace, and `respondWith`, a function which takes an object with a `formData` property (`FormData`) and returns a `Promise` of a `Response`:

```typescript
export type PluginArgs = {
	kv: KVNamespace;
	respondWith: (args: { formData: FormData }) => Promise<Response>;
};

export default function (args: PluginArgs): PagesFunction;
```

### 3. Test your Pages Plugin

We are still working on creating a great testing experience for Pages Plugins authors. Please be patient with us until all those pieces come together. In the meantime, you can create an example project and include your Plugin manually for testing.

### 4. Publish your Pages Plugin

You can distribute your Plugin however you choose. Popular options include publishing on [npm](https://www.npmjs.com/), showcasing it in the #what-i-built or #pages-discussions channels in our [Developer Discord](https://discord.com/invite/cloudflaredev), and open-sourcing on [GitHub](https://github.com/).

Make sure you are including the generated `dist/` directory, your typings `index.d.ts`, as well as a `README.md` with instructions on how developers can use your Plugin.

---

### 5. Install your Pages Plugin

If you want to include a Pages Plugin in your application, you need to first install that Plugin to your project.

If you are not yet using `npm` in your project, run `npm init` to create a `package.json` file. The Plugin's `README.md` will typically include an installation command (for example, `npm install --save @cloudflare/static-form-interceptor`).

### 6. Mount your Pages Plugin

The `README.md` of the Plugin will likely include instructions for how to mount the Plugin in your application. You will need to:

1. Create a `functions` directory, if you do not already have one.
2. Decide where you want this Plugin to run and create a corresponding file in the `functions` directory.
3. Import the Plugin and export an `onRequest` method in this file, initializing the Plugin with any arguments it requires.

In the static form example, the Plugin you have created already was created as a middleware. This means it can run on either a single route, or across your entire project. If you had a single contact form on your website at `/contact`, you could create a `functions/contact.ts` file to intercept just that route. You could also create a `functions/_middleware.ts` file to intercept all other routes and any other future forms you might create. As the developer, you can choose where this Plugin can run.

A Plugin's default export is a function which takes the same context parameter that a normal Pages Functions handler is given.

```typescript
import staticFormInterceptorPlugin from "@cloudflare/static-form-interceptor";

export const onRequest = (context) => {
	return staticFormInterceptorPlugin({
		kv: context.env.FORM_KV,
		respondWith: async ({ formData }) => {
			// Could call email/notification service here
			const name = formData.get("name");
			return new Response(`Thank you for your submission, ${name}!`);
		},
	})(context);
};
```

### 7. Test your Pages Plugin

You can use `wrangler pages dev` to test a Pages project, including any Plugins you have installed. Remember to include any KV bindings and environment variables that the Plugin is expecting.

With your Plugin mounted on the `/contact` route, a corresponding HTML file might look like this:

```html
<!DOCTYPE html>
<html>
	<body>
		<h1>Contact us</h1>
		<!-- Include the `data-static-form-name` attribute to name the submission -->
		<form data-static-form-name="contact">
			<label>
				<span>Name</span>
				<input type="text" autocomplete="name" name="name" />
			</label>
			<label>
				<span>Message</span>
				<textarea name="message"></textarea>
			</label>
		</form>
	</body>
</html>
```

Your plugin should pick up the `data-static-form-name="contact"` attribute, set the `method="POST"`, inject in an `<input type="hidden" name="static-form-name" value="contact" />` element, and capture `POST` submissions.

### 8. Deploy your Pages project

Make sure the new Plugin has been added to your `package.json` and that everything works locally as you would expect. You can then `git commit` and `git push` to trigger a Cloudflare Pages deployment.

If you experience any problems with any one Plugin, file an issue on that Plugin's bug tracker.

If you experience any problems with Plugins in general, we would appreciate your feedback in the #pages-discussions channel in [Discord](https://discord.com/invite/cloudflaredev)! We are excited to see what you build with Plugins and welcome any feedback about the authoring or developer experience. Let us know in the Discord channel if there is anything you need to make Plugins even more powerful.

---

## Chain your Plugin

Finally, as with Pages Functions generally, it is possible to chain together Plugins in order to combine together different features. Middleware defined higher up in the filesystem will run before other handlers, and individual files can chain together Functions in an array like so:

```typescript
import sentryPlugin from "@cloudflare/pages-plugin-sentry";
import cloudflareAccessPlugin from "@cloudflare/pages-plugin-cloudflare-access";
import adminDashboardPlugin from "@cloudflare/a-fictional-admin-plugin";

export const onRequest = [
	// Initialize a Sentry Plugin to capture any errors
	sentryPlugin({ dsn: "https://sentry.io/welcome/xyz" }),

	// Initialize a Cloudflare Access Plugin to ensure only administrators can access this protected route
	cloudflareAccessPlugin({
		domain: "https://test.cloudflareaccess.com",
		aud: "4714c1358e65fe4b408ad6d432a5f878f08194bdb4752441fd56faefa9b2b6f2",
	}),

	// Populate the Sentry plugin with additional information about the current user
	(context) => {
		const email =
			context.data.cloudflareAccessJWT.payload?.email || "service user";

		context.data.sentry.setUser({ email });

		return next();
	},

	// Finally, serve the admin dashboard plugin, knowing that errors will be captured and that every incoming request has been authenticated
	adminDashboardPlugin(),
];
```

---

# Sentry

URL: https://developers.cloudflare.com/pages/functions/plugins/sentry/

import { PackageManagers } from "~/components";

:::note

Sentry now provides official support for Cloudflare Workers and Pages. Refer to the [Sentry documentation](https://docs.sentry.io/platforms/javascript/guides/cloudflare/) for more details.

:::

The Sentry Pages Plugin captures and logs all exceptions which occur below it in the execution chain of your Pages Functions. It is therefore recommended that you install this Plugin at the root of your application in `functions/_middleware.ts` as the very first Plugin.

## Installation

<PackageManagers pkg="@cloudflare/pages-plugin-sentry" />

## Usage

```typescript
import sentryPlugin from "@cloudflare/pages-plugin-sentry";

export const onRequest: PagesFunction = sentryPlugin({
	dsn: "https://sentry.io/welcome/xyz",
});
```

The Plugin uses [Toucan](https://github.com/robertcepa/toucan-js). Refer to the Toucan README to [review the options it can take](https://github.com/robertcepa/toucan-js#other-options). `context`, `request`, and `event` are automatically populated and should not be manually configured.

If your [DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/) is held as an environment variable or in KV, you can access it like so:

```typescript
import sentryPlugin from "@cloudflare/pages-plugin-sentry";

export const onRequest: PagesFunction<{
	SENTRY_DSN: string;
}> = (context) => {
	return sentryPlugin({ dsn: context.env.SENTRY_DSN })(context);
};
```

```typescript
import sentryPlugin from "@cloudflare/pages-plugin-sentry";

export const onRequest: PagesFunction<{
	KV: KVNamespace;
}> = async (context) => {
	return sentryPlugin({ dsn: await context.env.KV.get("SENTRY_DSN") })(context);
};
```

### Additional context

If you need to set additional context for Sentry (for example, user information or additional logs), use the `data.sentry` instance in any Function below the Plugin in the execution chain.

For example, you can access `data.sentry` and set user information like so:

```typescript
import type { PluginData } from "@cloudflare/pages-plugin-sentry";

export const onRequest: PagesFunction<unknown, any, PluginData> = async ({
	data,
	next,
}) => {
	// Authenticate the user from the request and extract user's email address
	const email = await getEmailFromRequest(request);

	data.sentry.setUser({ email });

	return next();
};
```

Again, the full list of features can be found in [Toucan's documentation](https://github.com/robertcepa/toucan-js#features).

---

# Stytch

URL: https://developers.cloudflare.com/pages/functions/plugins/stytch/

import { PackageManagers } from "~/components";

The Stytch Pages Plugin is a middleware which validates all requests and their `session_token`.

## Installation

<PackageManagers pkg="@cloudflare/pages-plugin-stytch" />

## Usage

```typescript
import stytchPlugin from "@cloudflare/pages-plugin-stytch";
import { envs } from "@cloudflare/pages-plugin-stytch/api";

export const onRequest: PagesFunction = stytchPlugin({
	project_id: "YOUR_STYTCH_PROJECT_ID",
	secret: "YOUR_STYTCH_PROJECT_SECRET",
	env: envs.live,
});
```

We recommend storing your secret in KV rather than in plain text as above.

The Stytch Plugin takes a single argument, an object with several properties. `project_id` and `secret` are mandatory strings and can be found in [Stytch's dashboard](https://stytch.com/dashboard/api-keys). `env` is also a mandatory string, and can be populated with the `envs.test` or `envs.live` variables in the API. By default, the Plugin validates a `session_token` cookie of the incoming request, but you can also optionally pass in a `session_token` or `session_jwt` string yourself if you are using some other mechanism to identify user sessions. Finally, you can also pass in a `session_duration_minutes` in order to extend the lifetime of the session. More information on these parameters can be found in [Stytch's documentation](https://stytch.com/docs/api/session-auth).

The validated session response containing user information is made available to subsequent Pages Functions on `data.stytch.session`.

---

# Static Forms

URL: https://developers.cloudflare.com/pages/functions/plugins/static-forms/

import { PackageManagers } from "~/components";

The Static Forms Pages Plugin intercepts all form submissions made which have the `data-static-form-name` attribute set. This allows you to take action on these form submissions by, for example, saving the submission to KV.

## Installation

<PackageManagers pkg="@cloudflare/pages-plugin-static-forms" />

## Usage

```typescript
import staticFormsPlugin from "@cloudflare/pages-plugin-static-forms";

export const onRequest: PagesFunction = staticFormsPlugin({
	respondWith: ({ formData, name }) => {
		const email = formData.get("email");
		return new Response(
			`Hello, ${email}! Thank you for submitting the ${name} form.`,
		);
	},
});
```

```html
<body>
	<h1>Sales enquiry</h1>
	<form data-static-form-name="sales">
		<label>Email address <input type="email" name="email" /></label>
		<label>Message <textarea name="message"></textarea></label>
		<button type="submit">Submit</button>
	</form>
</body>
```

The Plugin takes a single argument, an object with a `respondWith` property. This function takes an object with a `formData` property (the [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) instance) and `name` property (the name value of your `data-static-form-name` attribute). It should return a `Response` or `Promise` of a `Response`. It is in this `respondWith` function that you can take action such as serializing the `formData` and saving it to a KV namespace.

The `method` and `action` attributes of the HTML form do not need to be set. The Plugin will automatically override them to allow it to intercept the submission.

---

# Turnstile

URL: https://developers.cloudflare.com/pages/functions/plugins/turnstile/

import { Render, PackageManagers } from "~/components";

[Turnstile](/turnstile/) is Cloudflare's smart CAPTCHA alternative.

The Turnstile Pages Plugin validates Cloudflare Turnstile tokens.

## Installation

<PackageManagers pkg="@cloudflare/pages-plugin-turnstile" />

## Usage

```typescript
import turnstilePlugin from "@cloudflare/pages-plugin-turnstile";

/**
 * POST /api/submit-with-plugin
 */

export const onRequestPost = [
	turnstilePlugin({
		// This is the demo secret key. In prod, we recommend you store
		// your secret key(s) safely.
		secret: "0x4AAAAAAASh4E5cwHGsTTePnwcPbnFru6Y",
	}),
	// Alternatively, this is how you can use a secret key which has been stored as an environment variable
	// (async (context) => {
	//   return turnstilePlugin({secret: context.env.SECRET_KEY})(context)
	// }),
	async (context) => {
		// Request has been validated as coming from a human
		const formData = await context.request.formData();
		// Additional solve metadata data is available at context.data.turnstile
		return new Response(
			`Successfully verified! ${JSON.stringify(context.data.turnstile)}`,
		);
	},
];
```

This Plugin only exposes a single route to verify an incoming Turnstile response in a `POST` as the `cf-turnstile-response` parameter. It will be available wherever it is mounted. In the example above, it is mounted in `functions/register.ts`. As a result, it will validate requests to `/register`.

## Properties

The Plugin is mounted with a single object parameter with the following properties:

[`secret`](https://dash.cloudflare.com/login) is mandatory and can both be found in your Turnstile dashboard.

`response` and `remoteip` are optional strings. `response` is the Turnstile token to verify. If it is not provided, the plugin will default to extracting `cf-turnstile-response` value from a `multipart/form-data` request). `remoteip` is the requester's IP address. This defaults to the `CF-Connecting-IP` header of the request.

`onError` is an optional function which takes the Pages Function context object and returns a `Promise` of a `Response`. By default, it will return a human-readable error `Response`.

`context.data.turnstile` will be populated in subsequent Pages Functions (including for the `onError` function) with [the Turnstile Siteverify response object](/turnstile/get-started/server-side-validation/).

---

# vercel/og

URL: https://developers.cloudflare.com/pages/functions/plugins/vercel-og/

import { PackageManagers } from "~/components";

The `@vercel/og` Pages Plugin is a middleware which renders social images for webpages. It also includes an API to create arbitrary images.

As the name suggests, it is powered by [`@vercel/og`](https://vercel.com/docs/concepts/functions/edge-functions/og-image-generation). This plugin and its underlying [Satori](https://github.com/vercel/satori) library was created by the Vercel team.

## Install

To install the `@vercel/og` Pages Plugin, run:

<PackageManagers pkg="@cloudflare/pages-plugin-vercel-og" />

## Use

```typescript
import React from "react";
import vercelOGPagesPlugin from "@cloudflare/pages-plugin-vercel-og";

interface Props {
	ogTitle: string;
}

export const onRequest = vercelOGPagesPlugin<Props>({
	imagePathSuffix: "/social-image.png",
	component: ({ ogTitle, pathname }) => {
		return <div style={{ display: "flex" }}>{ogTitle}</div>;
	},
	extractors: {
		on: {
			'meta[property="og:title"]': (props) => ({
				element(element) {
					props.ogTitle = element.getAttribute("content");
				},
			}),
		},
	},
	autoInject: {
		openGraph: true,
	},
});
```

The Plugin takes an object with six properties:

- `imagePathSuffix`: the path suffix to make the generate image available at. For example, if you mount this Plugin at `functions/blog/_middleware.ts`, set the `imagePathSuffix` as `/social-image.png` and have a `/blog/hello-world` page, the image will be available at `/blog/hello-world/social-image.png`.

- `component`: the React component that will be used to render the image. By default, the React component is given a `pathname` property equal to the pathname of the underlying webpage (for example, `/blog/hello-world`), but more dynamic properties can be provided with the `extractors` option.

- `extractors`: an optional object with two optional properties: `on` and `onDocument`. These properties can be set to a function which takes an object and returns a [`HTMLRewriter` element handler](/workers/runtime-apis/html-rewriter/#element-handlers) or [document handler](/workers/runtime-apis/html-rewriter/#document-handlers) respectively. The object parameter can be mutated in order to provide the React component with additional properties. In the example above, you will use an element handler to extract the `og:title` meta tag from the webpage and pass that to the React component as the `ogTitle` property. This is the primary mechanism you will use to create dynamic images which use values from the underlying webpage.

- `options`: [an optional object which is given directly to the `@vercel/og` library](https://vercel.com/docs/concepts/functions/edge-functions/og-image-generation/og-image-api).

- `onError`: an optional function which returns a `Response` or a promise of a `Response`. This function is called when a request is made to the `imagePathSuffix` and `extractors` are provided but the underlying webpage is not valid HTML. Defaults to returning a `404` response.

- `autoInject`: an optional object with an optional property: `openGraph`. If set to `true`, the Plugin will automatically set the `og:image`, `og:image:height` and `og:image:width` meta tags on the underlying webpage.

### Generate arbitrary images

Use this Plugin's API to generate arbitrary images, not just as middleware.

For example, the below code will generate an image saying "Hello, world!" which is available at `/greet`.

```typescript
import React from "react";
import { ImageResponse } from "@cloudflare/pages-plugin-vercel-og/api";

export const onRequest: PagesFunction = async () => {
  return new ImageResponse(
    <div style={{ display: "flex" }}>Hello, world!</div>,
    {
      width: 1200,
      height: 630,
    }
  );
};
```

This is the same API that the underlying [`@vercel/og` library](https://vercel.com/docs/concepts/functions/edge-functions/og-image-generation/og-image-api) offers.

---

# Add a React form with Formspree

URL: https://developers.cloudflare.com/pages/tutorials/add-a-react-form-with-formspree/

import { PackageManagers } from "~/components";

Almost every React website needs a form to collect user data. [Formspree](https://formspree.io/) is a back-end service that handles form processing and storage, allowing developers to include forms on their website without writing server-side code or functions.

In this tutorial, you will create a `<form>` component using React and add it to a single page application built with `create-react-app`. Though you are using `create-react-app` (CRA), the concepts will apply to any React framework including Next.js, Gatsby, and more. You will use Formspree to collect the submitted data and send out email notifications when new submissions arrive, without requiring any server-side coding.

You will deploy your site to Cloudflare Pages. Refer to the [Get started guide](/pages/get-started/) to familiarize yourself with the platform.

## Setup

To begin, create a new React project on your local machine with `create-react-app`. Then create a [new GitHub repository](https://repo.new/), and attach the GitHub location as a remote destination:

```sh
# create new project with create-react-app
npx create-react-app new-app
# enter new directory
cd new-app
# attach git remote
git remote add origin git@github.com:<username>/<repo>.git
# change default branch name
git branch -M main
```

You may now modify the React application in the `new-app` directory you created.

## The front-end code

The starting point for `create-react-app` includes a simple Hello World website. You will be adding a Contact Us form that accepts a name, email address, and message. The form code is adapted from the HTML Forms tutorial. For a more in-depth explanation of how HTML forms work and additional learning resources, refer to the [HTML Forms tutorial](/pages/tutorials/forms/).

First, create a new react component called `ContactForm.js` and place it in the `src` folder alongside `App.js`.

```
project-root/
├─ package.json
└─ src/
   ├─ ContactForm.js
   ├─ App.js
   └─ ...
```

Next, you will build the form component using a helper library from Formspree, [`@formspree/react`](https://github.com/formspree/formspree-react). This library contains a `useForm` hook to simplify the process of handling form submission events and managing form state.

Install it with:

<PackageManagers pkg="@formspree/react" />

Then paste the following code snippet into the `ContactForm.js` file:

```jsx
import { useForm, ValidationError } from "@formspree/react";

export default function ContactForm() {
	const [state, handleSubmit] = useForm("YOUR_FORM_ID");

	if (state.succeeded) {
		return <p>Thanks for your submission!</p>;
	}

	return (
		<form method="POST" onSubmit={handleSubmit}>
			<label htmlFor="name">Full Name</label>
			<input id="name" type="text" name="name" required />
			<ValidationError prefix="Name" field="name" errors={state.errors} />

			<label htmlFor="email">Email Address</label>
			<input id="email" type="email" name="email" required />
			<ValidationError prefix="Email" field="email" errors={state.errors} />

			<label htmlFor="message">Message</label>
			<textarea id="message" name="message" required></textarea>
			<ValidationError prefix="Message" field="message" errors={state.errors} />

			<button type="submit" disabled={state.submitting}>
				Submit
			</button>
			<ValidationError errors={state.errors} />
		</form>
	);
}
```

Currently, the form contains a placeholder `YOUR_FORM_ID`. You replace this with your own form endpoint later in this tutorial.

The `useForm` hook returns a `state` object and a `handleSubmit` function which you pass to the `onSubmit` form attribute. Combined, these provide a way to submit the form data via AJAX and update form state depending on the response received.

For clarity, this form does not include any styling, but in the GitHub project ([https://github.com/formspree/formspree-example-cloudflare-react](https://github.com/formspree/formspree-example-cloudflare-react)) you can review an example of how to apply styles to the form.

:::note

`ValidationError` components are helpers that display error messages for field errors, or general form errors (if no `field` attribute is provided). For more information on validation, refer to the [Formspree React documentation](https://help.formspree.io/hc/en-us/articles/360055613373-The-Formspree-React-library#validation).

:::

To add this form to your website, import the component:

```jsx
import ContactForm from "./ContactForm";
```

Then insert the form into the page as a react component:

```jsx
<ContactForm />
```

For example, you can update your `src/App.js` file to add the form:

```jsx
import ContactForm from "./ContactForm"; // <-- import the form component
import logo from "./logo.svg";
import "./App.css";

function App() {
	return (
		<div className="App">
			<header className="App-header">
				<img src={logo} className="App-logo" alt="logo" />
				<p>
					Edit <code>src/App.js</code> and save to reload.
				</p>
				<a
					className="App-link"
					href="https://reactjs.org"
					target="_blank"
					rel="noopener noreferrer"
				>
					Learn React
				</a>

				{/* your contact form component goes here */}
				<ContactForm />
			</header>
		</div>
	);
}

export default App;
```

Now you have a single-page application containing a Contact Us form with several fields for the user to fill out. However, you have not set up the form to submit to a valid form endpoint yet. You will do that in the [next section](#the-formspree-back-end).

:::note[GitHub repository]

The source code for this example is [available on GitHub](https://github.com/formspree/formspree-example-cloudflare-react). It is a live Pages application with a [live demo](https://formspree-example-cloudflare-react.pages.dev/) available, too.

:::

## The Formspree back end

The React form is complete, however, when the user submits this form, they will get a `Form not found` error. To fix this, create a new Formspree form, and copy its unique ID into the form's `useForm` invocation.

To create a Formspree form, sign up for [an account on Formspree](https://formspree.io/register). Then create a new form with the **+ New form** button. Name your new form `Contact-us form` and update the recipient email to an email where you wish to receive your form submissions. Finally, select **Create Form**.

![Creating a Formspree form](~/assets/images/pages/tutorials/react-new-form-dialog.png)

You will be presented with instructions on how to integrate your new form. Copy the form’s `hashid` (the last 8 alphanumeric characters from the URL) and paste it into the `useForm` function in the `ContactForm` component you created above.

![Newly generated form endpoint that you can copy to use in the ContactForm component](~/assets/images/pages/tutorials/react-form-endpoint.png)

Your component should now have a line like this:

```jsx
const [state, handleSubmit] = useForm("mqldaqwx");

/* replace the random-like string above with your own form's ID */
```

Now when you submit your form, you should be shown a Thank You message. The form data will be submitted to your account on [Formspree.io](https://formspree.io/).

From here you can adjust your form processing logic to update the [notification email address](https://help.formspree.io/hc/en-us/articles/115008379348-Changing-a-form-email-address), or add plugins like [Google Sheets](https://help.formspree.io/hc/en-us/articles/360036563573-Use-Google-Sheets-to-send-your-submissions-to-a-spreadsheet), [Slack](https://help.formspree.io/hc/en-us/articles/360045648933-Send-Slack-notifications), and more.

For more help setting up Formspree, refer to the following resources:

- For general help with Formspree, refer to the [Formspree help site](https://help.formspree.io/hc/en-us).
- For more help creating forms in React, refer to the [formspree-react documentation](https://help.formspree.io/hc/en-us/articles/360055613373-The-Formspree-React-library)
- For tips on integrating Formspree with popular platforms like Next.js, Gatsby and Eleventy, refer to the [Formspree guides](https://formspree.io/guides).

## Deployment

You are now ready to deploy your project.

If you have not already done so, save your progress within `git` and then push the commit(s) to the GitHub repository:

```sh
# Add all files
git add -A
# Commit w/ message
git commit -m "working example"
# Push commit(s) to remote
git push -u origin main
```

Your work now resides within the GitHub repository, which means that Pages is able to access it too.

If this is your first Cloudflare Pages project, refer to the [Get started guide](/pages/get-started/) for a complete walkthrough. After selecting the appropriate GitHub repository, you must configure your project with the following build settings:

- **Project name** – Your choice
- **Production branch** – `main`
- **Framework preset** – Create React App
- **Build command** – `npm run build`
- **Build output directory** – `build`

After selecting **Save and Deploy**, your Pages project will begin its first deployment. When successful, you will be presented with a unique `*.pages.dev` subdomain and a link to your live demo.

## Using environment variables with forms

Sometimes it is helpful to set up two forms, one for development, and one for production. That way you can develop and test your form without corrupting your production dataset, or sending test notifications to clients.

To set up production and development forms first create a second form in Formspree. Name this form Contact Us Testing, and note the form's [`hashid`](https://help.formspree.io/hc/en-us/articles/360015130174-Getting-your-form-s-hashid-).

Then change the `useForm` hook in your `ContactForm.js` file so that it is initialized with an environment variable, rather than a string:

```jsx
const [state, handleSubmit] = useForm(process.env.REACT_APP_FORM_ID);
```

In your Cloudflare Pages project settings, add the `REACT_APP_FORM_ID` environment variable to both the Production and Preview environments. Use your original form's `hashid` for Production, and the new test form's `hashid` for the Preview environment:

![Edit option for environment variables in your Production and Preview environments](~/assets/images/pages/tutorials/env-vars.png)

Now, when you commit and push changes to a branch of your git repository, a new preview app will be created with a form that submits to the test form URL. However, your production website will continue to submit to the original form URL.

:::note

Create React App uses the prefix `REACT_APP_` to designate environment variables that are accessible to front-end JavaScript code. A different framework will use a different prefix to expose environment variables. For example, in the case of Next.js, the prefix is `NEXT_PUBLIC_`. Consult the documentation of your front-end framework to determine how to access environment variables from your React code.

:::

In this tutorial, you built and deployed a website using Cloudflare Pages and Formspree to handle form submissions. You created a React application with a form that communicates with Formspree to process and store submission requests and send notifications.

If you would like to review the full source code for this application, you can find it on [GitHub](https://github.com/formspree/formspree-example-cloudflare-react).

## Related resources

- [Add an HTML form with Formspree](/pages/tutorials/add-an-html-form-with-formspree/)
- [HTML Forms](/pages/tutorials/forms/)

---

# Add an HTML form with Formspree

URL: https://developers.cloudflare.com/pages/tutorials/add-an-html-form-with-formspree/

Almost every website, whether it is a simple HTML portfolio page or a complex JavaScript application, will need a form to collect user data. [Formspree](https://formspree.io) is a back-end service that handles form processing and storage, allowing developers to include forms on their website without writing server-side code or functions.

In this tutorial, you will create a `<form>` using plain HTML and CSS and add it to a static HTML website hosted on Cloudflare Pages. Refer to the [Get started guide](/pages/get-started/) to familiarize yourself with the platform. You will use Formspree to collect the submitted data and send out email notifications when new submissions arrive, without requiring any JavaScript or back-end coding.

## Setup

To begin, create a [new GitHub repository](https://repo.new/). Then create a new local directory on your machine, initialize git, and attach the GitHub location as a remote destination:

```sh
# create new directory
mkdir new-project
# enter new directory
cd new-project
# initialize git
git init
# attach remote
git remote add origin git@github.com:<username>/<repo>.git
# change default branch name
git branch -M main
```

You may now begin working in the `new-project` directory you created.

## The website markup

You will only be using plain HTML for this example project. The home page will include a Contact Us form that accepts a name, email address, and message.

:::note

The form code is adapted from the HTML Forms tutorial. For a more in-depth explanation of how HTML forms work and additional learning resources, refer to the [HTML Forms tutorial](/pages/tutorials/forms/).

:::

The form code:

```html
<form method="POST" action="/">
	<label for="name">Full Name</label>
	<input id="name" type="text" name="name" pattern="[A-Za-z]+" required />

	<label for="email">Email Address</label>
	<input id="email" type="email" name="email" required />

	<label for="message">Message</label>
	<textarea id="message" name="message" required></textarea>

	<button type="submit">Submit</button>
</form>
```

The `action` attribute determines where the form data is sent. You will update this later to send form data to Formspree. All `<input>` tags must have a unique `name` in order to capture the user's data. The `for` and `id` values must match in order to link the `<label>` with the corresponding `<input>` for accessibility tools like screen readers.

:::note

Refer to the [HTML Forms tutorial](/pages/tutorials/forms/) on how to build an HTML form.

:::

To add this form to your website, first, create a `public/index.html` in your project directory. The `public` directory should contain all front-end assets, and the `index.html` file will serve as the home page for the website.

Copy and paste the following content into your `public/index.html` file, which includes the above form:

```html
<html lang="en">
	<head>
		<meta charset="utf8" />
		<title>Form Demo</title>
		<meta name="viewport" content="width=device-width,initial-scale=1" />
	</head>
	<body>
		<!-- the form from above -->

		<form method="POST" action="/">
			<label for="name">Full Name</label>
			<input id="name" type="text" name="name" pattern="[A-Za-z]+" required />

			<label for="email">Email Address</label>
			<input id="email" type="email" name="email" required />

			<label for="message">Message</label>
			<textarea id="message" name="message" required></textarea>

			<button type="submit">Submit</button>
		</form>
	</body>
</html>
```

Now you have an HTML document containing a Contact Us form with several fields for the user to fill out. However, you have not yet set the `action` attribute to a server that can handle the form data. You will do this in the next section of this tutorial.

:::note[GitHub Repository]

The source code for this example is [available on GitHub](https://github.com/formspree/formspree-example-cloudflare-html). It is a live Pages application with a [live demo](https://formspree-example-cloudflare-html.pages.dev/) available, too.

:::

## The Formspree back end

The HTML form is complete, however, when the user submits this form, the data will be sent in a `POST` request to the `/` URL. No server exists to process the data at that URL, so it will cause an error. To fix that, create a new Formspree form, and copy its unique URL into the form's `action`.

To create a Formspree form, sign up for [an account on Formspree](https://formspree.io/register).

Next, create a new form with the **+ New form** button. Name it `Contact-us form` and update the recipient email to an email where you wish to receive your form submissions. Then select **Create Form**.

![Creating a Formspree form](~/assets/images/pages/tutorials/new-form-dialog.png)

You will then be presented with instructions on how to integrate your new form.

![Formspree endpoint](~/assets/images/pages/tutorials/form-endpoint.png)

Copy the `Form Endpoint` URL and paste it into the `action` attribute of the form you created above.

```html
<form method="POST" action="https://formspree.io/f/mqldaqwx">
	<!-- replace with your own formspree endpoint -->
</form>
```

Now when you submit your form, you should be redirected to a Thank You page. The form data will be submitted to your account on [Formspree.io](https://formspree.io/).

You can now adjust your form processing logic to change the [redirect page](https://help.formspree.io/hc/en-us/articles/360012378333--Thank-You-redirect), update the [notification email address](https://help.formspree.io/hc/en-us/articles/115008379348-Changing-a-form-email-address), or add plugins like [Google Sheets](https://help.formspree.io/hc/en-us/articles/360036563573-Use-Google-Sheets-to-send-your-submissions-to-a-spreadsheet), [Slack](https://help.formspree.io/hc/en-us/articles/360045648933-Send-Slack-notifications) and more.

For more help setting up Formspree, refer to the following resources:

- For general help with Formspree, refer to the [Formspree help site](https://help.formspree.io/hc/en-us).
- For examples and inspiration for your own HTML forms, review the [Formspree form library](https://formspree.io/library).
- For tips on integrating Formspree with popular platforms like Next.js, Gatsby and Eleventy, refer to the [Formspree guides](https://formspree.io/guides).

## Deployment

You are now ready to deploy your project.

If you have not already done so, save your progress within `git` and then push the commit(s) to the GitHub repository:

```sh
# Add all files
git add -A
# Commit w/ message
git commit -m "working example"
# Push commit(s) to remote
git push -u origin main
```

Your work now resides within the GitHub repository, which means that Pages is able to access it too.

If this is your first Cloudflare Pages project, refer to [Get started](/pages/get-started/) for a complete setup guide. After selecting the appropriate GitHub repository, you must configure your project with the following build settings:

- **Project name** – Your choice
- **Production branch** – `main`
- **Framework preset** – None
- **Build command** – None / Empty
- **Build output directory** – `public`

After selecting **Save and Deploy**, your Pages project will begin its first deployment. When successful, you will be presented with a unique `*.pages.dev` subdomain and a link to your live demo.

In this tutorial, you built and deployed a website using Cloudflare Pages and Formspree to handle form submissions. You created a static HTML document with a form that communicates with Formspree to process and store submission requests and send notifications.

If you would like to review the full source code for this application, you can find it on [GitHub](https://github.com/formspree/formspree-example-cloudflare-html).

## Related resources

- [Add a React form with Formspree](/pages/tutorials/add-a-react-form-with-formspree/)
- [HTML Forms](/pages/tutorials/forms/)

---

# Build a blog using Nuxt.js and Sanity.io on Cloudflare Pages

URL: https://developers.cloudflare.com/pages/tutorials/build-a-blog-using-nuxt-and-sanity/

import { Stream, PackageManagers } from "~/components";

In this tutorial, you will build a blog application using Nuxt.js and Sanity.io and deploy it on Cloudflare Pages. Nuxt.js is a powerful static site generator built on the front-end framework Vue.js. Sanity.io is a headless CMS tool built for managing your application's data without needing to maintain a database.

## Prerequisites

- A recent version of [npm](https://docs.npmjs.com/getting-started) on your computer
- A [Sanity.io](https://www.sanity.io) account

## Creating a new Sanity project

To begin, create a new Sanity project, using one of Sanity's templates, the blog template. If you would like to customize your configuration, you can modify the schema or pick a custom template.

### Installing Sanity and configuring your dataset

Create your new Sanity project by installing the `@sanity/cli` client from npm, and running `sanity init` in your terminal:

<PackageManagers pkg="@sanity/cli" />

<PackageManagers type="exec" pkg="sanity" args="init" />

When you create a Sanity project, you can choose to use one of their pre-defined schemas. Schemas describe the shape of your data in your Sanity dataset -- if you were to start a brand new project, you may choose to initialize the schema from scratch, but for now, select the **Blog** schema.

### Inspecting your schema

With your project created, you can navigate into the folder and start up the studio locally:

```sh
cd my-sanity-project
```

<PackageManagers type="exec" pkg="sanity" args="start" />

The Sanity studio is where you can create new records for your dataset. By default, running the studio locally makes it available at `localhost:3333`– go there now and create your author record. You can also create blog posts here.

![Creating a blog post in the Sanity Project dashboard](~/assets/images/pages/tutorials/sanity-studio.png)

### Deploying your dataset

When you are ready to deploy your studio, run `sanity deploy` to choose a unique URL for your studio. This means that you (or anyone else you invite to manage your blog) can access the studio at a `yoururl.sanity.studio` domain.

<PackageManagers type="exec" pkg="sanity" args="deploy" />

Once you have deployed your Sanity studio:

1. Go into Sanity's management panel ([manage.sanity.io](https://manage.sanity.io)).
2. Find your project.
3. Select **API**.
4. Add `http://localhost:3000` as an allowed CORS origin for your project.

This means that requests that come to your Sanity dataset from your Nuxt application will be allowlisted.

![Your Sanity project's CORS settings](~/assets/images/pages/tutorials/cors.png)

## Creating a new Nuxt.js project

Next, create a Nuxt.js project. In a new terminal, use `create-nuxt-app` to set up a new Nuxt project:

<PackageManagers type="dlx" pkg="create-nuxt-app" args="blog" />

Importantly, ensure that you select a rendering mode of **Universal (SSR / SSG)** and a deployment target of **Static (Static/JAMStack hosting)**, while going through the setup process.

After you have completed your project, `cd` into your new project, and start a local development server by running `yarn dev` (or, if you chose npm as your package manager, `npm run dev`):

```sh
cd blog
```

<PackageManagers type="run" args="dev" />

### Integrating Sanity.io

After your Nuxt.js application is set up, add Sanity's `@sanity/nuxt` plugin to your Nuxt project:

<PackageManagers pkg="@nuxtjs/sanity @sanity/client" />

To configure the plugin in your Nuxt.js application, you will need to provide some configuration details. The easiest way to do this is to copy the `sanity.json` folder from your studio into your application directory (though there are other methods, too: [refer to the `@nuxt/sanity` documentation](https://sanity.nuxtjs.org/getting-started/quick-start/).

```sh title="Adding sanity.json"
cp ../my-sanity-project/sanity.json .
```

Finally, add `@nuxtjs/sanity` as a **build module** in your Nuxt configuration:

```js title="nuxt.config.js"
{
	buildModules: ["@nuxtjs/sanity"];
}
```

### Setting up components

With Sanity configured in your application, you can begin using it to render your blog. You will now set up a few pages to pull data from your Sanity API and render it. Note that if you are not familiar with Nuxt, it is recommended that you review the [Nuxt guide](https://nuxtjs.org/guide), which will teach you some fundamentals concepts around building applications with Nuxt.

### Setting up the index page

To begin, update the `index` page, which will be rendered when you visit the root route (`/`). In `pages/index.vue`:

```html title="pages/index.vue"
<template>
	<div class="container">
		<div>
			<h1 class="title">My Blog</h1>
		</div>
		<div class="posts">
			<div v-for="post in posts" :key="post._id">
				<h2><a v-bind:href="post.slug.current" v-text="post.title" /></h2>
			</div>
		</div>
	</div>
</template>

<script>
	import { groq } from "@nuxtjs/sanity";

	export default {
		async asyncData({ $sanity }) {
			const query = groq`*[_type == "post"]`;
			const posts = await $sanity.fetch(query);
			return { posts };
		},
	};
</script>

<style>
	.container {
		margin: 2rem;
		min-height: 100vh;
	}
	.posts {
		margin: 2rem 0;
	}
</style>
```

Vue SFCs, or _single file components_, are a unique Vue feature that allow you to combine JavaScript, HTML and CSS into a single file. In `pages/index.vue`, a `template` tag is provided, which represents the Vue component.

Importantly, `v-for` is used as a directive to tell Vue to render HTML for each `post` in an array of `posts`:

```html title="Inspecting the v-for directive"
<div v-for="post in posts" :key="post._id">
	<h2><a v-bind:href="post.slug.current" v-text="post.title" /></h2>
</div>
```

To populate that `posts` array, the `asyncData` function is used, which is provided by Nuxt to make asynchronous calls (for example, network requests) to populate the page's data.

The `$sanity` object is provided by the Nuxt and Sanity.js integration as a way to make requests to your Sanity dataset. By calling `$sanity.fetch`, and passing a query, you can retrieve specific data from our Sanity dataset, and return it as your page's data.

If you have not used Sanity before, you will probably be unfamiliar with GROQ, the GRaph Oriented Query language provided by Sanity for interfacing with your dataset. GROQ is a powerful language that allows you to tell the Sanity API what data you want out of your dataset. For our first query, you will tell Sanity to retrieve every object in the dataset with a `_type` value of `post`:

```js title="A basic GROQ query"
const query = groq`*[_type == "post"]`;
const posts = await $sanity.fetch(query);
```

### Setting up the blog post page

Our `index` page renders a link for each blog post in our dataset, using the `slug` value to set the URL for a blog post. For example, if I create a blog post called "Hello World" and set the slug to `hello-world`, my Nuxt application should be able to handle a request to the page `/hello-world`, and retrieve the corresponding blog post from Sanity.

Nuxt has built-in support for these kind of pages, by creating a new file in `pages` in the format `_slug.vue`. In the `asyncData` function of your page, you can then use the `params` argument to reference the slug:

```html title="pages/_slug.vue"
<script>
	export default {
		async asyncData({ params, $sanity }) {
			console.log(params); // { slug: "hello-world" }
		},
	};
</script>
```

With that in mind, you can build `pages/_slug.vue` to take the incoming `slug` value, make a query to Sanity to find the matching blog post, and render the `post` title for the blog post:

```html title="pages/_slug.vue"
<template>
	<div class="container">
		<div v-if="post">
			<h1 class="title" v-text="post.title" />
			<div class="content"></div>
		</div>
		<h4><a href="/">← Go back</a></h4>
	</div>
</template>

<script>
	import { groq } from "@nuxtjs/sanity";

	export default {
		async asyncData({ params, $sanity }) {
			const query = groq`*[_type == "post" && slug.current == "${params.slug}"][0]`;
			const post = await $sanity.fetch(query);
			return { post };
		},
	};
</script>

<style>
	.container {
		margin: 2rem;
		min-height: 100vh;
	}

	.content {
		margin: 2rem 0;
		max-width: 38rem;
	}

	p {
		margin: 1rem 0;
	}
</style>
```

When visiting, for example, `/hello-world`, Nuxt will take the incoming slug `hello-world`, and make a GROQ query to Sanity for any objects with a `_type` of `post`, as well as a slug that matches the value `/hello-world`. From that set, you can get the first object in the array (using the array index operator you would find in JavaScript – `[0]`) and set it as `post` in your page data.

### Rendering content for a blog post

You have rendered the `post` title for our blog, but you are still missing the content of the blog post itself. To render this, import the [`sanity-blocks-vue-component`](https://github.com/rdunk/sanity-blocks-vue-component) package, which takes Sanity's [Portable Text](https://www.sanity.io/docs/presenting-block-text) format and renders it as a Vue component.

First, install the npm package:

<PackageManagers pkg="sanity-blocks-vue-component" />

After the package is installed, create `plugins/sanity-blocks.js`, which will import the component and register it as the Vue component `block-content`:

```js title="plugins/sanity-blocks.js"
import Vue from "vue";
import BlockContent from "sanity-blocks-vue-component";
Vue.component("block-content", BlockContent);
```

In your Nuxt configuration, `nuxt.config.js`, import that file as part of the `plugins` directive:

```js title="nuxt.config.js"
{
	plugins: ["@/plugins/sanity-blocks.js"];
}
```

In `pages/_slug.vue`, you can now use the `<block-content>` component to render your content. This takes the format of a custom HTML component, and takes three arguments: `:blocks`, which indicates what to render (in our case, `child`), `v-for`, which accepts an iterator of where to get `child` from (in our case, `post.body`), and `:key`, which helps Vue [keep track of state rendering](https://vuejs.org/v2/guide/list.html#Maintaining-State) by providing a unique value for each post: that is, the `_id` value.

```html title="pages/_slug.vue" {6}
<template>
	<div class="container">
		<div v-if="post">
			<h1 class="title" v-text="post.title" />
			<div class="content">
				<block-content
					:blocks="child"
					v-for="child in post.body"
					:key="child._id"
				/>
			</div>
		</div>
		<h4><a href="/">← Go back</a></h4>
	</div>
</template>

<script>
	import { groq } from "@nuxtjs/sanity";

	export default {
		async asyncData({ params, $sanity }) {
			const query = groq`*[_type == "post" && slug.current == "${params.slug}"][0]`;
			const post = await $sanity.fetch(query);
			return { post };
		},
	};
</script>

<style>
	.container {
		margin: 2rem;
		min-height: 100vh;
	}

	.content {
		margin: 2rem 0;
		max-width: 38rem;
	}

	p {
		margin: 1rem 0;
	}
</style>
```

In `pages/index.vue`, you can use the `block-content` component to render a summary of the content, by taking the first block in your blog post content and rendering it:

```html title="pages/index.vue" {11-13,39}
<template>
	<div class="container">
		<div>
			<h1 class="title">My Blog</h1>
		</div>
		<div class="posts">
			<div v-for="post in posts" :key="post._id">
				<h2><a v-bind:href="post.slug.current" v-text="post.title" /></h2>
				<div class="summary">
					<block-content
						:blocks="post.body[0]"
						v-bind:key="post.body[0]._id"
						v-if="post.body.length"
					/>
				</div>
			</div>
		</div>
	</div>
</template>

<script>
	import { groq } from "@nuxtjs/sanity";

	export default {
		async asyncData({ $sanity }) {
			const query = groq`*[_type == "post"]`;
			const posts = await $sanity.fetch(query);
			return { posts };
		},
	};
</script>

<style>
	.container {
		margin: 2rem;
		min-height: 100vh;
	}
	.posts {
		margin: 2rem 0;
	}
	.summary {
		margin-top: 0.5rem;
	}
</style>
```

<Stream id="cdf12588663302139f022c26c4e5cede" title="Nuxt & Sanity video" />

There are many other things inside of your blog schema that you can add to your project. As an exercise, consider one of the following to continue developing your understanding of how to build with a headless CMS:

- Create `pages/authors.vue`, and render a list of authors (similar to `pages/index.vue`, but for objects with `_type == "author"`)
- Read the Sanity docs on [using references in GROQ](https://www.sanity.io/docs/how-queries-work#references-and-joins-db43dfd18d7d), and use it to render author information in a blog post page

## Publishing with Cloudflare Pages

Publishing your project with Cloudflare Pages is a two-step process: first, push your project to GitHub, and then in the Cloudflare Pages dashboard, set up a new project based on that GitHub repository. Pages will deploy a new version of your site each time you publish, and will even set up preview deployments whenever you open a new pull request.

To push your project to GitHub, [create a new repository](https://repo.new), and follow the instructions to push your local Git repository to GitHub.

After you have pushed your project to GitHub, deploy your site to Pages:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**.
3. Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, choose _Nuxt_. Pages will set the correct fields for you automatically.

When your site has been deployed, you will receive a unique URL to view it in production.

In order to automatically deploy your project when your Sanity.io data changes, you can use [Deploy Hooks](/pages/configuration/deploy-hooks/). Create a new Deploy Hook URL in your **Pages project** > **Settings**. In your Sanity project's Settings page, find the **Webhooks** section, and add the Deploy Hook URL, as seen below:

![Adding a Deploy Hook URL on Sanity's dashboard](~/assets/images/pages/tutorials/hooks.png)

Now, when you make a change to your Sanity.io dataset, Sanity will make a request to your unique Deploy Hook URL, which will begin a new Cloudflare Pages deploy. By doing this, your Pages application will remain up-to-date as you add new blog posts, or edit existing ones.

## Conclusion

By completing this guide, you have successfully deployed your own blog, powered by Nuxt, Sanity.io, and Cloudflare Pages. You can find the source code for both codebases on GitHub:

- Blog front end: [https://github.com/signalnerve/nuxt-sanity-blog](https://github.com/signalnerve/nuxt-sanity-blog)
- Sanity dataset: [https://github.com/signalnerve/sanity-blog-schema](https://github.com/signalnerve/sanity-blog-schema)

If you enjoyed this tutorial, you may be interested in learning how you can use Cloudflare Workers, our powerful serverless function platform, to augment your existing site. Refer to the [Build an API for your front end using Pages Functions tutorial](/pages/tutorials/build-an-api-with-pages-functions/) to learn more.

---

# Build an API for your front end using Pages Functions

URL: https://developers.cloudflare.com/pages/tutorials/build-an-api-with-pages-functions/

import { Stream, PackageManagers } from "~/components";

In this tutorial, you will build a full-stack Pages application. Your application will contain:

- A front end, built using Cloudflare Pages and the [React framework](/pages/framework-guides/deploy-a-react-site/).
- A JSON API, built with [Pages Functions](/pages/functions/get-started/), that returns blog posts that can be retrieved and rendered in your front end.

If you prefer to work with a headless CMS rather than an API to render your blog content, refer to the [headless CMS tutorial](/pages/tutorials/build-a-blog-using-nuxt-and-sanity/).

## Video Tutorial

<Stream
	id="2d8bbaa18fbd3ffa859a7fb30e9b3dd1"
	title="Build an API With Pages Functions"
	thumbnail="29s"
/>

## 1. Build your front end

To begin, create a new Pages application using the React framework.

### Create a new React project

In your terminal, create a new React project called `blog-frontend` using the `create-vite` command. Go into the newly created `blog-frontend` directory and start a local development server:

```sh title="Create a new React application"
npx create-vite -t react blog-frontend
cd blog-frontend
npm install
npm run dev
```

### Set up your React project

To set up your React project:

1. Install the [React Router](https://reactrouter.com/en/main/start/tutorial) in the root of your `blog-frontend` directory.

<PackageManagers pkg="react-router-dom@6" />s

2. Clear the contents of `src/App.js`. Copy and paste the following code to import the React Router into `App.js`, and set up a new router with two routes:

```js
import { Routes, Route } from "react-router-dom";

import Posts from "./components/posts";
import Post from "./components/post";

function App() {
	return (
		<Routes>
			<Route path="/" element={<Posts />} />
			<Route path="/posts/:id" element={<Post />} />
		</Routes>
	);
}

export default App;
```

3. In the `src` directory, create a new folder called `components`.
4. In the `components` directory, create two files: `posts.js`, and `post.js`. These files will load the blog posts from your API, and render them.
5. Populate `posts.js` with the following code:

```js
import React, { useEffect, useState } from "react";
import { Link } from "react-router-dom";

const Posts = () => {
	const [posts, setPosts] = useState([]);

	useEffect(() => {
		const getPosts = async () => {
			const resp = await fetch("/api/posts");
			const postsResp = await resp.json();
			setPosts(postsResp);
		};

		getPosts();
	}, []);

	return (
		<div>
			<h1>Posts</h1>
			{posts.map((post) => (
				<div key={post.id}>
					<h2>
						<Link to={`/posts/${post.id}`}>{post.title}</Link>
					</h2>
				</div>
			))}
		</div>
	);
};

export default Posts;
```

6. Populate `post.js` with the following code:

```js
import React, { useEffect, useState } from "react";
import { Link, useParams } from "react-router-dom";

const Post = () => {
	const [post, setPost] = useState({});
	const { id } = useParams();

	useEffect(() => {
		const getPost = async () => {
			const resp = await fetch(`/api/post/${id}`);
			const postResp = await resp.json();
			setPost(postResp);
		};

		getPost();
	}, [id]);

	if (!Object.keys(post).length) return <div />;

	return (
		<div>
			<h1>{post.title}</h1>
			<p>{post.text}</p>
			<p>
				<em>Published {new Date(post.published_at).toLocaleString()}</em>
			</p>
			<p>
				<Link to="/">Go back</Link>
			</p>
		</div>
	);
};

export default Post;
```

## 2. Build your API

You will now create a Pages Functions that stores your blog content and retrieves it via a JSON API.

### Write your Pages Function

To create the Pages Function that will act as your JSON API:

1. Create a `functions` directory in your `blog-frontend` directory.
2. In `functions`, create a directory named `api`.
3. In `api`, create a `posts.js` file in the `api` directory.
4. Populate `posts.js` with the following code:

```js
import posts from "./post/data";

export function onRequestGet() {
	return Response.json(posts);
}
```

This code gets blog data (from `data.js`, which you will make in step 8) and returns it as a JSON response from the path `/api/posts`.

5. In the `api` directory, create a directory named `post`.
6. In the `post` directory, create a `data.js` file.
7. Populate `data.js` with the following code. This is where your blog content, blog title, and other information about your blog lives.

```js
const posts = [
	{
		id: 1,
		title: "My first blog post",
		text: "Hello world! This is my first blog post on my new Cloudflare Workers + Pages blog.",
		published_at: new Date("2020-10-23"),
	},
	{
		id: 2,
		title: "Updating my blog",
		text: "It's my second blog post! I'm still writing and publishing using Cloudflare Workers + Pages :)",
		published_at: new Date("2020-10-26"),
	},
];

export default posts;
```

8. In the `post` directory, create an `[[id]].js` file.
9. Populate `[[id]].js` with the following code:

```js title="[[id]].js"
import posts from "./data";

export function onRequestGet(context) {
	const id = context.params.id;

	if (!id) {
		return new Response("Not found", { status: 404 });
	}

	const post = posts.find((post) => post.id === Number(id));

	if (!post) {
		return new Response("Not found", { status: 404 });
	}

	return Response.json(post);
}
```

`[[id]].js` is a [dynamic route](/pages/functions/routing#dynamic-routes) which is used to accept a blog post `id`.

## 3. Deploy

After you have configured your Pages application and Pages Function, deploy your project using the Wrangler or via the dashboard.

### Deploy with Wrangler

In your `blog-frontend` directory, run [`wrangler pages deploy`](/workers/wrangler/commands/#deploy-1) to deploy your project to the Cloudflare dashboard.

```sh
wrangler pages deploy blog-frontend
```

### Deploy via the dashboard

To deploy via the Cloudflare dashboard, you will need to create a new Git repository for your Pages project and connect your Git repository to Cloudflare. This tutorial uses GitHub as its Git provider.

#### Create a new repository

Create a new GitHub repository by visiting [repo.new](https://repo.new). After creating a new repository, prepare and push your local application to GitHub by running the following commands in your terminal:

```sh
git init
git remote add origin https://github.com/<YOUR-GH-USERNAME>/<REPOSITORY-NAME>
git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main
```

#### Deploy with Cloudflare Pages

Deploy your application to Pages:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.
2. In Account Home, select **Workers & Pages** > **Create application** > **Pages** > **Connect to Git**.
3. Select the new GitHub repository that you created and, in the **Set up builds and deployments** section, provide the following information:

<div>

| Configuration option | Value           |
| -------------------- | --------------- |
| Production branch    | `main`          |
| Build command        | `npm run build` |
| Build directory      | `build`         |

</div>

After configuring your site, begin your first deploy. You should see Cloudflare Pages installing `blog-frontend`, your project dependencies, and building your site.

By completing this tutorial, you have created a full-stack Pages application.

## Related resources

- Learn about [Pages Functions routing](/pages/functions/routing)

---

# Create a HTML form

URL: https://developers.cloudflare.com/pages/tutorials/forms/

import { Render } from "~/components";

In this tutorial, you will create a simple `<form>` using plain HTML and CSS and deploy it to Cloudflare Pages. While doing so, you will learn about some of the HTML form attributes and how to collect submitted data within a Worker.

:::note[MDN Introductory Series]

This tutorial will briefly touch upon the basics of HTML forms. For a more in-depth overview, refer to MDN's [Web Forms – Working with user data](https://developer.mozilla.org/en-US/docs/Learn/Forms) introductory series.

:::

This tutorial will make heavy use of Cloudflare Pages and [its Workers integration](/pages/functions/). Refer to the [Get started guide](/pages/get-started/) guide to familiarize yourself with the platform.

## Overview

On the web, forms are a common point of interaction between the user and the web document. They allow a user to enter data and, generally, submit their data to a server. A form is comprised of at least one form input, which can vary from text fields to dropdowns to checkboxes and more.

Each input should be named – using the [`name`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-name) attribute – so that the input's value has an identifiable name when received by the server. Additionally, with the advancement of HTML5, form elements may declare additional attributes to opt into automatic form validation. The available validations vary by input type; for example, a text input that accepts emails (via [`type=email`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types)) can ensure that the value looks like a valid email address, a number input (via `type=number`) will only accept integers or decimal values (if allowed), and generic text inputs can define a custom [`pattern`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-pattern) to allow. However, all inputs can declare whether or not a value is [`required`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attr-required).

Below is an example HTML5 form with a few inputs and their validation rules defined:

```html
<form method="POST" action="/api/submit">
	<input type="text" name="fullname" pattern="[A-Za-z]+" required />
	<input type="email" name="email" required />
	<input type="number" name="age" min="18" required />

	<button type="submit">Submit</button>
</form>
```

If an HTML5 form has validation rules defined, browsers will automatically check all rules when the user attempts to submit the form. Should there be any errors, the submission is prevented and the browser displays the error message(s) to the user for correction. The `<form>` will only `POST` data to the `/submit` endpoint when there are no outstanding validation errors. This entire process is native to HTML5 and only requires the appropriate form and input attributes to exist — no JavaScript is required.

Form elements may also have a [`<label>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label) element associated with them, allowing you to clearly describe each input. This is great for visual clarity, of course, but it also allows for more accessible user experiences since the HTML markup is more well-defined. Assistive technologies directly benefit from this; for example, screen readers can announce which `<input>` is focused. And when a `<label>` is clicked, its assigned form input is focused instead, increasing the activation area for the input.

To enable this, you must create a `<label>` element for each input and assign each `<input>` element and unique `id` attribute value. The `<label>` must also possess a [`for`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label#attr-for) attribute that reflects its input's unique `id` value. Amending the previous snippet should produce the following:

```html
<form method="POST" action="/api/submit">
	<label for="i-fullname">Full Name</label>
	<input
		id="i-fullname"
		type="text"
		name="fullname"
		pattern="[A-Za-z]+"
		required
	/>

	<label for="i-email">Email Address</label>
	<input id="i-email" type="email" name="email" required />

	<label for="i-age">Your Age</label>
	<input id="i-age" type="number" name="age" min="18" required />

	<button type="submit">Submit</button>
</form>
```

:::note

Your `for` and `id` values do not need to exactly match the values shown above. You may use any `id` values so long as they are unique to the HTML document. A `<label>` can only be linked with an `<input>` if the `for` and `id` attributes match.

:::

When this `<form>` is submitted with valid data, its data contents are sent to the server. You may customize how and where this data is sent by declaring attributes on the form itself. If you do not provide these details, the `<form>` will GET the data to the current URL address, which is rarely the desired behavior. To fix this, at minimum, you need to define an [`action`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-action) attribute with the target URL address, but declaring a [`method`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-method) is often recommended too, even if you are redeclaring the default `GET` value.

By default, HTML forms send their contents in the `application/x-www-form-urlencoded` MIME type. This value will be reflected in the `Content-Type` HTTP header, which the receiving server must read to determine how to parse the data contents. You may customize the MIME type through the [`enctype`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-enctype) attribute. For example, to accept files (via `type=file`), you must change the `enctype` to the `multipart/form-data` value:

```html
<form method="POST" action="/api/submit" enctype="multipart/form-data">
	<label for="i-fullname">Full Name</label>
	<input
		id="i-fullname"
		type="text"
		name="fullname"
		pattern="[A-Za-z]+"
		required
	/>

	<label for="i-email">Email Address</label>
	<input id="i-email" type="email" name="email" required />

	<label for="i-age">Your Age</label>
	<input id="i-age" type="number" name="age" min="18" required />

	<label for="i-avatar">Profile Picture</label>
	<input id="i-avatar" type="file" name="avatar" required />

	<button type="submit">Submit</button>
</form>
```

Because the `enctype` changed, the browser changes how it sends data to the server too. The `Content-Type` HTTP header will reflect the new approach and the HTTP request's body will conform to the new MIME type. The receiving server must accommodate the new format and adjust its request parsing method.

## Live example

The rest of this tutorial will focus on building an HTML form on Pages, including a Worker to receive and parse the form submissions.

:::note[GitHub Repository]

The source code for this example is [available on GitHub](https://github.com/cloudflare/submit.pages.dev). It is a live Pages application with a [live demo](https://submit.pages.dev/) available, too.

:::

### Setup

To begin, create a [new GitHub repository](https://repo.new/). Then create a new local directory on your machine, initialize git, and attach the GitHub location as a remote destination:

```sh
# create new directory
mkdir new-project
# enter new directory
cd new-project
# initialize git
git init
# attach remote
git remote add origin git@github.com:<username>/<repo>.git
# change default branch name
git branch -M main
```

You may now begin working in the `new-project` directory you created.

### Markup

The form for this example is fairly straightforward. It includes an array of different input types, including checkboxes for selecting multiple values. The form also does not include any validations so that you may see how empty and/or missing values are interpreted on the server.

You will only be using plain HTML for this example project. You may use your preferred JavaScript framework, but raw languages have been chosen for simplicity and familiarity – all frameworks are abstracting and/or producing a similar result.

Create a `public/index.html` in your project directory. All front-end assets will exist within this `public` directory and this `index.html` file will serve as the home page for the website.

Copy and paste the following content into your `public/index.html` file:

```html
<html lang="en">
	<head>
		<meta charset="utf8" />
		<title>Form Demo</title>
		<meta name="viewport" content="width=device-width,initial-scale=1" />
	</head>
	<body>
		<form method="POST" action="/api/submit">
			<div class="input">
				<label for="name">Full Name</label>
				<input id="name" name="name" type="text" />
			</div>

			<div class="input">
				<label for="email">Email Address</label>
				<input id="email" name="email" type="email" />
			</div>

			<div class="input">
				<label for="referers">How did you hear about us?</label>
				<select id="referers" name="referers">
					<option hidden disabled selected value></option>
					<option value="Facebook">Facebook</option>
					<option value="Twitter">Twitter</option>
					<option value="Google">Google</option>
					<option value="Bing">Bing</option>
					<option value="Friends">Friends</option>
				</select>
			</div>

			<div class="checklist">
				<label>What are your favorite movies?</label>
				<ul>
					<li>
						<input id="m1" type="checkbox" name="movies" value="Space Jam" />
						<label for="m1">Space Jam</label>
					</li>
					<li>
						<input
							id="m2"
							type="checkbox"
							name="movies"
							value="Little Rascals"
						/>
						<label for="m2">Little Rascals</label>
					</li>
					<li>
						<input id="m3" type="checkbox" name="movies" value="Frozen" />
						<label for="m3">Frozen</label>
					</li>
					<li>
						<input id="m4" type="checkbox" name="movies" value="Home Alone" />
						<label for="m4">Home Alone</label>
					</li>
				</ul>
			</div>

			<button type="submit">Submit</button>
		</form>
	</body>
</html>
```

This HTML document will contain a form with a few fields for the user to fill out. Because there is no validation rules within the form, all fields are optional and the user is able to submit an empty form. For this example, this is intended behavior.

:::note[Optional content]

Technically, only the `<form>` and its child elements are necessary. The `<head>` and the enclosing `<html>` and `<body>` tags are optional and not strictly necessary for a valid HTML document.

The HTML page is also completely unstyled at this point, relying on the browsers' default UI and color palettes. Styling the page is entirely optional and not necessary for the form to function. If you would like to attach a CSS stylesheet, you may [add a `<link>` element](https://developer.mozilla.org/en-US/docs/Learn/CSS/First_steps/Getting_started#adding_css_to_our_document). Refer to the finished tutorial's [source code](https://github.com/cloudflare/submit.pages.dev/blob/8c0594f48681935c268987f2f08bcf3726a74c57/public/index.html#L11) for an example or any inspiration – the only requirement is that your CSS stylesheet also resides within the `public` directory.

:::

### Worker

The HTML form is complete and ready for deployment. When the user submits this form, all data will be sent in a `POST` request to the `/api/submit` URL. This is due to the form's `method` and `action` attributes. However, there is currently no request handler at the `/api/submit` address. You will now create it.

Cloudflare Pages offers a [Functions](/pages/functions/) feature, which allows you to define and deploy Workers for dynamic behaviors.

Functions are linked to the `functions` directory and conveniently construct URL request handlers in relation to the `functions` file structure. For example, the `functions/about.js` file will map to the `/about` URL and `functions/hello/[name].js` will handle the `/hello/:name` URL pattern, where `:name` is any matching URL segment. Refer to the [Functions routing](/pages/functions/routing/) documentation for more information.

To define a handler for `/api/submit`, you must create a `functions/api/submit.js` file. This means that your `functions` and `public` directories should be siblings, with a total project structure similar to the following:

```txt
├── functions
│   └── api
│       └── submit.js
└── public
    └── index.html
```

The `<form>` will send `POST` requests, which means that the `functions/api/submit.js` file needs to export an `onRequestPost` handler:

```js
/**
 * POST /api/submit
 */
export async function onRequestPost(context) {
	// TODO: Handle the form submission
}
```

The `context` parameter is an object filled with several values of potential interest. For this example, you only need the [`Request`](/workers/runtime-apis/request/) object, which can be accessed through the `context.request` key.

As mentioned, a `<form>` defaults to the `application/x-www-form-urlencoded` MIME type when submitting. And, for more advanced scenarios, the `enctype="multipart/form-data"` attribute is needed. Luckily, both MIME types can be parsed and treated as [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData). This means that with Workers – which includes Pages Functions – you are able to use the native [`Request.formData`](https://developer.mozilla.org/en-US/docs/Web/API/Request/formData) parser.

For illustrative purposes, the example application's form handler will reply with all values it received. A `Response` must always be returned by the handler, too:

```js
/**
 * POST /api/submit
 */
export async function onRequestPost(context) {
	try {
		let input = await context.request.formData();
		let pretty = JSON.stringify([...input], null, 2);
		return new Response(pretty, {
			headers: {
				"Content-Type": "application/json;charset=utf-8",
			},
		});
	} catch (err) {
		return new Response("Error parsing JSON content", { status: 400 });
	}
}
```

With this handler in place, the example is now fully functional. When a submission is received, the Worker will reply with a JSON list of the `FormData` key-value pairs.

However, if you want to reply with a JSON object instead of the key-value pairs (an Array of Arrays), then you must do so manually. Recently, JavaScript added the [`Object.fromEntries`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries) utility. This works well in some cases; however, the example `<form>` includes a `movies` checklist that allows for multiple values. If using `Object.fromEntries`, the generated object would only keep one of the `movies` values, discarding the rest. To avoid this, you must write your own `FormData` to `Object` utility instead:

```js
/**
 * POST /api/submit
 */
export async function onRequestPost(context) {
	try {
		let input = await context.request.formData();

		// Convert FormData to JSON
		// NOTE: Allows multiple values per key
		let output = {};
		for (let [key, value] of input) {
			let tmp = output[key];
			if (tmp === undefined) {
				output[key] = value;
			} else {
				output[key] = [].concat(tmp, value);
			}
		}

		let pretty = JSON.stringify(output, null, 2);
		return new Response(pretty, {
			headers: {
				"Content-Type": "application/json;charset=utf-8",
			},
		});
	} catch (err) {
		return new Response("Error parsing JSON content", { status: 400 });
	}
}
```

The final snippet (above) allows the Worker to retain all values, returning a JSON response with an accurate representation of the `<form>` submission.

### Deployment

You are now ready to deploy your project.

If you have not already done so, save your progress within `git` and then push the commit(s) to the GitHub repository:

```sh
# Add all files
git add -A
# Commit w/ message
git commit -m "working example"
# Push commit(s) to remote
git push -u origin main
```

Your work now resides within the GitHub repository, which means that Pages is able to access it too.

If this is your first Cloudflare Pages project, refer to the [Get started guide](/pages/get-started/) for a complete walkthrough. After selecting the appropriate GitHub repository, you must configure your project with the following build settings:

- **Project name** – Your choice
- **Production branch** – `main`
- **Framework preset** – None
- **Build command** – None / Empty
- **Build output directory** – `public`

After clicking the **Save and Deploy** button, your Pages project will begin its first deployment. When successful, you will be presented with a unique `*.pages.dev` subdomain and a link to your live demo.

In this tutorial, you built and deployed a website and its back-end logic using Cloudflare Pages with its Workers integration. You created a static HTML document with a form that communicates with a Worker handler to parse the submission request(s).

If you would like to review the full source code for this application, you can find it on [GitHub](https://github.com/cloudflare/submit.pages.dev).

## Related resources

- [Build an API for your front end using Cloudflare Workers](/pages/tutorials/build-an-api-with-pages-functions/)
- [Handle form submissions with Airtable](/workers/tutorials/handle-form-submissions-with-airtable/)

---

# Localize a website with HTMLRewriter

URL: https://developers.cloudflare.com/pages/tutorials/localize-a-website/

import { Render, PackageManagers, WranglerConfig } from "~/components";

In this tutorial, you will build an example internationalization and localization engine (commonly referred to as **i18n** and **l10n**) for your application, serve the content of your site, and automatically translate the content based on your visitors’ location in the world.

This tutorial uses the [`HTMLRewriter`](/workers/runtime-apis/html-rewriter/) class built into the Cloudflare Workers runtime, which allows for parsing and rewriting of HTML on the Cloudflare global network. This gives developers the ability to efficiently and transparently customize their Workers applications.

![An example site that has been successfully localized in Japanese, German and English](~/assets/images/workers/tutorials/localize-website/i18n.jpg)

---

<Render file="tutorials-before-you-start" />

## Prerequisites

This tutorial is designed to use an existing website. To simplify this process, you will use a free HTML5 template from [HTML5 UP](https://html5up.net). With this website as the base, you will use the `HTMLRewriter` functionality in the Workers platform to overlay an i18n layer, automatically translating the site based on the user’s language.

If you would like to deploy your own version of the site, you can find the source [on GitHub](https://github.com/lauragift21/i18n-example-workers). Instructions on how to deploy this application can be found in the project’s README.

## Create a new application

Create a new application using the [`create-cloudflare`](/pages/get-started/c3), a CLI for creating and deploying new applications to Cloudflare.

<PackageManagers type="create" pkg="cloudflare@latest" args={"i18n-example"} />

For setup, select the following options:

- For _What would you like to start with_?, select `Framework Starter`.
- For _Which development framework do you want to use?_, select `React`.
- For, _Do you want to deploy your application?_, select `No`.

The newly generated `i18n-example` project will contain two folders: `public` and `src` these contain files for a React application:

```sh
cd i18n-example
ls
```

```sh output
public src package.json
```

We have to make a few adjustments to the generated project, first we want to the replace the content inside of the `public` directory, with the default generated HTML code for the HTML5 UP template seen in the demo screenshot: download a [release](https://github.com/signalnerve/i18n-example-workers/archive/v1.0.zip) (ZIP file) of the code for this project and copy the `public` folder to your own project to get started.

Next, let's create a functions directory with an `index.js` file, this will be where the logic of the application will be written.

```sh
mkdir functions
cd functions
touch index.js
```

Additionally, we'll remove the `src/` directory since its content isn't necessary for this project. With the static HTML for this project updated, you can focus on the script inside of the `functions` folder, at `index.js`.

## Understanding `data-i18n-key`

The `HTMLRewriter` class provided in the Workers runtime allows developers to parse HTML and write JavaScript to query and transform every element of the page.

The example website in this tutorial is a basic single-page HTML project that lives in the `public` directory. It includes an `h1` element with the text `Example Site` and a number of `p` elements with different text:

![Demo code shown in Chrome DevTools with the elements described above](~/assets/images/workers/tutorials/localize-website/code-example.png)

What is unique about this page is the addition of [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes) in the HTML – custom attributes defined on a number of elements on this page. The `data-i18n-key` on the `h1` tag on this page, as well as many of the `p` tags, indicates that there is a corresponding internationalization key, which should be used to look up a translation for this text:

```html
<!-- source clipped from i18n-example site -->

<div class="inner">
	<h1 data-i18n-key="headline">Example Site</h1>
	<p data-i18n-key="subtitle">This is my example site. Depending o...</p>
	<p data-i18n-key="disclaimer">Disclaimer: the initial translations...</p>
</div>
```

Using `HTMLRewriter`, you will parse the HTML within the `./public/index.html` page. When a `data-i18n-key` attribute is found, you should use the attribute's value to retrieve a matching translation from the `strings` object. With `HTMLRewriter`, you can query elements to accomplish tasks like finding a data attribute. However, as the name suggests, you can also rewrite elements by taking a translated string and directly inserting it into the HTML.

Another feature of this project is based on the `Accept-Language` header, which exists on incoming requests. You can set the translation language per request, allowing users from around the world to see a locally relevant and translated page.

## Using the HTML Rewriter API

Begin with the `functions/index.js` file. Your application in this tutorial will live entirely in this file.

Inside of this file, start by adding the default code for running a [Pages Function](/pages/functions/get-started/#create-a-function).

```js
export function onRequest(context) {
	return new Response("Hello, world!");
}
```

The important part of the code lives in the `onRequest` function. To implement translations on the site, take the HTML response retrieved from `env.ASSETS.fetch(request)` this allows you to fetch a static asset from your Pages project and pass it into a new instance of `HTMLRewriter`. When instantiating `HTMLRewriter`, you can attach handlers using the `on` function. For this tutorial, you will use the `[data-i18n-key]` selector (refer to the [HTMLRewriter documentation](/workers/runtime-apis/html-rewriter/) for more advanced usage) to locate all elements with the `data-i18n-key` attribute, which means that they must be translated. Any matching element will be passed to an instance of your `ElementHandler` class, which will contain the translation logic. With the created instance of `HTMLRewriter`, the `transform` function takes a `response` and can be returned to the client:

```js
export async function onRequest(context) {
	const { request, env } = context;
	const response = await env.ASSETS.fetch(request);
	return new HTMLRewriter()
		.on("[data-i18n-key]", new ElementHandler(countryStrings))
		.transform(response);
}
```

## Transforming HTML

Your `ElementHandler` will receive every element parsed by the `HTMLRewriter` instance, and due to the expressive API, you can query each incoming element for information.

In [How it works](#understanding-data-i18n-key), the documentation describes `data-i18n-key`, a custom data attribute that could be used to find a corresponding translated string for the website’s user interface. In `ElementHandler`, you can define an `element` function, which will be called as each element is parsed. Inside of the `element` function, you can query for the custom data attribute using `getAttribute`:

```js
class ElementHandler {
	element(element) {
		const i18nKey = element.getAttribute("data-i18n-key");
	}
}
```

With `i18nKey` defined, you can use it to search for a corresponding translated string. You will now set up a `strings` object with key-value pairs corresponding to the `data-i18n-key` value. For now, you will define a single example string, `headline`, with a German `string`, `"Beispielseite"` (`"Example Site"`), and retrieve it in the `element` function:

```js null {1,2,3,4,5,10}
const strings = {
	headline: "Beispielseite",
};

class ElementHandler {
	element(element) {
		const i18nKey = element.getAttribute("data-i18n-key");
		const string = strings[i18nKey];
	}
}
```

Take your translated `string` and insert it into the original element, using the `setInnerContent` function:

```js null {11,12,13}
const strings = {
	headline: "Beispielseite",
};

class ElementHandler {
	element(element) {
		const i18nKey = element.getAttribute("data-i18n-key");
		const string = strings[i18nKey];
		if (string) {
			element.setInnerContent(string);
		}
	}
}
```

To review that everything looks as expected, use the preview functionality built into Wrangler. Call [`wrangler pages dev ./public`](/workers/wrangler/commands/#dev) to open up a live preview of your project. The command is refreshed after every code change that you make.

You can expand on this translation functionality to provide country-specific translations, based on the incoming request’s `Accept-Language` header. By taking this header, parsing it, and passing the parsed language into your `ElementHandler`, you can retrieve a translated string in your user’s home language, provided that it is defined in `strings`.

To implement this:

1. Update the `strings` object, adding a second layer of key-value pairs and allowing strings to be looked up in the format `strings[country][key]`.
2. Pass a `countryStrings` object into our `ElementHandler`, so that it can be used during the parsing process.
3. Grab the `Accept-Language` header from an incoming request, parse it, and pass the parsed language to `ElementHandler`.

To parse the `Accept-Language` header, install the [`accept-language-parser`](https://www.npmjs.com/package/accept-language-parser) npm package:

```sh
npm i accept-language-parser
```

Once imported into your code, use the package to parse the most relevant language for a client based on `Accept-Language` header, and pass it to `ElementHandler`. Your final code for the project, with an included sample translation for Germany and Japan (using Google Translate) looks like this:

```js null {32,33,34,39,62,63,64,65}
import parser from "accept-language-parser";

// do not set to true in production!
const DEBUG = false;

const strings = {
	de: {
		title: "Beispielseite",
		headline: "Beispielseite",
		subtitle:
			"Dies ist meine Beispielseite. Abhängig davon, wo auf der Welt Sie diese Site besuchen, wird dieser Text in die entsprechende Sprache übersetzt.",
		disclaimer:
			"Haftungsausschluss: Die anfänglichen Übersetzungen stammen von Google Translate, daher sind sie möglicherweise nicht perfekt!",
		tutorial:
			"Das Tutorial für dieses Projekt finden Sie in der Cloudflare Workers-Dokumentation.",
		copyright: "Design von HTML5 UP.",
	},
	ja: {
		title: "サンプルサイト",
		headline: "サンプルサイト",
		subtitle:
			"これは私の例のサイトです。 このサイトにアクセスする世界の場所に応じて、このテキストは対応する言語に翻訳されます。",
		disclaimer:
			"免責事項：最初の翻訳はGoogle翻訳からのものですので、完璧ではないかもしれません！",
		tutorial:
			"Cloudflare Workersのドキュメントでこのプロジェクトのチュートリアルを見つけてください。",
		copyright: "HTML5 UPによる設計。",
	},
};

class ElementHandler {
	constructor(countryStrings) {
		this.countryStrings = countryStrings;
	}

	element(element) {
		const i18nKey = element.getAttribute("data-i18n-key");
		if (i18nKey) {
			const translation = this.countryStrings[i18nKey];
			if (translation) {
				element.setInnerContent(translation);
			}
		}
	}
}

export async function onRequest(context) {
	const { request, env } = context;
	try {
		let options = {};
		if (DEBUG) {
			options = {
				cacheControl: {
					bypassCache: true,
				},
			};
		}
		const languageHeader = request.headers.get("Accept-Language");
		const language = parser.pick(["de", "ja"], languageHeader);
		const countryStrings = strings[language] || {};

		const response = await env.ASSETS.fetch(request);
		return new HTMLRewriter()
			.on("[data-i18n-key]", new ElementHandler(countryStrings))
			.transform(response);
	} catch (e) {
		if (DEBUG) {
			return new Response(e.message || e.toString(), {
				status: 404,
			});
		} else {
			return env.ASSETS.fetch(request);
		}
	}
}
```

## Deploy

Your i18n tool built on Cloudflare Pages is complete and it is time to deploy it to your domain.

To deploy your application to a `*.pages.dev` subdomain, you need to specify a directory of static assets to serve, configure the `pages_build_output_dir` in your project’s Wrangler file and set the value to `./public`:

<WranglerConfig>

```toml null {2}
name = "i18n-example"
pages_build_output_dir = "./public"
compatibility_date = "2024-01-29"
```

</WranglerConfig>

Next, you need to configure a deploy script in `package.json` file in your project. Add a deploy script with the value `wrangler pages deploy`:

```json null {3}
"scripts": {
  "dev": "wrangler pages dev",
  "deploy": "wrangler pages deploy"
}
```

Using `wrangler`, deploy to Cloudflare’s network, using the `deploy` command:

```sh
npm run deploy
```

![An example site that has been successfully localized in Japanese, German and English](~/assets/images/workers/tutorials/localize-website/i18n.jpg)

## Related resources

In this tutorial, you built and deployed an i18n tool using `HTMLRewriter`. To review the full source code for this application, refer to the [repository on GitHub](https://github.com/lauragift21/i18n-example-workers).

If you want to get started building your own projects, review the existing list of [Quickstart templates](/workers/get-started/quickstarts/).

---

# Use R2 as static asset storage with Cloudflare Pages

URL: https://developers.cloudflare.com/pages/tutorials/use-r2-as-static-asset-storage-for-pages/

import { WranglerConfig } from "~/components";

This tutorial will teach you how to use [R2](/r2/) as a static asset storage bucket for your [Pages](/pages/) app. This is especially helpful if you're hitting the [file limit](/pages/platform/limits/#files) or the [max file size limit](/pages/platform/limits/#file-size) on Pages.

To illustrate how this is done, we will use R2 as a static asset storage for a fictional cat blog.

## The Cat blog

Imagine you run a static cat blog containing funny cat videos and helpful tips for cat owners. Your blog is growing and you need to add more content with cat images and videos.

The blog is hosted on Pages and currently has the following directory structure:

```
.
├── public
│   ├── index.html
│   ├── static
│   │   ├── favicon.ico
│   │   └── logo.png
│   └── style.css
└── wrangler.toml
```

Adding more videos and images to the blog would be great, but our asset size is above the [file limit on Pages](/pages/platform/limits/#file-size). Let us fix this with R2.

## Create an R2 bucket

The first step is creating an R2 bucket to store the static assets. A new bucket can be created with the dashboard or via Wrangler.

Using the dashboard, navigate to the R2 tab, then click on *Create bucket.* We will name the bucket for our blog _cat-media_. Always remember to give your buckets descriptive names:

![Dashboard](~/assets/images/pages/tutorials/pages-r2/dash.png)

With the bucket created, we can upload media files to R2. I’ll drag and drop two folders with a few cat images and videos into the R2 bucket:

![Upload](/images/pages/tutorials/pages-r2/upload.gif)

Alternatively, an R2 bucket can be created with Wrangler from the command line by running:

```sh
npx wrangler r2 bucket create <bucket_name>
# i.e
# npx wrangler r2 bucket create cat-media
```

Files can be uploaded to the bucket with the following command:

```sh
npx wrangler r2 object put <bucket_name>/<file_name> -f <path_to_file>
# i.e
# npx wrangler r2 object put cat-media/videos/video1.mp4 -f ~/Downloads/videos/video1.mp4
```

## Bind R2 to Pages

To bind the R2 bucket we have created to the cat blog, we need to update the Wrangler configuration.

Open the [Wrangler configuration file](/pages/functions/wrangler-configuration/), and add the following binding to the file. `bucket_name` should be the exact name of the bucket created earlier, while `binding` can be any custom name referring to the R2 resource:

<WranglerConfig>

```toml
[[r2_buckets]]
binding = "MEDIA"
bucket_name = "cat-media"
```

</WranglerConfig>

:::note

Note: The keyword `ASSETS` is reserved and cannot be used as a resource binding.
:::

Save the [Wrangler configuration file](/pages/functions/wrangler-configuration/), and we are ready to move on to the last step.

Alternatively, you can add a binding to your Pages project on the dashboard by navigating to the project’s _Settings_ tab > _Functions_ > _R2 bucket bindings_.

## Serve R2 Assets From Pages

The last step involves serving media assets from R2 on the blog. To do that, we will create a function to handle requests for media files.

In the project folder, create a _functions_ directory. Then, create a _media_ subdirectory and a file named `[[all]].js` in it. All HTTP requests to `/media` will be routed to this file.

After creating the folders and JavaScript file, the blog directory structure should look like:

```
.
├── functions
│   └── media
│       └── [[all]].js
├── public
│   ├── index.html
│   ├── static
│   │   ├── favicon.ico
│   │   └── icon.png
│   └── style.css
└── wrangler.toml

```

Finally, we will add a handler function to `[[all]].js`. This function receives all media requests, and returns the corresponding file asset from R2:

```js
export async function onRequestGet(ctx) {
	const path = new URL(ctx.request.url).pathname.replace("/media/", "");
	const file = await ctx.env.MEDIA.get(path);
	if (!file) return new Response(null, { status: 404 });
	return new Response(file.body, {
		headers: { "Content-Type": file.httpMetadata.contentType },
	});
}
```

## Deploy the blog

Before deploying the changes made so far to our cat blog, let us add a few new posts to `index.html`. These posts depend on media assets served from R2:

```html
<!doctype html>
<html lang="en">
	<body>
		<h1>Awesome Cat Blog! 😺</h1>
		<p>Today's post:</p>
		<video width="320" controls>
			<source src="/media/videos/video1.mp4" type="video/mp4" />
		</video>
		<p>Yesterday's post:</p>
		<img src="/media/images/cat1.jpg" width="320" />
	</body>
</html>
```

With all the files saved, open a new terminal window to deploy the app:

```sh
npx wrangler deploy
```

Once deployed, media assets are fetched and served from the R2 bucket.

![Deployed App](/images/pages/tutorials/pages-r2/deployed.gif)

## **Related resources**

- [Learn how function routing works in Pages.](/pages/functions/routing/)
- [Learn how to create public R2 buckets](/r2/buckets/public-buckets/).
- [Learn how to use R2 from Workers](/r2/api/workers/workers-api-usage/).

---

# Configure HTTP endpoint

URL: https://developers.cloudflare.com/pipelines/build-with-pipelines/sources/http/

import { Render, PackageManagers } from "~/components";

Pipelines support data ingestion over HTTP. When you create a new pipeline using the default settings you will receive a globally scalable ingestion endpoint. To ingest data, make HTTP POST requests to the endpoint.

```sh
$ npx wrangler@latest pipelines create my-clickstream-pipeline --r2-bucket my-bucket

🌀 Authorizing R2 bucket "my-bucket"
🌀 Creating pipeline named "my-clickstream-pipeline"
✅ Successfully created pipeline my-clickstream-pipeline

Id:    0e00c5ff09b34d018152af98d06f5a1xvc
Name:  my-clickstream-pipeline
Sources:
  HTTP:
    Endpoint:        https://0e00c5ff09b34d018152af98d06f5a1xvc.pipelines.cloudflare.com/
    Authentication:  off
    Format:          JSON
  Worker:
    Format:  JSON
Destination:
  Type:         R2
  Bucket:       my-bucket
  Format:       newline-delimited JSON
  Compression:  GZIP
Batch hints:
  Max bytes:     100 MB
  Max duration:  300 seconds
  Max records:   100,000

🎉 You can now send data to your pipeline!

Send data to your pipeline's HTTP endpoint:
curl "https://0e00c5ff09b34d018152af98d06f5a1xvc.pipelines.cloudflare.com/" -d '[{ ...JSON_DATA... }]'
```

## Authentication
You can secure your HTTP ingestion endpoint using Cloudflare API tokens. By default, authentication is turned off. To configure authentication, use the `--require-http-auth` flag while creating or updating a pipeline.

```sh
$ npx wrangler pipelines create [PIPELINE-NAME] --r2-bucket [R2-BUCKET-NAME] --require-http-auth true
```

Once authentication is turned on, you will need to include a Cloudflare API token in your request headers.

### Get API token
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Navigate to your [API Keys](https://dash.cloudflare.com/profile/api-tokens).
3. Select **Create Token**.
4. Choose the template for Workers Pipelines. Select **Continue to summary** > **Create token**. Make sure to copy the API token and save it securely.

### Making authenticated requests
Include the API token you created in the previous step in the headers for your request:

```sh
curl https://<PIPELINE-ID>.pipelines.cloudflare.com
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer ${API_TOKEN}" \
	-d '[{"foo":"bar"}, {"foo":"bar"}, {"foo":"bar"}]'
```

## Specifying CORS Settings
If you want to use your pipeline to ingest client side data, such as website clicks, you will need to configure your [Cross-Origin Resource Sharing (CORS) settings](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).

Without setting your CORS settings, browsers will restrict requests made to your pipeline endpoint. For example, if your website domain is `https://my-website.com`, and you want to post client side data to your pipeline at `https://<PIPELINE-ID>.pipelines.cloudflare.com`, without CORS settings, the request will fail.

To fix this, you need to configure your pipeline to accept requests from `https://my-website.com`. You can do so while creating or updating a pipeline, using the flag `--cors-origins`. You can specify multiple domains separated by a space.

```sh
$ npx wrangler pipelines update [PIPELINE-NAME] --cors-origins https://mydomain.com http://localhost:8787
```

You can specify that all cross origin requests are accepted. We recommend only using this option in development, and not for production use cases.
```sh
$ npx wrangler pipelines update [PIPELINE-NAME] --cors-origins "*"
```

After the `--cors-origins` have been set on your pipeline, your pipeline will respond to preflight requests and `POST` requests with the appropriate `Access-Control-Allow-Origin` headers set.

---

# Sources

URL: https://developers.cloudflare.com/pipelines/build-with-pipelines/sources/

Pipelines let you ingest data from the following sources:
* [HTTP Clients](/pipelines/build-with-pipelines/sources/http), with optional authentication and CORS settings
* [Cloudflare Workers](/workers/), using the [Pipelines Workers API](/pipelines/build-with-pipelines/sources/workers-apis)

Multiple sources can be active on a single pipeline simultaneously. For example, you can create a pipeline which accepts data from Workers and via HTTP. There is no limit to the number of source clients. Multiple Workers can be configured to send data to the same pipeline.

Each pipeline can ingest up to 100 MB/s of data or accept up to 100,000 requests per second, aggregated across all sources.

## Configuring allowed sources
By default, ingestion via HTTP and from Workers is turned on. You can configure the allowed sources by using the `--source` flag while creating or updating a pipeline.

For example, to create a pipeline which only accepts data via a Worker, you can run this command:
```sh
$ npx wrangler pipelines create [PIPELINE-NAME] --r2-bucket [R2-BUCKET-NAME] --source worker
```

## Accepted data formats
Pipelines accept arrays of valid JSON objects. You can send multiple objects in a single request, provided the total data volume is within the [documented limits](/pipelines/platform/limits). Sending data in a different format will result in an error.

---

# Workers API

URL: https://developers.cloudflare.com/pipelines/build-with-pipelines/sources/workers-apis/

import { Render, PackageManagers, WranglerConfig } from "~/components";

Pipelines exposes an API directly to your [Workers](/workers) scripts via the [bindings](/workers/runtime-apis/bindings/#what-is-a-binding) concept. Bindings allow you to securely send data to a pipeline without having to manage API keys or clients. Sending data via a Worker is enabled by default.

## Send data from a Worker
### Setup a binding
Bind to a pipeline by defining a `pipelines` binding within your Wrangler configuration. For example:

<WranglerConfig>

```toml title="wrangler.toml"
#:schema node_modules/wrangler/config-schema.json
name = "pipeline-starter"
main = "src/index.ts"
compatibility_date = "2025-04-01"

[[pipelines]]
pipeline = "<MY-PIPELINE-NAME>" # The name of your Pipeline
binding = "PIPELINE" # The binding name, accessed using env.MY_PIPELINE
```

</WranglerConfig>

You can bind multiple pipelines to a Worker.

### Send data
The Pipelines binding exposes a `send()` method. For example, to log inbound HTTP requests to your Worker:

```ts
export default {
	async fetch(request, env, ctx): Promise<Response> {
		let log = {
			url: request.url,
			method: request.method,
			headers: Object.fromEntries(request.headers),
		  };
		await env.PIPELINE.send([log]);
		return new Response('Hello World!');
	},
} satisfies ExportedHandler<Env>;
```

## Workers API
### `Pipeline`
A binding which allows a Worker to send messages to a pipeline.

```ts
interface Pipeline<PipelineRecord> {
  send(records: PipelineRecord[]): Promise<void>;
}
```

* `send(records)`: `Promise<void>`

  * Sends records to the pipeline. The body must be an array of objects which are JSON serializable.
  * When the promise resolves, the records are confirmed to be ingested.

:::note
When running your Worker locally, pipelines are partially simulated. Worker code which sends data to a pipeline will execute successfully. However, the full pipeline, including batching & writing to R2, will not be executed locally.
:::

---

# Ingest data from a Worker, and analyze using MotherDuck

URL: https://developers.cloudflare.com/pipelines/tutorials/query-data-with-motherduck/

import { Render, PackageManagers, Details, WranglerConfig } from "~/components";

In this tutorial, you will learn how to ingest clickstream data to a [R2 bucket](/r2) using Pipelines. You will use the Pipeline binding to send the clickstream data to the R2 bucket from your Worker. You will also learn how to connect the bucket to MotherDuck. You will then query the data using MotherDuck.

For this tutorial, you will build a landing page of an e-commerce website. A user can click on the view button to view the product details or click on the add to cart button to add the product to their cart.

## Prerequisites

1. A [MotherDuck](https://motherduck.com/) account.
2. Install [`Node.js`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).

<Details header="Node.js version manager">
	Use a Node version manager like [Volta](https://volta.sh/) or
	[nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change
	Node.js versions. [Wrangler](/workers/wrangler/install-and-update/), discussed
	later in this guide, requires a Node version of `16.17.0` or later.
</Details>

## 1. Create a new project

You will create a new Worker project that will use [Static Assets](/workers/static-assets/) to serve the HTML file.

Create a new Worker project by running the following commands:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"e-commerce-pipelines"}
/>

    <Render
    	file="c3-post-run-steps"
    	product="workers"
    	params={{
    	category: "hello-world",
    	type: "SSR / full-stack app",
    	lang: "TypeScript",
    	}}
    />

Navigate to the `e-commerce-pipelines` directory:

```sh frame="none"
cd e-commerce-pipelines
```

## 2. Update the frontend

Using Static Assets, you can serve the frontend of your application from your Worker. The above step creates a new Worker project with a default `public/index.html` file. Update the `public/index.html` file with the following HTML code:

<details>
	<summary>Select to view the HTML code</summary>
```html
<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8" />
		<title>E-commerce Store</title>
		<script src="https://cdn.tailwindcss.com"></script>
	</head>
	<body>
		<nav class="bg-gray-800 text-white p-4">
			<div class="container mx-auto flex justify-between items-center">
				<a href="/" class="text-xl font-bold"> E-Commerce Demo </a>
				<div class="space-x-4 text-gray-800">
					<a href="#">
						<button class="border border-input bg-white h-10 px-4 py-2 rounded-md">Cart</button>
					</a>
					<a href="#">
						<button class="border border-input bg-white h-10 px-4 py-2 rounded-md">Login</button>
					</a>
					<a href="#">
						<button class="border border-input bg-white h-10 px-4 py-2 rounded-md">Signup</button>
					</a>
				</div>
			</div>
		</nav>
		<div class="container mx-auto px-4 py-8">
			<h1 class="text-3xl font-bold mb-6">Our Products</h1>
			<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6" id="products">
				<!-- This section repeats for each product -->

    			<!-- End of product section -->
    		</div>
    	</div>

    	<script>
    		// demo products
    		const products = [
    			{
    				id: 1,
    				name: 'Smartphone X',
    				desc: 'Latest model with advanced features',
    				cost: 799,
    			},
    			{
    				id: 2,
    				name: 'Laptop Pro',
    				desc: 'High-performance laptop for professionals',
    				cost: 1299,
    			},
    			{
    				id: 3,
    				name: 'Wireless Earbuds',
    				desc: 'True wireless earbuds with noise cancellation',
    				cost: 149,
    			},
    			{
    				id: 4,
    				name: 'Smart Watch',
    				desc: 'Fitness tracker and smartwatch combo',
    				cost: 199,
    			},
    			{
    				id: 5,
    				name: '4K TV',
    				desc: 'Ultra HD smart TV with HDR',
    				cost: 599,
    			},
    			{
    				id: 6,
    				name: 'Gaming Console',
    				desc: 'Next-gen gaming system',
    				cost: 499,
    			},
    		];

    		// function to render products
    		function renderProducts() {
    			console.log('Rendering products...');
    			const productContainer = document.getElementById('products');
    			productContainer.innerHTML = ''; // Clear existing content
    			products.forEach((product) => {
    				const productElement = document.createElement('div');
    				productElement.classList.add('rounded-lg', 'border', 'bg-card', 'text-card-foreground', 'shadow-sm');
    				productElement.innerHTML = `
            <div class="flex flex-col space-y-1.5 p-6">
              <h2 class="text-2xl font-semibold leading-none tracking-tight">${product.name}</h2>
            </div>
            <div class="p-6 pt-0">
              <p>${product.desc}</p>
              <p class="font-bold mt-2">$${product.cost}</p>
            </div>
            <div class="flex items-center p-6 pt-0 flex justify-between">
              <button class="border px-4 py-2 rounded-md" onclick="handleClick('product_view', ${product.id})" name="">View Details</button>
              <button class="border px-4 py-2 rounded-md" onclick="handleClick('add_to_cart', ${product.id})">Add to Cart</button>
            </div>
          `;
    				productContainer.appendChild(productElement);
    			});
    		}
    		renderProducts();

    		// function to handle click events
    		async function handleClick(action, id) {
    			console.log(`Clicked ${action} for product with id ${id}`);
    		}
    	</script>
    </body>

</html>

```
</details>

The above code does the following:

- Uses Tailwind CSS to style the page.
- Renders a list of products.
- Adds a button to view the details of a product.
- Adds a button to add a product to the cart.
- Contains a `handleClick` function to handle the click events. This function logs the action and the product ID. In the next steps, you will add the logic to send the click events to your pipeline.

## 3. Generate clickstream data

You need to send clickstream data like the `timestamp`, `user_id`, `session_id`, and `device_info` to your pipeline. You can generate this data on the client side. Add the following function in the `<script>` tag in your `public/index.html`. This function gets the device information:

```js title="public/index.html"
function extractDeviceInfo(userAgent) {
	let browser = "Unknown";
	let os = "Unknown";
	let device = "Unknown";

	// Extract browser
	if (userAgent.includes("Firefox")) {
		browser = "Firefox";
	} else if (userAgent.includes("Chrome")) {
		browser = "Chrome";
	} else if (userAgent.includes("Safari")) {
		browser = "Safari";
	} else if (userAgent.includes("Opera") || userAgent.includes("OPR")) {
		browser = "Opera";
	} else if (userAgent.includes("Edge")) {
		browser = "Edge";
	} else if (userAgent.includes("MSIE") || userAgent.includes("Trident/")) {
		browser = "Internet Explorer";
	}

	// Extract OS
	if (userAgent.includes("Win")) {
		os = "Windows";
	} else if (userAgent.includes("Mac")) {
		os = "MacOS";
	} else if (userAgent.includes("Linux")) {
		os = "Linux";
	} else if (userAgent.includes("Android")) {
		os = "Android";
	} else if (userAgent.includes("iOS")) {
		os = "iOS";
	}

	// Extract device
	const mobileKeywords = [
		"Android",
		"webOS",
		"iPhone",
		"iPad",
		"iPod",
		"BlackBerry",
		"Windows Phone",
	];
	device = mobileKeywords.some((keyword) => userAgent.includes(keyword))
		? "Mobile"
		: "Desktop";

	return { browser, os, device };
}
```

Next, update the `handleClick` function to make a `POST` request to the `/api/clickstream` endpoint with the data:

```js title="public/index.html" ins={3-40}
async function handleClick(action, id) {
	console.log(`Clicked ${action} for product with id ${id}`);

	const userAgent = window.navigator.userAgent;
	const timestamp = new Date().toISOString();
	const { browser, os, device } = extractDeviceInfo(userAgent);

	const data = {
		timestamp,
		session_id: "1234567890abcdef", // For production use a unique session ID
		user_id: "user" + Math.floor(Math.random() * 1000), // For production use a unique user ID
		event_data: {
			event_id: Math.floor(Math.random() * 1000),
			event_type: action,
			page_url: window.location.href,
			timestamp,
			product_id: id,
		},
		device_info: {
			browser,
			os,
			device,
			userAgent,
		},
		referrer: document.referrer,
	};
	try {
		const response = await fetch("/api/clickstream", {
			method: "POST",
			headers: {
				"Content-Type": "application/json",
			},
			body: JSON.stringify({ data }),
		});
		if (!response.ok) {
			throw new Error("Failed to send data to pipeline");
		}
	} catch (error) {
		console.error("Error sending data to pipeline:", error);
	}
}
```

The `handleClick` function does the following:

- Gets the device information using the `extractDeviceInfo` function.
- Creates a `POST` request to the `/api/clickstream` endpoint with the data.
- Logs any errors that occur.

## 4. Create an R2 bucket

You will create a new R2 bucket to use as the sink for our pipeline. Create a new r2 bucket `clickstream-data` using the [Wrangler CLI](/workers/wrangler/):

```sh
npx wrangler r2 bucket create clickstream-data
```

## 5. Create a pipeline
You need to create a new pipeline and connect it to the R2 bucket you created in the previous step.

Create a new pipeline `clickstream-pipeline` using the [Wrangler CLI](/workers/wrangler/):

```sh
npx wrangler pipelines create clickstream-pipeline --r2-bucket clickstream-data --compression none --batch-max-seconds 5
```

When you run the command, you will be prompted to authorize Cloudflare Workers Pipelines to create R2 API tokens on your behalf. These tokens are required by your Pipeline. Your Pipeline uses these tokens when loading data into your bucket. You can approve the request through the browser link which will open automatically.

:::note
The above command creates a pipeline using two optional flags: `--compression none`, and `--batch-max-seconds 5`.

With these flags, your pipeline will deliver an uncompressed file of data to your R2 bucket every 5 seconds.

These flags are useful for testing, but we recommend keeping the default settings in a production environment.
:::

```txt output
✅ Successfully created Pipeline "clickstream-pipeline" with ID <PIPELINE_ID>

Id:    <PIPELINE_ID>
Name:  clickstream-pipeline
Sources:
  HTTP:
    Endpoint:        https://<PIPELINE_ID>.pipelines.cloudflare.com
    Authentication:  off
    Format:          JSON
  Worker:
    Format:  JSON
Destination:
  Type:         R2
  Bucket:       clickstream-data
  Format:       newline-delimited JSON
  Compression:  NONE
  Batch hints:
    Max bytes:     100 MB
    Max duration:  300 seconds
    Max records:   10,000,000

🎉 You can now send data to your Pipeline!

Send data to your Pipeline's HTTP endpoint:

curl "https://<PIPELINE_ID>.pipelines.cloudflare.com" -d '[{"foo": "bar"}]'
```

## 5. Send clickstream data to your pipeline

You have setup the frontend of your application to make a call to the `/api/clickstream` route, everytime the user clicks on one of the buttons. The application makes a call to the `/api/clickstream` endpoint to send the clickstream data to your pipeline. The `/api/clickstream` endpoint is handled by a Worker in the `src/index.ts` file.

You will use the pipelines binding to send the clickstream data to your pipeline. In your `wrangler` file, add the following bindings:

<WranglerConfig>

```toml
[[pipelines]]
binding = "PIPELINE"
pipeline = "clickstream-pipeline"
```

</WranglerConfig>

Next, update the type in the `worker-configuration.d.ts` file. Add the following type:

```ts title="worker-configuration.d.ts"
interface Env {
	PIPELINE: Pipeline;
}
```

Update the `src/index.ts` file to handle the `POST` request:

```ts title="src/index.ts"
export default {
	async fetch(request, env, ctx): Promise<Response> {
		const pathname = new URL(request.url).pathname;
		const method = request.method;
		if (pathname === "/api/clickstream" && method === "POST") {
			const body = (await request.json()) as { data: any };
			try {
				await env.PIPELINE.send([body.data]);
				return new Response("OK", { status: 200 });
			} catch (error) {
				console.error(error);
				return new Response("Internal Server Error", { status: 500 });
			}
		}
		return new Response("Hello World!");
	},
} satisfies ExportedHandler<Env>;
```

The `src/index.ts` file does the following:

- Checks if the request is a `POST` request to the `/api/clickstream` endpoint.
- Extracts the data from the request body.
- Sends the data to your Pipeline.
- Returns a response to the client.

## 6. Deploy the application

You can run the local server to the test the application. However, the data will be not be sent to the production pipeline. You will need to deploy the application to send the data to the pipeline.

To start the development server execute the below command and naviagte to `http://localhost:8787`:

```sh
npm run dev
```

When you click on the `View Details` or the `Add to Cart` button, the `handleClick` function calls the `/api/clickstream` endpoint. This endpoint uses the pipelines bindinding and sends the clickstream data. Note that no actual data is sent to the pipeline when running the application locally.

To deploy the application, run the following command:

```sh
npm run deploy
```

This will deploy the application to the Cloudflare Workers platform.

```txt output
🌀 Building list of assets...
🌀 Starting asset upload...
🌀 Found 1 new or modified static asset to upload. Proceeding with upload...
+ /index.html
Uploaded 1 of 1 assets
✨ Success! Uploaded 1 file (2.37 sec)

Total Upload: 25.73 KiB / gzip: 6.17 KiB
Worker Startup Time: 15 ms
Uploaded e-commerce-clickstream (11.79 sec)
Deployed e-commerce-clickstream triggers (7.60 sec)
  https://<URL>.workers.dev
Current Version ID: <VERSION_ID>
```

You can access the application at the URL provided in the output of the command. Now when you click on the `View Details` or `Add to Cart` button, the clickstream data will be sent to your pipeline.

## 7. Connect the R2 bucket to MotherDuck

Your application sends clickstream data to the R2 bucket using pipelines. In this step, you will connect the R2 bucket to MotherDuck.

You can connect the bucket to MotherDuck in several ways, which you can learn about from the [MotherDuck documentation](https://motherduck.com/docs/integrations/cloud-storage/cloudflare-r2/). In this tutorial, you will connect the bucket to MotherDuck using the MotherDuck dashboard.

Before connecting the bucket to MotherDuck, you need to obtain the Access Key ID and Secret Access Key for the R2 bucket. You can find the instructions to obtain the keys in the [R2 API documentation](/r2/api/tokens/).

1. Log in to the MotherDuck dashboard and select your profile.
2. Navigate to the **Secrets** page.
3. Select the **Add Secret** button and enter the following information:

   - **Secret Name**: `Clickstream pipeline`
   - **Secret Type**: `Cloudflare R2`
   - **Access Key ID**: `ACCESS_KEY_ID` (replace with the Access Key ID)
   - **Secret Access Key**: `SECRET_ACCESS_KEY` (replace with the Secret Access Key)

4. Select the **Add Secret** button to save the secret.

## 8. Query the data

In this step, you will query the data stored in the R2 bucket using MotherDuck.

1. Navigate back to the MotherDuck dashboard and select the **+** icon to add a new Notebook.
2. Select the **Add Cell** button to add a new cell to the notebook.

3. In the cell, enter the following query and select the **Run** button to execute the query:

```sql
SELECT * FROM read_json_auto('r2://<BUCKET_NAME>/**/*');
```

Replace the `<BUCKET_NAME>` placeholder with the name of the R2 bucket.

The query will return the data stored in the R2 bucket.

## Conclusion

You have successfully built an e-commerce application that leverages Cloudflare's Pipelines, R2, and Workers. Through this tutorial, you've gained hands-on experience in:

1. Creating a Workers project with a static frontend
2. Generating and capturing clickstream data
3. Setting up a Cloudflare Pipelines to ingest data into R2
4. Connecting your R2 bucket to MotherDuck for advanced querying capabilities

This project serves as a foundation for building scalable, data-driven applications. You can now expand on this knowledge to create more complex e-commerce features, implement advanced analytics, or explore other Cloudflare products to enhance your application further.

For your next steps, consider exploring more advanced querying techniques with MotherDuck, implementing real-time analytics, or integrating additional Cloudflare services to further optimize your application's performance and security.

You can find the source code of the application in the [GitHub repository](https://github.com/harshil1712/cf-pipelines-bindings-demo).

---

# Create a data lake of clickstream data

URL: https://developers.cloudflare.com/pipelines/tutorials/send-data-from-client/

import { Render, PackageManagers, Details, WranglerConfig } from "~/components";

In this tutorial, you will learn how to build a data lake of website interaction events (clickstream data), using Pipelines.

Data lakes are a way to store large volumes of raw data in an object storage service such as [R2](/r2). You can run queries over a data lake to analyze the raw events.

For this tutorial, you will build a landing page for an e-commerce website. Users can click on the website, to view products or add them to the cart. When a user clicks on buttons on the page, events will be sent to a pipeline. These events are sent from the client-side (directly from the user's browser). Your pipeline will automatically batch the ingested data, build output files, and deliver them to an [R2 bucket](/r2) to build your data lake.

## Prerequisites

1. Install [`Node.js`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).

<Details header="Node.js version manager">
	Use a Node version manager like [Volta](https://volta.sh/) or
	[nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change
	Node.js versions. [Wrangler](/workers/wrangler/install-and-update/), discussed
	later in this guide, requires a Node version of `16.17.0` or later.
</Details>

## 1. Create a new Workers project

You will create a new Worker project that will use [Static Assets](/workers/static-assets/) to serve the HTML file. While you can use any front-end framework, this tutorial uses plain HTML and JavaScript to keep things simple. If you are interested in learning how to build and deploy a web application on Workers with Static Assets, you can refer to the [Frameworks](/workers/framework-guides/) documentation.

Create a new Worker project by running the following commands:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"e-commerce-pipelines-client-side"}
/>

    <Render
    	file="c3-post-run-steps"
    	product="workers"
    	params={{
    	category: "hello-world",
    	type: "SSR / full-stack app",
    	lang: "TypeScript",
    	}}
    />

Navigate to the `e-commerce-pipelines-client-side` directory:

```sh frame="none"
cd e-commerce-pipelines-client-side
```

## 2. Update the website frontend

Using Static Assets, you can serve the frontend of your application from your Worker. The above step creates a new Worker project with a default `public/index.html` file. Update the `public/index.html` file with the following HTML code:

<details>
	<summary>Select to view the HTML code</summary>
```html
<!DOCTYPE html>
<html>
	<head>
		<meta charset="utf-8" />
		<title>E-commerce Store</title>
		<script src="https://cdn.tailwindcss.com"></script>
	</head>
	<body>
		<nav class="bg-gray-800 text-white p-4">
			<div class="container mx-auto flex justify-between items-center">
				<a href="/" class="text-xl font-bold"> E-Commerce Demo </a>
				<div class="space-x-4 text-gray-800">
					<a href="#">
						<button class="border border-input bg-white h-10 px-4 py-2 rounded-md">Cart</button>
					</a>
					<a href="#">
						<button class="border border-input bg-white h-10 px-4 py-2 rounded-md">Login</button>
					</a>
					<a href="#">
						<button class="border border-input bg-white h-10 px-4 py-2 rounded-md">Signup</button>
					</a>
				</div>
			</div>
		</nav>
		<div class="container mx-auto px-4 py-8">
			<h1 class="text-3xl font-bold mb-6">Our Products</h1>
			<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6" id="products">
				<!-- This section repeats for each product -->

    			<!-- End of product section -->
    		</div>
    	</div>

    	<script>
    		// demo products
    		const products = [
    			{
    				id: 1,
    				name: 'Smartphone X',
    				desc: 'Latest model with advanced features',
    				cost: 799,
    			},
    			{
    				id: 2,
    				name: 'Laptop Pro',
    				desc: 'High-performance laptop for professionals',
    				cost: 1299,
    			},
    			{
    				id: 3,
    				name: 'Wireless Earbuds',
    				desc: 'True wireless earbuds with noise cancellation',
    				cost: 149,
    			},
    			{
    				id: 4,
    				name: 'Smart Watch',
    				desc: 'Fitness tracker and smartwatch combo',
    				cost: 199,
    			},
    			{
    				id: 5,
    				name: '4K TV',
    				desc: 'Ultra HD smart TV with HDR',
    				cost: 599,
    			},
    			{
    				id: 6,
    				name: 'Gaming Console',
    				desc: 'Next-gen gaming system',
    				cost: 499,
    			},
    		];

    		// function to render products
    		function renderProducts() {
    			console.log('Rendering products...');
    			const productContainer = document.getElementById('products');
    			productContainer.innerHTML = ''; // Clear existing content
    			products.forEach((product) => {
    				const productElement = document.createElement('div');
    				productElement.classList.add('rounded-lg', 'border', 'bg-card', 'text-card-foreground', 'shadow-sm');
    				productElement.innerHTML = `
            <div class="flex flex-col space-y-1.5 p-6">
              <h2 class="text-2xl font-semibold leading-none tracking-tight">${product.name}</h2>
            </div>
            <div class="p-6 pt-0">
              <p>${product.desc}</p>
              <p class="font-bold mt-2">$${product.cost}</p>
            </div>
            <div class="flex items-center p-6 pt-0 flex justify-between">
              <button class="border px-4 py-2 rounded-md" onclick="handleClick('product_view', ${product.id})" name="">View Details</button>
              <button class="border px-4 py-2 rounded-md" onclick="handleClick('add_to_cart', ${product.id})">Add to Cart</button>
            </div>
          `;
    				productContainer.appendChild(productElement);
    			});
    		}
    		renderProducts();

    		// function to handle click events
    		async function handleClick(action, id) {
    			console.log(`Clicked ${action} for product with id ${id}`);
    		}
    	</script>
    </body>

</html>
```
</details>

The above code does the following:

- Uses Tailwind CSS to style the page.
- Renders a list of products.
- Adds a button to view the details of a product.
- Adds a button to add a product to the cart.
- Contains a `handleClick` function to handle the click events. This function logs the action and the product ID. In the next steps, you will create a pipeline and add the logic to send the click events to this pipeline.

## 3. Create an R2 Bucket
We'll create a new R2 bucket to use as the sink for our pipeline. Create a new r2 bucket `clickstream-bucket` using the [Wrangler CLI](/workers/wrangler/). Open a terminal window, and run the following command:

```sh
npx wrangler r2 bucket create clickstream-bucket
```

## 4. Create a pipeline
You need to create a new pipeline and connect it to your R2 bucket.

Create a new pipeline `clickstream-pipeline-client` using the [Wrangler CLI](/workers/wrangler/). Open a terminal window, and run the following command:

```sh
npx wrangler pipelines create clickstream-pipeline-client --r2-bucket clickstream-bucket --compression none --batch-max-seconds 5
```

When you run the command, you will be prompted to authorize Cloudflare Workers Pipelines to create R2 API tokens on your behalf. These tokens are required by your Pipeline. Your Pipeline uses these tokens when loading data into your bucket. You can approve the request through the browser link which will open automatically.

:::note
The above command creates a pipeline using two optional flags: `--compression none`, and `--batch-max-seconds 5`.

With these flags, your pipeline will deliver an uncompressed file of data to your R2 bucket every 5 seconds.

These flags are useful for testing, but we recommend keeping the default settings in a production environment.
:::

```txt output
✅ Successfully created Pipeline "clickstream-pipeline-client" with ID <PIPELINE_ID>

Id:    <PIPELINE_ID>
Name:  clickstream-pipeline-client
Sources:
  HTTP:
    Endpoint:        https://<PIPELINE_ID>.pipelines.cloudflare.com
    Authentication:  off
    Format:          JSON
  Worker:
    Format:  JSON
Destination:
  Type:         R2
  Bucket:       clickstream-bucket
  Format:       newline-delimited JSON
  Compression:  NONE
  Batch hints:
    Max bytes:     100 MB
    Max duration:  300 seconds
    Max records:   10,000,000

🎉 You can now send data to your Pipeline!

Send data to your Pipeline's HTTP endpoint:

curl "https://<PIPELINE_ID>.pipelines.cloudflare.com" -d '[{"foo": "bar"}]'
```

Make a note of the URL of the pipeline. You will use this URL to send the clickstream data from the client-side.

## 5. Generate clickstream data

You need to send clickstream data like the `timestamp`, `user_id`, `session_id`, and `device_info` to your pipeline. You can generate this data on the client side. Add the following function in the `<script>` tag in your `public/index.html`. This function gets the device information:

```js title="public/index.html"
function extractDeviceInfo(userAgent) {
	let browser = "Unknown";
	let os = "Unknown";
	let device = "Unknown";

	// Extract browser
	if (userAgent.includes("Firefox")) {
		browser = "Firefox";
	} else if (userAgent.includes("Chrome")) {
		browser = "Chrome";
	} else if (userAgent.includes("Safari")) {
		browser = "Safari";
	} else if (userAgent.includes("Opera") || userAgent.includes("OPR")) {
		browser = "Opera";
	} else if (userAgent.includes("Edge")) {
		browser = "Edge";
	} else if (userAgent.includes("MSIE") || userAgent.includes("Trident/")) {
		browser = "Internet Explorer";
	}

	// Extract OS
	if (userAgent.includes("Win")) {
		os = "Windows";
	} else if (userAgent.includes("Mac")) {
		os = "MacOS";
	} else if (userAgent.includes("Linux")) {
		os = "Linux";
	} else if (userAgent.includes("Android")) {
		os = "Android";
	} else if (userAgent.includes("iOS")) {
		os = "iOS";
	}

	// Extract device
	const mobileKeywords = [
		"Android",
		"webOS",
		"iPhone",
		"iPad",
		"iPod",
		"BlackBerry",
		"Windows Phone",
	];
	device = mobileKeywords.some((keyword) => userAgent.includes(keyword))
		? "Mobile"
		: "Desktop";

	return { browser, os, device };
}
```

## 6. Send clickstream data to your pipeline

You will send the clickstream data to the pipline from the client-side. To do that, update the `handleClick` function to make a `POST` request to the pipeline URL with the data. Replace `<PIPELINE_URL>` with the URL of your pipeline.

```js title="public/index.html" ins={3-40}
async function handleClick(action, id) {
	console.log(`Clicked ${action} for product with id ${id}`);

	const userAgent = window.navigator.userAgent;
	const timestamp = new Date().toISOString();
	const { browser, os, device } = extractDeviceInfo(userAgent);

	const data = {
		timestamp,
		session_id: "1234567890abcdef", // For production use a unique session ID
		user_id: "user" + Math.floor(Math.random() * 1000), // For production use a unique user ID
		event_data: {
			event_id: Math.floor(Math.random() * 1000),
			event_type: action,
			page_url: window.location.href,
			timestamp,
			product_id: id,
		},
		device_info: {
			browser,
			os,
			device,
			userAgent,
		},
		referrer: document.referrer,
	};
	try {
		const response = await fetch("<PIPELINE_URL>", {
			method: "POST",
			headers: {
				"Content-Type": "application/json",
			},
			body: JSON.stringify([data]),
		});
		if (!response.ok) {
			throw new Error("Failed to send data to pipeline");
		}
	} catch (error) {
		console.error("Error sending data to pipeline:", error);
	}
}
```

The `handleClick` function does the following:

- Gets the device information using the `extractDeviceInfo` function.
- Makes a `POST` request to the pipeline with the data.
- Logs any errors that occur.

If you start the development server and open the application in the browser, you can see the `handleClick` function gets executed when you click on the `View Details` or `Add to Cart` button.

```sh
npm run dev
```

However, no data gets sent to the pipeline. Inspect the browser console to view the error message. The error message you see is for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). In the next step, you will update the CORS settings to allow the client-side JavaScript to send data to the pipeline.

## 7. Update CORS settings

By default, the HTTP ingestion endpoint for your pipeline does not allow cross-origin requests. You need to update the CORS settings to allow the client-side JavaScript to send data to the pipeline. To update the CORS settings, execute the following command:

```sh
npx wrangler pipelines update clickstream-pipeline-client --cors-origins http://localhost:8787
```

Now when you run the development server locally, and open the website in a browser, clickstream data will be successfully sent to the pipeline. You can learn more about the CORS settings in the [Specifying CORS settings](/pipelines/build-with-pipelines/sources/http/#specifying-cors-settings) documentation.

## 8. Deploy the application

To deploy the application, run the following command:

```sh
npm run deploy
```

This will deploy the application to the Cloudflare Workers platform.

```txt output
🌀 Building list of assets...
🌀 Starting asset upload...
🌀 Found 1 new or modified static asset to upload. Proceeding with upload...
+ /index.html
Uploaded 1 of 1 assets
✨ Success! Uploaded 1 file (2.37 sec)

Total Upload: 25.73 KiB / gzip: 6.17 KiB
Worker Startup Time: 15 ms
Uploaded e-commerce-pipelines-client-side (11.79 sec)
Deployed e-commerce-pipelines-client-side triggers (7.60 sec)
  https://<URL>.workers.dev
Current Version ID: <VERSION_ID>
```

We now need to update the pipeline's CORS settings again. This time, we'll include the URL of our newly deployed application. Run the command below, and replace `<URL>` with the URL of the application.

```sh
npx wrangler pipelines update clickstream-pipeline-client --cors-origins http://localhost:8787 https://<URL>.workers.dev
```

Now, you can access the application at the deployed URL. When you click on the `View Details` or `Add to Cart` button, the clickstream data will be sent to your pipeline.

## 9. View the data in R2

You can view the data in the R2 bucket. If you are not signed in to the Cloudflare dashboard, sign in and navigate to the [R2 overview](https://dash.cloudflare.com/?to=/:account/r2/overview) page.

Open the bucket you configured for your pipeline in Step 3. You can see files, representing the clickstream data. These files are newline delimited JSON files. Each row in a file represents one click event. Download one of the files, and open it in your preferred text editor to see the output:

```json
{"timestamp":"2025-04-06T16:24:29.213Z","session_id":"1234567890abcdef","user_id":"user965","event_data":{"event_id":673,"event_type":"product_view","page_url":"https://<URL>.workers.dev/","timestamp":"2025-04-06T16:24:29.213Z","product_id":2},"device_info":{"browser":"Chrome","os":"Linux","device":"Mobile","userAgent":"Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Mobile Safari/537.36"},"referrer":""}
{"timestamp":"2025-04-06T16:24:30.436Z","session_id":"1234567890abcdef","user_id":"user998","event_data":{"event_id":787,"event_type":"product_view","page_url":"https://<URL>.workers.dev/","timestamp":"2025-04-06T16:24:30.436Z","product_id":4},"device_info":{"browser":"Chrome","os":"Linux","device":"Mobile","userAgent":"Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Mobile Safari/537.36"},"referrer":""}
{"timestamp":"2025-04-06T16:24:31.330Z","session_id":"1234567890abcdef","user_id":"user22","event_data":{"event_id":529,"event_type":"product_view","page_url":"https://<URL>.workers.dev/","timestamp":"2025-04-06T16:24:31.330Z","product_id":4},"device_info":{"browser":"Chrome","os":"Linux","device":"Mobile","userAgent":"Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Mobile Safari/537.36"},"referrer":""}
{"timestamp":"2025-04-06T16:24:31.879Z","session_id":"1234567890abcdef","user_id":"user750","event_data":{"event_id":756,"event_type":"product_view","page_url":"https://<URL>.workers.dev/","timestamp":"2025-04-06T16:24:31.879Z","product_id":4},"device_info":{"browser":"Chrome","os":"Linux","device":"Mobile","userAgent":"Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Mobile Safari/537.36"},"referrer":""}
{"timestamp":"2025-04-06T16:24:33.978Z","session_id":"1234567890abcdef","user_id":"user333","event_data":{"event_id":467,"event_type":"product_view","page_url":"https://<URL>.workers.dev/","timestamp":"2025-04-06T16:24:33.978Z","product_id":6},"device_info":{"browser":"Chrome","os":"Linux","device":"Mobile","userAgent":"Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Mobile Safari/537.36"},"referrer":""}
```

## 10. Optional: Connect a query engine to your R2 bucket and query the data
Once you have collected the raw events in R2, you might want to query the events, to answer questions such as "how many events occurred?". You can connect a query engine, such as MotherDuck, to your R2 bucket.

You can connect the bucket to MotherDuck in several ways, which you can learn about from the [MotherDuck documentation](https://motherduck.com/docs/integrations/cloud-storage/cloudflare-r2/). In this tutorial, you will connect the bucket to MotherDuck using the MotherDuck dashboard.

### Connect your bucket to MotherDuck

Before connecting the bucket to MotherDuck, you need to obtain the Access Key ID and Secret Access Key for the R2 bucket. You can find the instructions to obtain the keys in the [R2 API documentation](/r2/api/tokens/).

1. Log in to the MotherDuck dashboard and select your profile.
2. Navigate to the **Secrets** page.
3. Select the **Add Secret** button and enter the following information:

   - **Secret Name**: `Clickstream pipeline`
   - **Secret Type**: `Cloudflare R2`
   - **Access Key ID**: `ACCESS_KEY_ID` (replace with the Access Key ID)
   - **Secret Access Key**: `SECRET_ACCESS_KEY` (replace with the Secret Access Key)

4. Select the **Add Secret** button to save the secret.

### Query the data
In this step, you will query the data stored in the R2 bucket using MotherDuck.

1. Navigate back to the MotherDuck dashboard and select the **+** icon to add a new Notebook.
2. Select the **Add Cell** button to add a new cell to the notebook.

3. In the cell, enter the following query and select the **Run** button to execute the query:

```sql
SELECT count(*) FROM read_json_auto('r2://clickstream-bucket/**/*');
```

The query will return a count of all the events received.

## Conclusion

You have successfully created a Pipeline and used it to send clickstream data from the client. Through this tutorial, you've gained hands-on experience in:

1. Creating a Workers project, using static assets
2. Generating and capturing clickstream data
3. Setting up a pipeline to ingest data into R2
4. Deploying the application to Workers
5. Using MotherDuck to query the data

You can find the source code of the application in the [GitHub repository](https://github.com/harshil1712/e-commerce-pipelines-client-side).

---

# Handle rate limits of external APIs

URL: https://developers.cloudflare.com/queues/tutorials/handle-rate-limits/

import { Render, PackageManagers, WranglerConfig } from "~/components";

This tutorial explains how to use Queues to handle rate limits of external APIs by building an application that sends email notifications using [Resend](https://www.resend.com/). However, you can use this pattern to handle rate limits of any external API.

Resend is a service that allows you to send emails from your application via an API. Resend has a default [rate limit](https://resend.com/docs/api-reference/introduction#rate-limit) of two requests per second. You will use Queues to handle the rate limit of Resend.

## Prerequisites

<Render file="prereqs" product="workers" />

4. Sign up for [Resend](https://resend.com/) and generate an API key by following the guide on the [Resend documentation](https://resend.com/docs/dashboard/api-keys/introduction).

5. Additionally, you will need access to Cloudflare Queues.

<Render file="enable-queues" />

## 1. Create a new Workers application

To get started, create a Worker application using the [`create-cloudflare` CLI](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare). Open a terminal window and run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"resend-rate-limit-queue"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

Then, go to your newly created directory:

```sh frame="none"
cd resend-rate-limit-queue
```

## 2. Set up a Queue

You need to create a Queue and a binding to your Worker. Run the following command to create a Queue named `rate-limit-queue`:

```sh title="Create a Queue"
npx wrangler queues create rate-limit-queue
```

```sh output
Creating queue rate-limit-queue.
Created queue rate-limit-queue.
```

### Add Queue bindings to your [Wrangler configuration file](/workers/wrangler/configuration/)

In your Wrangler file, add the following:

<WranglerConfig>

```toml
[[queues.producers]]
binding = "EMAIL_QUEUE"
queue = "rate-limit-queue"

[[queues.consumers]]
queue = "rate-limit-queue"
max_batch_size = 2
max_batch_timeout = 10
max_retries = 3
```

</WranglerConfig>

It is important to include the `max_batch_size` of two to the consumer queue is important because the Resend API has a default rate limit of two requests per second. This batch size allows the queue to process the message in the batch size of two. If the batch size is less than two, the queue will wait for 10 seconds to collect the next message. If no more messages are available, the queue will process the message in the batch. For more information, refer to the [Batching, Retries and Delays documentation](/queues/configuration/batching-retries)

Your final Wrangler file should look similar to the example below.

<WranglerConfig>

```toml title="wrangler.toml"
#:schema node_modules/wrangler/config-schema.json
name = "resend-rate-limit-queue"
main = "src/index.ts"
compatibility_date = "2024-09-09"
compatibility_flags = ["nodejs_compat"]

[[queues.producers]]
binding = "EMAIL_QUEUE"
queue = "rate-limit-queue"

[[queues.consumers]]
queue = "rate-limit-queue"
max_batch_size = 2
max_batch_timeout = 10
max_retries = 3
```

</WranglerConfig>

## 3. Add bindings to environment

Add the bindings to the environment interface in `worker-configuration.d.ts`, so TypeScript correctly types the bindings. Type the queue as `Queue<any>`. Refer to the following step for instructions on how to change this type.

```ts title="worker-configuration.d.ts"
interface Env {
	EMAIL_QUEUE: Queue<any>;
}
```

## 4. Send message to the queue

The application will send a message to the queue when the Worker receives a request. For simplicity, you will send the email address as a message to the queue. A new message will be sent to the queue with a delay of one second.

```ts title="src/index.ts"
export default {
	async fetch(req: Request, env: Env): Promise<Response> {
		try {
			await env.EMAIL_QUEUE.send(
				{ email: await req.text() },
				{ delaySeconds: 1 },
			);
			return new Response("Success!");
		} catch (e) {
			return new Response("Error!", { status: 500 });
		}
	},
};
```

This will accept requests to any subpath and forwards the request's body. It expects that the request body to contain only an email. In production, you should check that the request was a `POST` request. You should also avoid sending such sensitive information (email) directly to the queue. Instead, you can send a message to the queue that contains a unique identifier for the user. Then, your consumer queue can use the unique identifier to look up the email address in a database and use that to send the email.

## 5. Process the messages in the queue

After the message is sent to the queue, it will be processed by the consumer Worker. The consumer Worker will process the message and send the email.

Since you have not configured Resend yet, you will log the message to the console. After you configure Resend, you will use it to send the email.

Add the `queue()` handler as shown below:

```ts title="src/index.ts" ins={1-3,17-28}
interface Message {
	email: string;
}

export default {
	async fetch(req: Request, env: Env): Promise<Response> {
		try {
			await env.EMAIL_QUEUE.send(
				{ email: await req.text() },
				{ delaySeconds: 1 },
			);
			return new Response("Success!");
		} catch (e) {
			return new Response("Error!", { status: 500 });
		}
	},
	async queue(batch: MessageBatch<Message>, env: Env): Promise<void> {
		for (const message of batch.messages) {
			try {
				console.log(message.body.email);
				// After configuring Resend, you can send email
				message.ack();
			} catch (e) {
				console.error(e);
				message.retry({ delaySeconds: 5 });
			}
		}
	},
};
```

The above `queue()` handler will log the email address to the console and send the email. It will also retry the message if sending the email fails. The `delaySeconds` is set to five seconds to avoid sending the email too quickly.

To test the application, run the following command:

```sh title="Start the development server"
npm run dev
```

Use the following cURL command to send a request to the application:

```sh title="Test with a cURL request"
curl -X POST -d "test@example.com" http://localhost:8787/
```

```sh output
[wrangler:inf] POST / 200 OK (2ms)
QueueMessage {
  attempts: 1,
  body: { email: 'test@example.com' },
  timestamp: 2024-09-12T13:48:07.236Z,
  id: '72a25ff18dd441f5acb6086b9ce87c8c'
}
```

## 6. Set up Resend

To call the Resend API, you need to configure the Resend API key. Create a `.dev.vars` file in the root of your project and add the following:

```txt title=".dev.vars"
RESEND_API_KEY='your-resend-api-key'
```

Replace `your-resend-api-key` with your actual Resend API key.

Next, update the `Env` interface in `worker-configuration.d.ts` to include the `RESEND_API_KEY` variable.

```ts title="worker-configuration.d.ts" ins={3}
interface Env {
	EMAIL_QUEUE: Queue<any>;
	RESEND_API_KEY: string;
}
```

Lastly, install the [`resend` package](https://www.npmjs.com/package/resend) using the following command:

<PackageManagers pkg="resend" />

You can now use the `RESEND_API_KEY` variable in your code.

## 7. Send email with Resend

In your `src/index.ts` file, import the Resend package and update the `queue()` handler to send the email.

```ts title="src/index.ts" ins={1,21,26-40} del={24,41}
import { Resend } from "resend";

interface Message {
	email: string;
}

export default {
	async fetch(req: Request, env: Env): Promise<Response> {
		try {
			await env.EMAIL_QUEUE.send(
				{ email: await req.text() },
				{ delaySeconds: 1 },
			);
			return new Response("Success!");
		} catch (e) {
			return new Response("Error!", { status: 500 });
		}
	},
	async queue(batch: MessageBatch<Message>, env: Env): Promise<void> {
		// Initialize Resend
		const resend = new Resend(env.RESEND_API_KEY);
		for (const message of batch.messages) {
			try {
				console.log(message.body.email);
				// send email
				const sendEmail = await resend.emails.send({
					from: "onboarding@resend.dev",
					to: [message.body.email],
					subject: "Hello World",
					html: "<strong>Sending an email from Worker!</strong>",
				});

				// check if the email failed
				if (sendEmail.error) {
					console.error(sendEmail.error);
					message.retry({ delaySeconds: 5 });
				} else {
					// if success, ack the message
					message.ack();
				}
				message.ack();
			} catch (e) {
				console.error(e);
				message.retry({ delaySeconds: 5 });
			}
		}
	},
};
```

The `queue()` handler will now send the email using the Resend API. It also checks if sending the email failed and will retry the message.

The final script is included below:

```ts title="src/index.ts"
import { Resend } from "resend";

interface Message {
	email: string;
}

export default {
	async fetch(req: Request, env: Env): Promise<Response> {
		try {
			await env.EMAIL_QUEUE.send(
				{ email: await req.text() },
				{ delaySeconds: 1 },
			);
			return new Response("Success!");
		} catch (e) {
			return new Response("Error!", { status: 500 });
		}
	},
	async queue(batch: MessageBatch<Message>, env: Env): Promise<void> {
		// Initialize Resend
		const resend = new Resend(env.RESEND_API_KEY);
		for (const message of batch.messages) {
			try {
				// send email
				const sendEmail = await resend.emails.send({
					from: "onboarding@resend.dev",
					to: [message.body.email],
					subject: "Hello World",
					html: "<strong>Sending an email from Worker!</strong>",
				});

				// check if the email failed
				if (sendEmail.error) {
					console.error(sendEmail.error);
					message.retry({ delaySeconds: 5 });
				} else {
					// if success, ack the message
					message.ack();
				}
			} catch (e) {
				console.error(e);
				message.retry({ delaySeconds: 5 });
			}
		}
	},
};
```

To test the application, start the development server using the following command:

```sh title="Start the development server"
npm run dev
```

Use the following cURL command to send a request to the application:

```sh title="Test with a cURL request"
curl -X POST -d "delivered@resend.dev" http://localhost:8787/
```

On the Resend dashboard, you should see that the email was sent to the provided email address.

## 8. Deploy your Worker

To deploy your Worker, run the following command:

```sh title="Deploy your Worker"
npx wrangler deploy
```

Lastly, add the Resend API key using the following command:

```sh title="Add the Resend API key"
npx wrangler secret put RESEND_API_KEY
```

Enter the value of your API key. Your API key will get added to your project. You can now use the `RESEND_API_KEY` variable in your code.

You have successfully created a Worker which can send emails using the Resend API respecting rate limits.

To test your Worker, you could use the following cURL request. Replace `<YOUR_WORKER_URL>` with the URL of your deployed Worker.

```bash title="Test with a cURL request"
curl -X POST -d "delivered@resend.dev" <YOUR_WORKER_URL>
```

Refer to the [GitHub repository](https://github.com/harshil1712/queues-rate-limit) for the complete code for this tutorial. If you are using [Hono](https://hono.dev/), you can refer to the [Hono example](https://github.com/harshil1712/resend-rate-limit-demo).

## Related resources

- [How Queues works](/queues/reference/how-queues-works/)
- [Queues Batching and Retries](/queues/configuration/batching-retries/)
- [Resend](https://resend.com/docs/)

---

# Build a web crawler with Queues and Browser Rendering

URL: https://developers.cloudflare.com/queues/tutorials/web-crawler-with-browser-rendering/

import { Render, PackageManagers, WranglerConfig } from "~/components";

This tutorial explains how to build and deploy a web crawler with Queues, [Browser Rendering](/browser-rendering/), and [Puppeteer](/browser-rendering/platform/puppeteer/).

Puppeteer is a high-level library used to automate interactions with Chrome/Chromium browsers. On each submitted page, the crawler will find the number of links to `cloudflare.com` and take a screenshot of the site, saving results to [Workers KV](/kv/).

You can use Puppeteer to request all images on a page, save the colors used on a site, and more.

## Prerequisites

<Render file="prereqs" product="workers" />

## 1. Create new Workers application

To get started, create a Worker application using the [`create-cloudflare` CLI](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare). Open a terminal window and run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"queues-web-crawler"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

Then, move into your newly created directory:

```sh
cd queues-web-crawler
```

## 2. Create KV namespace

We need to create a KV store. This can be done through the Cloudflare dashboard or the Wrangler CLI. For this tutorial, we will use the Wrangler CLI.

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="kv namespace create crawler_links"
/>

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="kv namespace create crawler_screenshots"
/>

```sh output
🌀 Creating namespace with title "web-crawler-crawler-links"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
[[kv_namespaces]]
binding = "crawler_links"
id = "<GENERATED_NAMESPACE_ID>"

🌀 Creating namespace with title "web-crawler-crawler-screenshots"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
[[kv_namespaces]]
binding = "crawler_screenshots"
id = "<GENERATED_NAMESPACE_ID>"
```

### Add KV bindings to the [Wrangler configuration file](/workers/wrangler/configuration/)

Then, in your Wrangler file, add the following with the values generated in the terminal:

<WranglerConfig>

```toml
kv_namespaces = [
  { binding = "CRAWLER_SCREENSHOTS_KV", id = "<GENERATED_NAMESPACE_ID>" },
  { binding = "CRAWLER_LINKS_KV", id = "<GENERATED_NAMESPACE_ID>" }
]
```

</WranglerConfig>

## 3. Set up Browser Rendering

Now, you need to set up your Worker for Browser Rendering.

In your current directory, install Cloudflare’s [fork of Puppeteer](/browser-rendering/platform/puppeteer/) and also [robots-parser](https://www.npmjs.com/package/robots-parser):

<PackageManagers pkg="@cloudflare/puppeteer" dev />

<PackageManagers pkg="robots-parser" />

Then, add a Browser Rendering binding. Adding a Browser Rendering binding gives the Worker access to a headless Chromium instance you will control with Puppeteer.

<WranglerConfig>

```toml
browser = { binding = "CRAWLER_BROWSER" }
```

</WranglerConfig>

## 4. Set up a Queue

Now, we need to set up the Queue.

<PackageManagers
	type="exec"
	pkg="wrangler"
	args="queues create queues-web-crawler"
/>

```txt title="Output"
Creating queue queues-web-crawler.
Created queue queues-web-crawler.
```

### Add Queue bindings to wrangler.toml

Then, in your Wrangler file, add the following:

<WranglerConfig>

```toml
[[queues.consumers]]
queue = "queues-web-crawler"
max_batch_timeout = 60

[[queues.producers]]
queue = "queues-web-crawler"
binding = "CRAWLER_QUEUE"
```

</WranglerConfig>

Adding the `max_batch_timeout` of 60 seconds to the consumer queue is important because Browser Rendering has a limit of two new browsers per minute per account. This timeout waits up to a minute before collecting queue messages into a batch. The Worker will then remain under this browser invocation limit.

Your final Wrangler file should look similar to the one below.

<WranglerConfig>

```toml
#:schema node_modules/wrangler/config-schema.json
name = "web-crawler"
main = "src/index.ts"
compatibility_date = "2024-07-25"
compatibility_flags = ["nodejs_compat"]

kv_namespaces = [
  { binding = "CRAWLER_SCREENSHOTS_KV", id = "<GENERATED_NAMESPACE_ID>" },
  { binding = "CRAWLER_LINKS_KV", id = "<GENERATED_NAMESPACE_ID>" }
]

browser = { binding = "CRAWLER_BROWSER" }

[[queues.consumers]]
queue = "queues-web-crawler"
max_batch_timeout = 60

[[queues.producers]]
queue = "queues-web-crawler"
binding = "CRAWLER_QUEUE"
```

</WranglerConfig>

## 5. Add bindings to environment

Add the bindings to the environment interface in `src/index.ts`, so TypeScript correctly types the bindings. Type the queue as `Queue<any>`. The following step will show you how to change this type.

```ts
import { BrowserWorker } from "@cloudflare/puppeteer";

export interface Env {
	CRAWLER_QUEUE: Queue<any>;
	CRAWLER_SCREENSHOTS_KV: KVNamespace;
	CRAWLER_LINKS_KV: KVNamespace;
	CRAWLER_BROWSER: BrowserWorker;
}
```

## 6. Submit links to crawl

Add a `fetch()` handler to the Worker to submit links to crawl.

```ts
type Message = {
	url: string;
};

export interface Env {
	CRAWLER_QUEUE: Queue<Message>;
	// ... etc.
}

export default {
	async fetch(req, env): Promise<Response> {
		await env.CRAWLER_QUEUE.send({ url: await req.text() });
		return new Response("Success!");
	},
} satisfies ExportedHandler<Env>;
```

This will accept requests to any subpath and forwards the request's body to be crawled. It expects that the request body only contains a URL. In production, you should check that the request was a `POST` request and contains a well-formed URL in its body. This has been omitted for simplicity.

## 7. Crawl with Puppeteer

Add a `queue()` handler to the Worker to process the links you send.

```ts
import puppeteer from "@cloudflare/puppeteer";
import robotsParser from "robots-parser";

async queue(batch: MessageBatch<Message>, env: Env): Promise<void> {
  let browser: puppeteer.Browser | null = null;
  try {
    browser = await puppeteer.launch(env.CRAWLER_BROWSER);
  } catch {
    batch.retryAll();
	return;
  }

  for (const message of batch.messages) {
    const { url } = message.body;

    let isAllowed = true;
    try {
      const robotsTextPath = new URL(url).origin + "/robots.txt";
      const response = await fetch(robotsTextPath);

      const robots = robotsParser(robotsTextPath, await response.text());
      isAllowed = robots.isAllowed(url) ?? true; // respect robots.txt!
    } catch {}

    if (!isAllowed) {
      message.ack();
      continue;
    }

	// TODO: crawl!
    message.ack();
  }

  await browser.close();
},
```

This is a skeleton for the crawler. It launches the Puppeteer browser and iterates through the Queue's received messages. It fetches the site's `robots.txt` and uses `robots-parser` to check that this site allows crawling. If crawling is not allowed, the message is `ack`'ed, removing it from the Queue. If crawling is allowed, you can continue to crawl the site.

The `puppeteer.launch()` is wrapped in a `try...catch` to allow the whole batch to be retried if the browser launch fails. The browser launch may fail due to going over the limit for number of browsers per account.

```ts
type Result = {
	numCloudflareLinks: number;
	screenshot: ArrayBuffer;
};

const crawlPage = async (url: string): Promise<Result> => {
	const page = await (browser as puppeteer.Browser).newPage();

	await page.goto(url, {
		waitUntil: "load",
	});

	const numCloudflareLinks = await page.$$eval("a", (links) => {
		links = links.filter((link) => {
			try {
				return new URL(link.href).hostname.includes("cloudflare.com");
			} catch {
				return false;
			}
		});
		return links.length;
	});

	await page.setViewport({
		width: 1920,
		height: 1080,
		deviceScaleFactor: 1,
	});

	return {
		numCloudflareLinks,
		screenshot: ((await page.screenshot({ fullPage: true })) as Buffer).buffer,
	};
};
```

This helper function opens a new page in Puppeteer and navigates to the provided URL. `numCloudflareLinks` uses Puppeteer's `$$eval` (equivalent to `document.querySelectorAll`) to find the number of links to a `cloudflare.com` page. Checking if the link's `href` is to a `cloudflare.com` page is wrapped in a `try...catch` to handle cases where `href`s may not be URLs.

Then, the function sets the browser viewport size and takes a screenshot of the full page. The screenshot is returned as a `Buffer` so it can be converted to an `ArrayBuffer` and written to KV.

To enable recursively crawling links, add a snippet after checking the number of Cloudflare links to send messages recursively from the queue consumer to the queue itself. Recursing too deep, as is possible with crawling, will cause a Durable Object `Subrequest depth limit exceeded.` error. If one occurs, it is caught, but the links are not retried.

```ts null {3-14}
// const numCloudflareLinks = await page.$$eval("a", (links) => { ...

await page.$$eval("a", async (links) => {
	const urls: MessageSendRequest<Message>[] = links.map((link) => {
		return {
			body: {
				url: link.href,
			},
		};
	});
	try {
		await env.CRAWLER_QUEUE.sendBatch(urls);
	} catch {} // do nothing, likely hit subrequest limit
});

// await page.setViewport({ ...
```

Then, in the `queue` handler, call `crawlPage` on the URL.

```ts null {8-23}
// in the `queue` handler:
// ...
if (!isAllowed) {
	message.ack();
	continue;
}

try {
	const { numCloudflareLinks, screenshot } = await crawlPage(url);
	const timestamp = new Date().getTime();
	const resultKey = `${encodeURIComponent(url)}-${timestamp}`;
	await env.CRAWLER_LINKS_KV.put(resultKey, numCloudflareLinks.toString(), {
		metadata: { date: timestamp },
	});
	await env.CRAWLER_SCREENSHOTS_KV.put(resultKey, screenshot, {
		metadata: { date: timestamp },
	});
	message.ack();
} catch {
	message.retry();
}

// ...
```

This snippet saves the results from `crawlPage` into the appropriate KV namespaces. If an unexpected error occurred, the URL will be retried and resent to the queue again.

Saving the timestamp of the crawl in KV helps you avoid crawling too frequently.

Add a snippet before checking `robots.txt` to check KV for a crawl within the last hour. This lists all KV keys beginning with the same URL (crawls of the same page), and check if any crawls have been done within the last hour. If any crawls have been done within the last hour, the message is `ack`'ed and not retried.

```ts null {12-23}
type KeyMetadata = {
  date: number;
};

// in the `queue` handler:
// ...
for (const message of batch.messages) {
  const sameUrlCrawls = await env.CRAWLER_LINKS_KV.list({
    prefix: `${encodeURIComponent(url)}`,
  });

  let shouldSkip = false;
  for (const key of sameUrlCrawls.keys) {
    if (timestamp - (key.metadata as KeyMetadata)?.date < 60 * 60 * 1000) {
      // if crawled in last hour, skip
      message.ack();
      shouldSkip = true;
      break;
    }
  }
  if (shouldSkip) {
    continue;
  }

  let isAllowed = true;
  // ...
```

The final script is included below.

```ts
import puppeteer, { BrowserWorker } from "@cloudflare/puppeteer";
import robotsParser from "robots-parser";

type Message = {
	url: string;
};

export interface Env {
	CRAWLER_QUEUE: Queue<Message>;
	CRAWLER_SCREENSHOTS_KV: KVNamespace;
	CRAWLER_LINKS_KV: KVNamespace;
	CRAWLER_BROWSER: BrowserWorker;
}

type Result = {
	numCloudflareLinks: number;
	screenshot: ArrayBuffer;
};

type KeyMetadata = {
	date: number;
};

export default {
	async fetch(req: Request, env: Env): Promise<Response> {
		// util endpoint for testing purposes
		await env.CRAWLER_QUEUE.send({ url: await req.text() });
		return new Response("Success!");
	},
	async queue(batch: MessageBatch<Message>, env: Env): Promise<void> {
		const crawlPage = async (url: string): Promise<Result> => {
			const page = await (browser as puppeteer.Browser).newPage();

			await page.goto(url, {
				waitUntil: "load",
			});

			const numCloudflareLinks = await page.$$eval("a", (links) => {
				links = links.filter((link) => {
					try {
						return new URL(link.href).hostname.includes("cloudflare.com");
					} catch {
						return false;
					}
				});
				return links.length;
			});

			// to crawl recursively - uncomment this!
			/*await page.$$eval("a", async (links) => {
        const urls: MessageSendRequest<Message>[] = links.map((link) => {
          return {
            body: {
              url: link.href,
            },
          };
        });
        try {
          await env.CRAWLER_QUEUE.sendBatch(urls);
        } catch {} // do nothing, might've hit subrequest limit
      });*/

			await page.setViewport({
				width: 1920,
				height: 1080,
				deviceScaleFactor: 1,
			});

			return {
				numCloudflareLinks,
				screenshot: ((await page.screenshot({ fullPage: true })) as Buffer)
					.buffer,
			};
		};

		let browser: puppeteer.Browser | null = null;
		try {
			browser = await puppeteer.launch(env.CRAWLER_BROWSER);
		} catch {
			batch.retryAll();
			return;
		}

		for (const message of batch.messages) {
			const { url } = message.body;
			const timestamp = new Date().getTime();
			const resultKey = `${encodeURIComponent(url)}-${timestamp}`;

			const sameUrlCrawls = await env.CRAWLER_LINKS_KV.list({
				prefix: `${encodeURIComponent(url)}`,
			});

			let shouldSkip = false;
			for (const key of sameUrlCrawls.keys) {
				if (timestamp - (key.metadata as KeyMetadata)?.date < 60 * 60 * 1000) {
					// if crawled in last hour, skip
					message.ack();
					shouldSkip = true;
					break;
				}
			}
			if (shouldSkip) {
				continue;
			}

			let isAllowed = true;
			try {
				const robotsTextPath = new URL(url).origin + "/robots.txt";
				const response = await fetch(robotsTextPath);

				const robots = robotsParser(robotsTextPath, await response.text());
				isAllowed = robots.isAllowed(url) ?? true; // respect robots.txt!
			} catch {}

			if (!isAllowed) {
				message.ack();
				continue;
			}

			try {
				const { numCloudflareLinks, screenshot } = await crawlPage(url);
				await env.CRAWLER_LINKS_KV.put(
					resultKey,
					numCloudflareLinks.toString(),
					{ metadata: { date: timestamp } },
				);
				await env.CRAWLER_SCREENSHOTS_KV.put(resultKey, screenshot, {
					metadata: { date: timestamp },
				});
				message.ack();
			} catch {
				message.retry();
			}
		}

		await browser.close();
	},
};
```

## 8. Deploy your Worker

To deploy your Worker, run the following command:

<PackageManagers type="exec" pkg="wrangler" args="deploy" />

You have successfully created a Worker which can submit URLs to a queue for crawling and save results to Workers KV.

To test your Worker, you could use the following cURL request to take a screenshot of this documentation page.

```bash title="Test with a cURL request"
curl <YOUR_WORKER_URL> \
  -H "Content-Type: application/json" \
  -d 'https://developers.cloudflare.com/queues/tutorials/web-crawler-with-browser-rendering/'

```

Refer to the [GitHub repository for the complete tutorial](https://github.com/cloudflare/queues-web-crawler), including a front end deployed with Pages to submit URLs and view crawler results.

## Related resources

- [How Queues works](/queues/reference/how-queues-works/)
- [Queues Batching and Retries](/queues/configuration/batching-retries/)
- [Browser Rendering](/browser-rendering/)
- [Puppeteer Examples](https://github.com/puppeteer/puppeteer/tree/main/examples)

---

# S3 API compatibility

URL: https://developers.cloudflare.com/r2/api/s3/api/

import { Details } from "~/components";

R2 implements the S3 API to allow users and their applications to migrate with ease. When comparing to AWS S3, Cloudflare has removed some API operations' features and added others. The S3 API operations are listed below with their current implementation status. Feature implementation is currently in progress. Refer back to this page for updates.
The API is available via the `https://<ACCOUNT_ID>.r2.cloudflarestorage.com` endpoint. Find your [account ID in the Cloudflare dashboard](/fundamentals/account/find-account-and-zone-ids/).

## How to read this page

This page has two sections: bucket-level operations and object-level operations.

Each section will have two tables: a table of implemented APIs and a table of unimplemented APIs.

Refer the feature column of each table to review which features of an API have been implemented and which have not.

✅ Feature Implemented <br/>
🚧 Feature Implemented (Experimental) <br/>
❌ Feature Not Implemented

## Bucket region

When using the S3 API, the region for an R2 bucket is `auto`. For compatibility with tools that do not allow you to specify a region, an empty value and `us-east-1` will alias to the `auto` region.

This also applies to the `LocationConstraint` for the `CreateBucket` API.

## Bucket-level operations

The following tables are related to bucket-level operations.

### Implemented bucket-level operations

Below is a list of implemented bucket-level operations. Refer to the Feature column to review which features have been implemented (✅) and have not been implemented (❌).

| API Name                                                                                                                       | Feature                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ✅ [ListBuckets](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html)                                         |                                                                                                                                                                                                                                                                                                                               |
| ✅ [HeadBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html)                                           | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                       |
| ✅ [CreateBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html)                                       | ❌ ACL: <br/>   ❌ x-amz-acl <br/>   ❌ x-amz-grant-full-control <br/>   ❌ x-amz-grant-read <br/>   ❌ x-amz-grant-read-acp <br/>   ❌ x-amz-grant-write <br/>   ❌ x-amz-grant-write-acp <br/> ❌ Object Locking: <br/>   ❌ x-amz-bucket-object-lock-enabled <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner |
| ✅ [DeleteBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html)                                       | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                       |
| ✅ [DeleteBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketCors.html)                               | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                       |
| ✅ [GetBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketCors.html)                                     | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                       |
| ✅ [GetBucketLifecycleConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLifecycleConfiguration.html) | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                       |
| ✅ [GetBucketLocation](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html)                             | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                       |
| ✅ [GetBucketEncryption](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketEncryption.html)                         | ❌ Bucket Owner: <br/> ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                         |
| ✅ [PutBucketCors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketCors.html)                                     | ❌ Checksums: <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                       |
| ✅ [PutBucketLifecycleConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLifecycleConfiguration.html) | ❌ Checksums: <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                       |

### Unimplemented bucket-level operations

<Details header="Unimplemented bucket-level operations">

| API Name                                                                                                                                             | Feature                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ❌ [GetBucketAccelerateConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketAccelerateConfiguration.html)                     | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketAcl](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketAcl.html)                                                             | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketAnalyticsConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketAnalyticsConfiguration.html)                       | ❌ id <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                         |
| ❌ [GetBucketIntelligentTieringConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketIntelligentTieringConfiguration.html)     | ❌ id                                                                                                                                                                                                                                                                                                                                       |
| ❌ [GetBucketInventoryConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketInventoryConfiguration.html)                       | ❌ id <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                         |
| ❌ [GetBucketLifecycle](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLifecycle.html)                                                 | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketLogging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLogging.html)                                                     | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketMetricsConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketMetricsConfiguration.html)                           | ❌ id <br/>❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                          |
| ❌ [GetBucketNotification](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketNotification.html)                                           | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketNotificationConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketNotificationConfiguration.html)                 | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketOwnershipControls](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketOwnershipControls.html)                                 | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketPolicy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketPolicy.html)                                                       | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketPolicyStatus](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketPolicyStatus.html)                                           | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketReplication](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketReplication.html)                                             | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketRequestPayment](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketRequestPayment.html)                                       | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketTagging.html)                                                     | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketVersioning](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketVersioning.html)                                               | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetBucketWebsite](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketWebsite.html)                                                     | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetObjectLockConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectLockConfiguration.html)                                 | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [GetPublicAccessBlock](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetPublicAccessBlock.html)                                             | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                     |
| ❌ [ListBucketAnalyticsConfigurations](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBucketAnalyticsConfigurations.html)                   | ❌ Query Parameters: <br/>   ❌ continuation-token <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                            |
| ❌ [ListBucketIntelligentTieringConfigurations](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBucketIntelligentTieringConfigurations.html) | ❌ Query Parameters: <br/>   ❌ continuation-token <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                            |
| ❌ [ListBucketInventoryConfigurations](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBucketInventoryConfigurations.html)                   | ❌ Query Parameters: <br/>   ❌ continuation-token <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                            |
| ❌ [ListBucketMetricsConfigurations](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBucketMetricsConfigurations.html)                       | ❌ Query Parameters: <br/>   ❌ continuation-token <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                            |
| ❌ [PutBucketAccelerateConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketAccelerateConfiguration.html)                     | ❌ Checksums: <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                             |
| ❌ [PutBucketAcl](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketAcl.html)                                                             | ❌ Permissions: <br/>   ❌ x-amz-grant-full-control <br/>   ❌ x-amz-grant-read <br/>   ❌ x-amz-grant-read-acp <br/>   ❌ x-amz-grant-write <br/>   ❌ x-amz-grant-write-acp <br/> ❌ Checksums: <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner |
| ❌ [PutBucketAnalyticsConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketAnalyticsConfiguration.html)                       | ❌ id <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                         |
| ❌ [PutBucketEncryption](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketEncryption.html)                                               | ❌ Checksums: <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                     |
| ❌ [PutBucketIntelligentTieringConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketIntelligentTieringConfiguration.html)     | ❌ id <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                         |
| ❌ [PutBucketInventoryConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketInventoryConfiguration.html)                       | ❌ id <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                         |
| ❌ [PutBucketLifecycle](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLifecycle.html)                                                 | ❌ Checksums: <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                     |
| ❌ [PutBucketLogging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketLifecycle.html)                                                   | ❌ Checksums: <br/>   ❌ Content-MD5 <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                              |
| ❌ [PutBucketMetricsConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketMetricsConfiguration.html)                           | ❌ id <br/>❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                          |
| ❌ [PutBucketNotification](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketNotification.html)                                           | ❌ Checksums: <br/>   ❌ Content-MD5 <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner:   <br/> ❌ x-amz-expected-bucket-owner                                                                                                                                                              |
| ❌ [PutBucketNotificationConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketNotificationConfiguration.html)                 | ❌ Validation: <br/>   ❌ x-amz-skip-destination-validation <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                   |
| ❌ [PutBucketOwnershipControls](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketOwnershipControls.html)                                 | ❌ Checksums: <br/>   ❌ Content-MD5 <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                          |
| ❌ [PutBucketPolicy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketPolicy.html)                                                       | ❌ Validation: <br/>   ❌ x-amz-confirm-remove-self-bucket-access <br/> ❌ Checksums: <br/>   ❌ Content-MD5 <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                      |
| ❌ [PutBucketReplication](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketReplication.html)                                             | ❌ Object Locking: <br/>   ❌ x-amz-bucket-object-lock-token <br/> ❌ Checksums: <br/>   ❌ Content-MD5 <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                           |
| ❌ [PutBucketRequestPayment](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketRequestPayment.html)                                       | ❌ Checksums: <br/>   ❌ Content-MD5 <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                              |
| ❌ [PutBucketTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketTagging.html)                                                     | ❌ Checksums: <br/>   ❌ Content-MD5 <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                              |
| ❌ [PutBucketVersioning](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketVersioning.html)                                               | ❌ Multi-factor authentication: <br/>   ❌ x-amz-mfa <br/> ❌ Checksums: <br/>   ❌ Content-MD5 <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                   |
| ❌ [PutBucketWebsite](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketWebsite.html)                                                     | ❌ Checksums: <br/>   ❌ Content-MD5 <br/> ❌ Bucket Owner: <br/> ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                            |
| ❌ [PutObjectLockConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectLockConfiguration.html)                                 | ❌ Object Locking: <br/>   ❌ x-amz-bucket-object-lock-token <br/> ❌ Checksums: <br/>   ❌ Content-MD5 <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                |
| ❌ [PutPublicAccessBlock](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutPublicAccessBlock.html)                                             | ❌ Checksums: <br/>   ❌ Content-MD5 <br/>   ❌ x-amz-sdk-checksum-algorithm <br/>   ❌ x-amz-checksum-algorithm <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                              |

</Details>

## Object-level operations

The following tables are related to object-level operations.

### Implemented object-level operations

Below is a list of implemented object-level operations. Refer to the Feature column to review which features have been implemented (✅) and have not been implemented (❌).

| API Name                                                                                                       | Feature                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ✅ [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)                           | ✅ Conditional Operations: <br/>   ✅ If-Match <br/>   ✅ If-Modified-Since <br/>   ✅ If-None-Match <br/>   ✅ If-Unmodified-Since <br/> ✅ Range: <br/>   ✅ Range (has no effect in HeadObject) <br/>   ✅ partNumber <br/> ✅ SSE-C: <br/>   ✅ x-amz-server-side-encryption-customer-algorithm <br/>   ✅ x-amz-server-side-encryption-customer-key <br/>   ✅ x-amz-server-side-encryption-customer-key-MD5 <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ✅ [ListObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html)                         | Query Parameters: <br/>   ✅ delimiter <br/>   ✅ encoding-type <br/>   ✅ marker <br/>   ✅ max-keys <br/>   ✅ prefix <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ✅ [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html)                     | Query Parameters: <br/>   ✅ list-type <br/>   ✅ continuation-token <br/>   ✅ delimiter <br/>   ✅ encoding-type <br/>   ✅ fetch-owner <br/>   ✅ max-keys <br/>   ✅ prefix <br/>   ✅ start-after <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ✅ [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)                             | ✅ Conditional Operations: <br/>   ✅ If-Match <br/>   ✅ If-Modified-Since <br/>   ✅ If-None-Match <br/>   ✅ If-Unmodified-Since <br/> ✅ Range: <br/>   ✅ Range <br/>   ✅ PartNumber <br/> ✅ SSE-C: <br/>   ✅ x-amz-server-side-encryption-customer-algorithm <br/>   ✅ x-amz-server-side-encryption-customer-key <br/>   ✅ x-amz-server-side-encryption-customer-key-MD5 <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ✅ [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)                             | ✅ System Metadata: <br/>   ✅ Content-Type <br/>   ✅ Cache-Control <br/>   ✅ Content-Disposition <br/>   ✅ Content-Encoding <br/>   ✅ Content-Language <br/>   ✅ Expires <br/>   ✅ Content-MD5 <br/> ✅ Storage Class: <br/>   ✅ x-amz-storage-class <br/>     ✅ STANDARD <br/>     ✅ STANDARD_IA <br/> ❌ Object Lifecycle <br/> ❌ Website: <br/>   ❌ x-amz-website-redirect-location <br/> ❌ SSE: <br/>   ❌ x-amz-server-side-encryption-aws-kms-key-id <br/>   ❌ x-amz-server-side-encryption <br/>   ❌ x-amz-server-side-encryption-context <br/>   ❌ x-amz-server-side-encryption-bucket-key-enabled <br/> ✅ SSE-C: <br/>   ✅ x-amz-server-side-encryption-customer-algorithm <br/>   ✅ x-amz-server-side-encryption-customer-key <br/>   ✅ x-amz-server-side-encryption-customer-key-MD5 <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Tagging: <br/>   ❌ x-amz-tagging <br/> ❌ Object Locking: <br/>   ❌ x-amz-object-lock-mode <br/>   ❌ x-amz-object-lock-retain-until-date <br/>   ❌ x-amz-object-lock-legal-hold <br/> ❌ ACL: <br/>   ❌ x-amz-acl <br/>   ❌ x-amz-grant-full-control <br/>   ❌ x-amz-grant-read <br/>   ❌ x-amz-grant-read-acp <br/>   ❌ x-amz-grant-write-acp <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ✅ [DeleteObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html)                       | ❌ Multi-factor authentication: <br/>   ❌ x-amz-mfa <br/> ❌ Object Locking: <br/>   ❌ x-amz-bypass-governance-retention <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ✅ [DeleteObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html)                     | ❌ Multi-factor authentication: <br/>   ❌ x-amz-mfa <br/> ❌ Object Locking: <br/>   ❌ x-amz-bypass-governance-retention <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ✅ [ListMultipartUploads](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html)       | ✅ Query Parameters: <br/>   ✅ delimiter <br/>   ✅ encoding-type <br/>   ✅ key-marker <br/>   ✅️ max-uploads <br/>   ✅ prefix <br/>   ✅ upload-id-marker                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ✅ [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html)     | ✅ System Metadata: <br/>   ✅ Content-Type <br/>   ✅ Cache-Control <br/>   ✅ Content-Disposition <br/>   ✅ Content-Encoding <br/>   ✅ Content-Language <br/>   ✅ Expires <br/>   ✅ Content-MD5 <br/> ✅ Storage Class: <br/>   ✅ x-amz-storage-class <br/>     ✅ STANDARD <br/>     ✅ STANDARD_IA <br/> ❌ Website: <br/>   ❌ x-amz-website-redirect-location <br/> ❌ SSE: <br/>   ❌ x-amz-server-side-encryption-aws-kms-key-id <br/>   ❌ x-amz-server-side-encryption <br/>   ❌ x-amz-server-side-encryption-context <br/>   ❌ x-amz-server-side-encryption-bucket-key-enabled <br/> ✅ SSE-C: <br/>   ✅ x-amz-server-side-encryption-customer-algorithm <br/>   ✅ x-amz-server-side-encryption-customer-key <br/>   ✅ x-amz-server-side-encryption-customer-key-MD5 <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Tagging: <br/>   ❌ x-amz-tagging <br/> ❌ Object Locking: <br/>   ❌ x-amz-object-lock-mode <br/>   ❌ x-amz-object-lock-retain-until-date <br/>   ❌ x-amz-object-lock-legal-hold <br/> ❌ ACL: <br/>   ❌ x-amz-acl <br/>   ❌ x-amz-grant-full-control <br/>   ❌ x-amz-grant-read <br/>   ❌ x-amz-grant-read-acp <br/>   ❌ x-amz-grant-write-acp <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ✅ [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ✅ [AbortMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html)       | ❌ Request Payer: <br/>   ❌ x-amz-request-payer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ✅ [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)                           | ✅ Operation Metadata: <br/>   ✅ x-amz-metadata-directive <br/> ✅ System Metadata: <br/>   ✅ Content-Type <br/>   ✅ Cache-Control <br/>   ✅ Content-Disposition <br/>   ✅ Content-Encoding <br/>   ✅ Content-Language <br/>   ✅ Expires <br/> ✅ Conditional Operations: <br/>   ✅ x-amz-copy-source <br/>   ✅ x-amz-copy-source-if-match <br/>   ✅ x-amz-copy-source-if-modified-since <br/>   ✅ x-amz-copy-source-if-none-match <br/>   ✅ x-amz-copy-source-if-unmodified-since <br/> ✅ Storage Class: <br/>   ✅ x-amz-storage-class <br/>     ✅ STANDARD <br/>     ✅ STANDARD_IA <br/> ❌ ACL: <br/>   ❌ x-amz-acl <br/>   ❌ x-amz-grant-full-control <br/>   ❌ x-amz-grant-read <br/>   ❌ x-amz-grant-read-acp <br/>   ❌ x-amz-grant-write-acp <br/> ❌ Website: <br/>   ❌ x-amz-website-redirect-location <br/> ❌ SSE: <br/>   ❌ x-amz-server-side-encryption <br/>   ❌ x-amz-server-side-encryption-aws-kms-key-id <br/>   ❌ x-amz-server-side-encryption-context <br/>   ❌ x-amz-server-side-encryption-bucket-key-enabled <br/> ✅ SSE-C: <br/>   ✅ x-amz-server-side-encryption-customer-algorithm <br/>   ✅ x-amz-server-side-encryption-customer-key <br/>   ✅ x-amz-server-side-encryption-customer-key-MD5 <br/>   ✅ x-amz-copy-source-server-side-encryption-customer-algorithm <br/>   ✅ x-amz-copy-source-server-side-encryption-customer-key <br/>   ✅ x-amz-copy-source-server-side-encryption-customer-key-MD5 <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Tagging: <br/>   ❌ x-amz-tagging <br/>   ❌ x-amz-tagging-directive <br/> ❌ Object Locking: <br/>   ❌ x-amz-object-lock-mode <br/>   ❌ x-amz-object-lock-retain-until-date <br/>   ❌ x-amz-object-lock-legal-hold <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner <br/>   ❌ x-amz-source-expected-bucket-owner <br/> ❌ Checksums: <br/>   ❌ x-amz-checksum-algorithm |
| ✅ [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html)                           | ✅ System Metadata: <br/>   ✅ Content-MD5 <br/> ❌ SSE: <br/>   ❌ x-amz-server-side-encryption <br/> ✅ SSE-C: <br/>   ✅ x-amz-server-side-encryption-customer-algorithm <br/>   ✅ x-amz-server-side-encryption-customer-key <br/>   ✅ x-amz-server-side-encryption-customer-key-MD5 <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ✅ [UploadPartCopy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html)                   | ❌ Conditional Operations: <br/>   ❌ x-amz-copy-source <br/>   ❌ x-amz-copy-source-if-match <br/>   ❌ x-amz-copy-source-if-modified-since <br/>   ❌ x-amz-copy-source-if-none-match <br/>   ❌ x-amz-copy-source-if-unmodified-since <br/> ✅ Range: <br/>   ✅ x-amz-copy-source-range <br/> ✅ SSE-C: <br/>   ✅ x-amz-server-side-encryption-customer-algorithm <br/>   ✅ x-amz-server-side-encryption-customer-key <br/>   ✅ x-amz-server-side-encryption-customer-key-MD5 <br/>   ✅ x-amz-copy-source-server-side-encryption-customer-algorithm <br/>   ✅ x-amz-copy-source-server-side-encryption-customer-key <br/>   ✅ x-amz-copy-source-server-side-encryption-customer-key-MD5 <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner <br/>   ❌ x-amz-source-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ✅ [ListParts](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html)                             | Query Parameters: <br/>   ✅ max-parts <br/>   ✅ part-number-marker <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

:::caution

Even though `ListObjects` is a supported operation, it is recommended that you use `ListObjectsV2` instead when developing applications. For more information, refer to [ListObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html).

:::

### Unimplemented object-level operations

<Details header="Unimplemented object-level operations">

| API Name                                                                                               | Feature                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ❌ [GetObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectTagging.html)       | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer                                                             |
| ❌ [PutObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectTagging.html)       | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner <br/> ❌ Request Payer: <br/>   ❌ x-amz-request-payer <br/> ❌ Checksums: <br/>   ❌ x-amz-sdk-checksum-algorithm |
| ❌ [DeleteObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjectTagging.html) | ❌ Bucket Owner: <br/>   ❌ x-amz-expected-bucket-owner                                                                                                                    |

</Details>

---

# Extensions

URL: https://developers.cloudflare.com/r2/api/s3/extensions/

R2 implements some extensions on top of the basic S3 API. This page outlines these additional, available features. Some of the functionality described in this page requires setting a custom header. For examples on how to do so, refer to [Configure custom headers](/r2/examples/aws/custom-header).

## Extended metadata using Unicode

The [Workers R2 API](/r2/api/workers/workers-api-reference/) supports Unicode in keys and values natively without requiring any additional encoding or decoding for the `customMetadata` field. These fields map to the `x-amz-meta-`-prefixed headers used within the R2 S3-compatible API endpoint.

HTTP header names and values may only contain ASCII characters, which is a small subset of the Unicode character library. To easily accommodate users, R2 adheres to [RFC 2047](https://datatracker.ietf.org/doc/html/rfc2047) and automatically decodes all `x-amz-meta-*` header values before storage. On retrieval, any metadata values with unicode are RFC 2047-encoded before rendering the response. The length limit for metadata values is applied to the decoded Unicode value.

:::caution[Metadata variance]

Be mindful when using both Workers and S3 API endpoints to access the same data. If the R2 metadata keys contain Unicode, they are stripped when accessed through the S3 API and the `x-amz-missing-meta` header is set to the number of keys that were omitted. 
:::

These headers map to the `httpMetadata` field in the [R2 bindings](/workers/runtime-apis/bindings/):



| HTTP Header           | Property Name                     |
| --------------------- | --------------------------------- |
| `Content-Encoding`    | `httpMetadata.contentEncoding`    |
| `Content-Type`        | `httpMetadata.contentType`        |
| `Content-Language`    | `httpMetadata.contentLanguage`    |
| `Content-Disposition` | `httpMetadata.contentDisposition` |
| `Cache-Control`       | `httpMetadata.cacheControl`       |
| `Expires`             | `httpMetadata.expires`            |
|                       |                                   |

If using Unicode in object key names, refer to [Unicode Interoperability](/r2/reference/unicode-interoperability/).

## Auto-creating buckets on upload

If you are creating buckets on demand, you might initiate an upload with the assumption that a target bucket exists. In this situation, if you received a `NoSuchBucket` error, you would probably issue a `CreateBucket` operation. However, following this approach can cause issues: if the body has already been partially consumed, the upload will need to be aborted. A common solution to this issue, followed by other object storage providers, is to use the [HTTP `100`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/100) response to detect whether the body should be sent, or if the bucket must be created before retrying the upload. However, Cloudflare does not support the HTTP `100` response. Even if the HTTP `100` response was supported, you would still have additional latency due to the round trips involved.

To support sending an upload with a streaming body to a bucket that may not exist yet, upload operations such as `PutObject` or `CreateMultipartUpload` allow you to specify a header that will ensure the `NoSuchBucket` error is not returned. If the bucket does not exist at the time of upload, it is implicitly instantiated with the following `CreateBucket` request:

```txt
PUT / HTTP/1.1
Host: bucket.account.r2.cloudflarestorage.com
<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <LocationConstraint>auto</LocationConstraint>
</CreateBucketConfiguration>
```

This is only useful if you are creating buckets on demand because you do not know the name of the bucket or the preferred access location ahead of time. For example, you have one bucket per one of your customers and the bucket is created on first upload to the bucket and not during account registration. In these cases, the [`ListBuckets` extension](#listbuckets), which supports accounts with more than 1,000 buckets, may also be useful.

## PutObject and CreateMultipartUpload

### cf-create-bucket-if-missing

Add a `cf-create-bucket-if-missing` header with the value `true` to implicitly create the bucket if it does not exist yet. Refer to [Auto-creating buckets on upload](#auto-creating-buckets-on-upload) for a more detailed explanation of when to add this header.

## PutObject

### Conditional operations in `PutObject`

`PutObject` supports [conditional uploads](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests) via the [`If-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-Match), [`If-None-Match`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-None-Match), [`If-Modified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-Modified-Since), and [`If-Unmodified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-Unmodified-Since) headers. These headers will cause the `PutObject` operation to be rejected with `412 PreconditionFailed` error codes when the preceding state of the object that is being written to does not match the specified conditions.

## CopyObject

### MERGE metadata directive

The `x-amz-metadata-directive` allows a `MERGE` value, in addition to the standard `COPY` and `REPLACE` options. When used, `MERGE` is a combination of `COPY` and `REPLACE`, which will `COPY` any metadata keys from the source object and `REPLACE` those that are specified in the request with the new value. You cannot use `MERGE` to remove existing metadata keys from the source — use `REPLACE` instead.

## `ListBuckets`

`ListBuckets` supports all the same search parameters as `ListObjectsV2` in R2 because some customers may have more than 1,000 buckets. Because tooling, like existing S3 libraries, may not expose a way to set these search parameters, these values may also be sent in via headers. Values in headers take precedence over the search parameters.



| Search parameter     | HTTP Header             | Meaning                                                           |
| -------------------- | ----------------------- | ----------------------------------------------------------------- |
| `prefix`             | `cf-prefix`             | Show buckets with this prefix only.                               |
| `start-after`        | `cf-start-after`        | Show buckets whose name appears lexicographically in the account. |
| `continuation-token` | `cf-continuation-token` | Resume listing from a previously returned continuation token.     |
| `max-keys`           | `cf-max-keys`           | Return this maximum number of buckets. Default and max is `1000`. |
|                      |                         |                                                                   |

The XML response contains a `NextContinuationToken` and `IsTruncated` elements as appropriate. Since these may not be accessible from existing S3 APIs, these are also available in response headers:



| XML Response Element    | HTTP Response Header         | Meaning                                                                                        |
| ----------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------- |
| `IsTruncated`           | `cf-is-truncated`            | This is set to `true` if the list of buckets returned is not all the buckets on the account.   |
| `NextContinuationToken` | `cf-next-continuation-token` | This is set to continuation token to pass on a subsequent `ListBuckets` to resume the listing. |
| `StartAfter`            |                              | This is the start-after value that was passed in on the request.                               |
| `KeyCount`              |                              | The number of buckets returned.                                                                |
| `ContinuationToken`     |                              | The continuation token that was supplied in the request.                                       |
| `MaxKeys`               |                              | The max keys that were specified in the request.                                               |
|                         |                              |                                                                                                |

### Conditional operations in `CopyObject` for the destination object

:::note

This feature is currently in beta. If you have feedback, reach out to us on the [Cloudflare Developer Discord](https://discord.cloudflare.com) in the #r2-storage channel or open a thread on the [Community Forum](https://community.cloudflare.com/c/developers/storage/81). 
:::

`CopyObject` already supports conditions that relate to the source object through the `x-amz-copy-source-if-...` headers as part of our compliance with the S3 API. In addition to this, R2 supports an R2 specific set of headers that allow the `CopyObject` operation to be conditional on the target object:

* `cf-copy-destination-if-match`
* `cf-copy-destination-if-none-match`
* `cf-copy-destination-if-modified-since`
* `cf-copy-destination-if-unmodified-since`

These headers work akin to the similarly named conditional headers supported on `PutObject`. When the preceding state of the destination object to does not match the specified conditions the `CopyObject` operation will be rejected with a `412 PreconditionFailed` error code.

#### Non-atomicity relative to `x-amz-copy-source-if`

The `x-amz-copy-source-if-...` headers are guaranteed to be checked when the source object for the copy operation is selected, and the `cf-copy-destination-if-...` headers are guaranteed to be checked when the object is committed to the bucket state.
However, the time at which the source object is selected for copying, and the point in time when the destination object is committed to the bucket state are not necessarily the same. This means that the `cf-copy-destination-if-...` headers are not atomic in relation to the `x-amz-copy-source-if...` headers.

---

# S3

URL: https://developers.cloudflare.com/r2/api/s3/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Presigned URLs

URL: https://developers.cloudflare.com/r2/api/s3/presigned-urls/

import {Tabs, TabItem } from "~/components";

Presigned URLs are an [S3 concept](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html) for sharing direct access to your bucket without revealing your token secret. A presigned URL authorizes anyone with the URL to perform an action to the S3 compatibility endpoint for an R2 bucket. By default, the S3 endpoint requires an `AUTHORIZATION` header signed by your token. Every presigned URL has S3 parameters and search parameters containing the signature information that would be present in an `AUTHORIZATION` header. The performable action is restricted to a specific resource, an [operation](/r2/api/s3/api/), and has an associated timeout.

There are three kinds of resources in R2:

1. **Account**: For account-level operations (such as `CreateBucket`, `ListBuckets`, `DeleteBucket`) the identifier is the account ID.
2. **Bucket**: For bucket-level operations (such as `ListObjects`, `PutBucketCors`) the identifier is the account ID, and bucket name.
3. **Object**: For object-level operations (such as `GetObject`, `PutObject`, `CreateMultipartUpload`) the identifier is the account ID, bucket name, and object path.

All parts of the identifier are part of the presigned URL.

You cannot change the resource being accessed after the request is signed. For example, trying to change the bucket name to access the same object in a different bucket will return a `403` with an error code of `SignatureDoesNotMatch`.

Presigned URLs must have a defined expiry. You can set a timeout from one second to 7 days (604,800 seconds) into the future. The URL will contain the time when the URL was generated (`X-Amz-Date`) and the timeout (`X-Amz-Expires`) as search parameters. These search parameters are signed and tampering with them will result in `403` with an error code of `SignatureDoesNotMatch`.

Presigned URLs are generated with no communication with R2 and must be generated by an application with access to your R2 bucket's credentials.

## Presigned URL use cases

There are three ways to grant an application access to R2:

1. The application has its own copy of an [R2 API token](/r2/api/tokens/).
2. The application requests a copy of an R2 API token from a vault application and promises to not permanently store that token locally.
3. The application requests a central application to give it a presigned URL it can use to perform an action.

In scenarios 1 and 2, if the application or vault application is compromised, the holder of the token can perform arbitrary actions.

Scenario 3 keeps the credential secret. If the application making a presigned URL request to the central application leaks that URL, but the central application does not have its key storage system compromised, the impact is limited to one operation on the specific resource that was signed.

Additionally, the central application can perform monitoring, auditing, logging tasks so you can review when a request was made to perform an operation on a specific resource. In the event of a security incident, you can use a central application's logging functionality to review details of the incident.

The central application can also perform policy enforcement. For example, if you have an application responsible for uploading resources, you can restrict the upload to a specific bucket or folder within a bucket. The requesting application can obtain a JSON Web Token (JWT) from your authorization service to sign a request to the central application. The central application then uses the information contained in the JWT to validate the inbound request parameters.

The central application can be, for example, a Cloudflare Worker. Worker secrets are cryptographically impossible to obtain outside of your script running on the Workers runtime. If you do not store a copy of the secret elsewhere and do not have your code log the secret somewhere, your Worker secret will remain secure. However, as previously mentioned, presigned URLs are generated outside of R2 and all that's required is the secret + an implementation of the signing algorithm, so you can generate them anywhere.

Another potential use case for presigned URLs is debugging. For example, if you are debugging your application and want to grant temporary access to a specific test object in a production environment, you can do this without needing to share the underlying token and remembering to revoke it.

## Supported HTTP methods

R2 currently supports the following methods when generating a presigned URL:

- `GET`: allows a user to fetch an object from a bucket
- `HEAD`: allows a user to fetch an object's metadata from a bucket
- `PUT`: allows a user to upload an object to a bucket
- `DELETE`: allows a user to delete an object from a bucket

`POST`, which performs uploads via native HTML forms, is not currently supported.

## Presigned URL alternative with Workers

A valid alternative design to presigned URLs is to use a Worker with a [binding](/workers/runtime-apis/bindings/) that implements your security policy.

:::note[Bindings]

A binding is how your Worker interacts with external resources such as [KV Namespaces](/kv/concepts/kv-namespaces/), [Durable Objects](/durable-objects/), or [R2 Buckets](/r2/buckets/). A binding is a runtime variable that the Workers runtime provides to your code. You can declare a variable name in your Wrangler file that will be bound to these resources at runtime, and interact with them through this variable. Every binding's variable name and behavior is determined by you when deploying the Worker. Refer to [Environment Variables](/workers/configuration/environment-variables/) for more information.

A binding is defined in the Wrangler file of your Worker project's directory.

:::

Refer to [Use R2 from Workers](/r2/api/workers/workers-api-usage/) to learn how to bind a bucket to a Worker and use the binding to interact with your bucket.

## Generate presigned URLs

Generate a presigned URL by referring to the following examples:

- [AWS SDK for Go](/r2/examples/aws/aws-sdk-go/#generate-presigned-urls)
- [AWS SDK for JS v3](/r2/examples/aws/aws-sdk-js-v3/#generate-presigned-urls)
- [AWS SDK for JS](/r2/examples/aws/aws-sdk-js/#generate-presigned-urls)
- [AWS SDK for PHP](/r2/examples/aws/aws-sdk-php/#generate-presigned-urls)
- [AWS CLI](/r2/examples/aws/aws-cli/#generate-presigned-urls)

### Example of generating presigned URLs

A possible use case may be restricting an application to only be able to upload to a specific URL. With presigned URLs, your central signing application might look like the following JavaScript code running on Cloudflare Workers, `workerd`, or another platform (you might have to update the code based on the platform you are using).

If the application received a request for `https://example.com/uploads/dog.png`, it would respond with a presigned URL allowing a user to upload to your R2 bucket at the `/uploads/dog.png` path.

To create a presigned URL, you will need to either use a package that implements the signing algorithm, or implement the signing algorithm yourself. In this example, the `aws4fetch` package is used. You also need to have an access key ID and a secret access key. Refer to [R2 API tokens](/r2/api/tokens/) for more information.

```ts
import { AwsClient } from "aws4fetch";

// Create a new client
// Replace with your own access key ID and secret access key
// Make sure to store these securely and not expose them
const client = new AwsClient({
	accessKeyId: "",
	secretAccessKey: "",
});

export default {
	async fetch(req): Promise<Response> {
		// This is just an example to demonstrating using aws4fetch to generate a presigned URL.
		// This Worker should not be used as-is as it does not authenticate the request, meaning
		// that anyone can upload to your bucket.
		//
		// Consider implementing authorization, such as a preshared secret in a request header.
		const requestPath = new URL(req.url).pathname;

		// Cannot upload to the root of a bucket
		if (requestPath === "/") {
			return new Response("Missing a filepath", { status: 400 });
		}

		// Replace with your bucket name and account ID
		const bucketName = "";
		const accountId = "";

		const url = new URL(
			`https://${bucketName}.${accountId}.r2.cloudflarestorage.com`,
		);

		// preserve the original path
		url.pathname = requestPath;

		// Specify a custom expiry for the presigned URL, in seconds
		url.searchParams.set("X-Amz-Expires", "3600");

		const signed = await client.sign(
			new Request(url, {
				method: "PUT",
			}),
			{
				aws: { signQuery: true },
			},
		);

		// Caller can now use this URL to upload to that object.
		return new Response(signed.url, { status: 200 });
	},

	// ... handle other kinds of requests
} satisfies ExportedHandler;
```

## Differences between presigned URLs and R2 binding

- When using an R2 binding, you will not need any token secrets in your Worker code. Instead, in your [Wrangler configuration file](/workers/wrangler/configuration/), you will create a [binding](/r2/api/workers/workers-api-usage/#3-bind-your-bucket-to-a-worker) to your R2 bucket. Additionally, authorization is handled in-line, which can reduce latency.
- When using presigned URLs, you will need to create and use the token secrets in your Worker code.

In some cases, R2 bindings let you implement certain functionality more easily. For example, if you wanted to offer a write-once guarantee so that users can only upload to a path once:

- With R2 binding: You only need to pass the header once.
- With presigned URLs: You need to first sign specific headers, then request the user to send the same headers.

<Tabs>
<TabItem label="R2 binding example">

If you are using R2 bindings, you would change your upload to:

```ts
const existingObject = await env.R2_BUCKET.put(key, request.body, {
	onlyIf: {
		// No objects will have been uploaded before September 28th, 2021 which
		// is the initial R2 announcement.
		uploadedBefore: new Date(1632844800000),
	},
});
if (existingObject?.etag !== request.headers.get("etag")) {
	return new Response("attempt to overwrite object", { status: 400 });
}
```

When using R2 bindings, you may need to consider the following limitations:

- You cannot upload more than 100 MiB (200 MiB for Business customers) when using R2 bindings.
- Enterprise customers can upload 500 MiB by default and can ask their account team to raise this limit.
- Detecting [precondition failures](/r2/api/s3/extensions/#conditional-operations-in-putobject) is currently easier with presigned URLs as compared with R2 bindings.

Note that these limitations depend on R2's extension for conditional uploads. Amazon's S3 service does not offer such functionality at this time.
</TabItem>
<TabItem label="Presigned URL example">
You can modify the previous example to sign additional headers:

```ts
const signed = await client.sign(
	new Request(url, {
		method: "PUT",
	}),
	{
		aws: { signQuery: true },
		headers: {
			"If-Unmodified-Since": "Tue, 28 Sep 2021 16:00:00 GMT",
		},
	},
);
```

```ts
// Use the presigned URL to upload the file
const response = await fetch(signed.url, {
	method: "PUT",
	body: file,
	headers: {
		"If-Unmodified-Since": "Tue, 28 Sep 2021 16:00:00 GMT",
	},
});
```

Note that the caller has to add the same `If-Unmodified-Since` header to use the URL. The caller cannot omit the header or use a different header, since the signature covers the headers. If the caller uses a different header, the presigned URL signature would not match, and they would receive a `403/SignatureDoesNotMatch`.

</TabItem>
</Tabs>

## Differences between presigned URLs and public buckets

Presigned URLs share some superficial similarity with public buckets. If you give out presigned URLs only for `GET`/`HEAD` operations on specific objects in a bucket, then your presigned URL functionality is mostly similar to public buckets. The notable exception is that any custom metadata associated with the object is rendered in headers with the `x-amz-meta-` prefix. Any error responses are returned as XML documents, as they would with normal non-presigned S3 access.

Presigned URLs can be generated for any S3 operation. After a presigned URL is generated it can be reused as many times as the holder of the URL wants until the signed expiry date.

[Public buckets](/r2/buckets/public-buckets/) are available on a regular HTTP endpoint. By default, there is no authorization or access controls associated with a public bucket. Anyone with a public bucket URL can access an object in that public bucket. If you are using a custom domain to expose the R2 bucket, you can manage authorization and access controls as you would for a Cloudflare zone. Public buckets only provide `GET`/`HEAD` on a known object path. Public bucket errors are rendered as HTML pages.

Choosing between presigned URLs and public buckets is dependent on your specific use case. You can also use both if your architecture should use public buckets in one situation and presigned URLs in another. It is useful to note that presigned URLs will expose your account ID and bucket name to whoever gets a copy of the URL. Public bucket URLs do not contain the account ID or bucket name. Typically, you will not share presigned URLs directly with end users or browsers, as presigned URLs are used more for internal applications.

## Limitations

Presigned URLs can only be used with the `<accountid>.r2.cloudflarestorage.com` S3 API domain and cannot be used with custom domains. Instead, you can use the [general purpose HMAC validation feature of the WAF](/ruleset-engine/rules-language/functions/#hmac-validation), which requires a Pro plan or above.

## Related resources

- [Create a public bucket](/r2/buckets/public-buckets/)
- [Storing user generated content](/reference-architecture/diagrams/storage/storing-user-generated-content/)

---

# Workers API

URL: https://developers.cloudflare.com/r2/api/workers/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Workers API reference

URL: https://developers.cloudflare.com/r2/api/workers/workers-api-reference/

import { Type, MetaInfo, WranglerConfig } from "~/components";

The in-Worker R2 API is accessed by binding an R2 bucket to a [Worker](/workers). The Worker you write can expose external access to buckets via a route or manipulate R2 objects internally.

The R2 API includes some extensions and semantic differences from the S3 API. If you need S3 compatibility, consider using the [S3-compatible API](/r2/api/s3/).

## Concepts

R2 organizes the data you store, called objects, into containers, called buckets. Buckets are the fundamental unit of performance, scaling, and access within R2.

## Create a binding

:::note[Bindings]

A binding is how your Worker interacts with external resources such as [KV Namespaces](/kv/concepts/kv-namespaces/), [Durable Objects](/durable-objects/), or [R2 Buckets](/r2/buckets/). A binding is a runtime variable that the Workers runtime provides to your code. You can declare a variable name in your Wrangler file that will be bound to these resources at runtime, and interact with them through this variable. Every binding's variable name and behavior is determined by you when deploying the Worker. Refer to [Environment Variables](/workers/configuration/environment-variables/) for more information.

A binding is defined in the Wrangler file of your Worker project's directory.

:::

To bind your R2 bucket to your Worker, add the following to your Wrangler file. Update the `binding` property to a valid JavaScript variable identifier and `bucket_name` to the name of your R2 bucket:

<WranglerConfig>

```toml
[[r2_buckets]]
binding = 'MY_BUCKET' # <~ valid JavaScript variable name
bucket_name = '<YOUR_BUCKET_NAME>'
```

</WranglerConfig>

Within your Worker, your bucket binding is now available under the `MY_BUCKET` variable and you can begin interacting with it using the [bucket methods](#bucket-method-definitions) described below.

## Bucket method definitions

The following methods are available on the bucket binding object injected into your code.

For example, to issue a `PUT` object request using the binding above:

```js
export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		const key = url.pathname.slice(1);

		switch (request.method) {
			case "PUT":
				await env.MY_BUCKET.put(key, request.body);
				return new Response(`Put ${key} successfully!`);

			default:
				return new Response(`${request.method} is not allowed.`, {
					status: 405,
					headers: {
						Allow: "PUT",
					},
				});
		}
	},
};
```

- `head` <Type text="(key: string): Promise<R2Object | null>" />

  - Retrieves the `R2Object` for the given key containing only object metadata, if the key exists, and `null` if the key does not exist.

- `get` <Type text="(key: string, options?: R2GetOptions): Promise<R2ObjectBody | R2Object | null>" />

  - Retrieves the `R2ObjectBody` for the given key containing object metadata and the object body as a <code>ReadableStream</code>, if the key exists, and `null` if the key does not exist.
  - In the event that a precondition specified in <code>options</code> fails, <code>get()</code> returns an <code>R2Object</code> with <code>body</code> undefined.

- `put` <Type text="(key: string, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | null | Blob, options?: R2PutOptions): Promise<R2Object | null>" />

  - Stores the given <code>value</code> and metadata under the associated <code>key</code>. Once the write succeeds, returns an `R2Object` containing metadata about the stored Object.
  - In the event that a precondition specified in <code>options</code> fails, <code>put()</code> returns `null`, and the object will not be stored.
  - R2 writes are strongly consistent. Once the Promise resolves, all subsequent read operations will see this key value pair globally.

- `delete` <Type text="(key: string | string[]): Promise<void>" />

  - Deletes the given <code>values</code> and metadata under the associated <code>keys</code>. Once the delete succeeds, returns <code>void</code>.
  - R2 deletes are strongly consistent. Once the Promise resolves, all subsequent read operations will no longer see the provided key value pairs globally.
  - Up to 1000 keys may be deleted per call.

- `list` <Type text="(options?: R2ListOptions): Promise<R2Objects>" />

  * Returns an <code>R2Objects</code> containing a list of <code>R2Object</code> contained within the bucket.
  * The returned list of objects is ordered lexicographically.
  * Returns up to 1000 entries, but may return less in order to minimize memory pressure within the Worker.
  * To explicitly set the number of objects to list, provide an [R2ListOptions](/r2/api/workers/workers-api-reference/#r2listoptions) object with the `limit` property set.

* `createMultipartUpload` <Type text="(key: string, options?: R2MultipartOptions): Promise<R2MultipartUpload>" />

  - Creates a multipart upload.
  - Returns Promise which resolves to an `R2MultipartUpload` object representing the newly created multipart upload. Once the multipart upload has been created, the multipart upload can be immediately interacted with globally, either through the Workers API, or through the S3 API.

- `resumeMultipartUpload` <Type text="(key: string, uploadId: string): R2MultipartUpload" />

  - Returns an object representing a multipart upload with the given key and uploadId.
  - The resumeMultipartUpload operation does not perform any checks to ensure the validity of the uploadId, nor does it verify the existence of a corresponding active multipart upload. This is done to minimize latency before being able to call subsequent operations on the `R2MultipartUpload` object.

## `R2Object` definition

`R2Object` is created when you `PUT` an object into an R2 bucket. `R2Object` represents the metadata of an object based on the information provided by the uploader. Every object that you `PUT` into an R2 bucket will have an `R2Object` created.

- `key` <Type text="string" />

  - The object's key.

- `version` <Type text="string" />

  - Random unique string associated with a specific upload of a key.

- `size` <Type text="number" />

  - Size of the object in bytes.

- `etag` <Type text="string" />

:::note

Cloudflare recommends using the `httpEtag` field when returning an etag in a response header. This ensures the etag is quoted and conforms to [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#section-8.8.3).
:::

- The etag associated with the object upload.

- `httpEtag` <Type text="string" />

  - The object's etag, in quotes so as to be returned as a header.

- `uploaded` <Type text="Date" />

  - A Date object representing the time the object was uploaded.

- `httpMetadata` <Type text="R2HTTPMetadata" />

  - Various HTTP headers associated with the object. Refer to [HTTP Metadata](#http-metadata).

- `customMetadata` <Type text="Record<string, string>" />

  - A map of custom, user-defined metadata associated with the object.

- `range` <Type text="R2Range" />

  - A `R2Range` object containing the returned range of the object.

- `checksums` <Type text="R2Checksums" />

  - A `R2Checksums` object containing the stored checksums of the object. Refer to [checksums](#checksums).

- `writeHttpMetadata` <Type text="(headers: Headers): void" />

  - Retrieves the `httpMetadata` from the `R2Object` and applies their corresponding HTTP headers to the `Headers` input object. Refer to [HTTP Metadata](#http-metadata).

- `storageClass` <Type text="'Standard' | 'InfrequentAccess'" />

  - The storage class associated with the object. Refer to [Storage Classes](#storage-class).

- `ssecKeyMd5` <Type text="string" />

  - Hex-encoded MD5 hash of the [SSE-C](/r2/examples/ssec) key used for encryption (if one was provided). Hash can be used to identify which key is needed to decrypt object.

## `R2ObjectBody` definition

`R2ObjectBody` represents an object's metadata combined with its body. It is returned when you `GET` an object from an R2 bucket. The full list of keys for `R2ObjectBody` includes the list below and all keys inherited from [`R2Object`](#r2object-definition).

- `body` <Type text="ReadableStream" />

  - The object's value.

- `bodyUsed` <Type text="boolean" />

  - Whether the object's value has been consumed or not.

- `arrayBuffer` <Type text="(): Promise<ArrayBuffer>" />

  - Returns a Promise that resolves to an `ArrayBuffer` containing the object's value.

- `text` <Type text="(): Promise<string>" />

  - Returns a Promise that resolves to an string containing the object's value.

- `json` <Type text="<T>() : Promise<T>" />

  - Returns a Promise that resolves to the given object containing the object's value.

- `blob` <Type text="(): Promise<Blob>" />

  - Returns a Promise that resolves to a binary Blob containing the object's value.

## `R2MultipartUpload` definition

An `R2MultipartUpload` object is created when you call `createMultipartUpload` or `resumeMultipartUpload`. `R2MultipartUpload` is a representation of an ongoing multipart upload.

Uncompleted multipart uploads will be automatically aborted after 7 days.

:::note

An `R2MultipartUpload` object does not guarantee that there is an active underlying multipart upload corresponding to that object.

A multipart upload can be completed or aborted at any time, either through the S3 API, or by a parallel invocation of your Worker. Therefore it is important to add the necessary error handling code around each operation on a `R2MultipartUpload` object in case the underlying multipart upload no longer exists.

:::

- `key` <Type text="string" />

  - The `key` for the multipart upload.

- `uploadId` <Type text="string" />

  - The `uploadId` for the multipart upload.

- `uploadPart` <Type text="(partNumber: number, value: ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob, options?: R2MultipartOptions): Promise<R2UploadedPart>" />

  - Uploads a single part with the specified part number to this multipart upload. Each part must be uniform in size with an exception for the final part which can be smaller.
  - Returns an `R2UploadedPart` object containing the `etag` and `partNumber`. These `R2UploadedPart` objects are required when completing the multipart upload.

- `abort` <Type text="(): Promise<void>" />

  - Aborts the multipart upload. Returns a Promise that resolves when the upload has been successfully aborted.

- `complete` <Type text="(uploadedParts: R2UploadedPart[]): Promise<R2Object>" />

  - Completes the multipart upload with the given parts.
  - Returns a Promise that resolves when the complete operation has finished. Once this happens, the object is immediately accessible globally by any subsequent read operation.

## Method-specific types

### R2GetOptions

- `onlyIf` <Type text="R2Conditional | Headers" />

  - Specifies that the object should only be returned given satisfaction of certain conditions in the `R2Conditional` or in the conditional Headers. Refer to [Conditional operations](#conditional-operations).

- `range` <Type text="R2Range" />

  - Specifies that only a specific length (from an optional offset) or suffix of bytes from the object should be returned. Refer to [Ranged reads](#ranged-reads).

- `ssecKey` <Type text="ArrayBuffer | string" />

  - Specifies a key to be used for [SSE-C](/r2/examples/ssec). Key must be 32 bytes in length, in the form of a hex-encoded string or an ArrayBuffer.

#### Ranged reads

`R2GetOptions` accepts a `range` parameter, which can be used to restrict the data returned in `body`.

There are 3 variations of arguments that can be used in a range:

- An offset with an optional length.
- An optional offset with a length.
- A suffix.

- `offset` <Type text="number" />

  - The byte to begin returning data from, inclusive.

- `length` <Type text="number" />

  - The number of bytes to return. If more bytes are requested than exist in the object, fewer bytes than this number may be returned.

- `suffix` <Type text="number" />

  - The number of bytes to return from the end of the file, starting from the last byte. If more bytes are requested than exist in the object, fewer bytes than this number may be returned.

### R2PutOptions

- `onlyIf` <Type text="R2Conditional | Headers" />

  - Specifies that the object should only be stored given satisfaction of certain conditions in the `R2Conditional`. Refer to [Conditional operations](#conditional-operations).

- `httpMetadata` <Type text="R2HTTPMetadata | Headers" /> <MetaInfo text="optional" />

  - Various HTTP headers associated with the object. Refer to [HTTP Metadata](#http-metadata).

- `customMetadata` <Type text="Record<string, string>" /> <MetaInfo text="optional" />

  - A map of custom, user-defined metadata that will be stored with the object.

:::note

Only a single hashing algorithm can be specified at once.

:::

- `md5` <Type text="ArrayBuffer | string" /> <MetaInfo text="optional" />

  - A md5 hash to use to check the received object's integrity.

- `sha1` <Type text="ArrayBuffer | string" /> <MetaInfo text="optional" />

  - A SHA-1 hash to use to check the received object's integrity.

- `sha256` <Type text="ArrayBuffer | string" /> <MetaInfo text="optional" />

  - A SHA-256 hash to use to check the received object's integrity.

- `sha384` <Type text="ArrayBuffer | string" /> <MetaInfo text="optional" />

  - A SHA-384 hash to use to check the received object's integrity.

- `sha512` <Type text="ArrayBuffer | string" /> <MetaInfo text="optional" />

  - A SHA-512 hash to use to check the received object's integrity.

- `storageClass` <Type text="'Standard' | 'InfrequentAccess'" />

  - Sets the storage class of the object if provided. Otherwise, the object will be stored in the default storage class associated with the bucket. Refer to [Storage Classes](#storage-class).

- `ssecKey` <Type text="ArrayBuffer | string" />

  - Specifies a key to be used for [SSE-C](/r2/examples/ssec). Key must be 32 bytes in length, in the form of a hex-encoded string or an ArrayBuffer.

### R2MultipartOptions

- `httpMetadata` <Type text="R2HTTPMetadata | Headers" /> <MetaInfo text="optional" />

  - Various HTTP headers associated with the object. Refer to [HTTP Metadata](#http-metadata).

- `customMetadata` <Type text="Record<string, string>" /> <MetaInfo text="optional" />

  - A map of custom, user-defined metadata that will be stored with the object.

- `storageClass` <Type text="string" />

  - Sets the storage class of the object if provided. Otherwise, the object will be stored in the default storage class associated with the bucket. Refer to [Storage Classes](#storage-class).

- `ssecKey` <Type text="ArrayBuffer | string" />

  - Specifies a key to be used for [SSE-C](/r2/examples/ssec). Key must be 32 bytes in length, in the form of a hex-encoded string or an ArrayBuffer.

### R2ListOptions

- `limit` <Type text="number" /> <MetaInfo text="optional" />

  - The number of results to return. Defaults to `1000`, with a maximum of `1000`.

  - If `include` is set, you may receive fewer than `limit` results in your response to accommodate metadata.

- `prefix` <Type text="string" /> <MetaInfo text="optional" />

  - The prefix to match keys against. Keys will only be returned if they start with given prefix.

- `cursor` <Type text="string" /> <MetaInfo text="optional" />

  - An opaque token that indicates where to continue listing objects from. A cursor can be retrieved from a previous list operation.

- `delimiter` <Type text="string" /> <MetaInfo text="optional" />

  - The character to use when grouping keys.

- `include` <Type text="Array<string>" /> <MetaInfo text="optional" />

  - Can include `httpMetadata` and/or `customMetadata`. If included, items returned by the list will include the specified metadata.

  - Note that there is a limit on the total amount of data that a single `list` operation can return. If you request data, you may receive fewer than `limit` results in your response to accommodate metadata.

  - The [compatibility date](/workers/configuration/compatibility-dates/) must be set to `2022-08-04` or later in your Wrangler file. If not, then the `r2_list_honor_include` compatibility flag must be set. Otherwise it is treated as `include: ['httpMetadata', 'customMetadata']` regardless of what the `include` option provided actually is.

  This means applications must be careful to avoid comparing the amount of returned objects against your `limit`. Instead, use the `truncated` property to determine if the `list` request has more data to be returned.

```js
const options = {
	limit: 500,
	include: ["customMetadata"],
};

const listed = await env.MY_BUCKET.list(options);

let truncated = listed.truncated;
let cursor = truncated ? listed.cursor : undefined;

// ❌ - if your limit can't fit into a single response or your
// bucket has less objects than the limit, it will get stuck here.
while (listed.objects.length < options.limit) {
	// ...
}

// ✅ - use the truncated property to check if there are more
// objects to be returned
while (truncated) {
	const next = await env.MY_BUCKET.list({
		...options,
		cursor: cursor,
	});
	listed.objects.push(...next.objects);

	truncated = next.truncated;
	cursor = next.cursor;
}
```

### R2Objects

An object containing an `R2Object` array, returned by `BUCKET_BINDING.list()`.

- `objects` <Type text="Array<R2Object>" />

  - An array of objects matching the `list` request.

- `truncated` boolean

  - If true, indicates there are more results to be retrieved for the current `list` request.

- `cursor` <Type text="string" /> <MetaInfo text="optional" />

  - A token that can be passed to future `list` calls to resume listing from that point. Only present if truncated is true.

- `delimitedPrefixes` <Type text="Array<string>" />

  - If a delimiter has been specified, contains all prefixes between the specified prefix and the next occurrence of the delimiter.

  - For example, if no prefix is provided and the delimiter is '/', `foo/bar/baz` would return `foo` as a delimited prefix. If `foo/` was passed as a prefix with the same structure and delimiter, `foo/bar` would be returned as a delimited prefix.

### Conditional operations

You can pass an `R2Conditional` object to `R2GetOptions` and `R2PutOptions`. If the condition check for `get()` fails, the body will not be returned. This will make `get()` have lower latency.

If the condition check for `put()` fails, `null` will be returned instead of the `R2Object`.

- `etagMatches` <Type text="string" /> <MetaInfo text="optional" />

  - Performs the operation if the object's etag matches the given string.

- `etagDoesNotMatch` <Type text="string" /> <MetaInfo text="optional" />

  - Performs the operation if the object's etag does not match the given string.

- `uploadedBefore` <Type text="Date" /> <MetaInfo text="optional" />

  - Performs the operation if the object was uploaded before the given date.

- `uploadedAfter` <Type text="Date" /> <MetaInfo text="optional" />

  - Performs the operation if the object was uploaded after the given date.

Alternatively, you can pass a `Headers` object containing conditional headers to `R2GetOptions` and `R2PutOptions`. For information on these conditional headers, refer to [the MDN docs on conditional requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests#conditional_headers). All conditional headers aside from `If-Range` are supported.

For more specific information about conditional requests, refer to [RFC 7232](https://datatracker.ietf.org/doc/html/rfc7232).

### HTTP Metadata

Generally, these fields match the HTTP metadata passed when the object was created. They can be overridden when issuing `GET` requests, in which case, the given values will be echoed back in the response.

- `contentType` <Type text="string" /> <MetaInfo text="optional" />

- `contentLanguage` <Type text="string" /> <MetaInfo text="optional" />

- `contentDisposition` <Type text="string" /> <MetaInfo text="optional" />

- `contentEncoding` <Type text="string" /> <MetaInfo text="optional" />

- `cacheControl` <Type text="string" /> <MetaInfo text="optional" />

- `cacheExpiry` <Type text="Date" /> <MetaInfo text="optional" />

### Checksums

If a checksum was provided when using the `put()` binding, it will be available on the returned object under the `checksums` property. The MD5 checksum will be included by default for non-multipart objects.

- `md5` <Type text="ArrayBuffer" /> <MetaInfo text="optional" />

  - The MD5 checksum of the object.

- `sha1` <Type text="ArrayBuffer" /> <MetaInfo text="optional" />

  - The SHA-1 checksum of the object.

- `sha256` <Type text="ArrayBuffer" /> <MetaInfo text="optional" />

  - The SHA-256 checksum of the object.

- `sha384` <Type text="ArrayBuffer" /> <MetaInfo text="optional" />

  - The SHA-384 checksum of the object.

- `sha512` <Type text="ArrayBuffer" /> <MetaInfo text="optional" />

  - The SHA-512 checksum of the object.

### `R2UploadedPart`

An `R2UploadedPart` object represents a part that has been uploaded. `R2UploadedPart` objects are returned from `uploadPart` operations and must be passed to `completeMultipartUpload` operations.

- `partNumber` <Type text="number" />

  - The number of the part.

- `etag` <Type text="string" />

  - The `etag` of the part.

### Storage Class

The storage class where an `R2Object` is stored. The available storage classes are `Standard` and `InfrequentAccess`. Refer to [Storage classes](/r2/buckets/storage-classes/)
for more information.

---

# Use R2 from Workers

URL: https://developers.cloudflare.com/r2/api/workers/workers-api-usage/

import { Render, PackageManagers, WranglerConfig } from "~/components";

## 1. Create a new application with C3

C3 (`create-cloudflare-cli`) is a command-line tool designed to help you set up and deploy Workers & Pages applications to Cloudflare as fast as possible.

To get started, open a terminal window and run:

<PackageManagers type="create" pkg="cloudflare@latest" args={"r2-worker"} />

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Then, move into your newly created directory:

```sh
cd r2-worker
```

## 2. Create your bucket

Create your bucket by running:

```sh
npx wrangler r2 bucket create <YOUR_BUCKET_NAME>
```

To check that your bucket was created, run:

```sh
npx wrangler r2 bucket list
```

After running the `list` command, you will see all bucket names, including the one you have just created.

## 3. Bind your bucket to a Worker

You will need to bind your bucket to a Worker.

:::note[Bindings]

A binding is how your Worker interacts with external resources such as [KV Namespaces](/kv/concepts/kv-namespaces/), [Durable Objects](/durable-objects/), or [R2 Buckets](/r2/buckets/). A binding is a runtime variable that the Workers runtime provides to your code. You can declare a variable name in your Wrangler file that will be bound to these resources at runtime, and interact with them through this variable. Every binding's variable name and behavior is determined by you when deploying the Worker. Refer to the [Environment Variables](/workers/configuration/environment-variables/) documentation for more information.

A binding is defined in the Wrangler file of your Worker project's directory.

:::

To bind your R2 bucket to your Worker, add the following to your Wrangler file. Update the `binding` property to a valid JavaScript variable identifier and `bucket_name` to the `<YOUR_BUCKET_NAME>` you used to create your bucket in [step 2](#2-create-your-bucket):

<WranglerConfig>

```toml
[[r2_buckets]]
binding = 'MY_BUCKET' # <~ valid JavaScript variable name
bucket_name = '<YOUR_BUCKET_NAME>'
```

</WranglerConfig>

Find more detailed information on configuring your Worker in the [Wrangler Configuration documentation](/workers/wrangler/configuration/).

## 4. Access your R2 bucket from your Worker

Within your Worker code, your bucket is now available under the `MY_BUCKET` variable and you can begin interacting with it.

:::caution[Local Development mode in Wrangler]

By default `wrangler dev` runs in local development mode. In this mode, all operations performed by your local worker will operate against local storage on your machine.
Use `wrangler dev --remote` if you want R2 operations made during development to be performed against a real R2 bucket.

:::

An R2 bucket is able to READ, LIST, WRITE, and DELETE objects. You can see an example of all operations below using the Module Worker syntax. Add the following snippet into your project's `index.js` file:

```js
export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		const key = url.pathname.slice(1);

		switch (request.method) {
			case "PUT":
				await env.MY_BUCKET.put(key, request.body);
				return new Response(`Put ${key} successfully!`);
			case "GET":
				const object = await env.MY_BUCKET.get(key);

				if (object === null) {
					return new Response("Object Not Found", { status: 404 });
				}

				const headers = new Headers();
				object.writeHttpMetadata(headers);
				headers.set("etag", object.httpEtag);

				return new Response(object.body, {
					headers,
				});
			case "DELETE":
				await env.MY_BUCKET.delete(key);
				return new Response("Deleted!");

			default:
				return new Response("Method Not Allowed", {
					status: 405,
					headers: {
						Allow: "PUT, GET, DELETE",
					},
				});
		}
	},
};
```

<Render file="request-dot-clone-warning" product="workers" />

## 5. Bucket access and privacy

With the above code added to your Worker, every incoming request has the ability to interact with your bucket. This means your bucket is publicly exposed and its contents can be accessed and modified by undesired actors.

You must now define authorization logic to determine who can perform what actions to your bucket. This logic lives within your Worker's code, as it is your application's job to determine user privileges. The following is a short list of resources related to access and authorization practices:

1. [Basic Authentication](/workers/examples/basic-auth/): Shows how to restrict access using the HTTP Basic schema.
2. [Using Custom Headers](/workers/examples/auth-with-headers/): Allow or deny a request based on a known pre-shared key in a header.

{/* <!-- 3. [Authorizing users with Auth0](/workers/tutorials/authorize-users-with-auth0/#overview): Integrate Auth0, an identity management platform, into a Cloudflare Workers application. --> */}

Continuing with your newly created bucket and Worker, you will need to protect all bucket operations.

For `PUT` and `DELETE` requests, you will make use of a new `AUTH_KEY_SECRET` environment variable, which you will define later as a Wrangler secret.

For `GET` requests, you will ensure that only a specific file can be requested. All of this custom logic occurs inside of an `authorizeRequest` function, with the `hasValidHeader` function handling the custom header logic. If all validation passes, then the operation is allowed.

```js
const ALLOW_LIST = ["cat-pic.jpg"];

// Check requests for a pre-shared secret
const hasValidHeader = (request, env) => {
	return request.headers.get("X-Custom-Auth-Key") === env.AUTH_KEY_SECRET;
};

function authorizeRequest(request, env, key) {
	switch (request.method) {
		case "PUT":
		case "DELETE":
			return hasValidHeader(request, env);
		case "GET":
			return ALLOW_LIST.includes(key);
		default:
			return false;
	}
}

export default {
	async fetch(request, env, ctx) {
		const url = new URL(request.url);
		const key = url.pathname.slice(1);

		if (!authorizeRequest(request, env, key)) {
			return new Response("Forbidden", { status: 403 });
		}

		// ...
	},
};
```

For this to work, you need to create a secret via Wrangler:

```sh
npx wrangler secret put AUTH_KEY_SECRET
```

This command will prompt you to enter a secret in your terminal:

```sh
npx wrangler secret put AUTH_KEY_SECRET
```

```sh output
Enter the secret text you'd like assigned to the variable AUTH_KEY_SECRET on the script named <YOUR_WORKER_NAME>:
*********
🌀  Creating the secret for script name <YOUR_WORKER_NAME>
✨  Success! Uploaded secret AUTH_KEY_SECRET.
```

This secret is now available as `AUTH_KEY_SECRET` on the `env` parameter in your Worker.

## 6. Deploy your bucket

With your Worker and bucket set up, run the `npx wrangler deploy` [command](/workers/wrangler/commands/#deploy) to deploy to Cloudflare's global network:

```sh
npx wrangler deploy
```

You can verify your authorization logic is working through the following commands, using your deployed Worker endpoint:

:::caution

When uploading files to R2 via `curl`, ensure you use **[`--data-binary`](https://everything.curl.dev/http/post/binary)** instead of `--data` or `-d`. Files will otherwise be truncated.
:::

```sh
# Attempt to write an object without providing the "X-Custom-Auth-Key" header
curl https://your-worker.dev/cat-pic.jpg -X PUT --data-binary 'test'
#=> Forbidden
# Expected because header was missing

# Attempt to write an object with the wrong "X-Custom-Auth-Key" header value
curl https://your-worker.dev/cat-pic.jpg -X PUT --header "X-Custom-Auth-Key: hotdog" --data-binary 'test'
#=> Forbidden
# Expected because header value did not match the AUTH_KEY_SECRET value

# Attempt to write an object with the correct "X-Custom-Auth-Key" header value
# Note: Assume that "*********" is the value of your AUTH_KEY_SECRET Wrangler secret
curl https://your-worker.dev/cat-pic.jpg -X PUT --header "X-Custom-Auth-Key: *********" --data-binary 'test'
#=> Put cat-pic.jpg successfully!

# Attempt to read object called "foo"
curl https://your-worker.dev/foo
#=> Forbidden
# Expected because "foo" is not in the ALLOW_LIST

# Attempt to read an object called "cat-pic.jpg"
curl https://your-worker.dev/cat-pic.jpg
#=> test
# Note: This is the value that was successfully PUT above
```

By completing this guide, you have successfully installed Wrangler and deployed your R2 bucket to Cloudflare.

## Related resources

1. [Workers Tutorials](/workers/tutorials/)
2. [Workers Examples](/workers/examples/)

---

# DuckDB

URL: https://developers.cloudflare.com/r2/data-catalog/config-examples/duckdb/

Below is an example of using [DuckDB](https://duckdb.org/) to connect to R2 Data Catalog (read-only). For more information on connecting to R2 Data Catalog with DuckDB, refer to [DuckDB documentation](https://duckdb.org/docs/stable/core_extensions/iceberg/iceberg_rest_catalogs#r2-catalog).

## Prerequisites

- Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages).
- [Create an R2 bucket](/r2/buckets/create-buckets/) and [enable the data catalog](/r2/data-catalog/manage-catalogs/#enable-r2-data-catalog-on-a-bucket).
- [Create an R2 API token](/r2/api/tokens/) with both [R2 and data catalog permissions](/r2/api/tokens/#permissions).
- Install [DuckDB](https://duckdb.org/docs/installation/).
  - Note: [DuckDB 1.3.0](https://github.com/duckdb/duckdb/releases/tag/v1.3.0) or greater is required to attach [Iceberg REST Catalogs](https://duckdb.org/docs/stable/core_extensions/iceberg/iceberg_rest_catalogs).

## Example usage

In the [DuckDB CLI](https://duckdb.org/docs/stable/clients/cli/overview.html) (Command Line Interface), run the following commands:

```sql
-- Install the iceberg DuckDB extension (if you haven't already) and load the extension.
INSTALL iceberg;
LOAD iceberg;

-- Create a DuckDB secret to store R2 Data Catalog credentials.
CREATE SECRET r2_secret (
    TYPE ICEBERG,
    TOKEN '<token>'
);

-- Attach R2 Data Catalog with the following ATTACH statement (read-only).
ATTACH '<warehouse_name>' AS my_r2_catalog (
    TYPE ICEBERG,
    ENDPOINT '<catalog_uri>'
);

-- Show all available tables.
SHOW ALL TABLES;

-- Query your Iceberg table.
SELECT * FROM my_r2_catalog.default.my_iceberg_table;
```

---

# Use the R2 multipart API from Workers

URL: https://developers.cloudflare.com/r2/api/workers/workers-multipart-usage/

By following this guide, you will create a Worker through which your applications can perform multipart uploads.
This example worker could serve as a basis for your own use case where you can add authentication to the worker, or even add extra validation logic when uploading each part.
This guide also contains an example Python application that uploads files to this worker.

This guide assumes you have set up the [R2 binding](/workers/runtime-apis/bindings/) for your Worker. Refer to [Use R2 from Workers](/r2/api/workers/workers-api-usage) for instructions on setting up an R2 binding.

## An example Worker using the multipart API

The following example Worker exposes an HTTP API which enables applications to use the multipart API through the Worker.

In this example, each request is routed based on the HTTP method and the action request parameter. As your Worker becomes more complicated, consider utilizing a serverless web framework such as [Hono](https://honojs.dev/) to handle the routing for you.

The following example Worker includes any new information about the state of the multipart upload in the response to each request. For the request which creates the multipart upload, the `uploadId` is returned. For requests uploading a part, the part number and `etag` are returned. In turn, the client keeps track of this state, and includes the uploadId in subsequent requests, and the `etag` and part number of each part when completing a multipart upload.

Add the following code to your project's `index.js` file and replace `MY_BUCKET` with your bucket's name:

```js
interface Env {
  MY_BUCKET: R2Bucket;
}

export default {
  async fetch(
    request,
    env,
    ctx
  ): Promise<Response> {
    const bucket = env.MY_BUCKET;

    const url = new URL(request.url);
    const key = url.pathname.slice(1);
    const action = url.searchParams.get("action");

    if (action === null) {
      return new Response("Missing action type", { status: 400 });
    }

    // Route the request based on the HTTP method and action type
    switch (request.method) {
      case "POST":
        switch (action) {
          case "mpu-create": {
            const multipartUpload = await bucket.createMultipartUpload(key);
            return new Response(
              JSON.stringify({
                key: multipartUpload.key,
                uploadId: multipartUpload.uploadId,
              })
            );
          }
          case "mpu-complete": {
            const uploadId = url.searchParams.get("uploadId");
            if (uploadId === null) {
              return new Response("Missing uploadId", { status: 400 });
            }

            const multipartUpload = env.MY_BUCKET.resumeMultipartUpload(
              key,
              uploadId
            );

            interface completeBody {
              parts: R2UploadedPart[];
            }
            const completeBody: completeBody = await request.json();
            if (completeBody === null) {
              return new Response("Missing or incomplete body", {
                status: 400,
              });
            }

            // Error handling in case the multipart upload does not exist anymore
            try {
              const object = await multipartUpload.complete(completeBody.parts);
              return new Response(null, {
                headers: {
                  etag: object.httpEtag,
                },
              });
            } catch (error: any) {
              return new Response(error.message, { status: 400 });
            }
          }
          default:
            return new Response(`Unknown action ${action} for POST`, {
              status: 400,
            });
        }
      case "PUT":
        switch (action) {
          case "mpu-uploadpart": {
            const uploadId = url.searchParams.get("uploadId");
            const partNumberString = url.searchParams.get("partNumber");
            if (partNumberString === null || uploadId === null) {
              return new Response("Missing partNumber or uploadId", {
                status: 400,
              });
            }
            if (request.body === null) {
              return new Response("Missing request body", { status: 400 });
            }

            const partNumber = parseInt(partNumberString);
            const multipartUpload = env.MY_BUCKET.resumeMultipartUpload(
              key,
              uploadId
            );
            try {
              const uploadedPart: R2UploadedPart =
                await multipartUpload.uploadPart(partNumber, request.body);
              return new Response(JSON.stringify(uploadedPart));
            } catch (error: any) {
              return new Response(error.message, { status: 400 });
            }
          }
          default:
            return new Response(`Unknown action ${action} for PUT`, {
              status: 400,
            });
        }
      case "GET":
        if (action !== "get") {
          return new Response(`Unknown action ${action} for GET`, {
            status: 400,
          });
        }
        const object = await env.MY_BUCKET.get(key);
        if (object === null) {
          return new Response("Object Not Found", { status: 404 });
        }
        const headers = new Headers();
        object.writeHttpMetadata(headers);
        headers.set("etag", object.httpEtag);
        return new Response(object.body, { headers });
      case "DELETE":
        switch (action) {
          case "mpu-abort": {
            const uploadId = url.searchParams.get("uploadId");
            if (uploadId === null) {
              return new Response("Missing uploadId", { status: 400 });
            }
            const multipartUpload = env.MY_BUCKET.resumeMultipartUpload(
              key,
              uploadId
            );

            try {
              multipartUpload.abort();
            } catch (error: any) {
              return new Response(error.message, { status: 400 });
            }
            return new Response(null, { status: 204 });
          }
          case "delete": {
            await env.MY_BUCKET.delete(key);
            return new Response(null, { status: 204 });
          }
          default:
            return new Response(`Unknown action ${action} for DELETE`, {
              status: 400,
            });
        }
      default:
        return new Response("Method Not Allowed", {
          status: 405,
          headers: { Allow: "PUT, POST, GET, DELETE" },
        });
    }
  },
} satisfies ExportedHandler<Env>;
```

After you have updated your Worker with the above code, run `npx wrangler deploy`.

You can now use this Worker to perform multipart uploads. You can either send requests from your existing application to this Worker to perform uploads or use a script to upload files through this Worker.

The next section is optional and shows an example of a Python script which uploads a chosen file on your machine to your Worker.

## Perform a multipart upload with your Worker (optional)

This example application uploads a local file to the Worker in multiple parts. It uses Python's built-in `ThreadPoolExecutor` to parallelize the uploading of parts to the Worker, which increases upload speeds. HTTP requests to the Worker are made with the [requests](https://pypi.org/project/requests/) library.

Utilizing the multipart API in this way also allows you to use your Worker to upload files larger than the [Workers request body size limit](/workers/platform/limits#request-limits). The uploading of individual parts is still subject to this limit.

Save the following code in a file named `mpuscript.py` on your local machine. Change the `worker_endpoint variable` to where your worker is deployed. Pass the file you want to upload as an argument when running this script: `python3 mpuscript.py myfile`. This will upload the file `myfile` from your machine to your bucket through the Worker.

```python
import math
import os
import requests
from requests.adapters import HTTPAdapter, Retry
import sys
import concurrent.futures

# Take the file to upload as an argument
filename = sys.argv[1]
# The endpoint for our worker, change this to wherever you deploy your worker
worker_endpoint = "https://myworker.myzone.workers.dev/"
# Configure the part size to be 10MB. 5MB is the minimum part size, except for the last part
partsize = 10 * 1024 * 1024


def upload_file(worker_endpoint, filename, partsize):
    url = f"{worker_endpoint}{filename}"

    # Create the multipart upload
    uploadId = requests.post(url, params={"action": "mpu-create"}).json()["uploadId"]

    part_count = math.ceil(os.stat(filename).st_size / partsize)
    # Create an executor for up to 25 concurrent uploads.
    executor = concurrent.futures.ThreadPoolExecutor(25)
    # Submit a task to the executor to upload each part
    futures = [
        executor.submit(upload_part, filename, partsize, url, uploadId, index)
        for index in range(part_count)
    ]
    concurrent.futures.wait(futures)
    # get the parts from the futures
    uploaded_parts = [future.result() for future in futures]

    # complete the multipart upload
    response = requests.post(
        url,
        params={"action": "mpu-complete", "uploadId": uploadId},
        json={"parts": uploaded_parts},
    )
    if response.status_code == 200:
        print("🎉 successfully completed multipart upload")
    else:
        print(response.text)


def upload_part(filename, partsize, url, uploadId, index):
    # Open the file in rb mode, which treats it as raw bytes rather than attempting to parse utf-8
    with open(filename, "rb") as file:
        file.seek(partsize * index)
        part = file.read(partsize)

    # Retry policy for when uploading a part fails
    s = requests.Session()
    retries = Retry(total=3, status_forcelist=[400, 500, 502, 503, 504])
    s.mount("https://", HTTPAdapter(max_retries=retries))

    return s.put(
        url,
        params={
            "action": "mpu-uploadpart",
            "uploadId": uploadId,
            "partNumber": str(index + 1),
        },
        data=part,
    ).json()


upload_file(worker_endpoint, filename, partsize)
```

## State management

The stateful nature of multipart uploads does not easily map to the usage model of Workers, which are inherently stateless. In a normal multipart upload, the multipart upload is usually performed in one continuous execution of the client application. This is different from multipart uploads in a Worker, which will often be completed over multiple invocations of that Worker. This makes state management more challenging.

To overcome this, the state associated with a multipart upload, namely the `uploadId` and which parts have been uploaded, needs to be kept track of somewhere outside of the Worker.

In the example Worker and Python application described in this guide, the state of the multipart upload is tracked in the client application which sends requests to the Worker, with the necessary state contained in each request. Keeping track of the multipart state in the client application enables maximal flexibility and allows for parallel and unordered uploads of each part.

When keeping track of this state in the client is impossible, alternative designs can be considered. For example, you could track the `uploadId` and which parts have been uploaded in a Durable Object or other database.

---

# Connect to Iceberg engines

URL: https://developers.cloudflare.com/r2/data-catalog/config-examples/

import { DirectoryListing } from "~/components";

Below are configuration examples to connect various Iceberg engines to [R2 Data Catalog](/r2/data-catalog/):

<DirectoryListing />

---

# Snowflake

URL: https://developers.cloudflare.com/r2/data-catalog/config-examples/snowflake/

Below is an example of using [Snowflake](https://docs.snowflake.com/en/user-guide/tables-iceberg-configure-catalog-integration-rest) to connect and query data from R2 Data Catalog (read-only).

## Prerequisites

- Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages).
- [Create an R2 bucket](/r2/buckets/create-buckets/) and [enable the data catalog](/r2/data-catalog/manage-catalogs/#enable-r2-data-catalog-on-a-bucket).
- [Create an R2 API token](/r2/api/tokens/) with both [R2 and data catalog permissions](/r2/api/tokens/#permissions).
- A [Snowflake](https://www.snowflake.com/) account with the necessary privileges to create external volumes and catalog integrations.

## Example usage

In your Snowflake [SQL worksheet](https://docs.snowflake.com/en/user-guide/ui-snowsight-worksheets-gs) or [notebook](https://docs.snowflake.com/en/user-guide/ui-snowsight/notebooks), run the following commands:

```sql
-- Create a database (if you don't already have one) to organize your external data
CREATE DATABASE IF NOT EXISTS r2_example_db;

-- Create an external volume pointing to your R2 bucket
CREATE OR REPLACE EXTERNAL VOLUME ext_vol_r2
    STORAGE_LOCATIONS = (
        (
            NAME = 'my_r2_storage_location'
            STORAGE_PROVIDER = 'S3COMPAT'
            STORAGE_BASE_URL = 's3compat://<bucket-name>'
            CREDENTIALS = (
                AWS_KEY_ID = '<access_key>'
                AWS_SECRET_KEY = '<secret_access_key>'
            )
            STORAGE_ENDPOINT = '<account_id>.r2.cloudflarestorage.com'
        )
    )
    ALLOW_WRITES = FALSE;

-- Create a catalog integration for R2 Data Catalog (read-only)
CREATE OR REPLACE CATALOG INTEGRATION r2_data_catalog
    CATALOG_SOURCE = ICEBERG_REST
    TABLE_FORMAT = ICEBERG
    CATALOG_NAMESPACE = 'default'
    REST_CONFIG = (
        CATALOG_URI = '<catalog_uri>'
        CATALOG_NAME = '<warehouse_name>'
    )
    REST_AUTHENTICATION = (
        TYPE = BEARER
        BEARER_TOKEN = '<token>'
    )
    ENABLED = TRUE;

-- Create an Apache Iceberg table in your selected Snowflake database
CREATE ICEBERG TABLE my_iceberg_table
    CATALOG = 'r2_data_catalog'
    EXTERNAL_VOLUME = 'ext_vol_r2'
    CATALOG_TABLE_NAME = 'my_table';  -- Name of existing table in your R2 data catalog

-- Query your Iceberg table
SELECT * FROM my_iceberg_table;
```

---

# PyIceberg

URL: https://developers.cloudflare.com/r2/data-catalog/config-examples/pyiceberg/

Below is an example of using [PyIceberg](https://py.iceberg.apache.org/) to connect to R2 Data Catalog.

## Prerequisites

- Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages).
- [Create an R2 bucket](/r2/buckets/create-buckets/) and [enable the data catalog](/r2/data-catalog/manage-catalogs/#enable-r2-data-catalog-on-a-bucket).
- [Create an R2 API token](/r2/api/tokens/) with both [R2 and data catalog permissions](/r2/api/tokens/#permissions).
- Install the [PyIceberg](https://py.iceberg.apache.org/#installation) and [PyArrow](https://arrow.apache.org/docs/python/install.html) libraries.

## Example usage

```py
import pyarrow as pa
from pyiceberg.catalog.rest import RestCatalog
from pyiceberg.exceptions import NamespaceAlreadyExistsError

# Define catalog connection details (replace variables)
WAREHOUSE = "<WAREHOUSE>"
TOKEN = "<TOKEN>"
CATALOG_URI = "<CATALOG_URI>"

# Connect to R2 Data Catalog
catalog = RestCatalog(
    name="my_catalog",
    warehouse=WAREHOUSE,
    uri=CATALOG_URI,
    token=TOKEN,
)

# Create default namespace
catalog.create_namespace("default")

# Create simple PyArrow table
df = pa.table({
    "id": [1, 2, 3],
    "name": ["Alice", "Bob", "Charlie"],
})

# Create an Iceberg table
test_table = ("default", "my_table")
table = catalog.create_table(
    test_table,
    schema=df.schema,
)
```

---

# Spark (PySpark)

URL: https://developers.cloudflare.com/r2/data-catalog/config-examples/spark-python/

Below is an example of using [PySpark](https://spark.apache.org/docs/latest/api/python/index.html) to connect to R2 Data Catalog.

## Prerequisites

- Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages).
- [Create an R2 bucket](/r2/buckets/create-buckets/) and [enable the data catalog](/r2/data-catalog/manage-catalogs/#enable-r2-data-catalog-on-a-bucket).
- [Create an R2 API token](/r2/api/tokens/) with both [R2 and data catalog permissions](/r2/api/tokens/#permissions).
- Install the [PySpark](https://spark.apache.org/docs/latest/api/python/getting_started/install.html) library.

## Example usage

```py
from pyspark.sql import SparkSession

# Define catalog connection details (replace variables)
WAREHOUSE = "<WAREHOUSE>"
TOKEN = "<TOKEN>"
CATALOG_URI = "<CATALOG_URI>"

# Build Spark session with Iceberg configurations
spark = SparkSession.builder \
  .appName("R2DataCatalogExample") \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.6.1,org.apache.iceberg:iceberg-aws-bundle:1.6.1') \
  .config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions") \
  .config("spark.sql.catalog.my_catalog", "org.apache.iceberg.spark.SparkCatalog") \
  .config("spark.sql.catalog.my_catalog.type", "rest") \
  .config("spark.sql.catalog.my_catalog.uri", CATALOG_URI) \
  .config("spark.sql.catalog.my_catalog.warehouse", WAREHOUSE) \
  .config("spark.sql.catalog.my_catalog.token", TOKEN) \
  .config("spark.sql.catalog.my_catalog.header.X-Iceberg-Access-Delegation", "vended-credentials") \
  .config("spark.sql.catalog.my_catalog.s3.remote-signing-enabled", "false") \
  .config("spark.sql.defaultCatalog", "my_catalog") \
  .getOrCreate()
spark.sql("USE my_catalog")

# Create namespace if it does not exist
spark.sql("CREATE NAMESPACE IF NOT EXISTS default")

# Create a table in the namespace using Iceberg
spark.sql("""
    CREATE TABLE IF NOT EXISTS default.my_table (
        id BIGINT,
        name STRING
    )
    USING iceberg
""")

# Create a simple DataFrame
df = spark.createDataFrame(
    [(1, "Alice"), (2, "Bob"), (3, "Charlie")],
    ["id", "name"]
)

# Write the DataFrame to the Iceberg table
df.write \
    .format("iceberg") \
    .mode("append") \
    .save("default.my_table")

# Read the data back from the Iceberg table
result_df = spark.read \
    .format("iceberg") \
    .load("default.my_table")

result_df.show()
```

---

# Spark (Scala)

URL: https://developers.cloudflare.com/r2/data-catalog/config-examples/spark-scala/

import { FileTree } from "~/components"


Below is an example of how you can build an [Apache Spark](https://spark.apache.org/) application (with Scala) which connects to R2 Data Catalog. This application is built to run locally, but it can be adapted to run on a cluster.

## Prerequisites

- Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages).
- [Create an R2 bucket](/r2/buckets/create-buckets/) and [enable the data catalog](/r2/data-catalog/manage-catalogs/#enable-r2-data-catalog-on-a-bucket).
- [Create an R2 API token](/r2/api/tokens/) with both [R2 and data catalog permissions](/r2/api/tokens/#permissions).
- Install Java 17, Spark 3.5.3, and SBT 1.10.11
  - Note: The specific versions of tools are critical for getting things to work in this example.
  - Tip: [“SDKMAN”](https://sdkman.io/) is a convenient package manager for installing SDKs.

## Example usage

To start, create a new empty project directory somewhere on your machine.

Inside that directory, create the following file at `src/main/scala/com/example/R2DataCatalogDemo.scala`. This will serve as the main entry point for your Spark application.

```java
package com.example

import org.apache.spark.sql.SparkSession

object R2DataCatalogDemo {
    def main(args: Array[String]): Unit = {

        val uri = sys.env("CATALOG_URI")
        val warehouse = sys.env("WAREHOUSE")
        val token = sys.env("TOKEN")

        val spark = SparkSession.builder()
            .appName("My R2 Data Catalog Demo")
            .master("local[*]")
            .config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions")
            .config("spark.sql.catalog.mydemo", "org.apache.iceberg.spark.SparkCatalog")
            .config("spark.sql.catalog.mydemo.type", "rest")
            .config("spark.sql.catalog.mydemo.uri", uri)
            .config("spark.sql.catalog.mydemo.warehouse", warehouse)
            .config("spark.sql.catalog.mydemo.token", token)
            .getOrCreate()

        import spark.implicits._

        val data = Seq(
            (1, "Alice", 25),
            (2, "Bob", 30),
            (3, "Charlie", 35),
            (4, "Diana", 40)
        ).toDF("id", "name", "age")

        spark.sql("USE mydemo")

        spark.sql("CREATE NAMESPACE IF NOT EXISTS demoNamespace")

        data.writeTo("demoNamespace.demotable").createOrReplace()

        val readResult = spark.sql("SELECT * FROM demoNamespace.demotable WHERE age > 30")
        println("Records with age > 30:")
        readResult.show()
    }
}
```

For building this application and managing dependencies, we will use [sbt (“simple build tool”)](https://www.scala-sbt.org/). The following is an example `build.sbt` file to place at the root of your project. It is configured to produce a "fat JAR", bundling all required dependencies.

```java
name := "R2DataCatalogDemo"

version := "1.0"

val sparkVersion = "3.5.3"
val icebergVersion = "1.8.1"

// You need to use binaries of Spark compiled with either 2.12 or 2.13; and 2.12 is more common.
// If you download Spark 3.5.3 with sdkman, then it comes with 2.12.18
scalaVersion := "2.12.18"

libraryDependencies ++= Seq(
    "org.apache.spark" %% "spark-core" % sparkVersion,
    "org.apache.spark" %% "spark-sql" % sparkVersion,
    "org.apache.iceberg" % "iceberg-core" % icebergVersion,
    "org.apache.iceberg" % "iceberg-spark-runtime-3.5_2.12" % icebergVersion,
    "org.apache.iceberg" % "iceberg-aws-bundle" % icebergVersion,
)

// build a fat JAR with all dependencies
assembly / assemblyMergeStrategy := {
    case PathList("META-INF", "services", xs @ _*) => MergeStrategy.concat
    case PathList("META-INF", xs @ _*) => MergeStrategy.discard
    case "reference.conf" => MergeStrategy.concat
    case "application.conf" => MergeStrategy.concat
    case x if x.endsWith(".properties") => MergeStrategy.first
    case x => MergeStrategy.first
}

// For Java  17 Compatability
Compile / javacOptions ++= Seq("--release", "17")
```

To enable the [sbt-assembly plugin](https://github.com/sbt/sbt-assembly?tab=readme-ov-file) (used to build fat JARs), add the following to a new file at `project/assembly.sbt`:

```
addSbtPlugin("com.eed3si9n" % "sbt-assembly" % "1.2.0")
```

Make sure Java, Spark, and sbt are installed and available in your shell. If you are using SDKMAN, you can install them as shown below:

```bash
sdk install java 17.0.14-amzn
sdk install spark 3.5.3
sdk install sbt 1.10.11
```

With everything installed, you can now build the project using sbt. This will generate a single bundled JAR file.

```bash
sbt clean assembly
```

After building, the output JAR should be located at `target/scala-2.12/R2DataCatalogDemo-assembly-1.0.jar`.

To run the application, you will use `spark-submit`. Below is an example shell script (`submit.sh`) that includes the necessary Java compatability flags for Spark on Java 17:

```
# We need to set these "--add-opens" so that Spark can run on Java 17 (it needs access to
# parts of the JVM which have been modularized and made internal).
JAVA_17_COMPATABILITY="--add-opens=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED"

spark-submit \
--conf "spark.driver.extraJavaOptions=$JAVA_17_COMPATABILITY" \
--conf "spark.executor.extraJavaOptions=$JAVA_17_COMPATABILITY" \
--class com.example.R2DataCatalogDemo target/scala-2.12/R2DataCatalogDemo-assembly-1.0.jar
```

Before running it, make sure the script is executable:

```bash
chmod +x submit.sh
```

At this point, your project directory should be structured like this:

<FileTree>
- Makefile
- README.md
- build.sbt
- project
  - assembly.sbt
  - build.properties
  - project
- spark-submit.sh
- src
  - main
	  - scala
		  - com
			  - example
				  - R2DataCatalogDemo.scala
</FileTree>

Before submitting the job, make sure you have the required environment variable set for your catalog URI, warehouse, and [Cloudflare API token](/r2/api/tokens/).

```bash
export CATALOG_URI=
export WAREHOUSE=
export TOKEN=
```

You are now ready to run the job:

```bash
./submit.sh
```

---

# aws CLI

URL: https://developers.cloudflare.com/r2/examples/aws/aws-cli/

import { Render } from "~/components";

<Render file="keys" />
<br />

With the [`aws`](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) CLI installed, you may run [`aws configure`](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config) to configure a new profile. You will be prompted with a series of questions for the new profile's details.

:::note[Compatibility]
Client versions `2.23.0` and `1.37.0` introduced a modification to the default checksum behavior from the client that is currently incompatible with R2 APIs.

To mitigate, users can use `2.22.35` or `1.36.40`, or alternatively, add the CRC32 checksum flag to the cli command:

```sh
aws s3api put-object --bucket sdk-example --key sdk.png --body file/path --checksum-algorithm CRC32
```

:::

```shell
aws configure
```

```sh output
AWS Access Key ID [None]: <access_key_id>
AWS Secret Access Key [None]: <access_key_secret>
Default region name [None]: auto
Default output format [None]: json
```

You may then use the `aws` CLI for any of your normal workflows.

```sh
aws s3api list-buckets --endpoint-url https://<accountid>.r2.cloudflarestorage.com
# {
#     "Buckets": [
#         {
#             "Name": "sdk-example",
#             "CreationDate": "2022-05-18T17:19:59.645000+00:00"
#         }
#     ],
#     "Owner": {
#         "DisplayName": "134a5a2c0ba47b38eada4b9c8ead10b6",
#         "ID": "134a5a2c0ba47b38eada4b9c8ead10b6"
#     }
# }

aws s3api list-objects-v2 --endpoint-url https://<accountid>.r2.cloudflarestorage.com --bucket sdk-example
# {
#     "Contents": [
#         {
#             "Key": "ferriswasm.png",
#             "LastModified": "2022-05-18T17:20:21.670000+00:00",
#             "ETag": "\"eb2b891dc67b81755d2b726d9110af16\"",
#             "Size": 87671,
#             "StorageClass": "STANDARD"
#         }
#     ]
# }
```

## Generate presigned URLs

You can also generate presigned links which allow you to share public access to a file temporarily.

```sh
# You can pass the --expires-in flag to determine how long the presigned link is valid.
$ aws s3 presign --endpoint-url https://<accountid>.r2.cloudflarestorage.com  s3://sdk-example/ferriswasm.png --expires-in 3600
# https://<accountid>.r2.cloudflarestorage.com/sdk-example/ferriswasm.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>
aws s3 presign --endpoint-url https://<accountid>.r2.cloudflarestorage.com  s3://sdk-example/ferriswasm.png --expires-in 3600
# https://<accountid>.r2.cloudflarestorage.com/sdk-example/ferriswasm.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>
```

---

# aws-sdk-go

URL: https://developers.cloudflare.com/r2/examples/aws/aws-sdk-go/

import { Render } from "~/components";

<Render file="keys" />
<br />

This example uses version 2 of the [aws-sdk-go](https://github.com/aws/aws-sdk-go-v2) package. You must pass in the R2 configuration credentials when instantiating your `S3` service client:

:::note[Compatibility]
Client version `1.73.0` introduced a modification to the default checksum behavior from the client that is currently incompatible with R2 APIs.

To mitigate, users can use `1.72.3` or add the following to their config:

```go
config.WithRequestChecksumCalculation(0)
config.WithResponseChecksumValidation(0)
```

:::

```go
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/credentials"
	"github.com/aws/aws-sdk-go-v2/service/s3"
	"log"
)

func main() {
	var bucketName = "sdk-example"
	var accountId = "<accountid>"
	var accessKeyId = "<access_key_id>"
	var accessKeySecret = "<access_key_secret>"

	cfg, err := config.LoadDefaultConfig(context.TODO(),
		config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(accessKeyId, accessKeySecret, "")),
		config.WithRegion("auto"),
	)
	if err != nil {
		log.Fatal(err)
	}

	client := s3.NewFromConfig(cfg, func(o *s3.Options) {
			o.BaseEndpoint = aws.String(fmt.Sprintf("https://%s.r2.cloudflarestorage.com", accountId))
	})

	listObjectsOutput, err := client.ListObjectsV2(context.TODO(), &s3.ListObjectsV2Input{
		Bucket: &bucketName,
	})
	if err != nil {
		log.Fatal(err)
	}

	for _, object := range listObjectsOutput.Contents {
		obj, _ := json.MarshalIndent(object, "", "\t")
		fmt.Println(string(obj))
	}

	//  {
	//  	"ChecksumAlgorithm": null,
	//  	"ETag": "\"eb2b891dc67b81755d2b726d9110af16\"",
	//  	"Key": "ferriswasm.png",
	//  	"LastModified": "2022-05-18T17:20:21.67Z",
	//  	"Owner": null,
	//  	"Size": 87671,
	//  	"StorageClass": "STANDARD"
	//  }

	listBucketsOutput, err := client.ListBuckets(context.TODO(), &s3.ListBucketsInput{})
	if err != nil {
		log.Fatal(err)
	}

	for _, object := range listBucketsOutput.Buckets {
		obj, _ := json.MarshalIndent(object, "", "\t")
		fmt.Println(string(obj))
	}

	// {
	// 		"CreationDate": "2022-05-18T17:19:59.645Z",
	// 		"Name": "sdk-example"
	// }
}
```

## Generate presigned URLs

You can also generate presigned links that can be used to temporarily share public write access to a bucket.

```go
presignClient := s3.NewPresignClient(client)

	presignResult, err := presignClient.PresignPutObject(context.TODO(), &s3.PutObjectInput{
		Bucket: aws.String(bucketName),
		Key:    aws.String("example.txt"),
	})

	if err != nil {
		panic("Couldn't get presigned URL for PutObject")
	}

	fmt.Printf("Presigned URL For object: %s\n", presignResult.URL)
```

---

# aws-sdk-java

URL: https://developers.cloudflare.com/r2/examples/aws/aws-sdk-java/

import { Render } from "~/components";

<Render file="keys" />
<br />

This example uses version 2 of the [aws-sdk-java](https://github.com/aws/aws-sdk-java-v2/#using-the-sdk) package. You must pass in the R2 configuration credentials when instantiating your `S3` service client:

:::note[Compatibility]
Client version `2.30.0` introduced a modification to the default checksum behavior from the client that is currently incompatible with R2 APIs.

To mitigate, users can use `2.29.52` or add the following to their S3Config:

```java
this.requestChecksumCalculation = "when_required",
this.responseChecksumValidation = "when_required"
```

:::

```java
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.*;
import software.amazon.awssdk.services.s3.S3Configuration;
import java.net.URI;
import java.util.List;

/**
 * Client for interacting with Cloudflare R2 Storage using AWS SDK S3 compatibility
 */
public class CloudflareR2Client {
    private final S3Client s3Client;

    /**
     * Creates a new CloudflareR2Client with the provided configuration
     */
    public CloudflareR2Client(S3Config config) {
        this.s3Client = buildS3Client(config);
    }

    /**
     * Configuration class for R2 credentials and endpoint
     */
    public static class S3Config {
        private final String accountId;
        private final String accessKey;
        private final String secretKey;
        private final String endpoint;

        public S3Config(String accountId, String accessKey, String secretKey) {
            this.accountId = accountId;
            this.accessKey = accessKey;
            this.secretKey = secretKey;
            this.endpoint = String.format("https://%s.r2.cloudflarestorage.com", accountId);
        }

        public String getAccessKey() { return accessKey; }
        public String getSecretKey() { return secretKey; }
        public String getEndpoint() { return endpoint; }
    }

    /**
     * Builds and configures the S3 client with R2-specific settings
     */
    private static S3Client buildS3Client(S3Config config) {
        AwsBasicCredentials credentials = AwsBasicCredentials.create(
            config.getAccessKey(),
            config.getSecretKey()
        );

        S3Configuration serviceConfiguration = S3Configuration.builder()
            .pathStyleAccessEnabled(true)
            .build();

        return S3Client.builder()
            .endpointOverride(URI.create(config.getEndpoint()))
            .credentialsProvider(StaticCredentialsProvider.create(credentials))
            .region(Region.of("auto"))
            .serviceConfiguration(serviceConfiguration)
            .build();
    }

    /**
     * Lists all buckets in the R2 storage
     */
    public List<Bucket> listBuckets() {
        try {
            return s3Client.listBuckets().buckets();
        } catch (S3Exception e) {
            throw new RuntimeException("Failed to list buckets: " + e.getMessage(), e);
        }
    }

    /**
     * Lists all objects in the specified bucket
     */
    public List<S3Object> listObjects(String bucketName) {
        try {
            ListObjectsV2Request request = ListObjectsV2Request.builder()
                .bucket(bucketName)
                .build();

            return s3Client.listObjectsV2(request).contents();
        } catch (S3Exception e) {
            throw new RuntimeException("Failed to list objects in bucket " + bucketName + ": " + e.getMessage(), e);
        }
    }

    public static void main(String[] args) {
        S3Config config = new S3Config(
            "your_account_id",
            "your_access_key",
            "your_secret_key"
        );

        CloudflareR2Client r2Client = new CloudflareR2Client(config);

        // List buckets
        System.out.println("Available buckets:");
        r2Client.listBuckets().forEach(bucket ->
            System.out.println("* " + bucket.name())
        );

        // List objects in a specific bucket
        String bucketName = "demos";
        System.out.println("\nObjects in bucket '" + bucketName + "':");
        r2Client.listObjects(bucketName).forEach(object ->
            System.out.printf("* %s (size: %d bytes, modified: %s)%n",
                object.key(),
                object.size(),
                object.lastModified())
        );
    }
}
```

## Generate presigned URLs

You can also generate presigned links that can be used to temporarily share public write access to a bucket.

```java
// import required packages for presigning
// Rest of the packages are same as above
import software.amazon.awssdk.services.s3.presigner.S3Presigner;
import software.amazon.awssdk.services.s3.presigner.model.PutObjectPresignRequest;
import software.amazon.awssdk.services.s3.presigner.model.PresignedPutObjectRequest;
import java.time.Duration;

public class CloudflareR2Client {
  private final S3Client s3Client;
  private final S3Presigner presigner;

    /**
     * Creates a new CloudflareR2Client with the provided configuration
     */
    public CloudflareR2Client(S3Config config) {
        this.s3Client = buildS3Client(config);
        this.presigner = buildS3Presigner(config);
    }

    /**
     * Builds and configures the S3 presigner with R2-specific settings
     */
    private static S3Presigner buildS3Presigner(S3Config config) {
        AwsBasicCredentials credentials = AwsBasicCredentials.create(
            config.getAccessKey(),
            config.getSecretKey()
        );

        return S3Presigner.builder()
            .endpointOverride(URI.create(config.getEndpoint()))
            .credentialsProvider(StaticCredentialsProvider.create(credentials))
            .region(Region.of("auto"))
            .serviceConfiguration(S3Configuration.builder()
                .pathStyleAccessEnabled(true)
                .build())
            .build();
    }

    public String generatePresignedUploadUrl(String bucketName, String objectKey, Duration expiration) {
        PutObjectPresignRequest presignRequest = PutObjectPresignRequest.builder()
            .signatureDuration(expiration)
            .putObjectRequest(builder -> builder
                .bucket(bucketName)
                .key(objectKey)
                .build())
            .build();

        PresignedPutObjectRequest presignedRequest = presigner.presignPutObject(presignRequest);
        return presignedRequest.url().toString();
    }

    // Rest of the methods remains the same

    public static void main(String[] args) {
      // config the client as before

      // Generate a pre-signed upload URL valid for 15 minutes
        String uploadUrl = r2Client.generatePresignedUploadUrl(
            "demos",
            "README.md",
            Duration.ofMinutes(15)
        );
        System.out.println("Pre-signed Upload URL (valid for 15 minutes):");
        System.out.println(uploadUrl);
    }

}
```

---

# aws-sdk-js-v3

URL: https://developers.cloudflare.com/r2/examples/aws/aws-sdk-js-v3/

import { Render } from "~/components";

<Render file="keys" />
<br />

JavaScript or TypeScript users may continue to use the [`@aws-sdk/client-s3`](https://www.npmjs.com/package/@aws-sdk/client-s3) npm package as per normal. You must pass in the R2 configuration credentials when instantiating your `S3` service client.

:::note
Currently, you cannot use AWS S3-compatible API while developing locally via `wrangler dev`.
:::

:::note[Compatibility]
Client version `3.729.0` introduced a modification to the default checksum behavior from the client that is currently incompatible with R2 APIs.

To mitigate, users can use `3.726.1` or add the following to their S3Client config:

```ts
requestChecksumCalculation: "WHEN_REQUIRED",
responseChecksumValidation: "WHEN_REQUIRED",
```

:::

```ts
import {
	S3Client,
	ListBucketsCommand,
	ListObjectsV2Command,
	GetObjectCommand,
	PutObjectCommand,
} from "@aws-sdk/client-s3";

const S3 = new S3Client({
	region: "auto",
	endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
	credentials: {
		accessKeyId: ACCESS_KEY_ID,
		secretAccessKey: SECRET_ACCESS_KEY,
	},
});

console.log(await S3.send(new ListBucketsCommand({})));
// {
//     '$metadata': {
//     httpStatusCode: 200,
//         requestId: undefined,
//         extendedRequestId: undefined,
//         cfId: undefined,
//         attempts: 1,
//         totalRetryDelay: 0
// },
//     Buckets: [
//     { Name: 'user-uploads', CreationDate: 2022-04-13T21:23:47.102Z },
//     { Name: 'my-bucket-name', CreationDate: 2022-05-07T02:46:49.218Z }
//     ],
//     Owner: {
//         DisplayName: '...',
//         ID: '...'
//     }
// }

console.log(
	await S3.send(new ListObjectsV2Command({ Bucket: "my-bucket-name" })),
);
// {
//     '$metadata': {
//       httpStatusCode: 200,
//       requestId: undefined,
//       extendedRequestId: undefined,
//       cfId: undefined,
//       attempts: 1,
//       totalRetryDelay: 0
//     },
//     CommonPrefixes: undefined,
//     Contents: [
//       {
//         Key: 'cat.png',
//         LastModified: 2022-05-07T02:50:45.616Z,
//         ETag: '"c4da329b38467509049e615c11b0c48a"',
//         ChecksumAlgorithm: undefined,
//         Size: 751832,
//         StorageClass: 'STANDARD',
//         Owner: undefined
//       },
//       {
//         Key: 'todos.txt',
//         LastModified: 2022-05-07T21:37:17.150Z,
//         ETag: '"29d911f495d1ba7cb3a4d7d15e63236a"',
//         ChecksumAlgorithm: undefined,
//         Size: 279,
//         StorageClass: 'STANDARD',
//         Owner: undefined
//       }
//     ],
//     ContinuationToken: undefined,
//     Delimiter: undefined,
//     EncodingType: undefined,
//     IsTruncated: false,
//     KeyCount: 8,
//     MaxKeys: 1000,
//     Name: 'my-bucket-name',
//     NextContinuationToken: undefined,
//     Prefix: undefined,
//     StartAfter: undefined
//   }
```

## Generate presigned URLs

You can also generate presigned links that can be used to share public read or write access to a bucket temporarily.

```ts
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

// Use the expiresIn property to determine how long the presigned link is valid.
console.log(
	await getSignedUrl(
		S3,
		new GetObjectCommand({ Bucket: "my-bucket-name", Key: "dog.png" }),
		{ expiresIn: 3600 },
	),
);
// https://my-bucket-name.<accountid>.r2.cloudflarestorage.com/dog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-Signature=<signature>&X-Amz-SignedHeaders=host&x-id=GetObject

// You can also create links for operations such as putObject to allow temporary write access to a specific key.
console.log(
	await getSignedUrl(
		S3,
		new PutObjectCommand({ Bucket: "my-bucket-name", Key: "dog.png" }),
		{ expiresIn: 3600 },
	),
);
```

You can use the link generated by the `putObject` example to upload to the specified bucket and key, until the presigned link expires.

```sh
curl -X PUT https://my-bucket-name.<accountid>.r2.cloudflarestorage.com/dog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-Signature=<signature>&X-Amz-SignedHeaders=host&x-id=PutObject -F "data=@dog.png"
```

---

# aws-sdk-net

URL: https://developers.cloudflare.com/r2/examples/aws/aws-sdk-net/

import { Render } from "~/components";

<Render file="keys" />
<br />

This example uses version 3 of the [aws-sdk-net](https://www.nuget.org/packages/AWSSDK.S3) package. You must pass in the R2 configuration credentials when instantiating your `S3` service client:

## Client setup

In this example, you will pass credentials explicitly to the `IAmazonS3` initialization. If you wish, use a shared AWS credentials file or the SDK store in-line with other AWS SDKs. Refer to [Configure AWS credentials](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-creds.html) for more details.

:::note[Compatibility]
Client version `3.7.963.0` introduced a modification to the default checksum behavior from the client that is currently incompatible with R2 APIs.

To mitigate, users can use `3.7.962.0` or add the following to their AmazonS3Config:

```csharp
RequestChecksumCalculation = "WHEN_REQUIRED",
ResponseChecksumValidation = "WHEN_REQUIRED"
```

:::

```csharp
private static IAmazonS3 s3Client;

public static void Main(string[] args)
{
	var accessKey = "<ACCESS_KEY>";
	var secretKey = "<SECRET_KEY>";
	var credentials = new BasicAWSCredentials(accessKey, secretKey);
	s3Client = new AmazonS3Client(credentials, new AmazonS3Config
		{
			ServiceURL = "https://<ACCOUNT_ID>.r2.cloudflarestorage.com",
		});
}
```

## List buckets and objects

The [ListBucketsAsync](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/MIS3ListBucketsAsyncListBucketsRequestCancellationToken.html) and [ListObjectsAsync](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/MIS3ListObjectsV2AsyncListObjectsV2RequestCancellationToken.html) methods can be used to list buckets under your account and the contents of those buckets respectively.

```csharp
static async Task ListBuckets()
{
	var response = await s3Client.ListBucketsAsync();

	foreach (var s3Bucket in response.Buckets)
	{
		Console.WriteLine("{0}", s3Bucket.BucketName);
	}
}
// sdk-example
// my-bucket-name
```

```csharp
static async Task ListObjectsV2()
{
	var request = new ListObjectsV2Request
	{
		BucketName = "sdk-example"
	};

	var response = await s3Client.ListObjectsV2Async(request);

	foreach (var s3Object in response.S3Objects)
	{
		Console.WriteLine("{0}", s3Object.Key);
	}
}
// dog.png
// cat.png
```

## Upload and retrieve objects

The [PutObjectAsync](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/MIS3PutObjectAsyncPutObjectRequestCancellationToken.html) and [GetObjectAsync](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/MIS3GetObjectAsyncStringStringCancellationToken.html) methods can be used to upload objects and download objects from an R2 bucket respectively.

:::caution
`DisablePayloadSigning = true` and `DisableDefaultChecksumValidation = true` must be passed as Cloudflare R2 does not currently support the Streaming SigV4 implementation used by AWSSDK.S3.
:::

```csharp
static async Task PutObject()
{
	var request = new PutObjectRequest
	{
		FilePath = @"/path/file.txt",
		BucketName = "sdk-example",
		DisablePayloadSigning = true,
    DisableDefaultChecksumValidation = true
	};

	var response = await s3Client.PutObjectAsync(request);

	Console.WriteLine("ETag: {0}", response.ETag);
}
// ETag: "186a71ee365d9686c3b98b6976e1f196"
```

```csharp
static async Task GetObject()
{
  var bucket = "sdk-example";
  var key = "file.txt"

	var response = await s3Client.GetObjectAsync(bucket, key);

	Console.WriteLine("ETag: {0}", response.ETag);
}
// ETag: "186a71ee365d9686c3b98b6976e1f196"
```

## Generate presigned URLs

The [GetPreSignedURL](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/S3/MIS3GetPreSignedURLGetPreSignedUrlRequest.html) method allows you to sign ahead of time, giving temporary access to a specific operation. In this case, presigning a `PutObject` request for `sdk-example/file.txt`.

```csharp
static string? GeneratePresignedUrl()
{
	AWSConfigsS3.UseSignatureVersion4 = true;
	var presign = new GetPreSignedUrlRequest
	{
		BucketName = "sdk-example",
		Key = "file.txt",
		Verb = HttpVerb.GET,
		Expires = DateTime.Now.AddDays(7),
	};

	var presignedUrl = s3Client.GetPreSignedURL(presign);

	Console.WriteLine(presignedUrl);

	return presignedUrl;
}
// URL: https://<accountid>.r2.cloudflarestorage.com/sdk-example/file.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>
```

---

# aws-sdk-js

URL: https://developers.cloudflare.com/r2/examples/aws/aws-sdk-js/

import { Render } from "~/components";

<Render file="keys" />
<br />

If you are interested in the newer version of the AWS JavaScript SDK visit this [dedicated aws-sdk-js-v3 example page](/r2/examples/aws/aws-sdk-js-v3/).

JavaScript or TypeScript users may continue to use the [`aws-sdk`](https://www.npmjs.com/package/aws-sdk) npm package as per normal. You must pass in the R2 configuration credentials when instantiating your `S3` service client:

```ts
import S3 from "aws-sdk/clients/s3.js";

const s3 = new S3({
	endpoint: `https://${accountid}.r2.cloudflarestorage.com`,
	accessKeyId: `${access_key_id}`,
	secretAccessKey: `${access_key_secret}`,
	signatureVersion: "v4",
});

console.log(await s3.listBuckets().promise());
//=> {
//=>   Buckets: [
//=>     { Name: 'user-uploads', CreationDate: 2022-04-13T21:23:47.102Z },
//=>     { Name: 'my-bucket-name', CreationDate: 2022-05-07T02:46:49.218Z }
//=>   ],
//=>   Owner: {
//=>     DisplayName: '...',
//=>     ID: '...'
//=>   }
//=> }

console.log(await s3.listObjects({ Bucket: "my-bucket-name" }).promise());
//=> {
//=>   IsTruncated: false,
//=>   Name: 'my-bucket-name',
//=>   CommonPrefixes: [],
//=>   MaxKeys: 1000,
//=>   Contents: [
//=>     {
//=>       Key: 'cat.png',
//=>       LastModified: 2022-05-07T02:50:45.616Z,
//=>       ETag: '"c4da329b38467509049e615c11b0c48a"',
//=>       ChecksumAlgorithm: [],
//=>       Size: 751832,
//=>       Owner: [Object]
//=>     },
//=>     {
//=>       Key: 'todos.txt',
//=>       LastModified: 2022-05-07T21:37:17.150Z,
//=>       ETag: '"29d911f495d1ba7cb3a4d7d15e63236a"',
//=>       ChecksumAlgorithm: [],
//=>       Size: 279,
//=>       Owner: [Object]
//=>     }
//=>   ]
//=> }
```

## Generate presigned URLs

You can also generate presigned links that can be used to share public read or write access to a bucket temporarily.

```ts
// Use the expires property to determine how long the presigned link is valid.
console.log(
	await s3.getSignedUrlPromise("getObject", {
		Bucket: "my-bucket-name",
		Key: "dog.png",
		Expires: 3600,
	}),
);
// https://my-bucket-name.<accountid>.r2.cloudflarestorage.com/dog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-Signature=<signature>&X-Amz-SignedHeaders=host

// You can also create links for operations such as putObject to allow temporary write access to a specific key.
console.log(
	await s3.getSignedUrlPromise("putObject", {
		Bucket: "my-bucket-name",
		Key: "dog.png",
		Expires: 3600,
	}),
);
```

You can use the link generated by the `putObject` example to upload to the specified bucket and key, until the presigned link expires.

```sh
curl -X PUT https://my-bucket-name.<accountid>.r2.cloudflarestorage.com/dog.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-Expires=3600&X-Amz-Signature=<signature>&X-Amz-SignedHeaders=host --data-binary @dog.png
```

---

# aws-sdk-php

URL: https://developers.cloudflare.com/r2/examples/aws/aws-sdk-php/

import { Render } from "~/components";

<Render file="keys" />
<br />

This example uses version 3 of the [aws-sdk-php](https://packagist.org/packages/aws/aws-sdk-php) package. You must pass in the R2 configuration credentials when instantiating your `S3` service client:

:::note[Compatibility]
Client version `3.337.0` introduced a modification to the default checksum behavior from the client that is currently incompatible with R2 APIs.

To mitigate, users can use `3.336.15` or add the following to their $options:

```php
'request_checksum_calculation' => 'when_required',
'response_checksum_validation' => 'when_required'
```

:::

```php
<?php
require 'vendor/aws/aws-autoloader.php';

$bucket_name        = "sdk-example";
$account_id         = "<accountid>";
$access_key_id      = "<access_key_id>";
$access_key_secret  = "<access_key_secret>";

$credentials = new Aws\Credentials\Credentials($access_key_id, $access_key_secret);

$options = [
    'region' => 'auto',
    'endpoint' => "https://$account_id.r2.cloudflarestorage.com",
    'version' => 'latest',
    'credentials' => $credentials
];

$s3_client = new Aws\S3\S3Client($options);

$contents = $s3_client->listObjectsV2([
    'Bucket' => $bucket_name
]);

var_dump($contents['Contents']);

// array(1) {
//   [0]=>
//   array(5) {
//     ["Key"]=>
//     string(14) "ferriswasm.png"
//     ["LastModified"]=>
//     object(Aws\Api\DateTimeResult)#187 (3) {
//       ["date"]=>
//       string(26) "2022-05-18 17:20:21.670000"
//       ["timezone_type"]=>
//       int(2)
//       ["timezone"]=>
//       string(1) "Z"
//     }
//     ["ETag"]=>
//     string(34) ""eb2b891dc67b81755d2b726d9110af16""
//     ["Size"]=>
//     string(5) "87671"
//     ["StorageClass"]=>
//     string(8) "STANDARD"
//   }
// }

$buckets = $s3_client->listBuckets();

var_dump($buckets['Buckets']);

// array(1) {
//   [0]=>
//   array(2) {
//     ["Name"]=>
//     string(11) "sdk-example"
//     ["CreationDate"]=>
//     object(Aws\Api\DateTimeResult)#212 (3) {
//       ["date"]=>
//       string(26) "2022-05-18 17:19:59.645000"
//       ["timezone_type"]=>
//       int(2)
//       ["timezone"]=>
//       string(1) "Z"
//     }
//   }
// }

?>
```

## Generate presigned URLs

You can also generate presigned links that can be used to share public read or write access to a bucket temporarily.

```php
$cmd = $s3_client->getCommand('GetObject', [
    'Bucket' => $bucket_name,
    'Key' => 'ferriswasm.png'
]);

// The second parameter allows you to determine how long the presigned link is valid.
$request = $s3_client->createPresignedRequest($cmd, '+1 hour');

print_r((string)$request->getUri())
// https://sdk-example.<accountid>.r2.cloudflarestorage.com/ferriswasm.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=<signature>

// You can also create links for operations such as putObject to allow temporary write access to a specific key.
$cmd = $s3_client->getCommand('PutObject', [
    'Bucket' => $bucket_name,
    'Key' => 'ferriswasm.png'
]);

$request = $s3_client->createPresignedRequest($cmd, '+1 hour');

print_r((string)$request->getUri())
```

You can use the link generated by the `putObject` example to upload to the specified bucket and key, until the presigned link expires.

```sh
curl -X PUT https://sdk-example.<accountid>.r2.cloudflarestorage.com/ferriswasm.png?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>&X-Amz-Date=<timestamp>&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=<signature> --data-binary @ferriswasm.png
```

---

# aws-sdk-ruby

URL: https://developers.cloudflare.com/r2/examples/aws/aws-sdk-ruby/

import { Render } from "~/components";

<Render file="keys" />
<br />

Many Ruby projects also store these credentials in environment variables instead.

:::note[Compatibility]
Client version `1.178.0` introduced a modification to the default checksum behavior from the client that is currently incompatible with R2 APIs.

To mitigate, users can use `1.177.0` or add the following to their s3 client instantiation:

```ruby
request_checksum_calculation: "when_required",
response_checksum_validation: "when_required"
```

:::

Add the following dependency to your `Gemfile`:

```ruby
gem "aws-sdk-s3"
```

Then you can use Ruby to operate on R2 buckets:

```ruby
require "aws-sdk-s3"

@r2 = Aws::S3::Client.new(
  access_key_id: "#{access_key_id}",
  secret_access_key: "#{secret_access_key}",
  endpoint: "https://#{cloudflare_account_id}.r2.cloudflarestorage.com",
  region: "auto",
)

# List all buckets on your account
puts @r2.list_buckets

#=> {
#=>   :buckets => [{
#=>     :name => "your-bucket",
#=>     :creation_date => "…",
#=>   }],
#=>   :owner => {
#=>     :display_name => "…",
#=>     :id => "…"
#=>   }
#=> }

# List the first 20 items in a bucket
puts @r2.list_objects(bucket:"your-bucket", max_keys:20)

#=> {
#=>   :is_truncated => false,
#=>   :marker => nil,
#=>   :next_marker => nil,
#=>   :name => "your-bucket",
#=>   :prefix => nil,
#=>   :delimiter =>nil,
#=>   :max_keys => 20,
#=>   :common_prefixes => [],
#=>   :encoding_type => nil
#=>   :contents => [
#=>     …,
#=>     …,
#=>     …,
#=>   ]
#=> }
```

---

# aws-sdk-rust

URL: https://developers.cloudflare.com/r2/examples/aws/aws-sdk-rust/

import { Render } from "~/components";

<Render file="keys" />
<br />

This example uses the [aws-sdk-s3](https://crates.io/crates/aws-sdk-s3) crate from the [AWS SDK for Rust](https://github.com/awslabs/aws-sdk-rust). You must pass in the R2 configuration credentials when instantiating your `S3` client:

:::note[Compatibility]
Client versions may introduce modifications to the default checksum behavior that could be incompatible with R2 APIs.

If you encounter checksum-related errors, add the following to your config:

```rust
.request_checksum_calculation(RequestChecksumCalculation::WhenRequired)
.response_checksum_validation(ResponseChecksumValidation::WhenRequired)
```

:::

## Basic Usage

```rust
use aws_sdk_s3 as s3;
use aws_smithy_types::date_time::Format::DateTime;

#[tokio::main]
async fn main() -> Result<(), s3::Error> {
    let bucket_name = "sdk-example";
    let account_id = "<accountid>";
    let access_key_id = "<access_key_id>";
    let access_key_secret = "<access_key_secret>";

    // Configure the client
    let config = aws_config::from_env()
        .endpoint_url(format!("https://{}.r2.cloudflarestorage.com", account_id))
        .credentials_provider(aws_sdk_s3::config::Credentials::new(
            access_key_id,
            access_key_secret,
            None, // session token is not used with R2
            None,
            "R2",
        ))
        .region("auto")
        .load()
        .await;

    let client = s3::Client::new(&config);

    // List buckets
    let list_buckets_output = client.list_buckets().send().await?;

    println!("Buckets:");
    for bucket in list_buckets_output.buckets() {
        println!("  - {}: {}",
            bucket.name().unwrap_or_default(),
            bucket.creation_date().map_or_else(
                || "Unknown creation date".to_string(),
                |date| date.fmt(DateTime).unwrap()
            )
        );
    }

    // List objects in a specific bucket
    let list_objects_output = client
        .list_objects_v2()
        .bucket(bucket_name)
        .send()
        .await?;

    println!("\nObjects in {}:", bucket_name);
    for object in list_objects_output.contents() {
        println!("  - {}: {} bytes, last modified: {}",
            object.key().unwrap_or_default(),
            object.size().unwrap_or_default(),
            object.last_modified().map_or_else(
                || "Unknown".to_string(),
                |date| date.fmt(DateTime).unwrap()
            )
        );
    }

    Ok(())
}
```

## Upload Objects

To upload an object to R2:

```rust
use aws_sdk_s3::primitives::ByteStream;
use std::path::Path;

async fn upload_object(
    client: &s3::Client,
    bucket: &str,
    key: &str,
    file_path: &str,
) -> Result<(), s3::Error> {
    let body = ByteStream::from_path(Path::new(file_path)).await.unwrap();

    client
        .put_object()
        .bucket(bucket)
        .key(key)
        .body(body)
        .send()
        .await?;

    println!("Uploaded {} to {}/{}", file_path, bucket, key);
    Ok(())
}
```

## Download Objects

To download an object from R2:

```rust
use std::fs;
use std::io::Write;

async fn download_object(
    client: &s3::Client,
    bucket: &str,
    key: &str,
    output_path: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    let resp = client
        .get_object()
        .bucket(bucket)
        .key(key)
        .send()
        .await?;

    let data = resp.body.collect().await?;
    let bytes = data.into_bytes();

    let mut file = fs::File::create(output_path)?;
    file.write_all(&bytes)?;

    println!("Downloaded {}/{} to {}", bucket, key, output_path);
    Ok(())
}
```

## Generate Presigned URLs

You can also generate presigned links that can be used to temporarily share public read or write access to a bucket.

```rust
use aws_sdk_s3::presigning::PresigningConfig;
use std::time::Duration;

async fn generate_get_presigned_url(
    client: &s3::Client,
    bucket: &str,
    key: &str,
    expires_in: Duration,
) -> Result<String, s3::Error> {
    let presigning_config = PresigningConfig::expires_in(expires_in)?;

    // Generate a presigned URL for GET (download)
    let presigned_get_request = client
        .get_object()
        .bucket(bucket)
        .key(key)
        .presigned(presigning_config)
        .await?;

    Ok(presigned_get_request.uri().to_string())
}

async fn generate_upload_presigned_url(
    client: &s3::Client,
    bucket: &str,
    key: &str,
    expires_in: Duration,
) -> Result<String, s3::Error> {
    let presigning_config = PresigningConfig::expires_in(expires_in)?;

    // Generate a presigned URL for PUT (upload)
    let presigned_put_request = client
        .put_object()
        .bucket(bucket)
        .key(key)
        .presigned(presigning_config)
        .await?;

    Ok(presigned_put_request.uri().to_string())
}
```

You can use these presigned URLs with any HTTP client. For example, to upload a file using the PUT URL:

```bash
curl -X PUT "https://<your-presigned-put-url>" -H "Content-Type: application/octet-stream" --data-binary "@local-file.txt"
```

To download a file using the GET URL:

```bash
curl -X GET "https://<your-presigned-get-url>" -o downloaded-file.txt
```

---

# aws4fetch

URL: https://developers.cloudflare.com/r2/examples/aws/aws4fetch/

import { Render } from "~/components";

<Render file="keys" />
<br />

JavaScript or TypeScript users may continue to use the [`aws4fetch`](https://www.npmjs.com/package/aws4fetch) npm package as per normal. This package uses the `fetch` and `SubtleCrypto` APIs which you will be familiar with when working in browsers or with Cloudflare Workers.

You must pass in the R2 configuration credentials when instantiating your `S3` service client:

```ts
import { AwsClient } from "aws4fetch";

const R2_URL = `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`;

const client = new AwsClient({
	accessKeyId: ACCESS_KEY_ID,
	secretAccessKey: SECRET_ACCESS_KEY,
});

const ListBucketsResult = await client.fetch(R2_URL);
console.log(await ListBucketsResult.text());
// <ListAllMyBucketsResult>
//     <Buckets>
//         <Bucket>
//             <CreationDate>2022-04-13T21:23:47.102Z</CreationDate>
//             <Name>user-uploads</Name>
//         </Bucket>
//         <Bucket>
//             <CreationDate>2022-05-07T02:46:49.218Z</CreationDate>
//             <Name>my-bucket-name</Name>
//         </Bucket>
//     </Buckets>
//     <Owner>
//         <DisplayName>...</DisplayName>
//         <ID>...</ID>
//     </Owner>
// </ListAllMyBucketsResult>

const ListObjectsV2Result = await client.fetch(
	`${R2_URL}/my-bucket-name?list-type=2`,
);
console.log(await ListObjectsV2Result.text());
// <ListBucketResult>
//   <Name>my-bucket-name</Name>
//   <Contents>
//     <Key>cat.png</Key>
//     <Size>751832</Size>
//     <LastModified>2022-05-07T02:50:45.616Z</LastModified>
//     <ETag>"c4da329b38467509049e615c11b0c48a"</ETag>
//     <StorageClass>STANDARD</StorageClass>
//   </Contents>
//   <Contents>
//     <Key>todos.txt</Key>
//     <Size>278</Size>
//     <LastModified> 2022-05-07T21:37:17.150Z</LastModified>
//     <ETag>"29d911f495d1ba7cb3a4d7d15e63236a"</ETag>
//     <StorageClass>STANDARD</StorageClass>
//   </Contents>
//   <IsTruncated>false</IsTruncated>
//   <MaxKeys>1000</MaxKeys>
//   <KeyCount>2</KeyCount>
// </ListBucketResult>
```

## Generate presigned URLs

You can also generate presigned links that can be used to share public read or write access to a bucket temporarily.

```ts
import { AwsClient } from "aws4fetch";

const client = new AwsClient({
	service: "s3",
	region: "auto",
	accessKeyId: ACCESS_KEY_ID,
	secretAccessKey: SECRET_ACCESS_KEY,
});

const R2_URL = `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`;

// Use the `X-Amz-Expires` query param to determine how long the presigned link is valid.
console.log(
	(
		await client.sign(
			new Request(`${R2_URL}/my-bucket-name/dog.png?X-Amz-Expires=${3600}`),
			{
				aws: { signQuery: true },
			},
		)
	).url.toString(),
);
// https://<accountid>.r2.cloudflarestorage.com/my-bucket-name/dog.png?X-Amz-Expires=3600&X-Amz-Date=<timestamp>&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>

// You can also create links for operations such as PutObject to allow temporary write access to a specific key.
console.log(
	(
		await client.sign(
			new Request(`${R2_URL}/my-bucket-name/dog.png?X-Amz-Expires=${3600}`, {
				method: "PUT",
			}),
			{
				aws: { signQuery: true },
			},
		)
	).url.toString(),
);
```

You can use the link generated by the `PutObject` example to upload to the specified bucket and key, until the presigned link expires.

```sh
curl -X PUT "https://<accountid>.r2.cloudflarestorage.com/my-bucket-name/dog.png?X-Amz-Expires=3600&X-Amz-Date=<timestamp>&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<credential>&X-Amz-SignedHeaders=host&X-Amz-Signature=<signature>" -F "data=@dog.png"
```

---

# boto3

URL: https://developers.cloudflare.com/r2/examples/aws/boto3/

import { Render } from "~/components";

<Render file="keys" />
<br />

You must configure [`boto3`](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) to use a preconstructed `endpoint_url` value. This can be done through any `boto3` usage that accepts connection arguments; for example:

:::note[Compatibility]
Client version `1.36.0` introduced a modification to the default checksum behavior from the client that is currently incompatible with R2 APIs.

To mitigate, users can use `1.35.99` or add the following to their s3 resource config:

```python
request_checksum_calculation = 'WHEN_REQUIRED',
response_checksum_validation = 'WHEN_REQUIRED'
```

:::

```python
import boto3

s3 = boto3.resource('s3',
  endpoint_url = 'https://<accountid>.r2.cloudflarestorage.com',
  aws_access_key_id = '<access_key_id>',
  aws_secret_access_key = '<access_key_secret>'
)
```

You may, however, omit the `aws_access_key_id` and `aws_secret_access_key ` arguments and allow `boto3` to rely on the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` [environment variables](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#using-environment-variables) instead.

An example script may look like the following:

```python
import boto3

s3 = boto3.client(
    service_name ="s3",
    endpoint_url = 'https://<accountid>.r2.cloudflarestorage.com',
    aws_access_key_id = '<access_key_id>',
    aws_secret_access_key = '<access_key_secret>',
    region_name="<location>", # Must be one of: wnam, enam, weur, eeur, apac, auto
)

# Get object information
object_information = s3.head_object(Bucket=<R2_BUCKET_NAME>, Key=<FILE_KEY_NAME>)

# Upload/Update single file
s3.upload_fileobj(io.BytesIO(file_content), <R2_BUCKET_NAME>, <FILE_KEY_NAME>)

# Delete object
s3.delete_object(Bucket=<R2_BUCKET_NAME>, Key=<FILE_KEY_NAME>)
```

```sh
python main.py
```

```sh output
Buckets:
 -  user-uploads
 -  my-bucket-name
Objects:
 -  cat.png
 -  todos.txt
```

---

# S3 SDKs

URL: https://developers.cloudflare.com/r2/examples/aws/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Configure custom headers

URL: https://developers.cloudflare.com/r2/examples/aws/custom-header/

Some of R2's [extensions](/r2/api/s3/extensions/) require setting a specific header when using them in the S3 compatible API. For some functionality you may want to set a request header on an entire category of requests. Other times you may want to configure a different header for each individual request. This page contains some examples on how to do so with `boto3` and with `aws-sdk-js-v3`.

## Setting a custom header on all requests

When using certain functionality, like the `cf-create-bucket-if-missing` header, you may want to set a constant header for all `PutObject` requests you're making.

### Set a header for all requests with `boto3`

`Boto3` has an event system which allows you to modify requests. Here we register a function into the event system which adds our header to every `PutObject` request being made.

```python
import boto3

client = boto3.resource('s3',
  endpoint_url = 'https://<accountid>.r2.cloudflarestorage.com',
  aws_access_key_id = '<access_key_id>',
  aws_secret_access_key = '<access_key_secret>'
)

event_system = client.meta.events

# Define function responsible for adding the header
def add_custom_header(params, **kwargs):
    params["headers"]['cf-create-bucket-if-missing'] = 'true'

event_system.register('before-call.s3.PutObject', add_custom_header)

response = client.put_object(Bucket="my_bucket", Key="my_file", Body="file_contents")
print(response)
```

### Set a header for all requests with `aws-sdk-js-v3`

`aws-sdk-js-v3` allows the customization of request behavior through the use of its [middleware stack](https://aws.amazon.com/blogs/developer/middleware-stack-modular-aws-sdk-js/). This example adds a middleware to the client which adds a header to every `PutObject` request being made.

```ts
import {
  PutObjectCommand,
  S3Client,
} from "@aws-sdk/client-s3";

const client = new S3Client({
  region: "auto",
  endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: ACCESS_KEY_ID,
    secretAccessKey: SECRET_ACCESS_KEY,
  },
});

client.middlewareStack.add(
  (next, context) => async (args) => {
      const r = args.request as RequestInit
      r.headers["cf-create-bucket-if-missing"] = "true";

      return await next(args)
    },
  { step: 'build', name: 'customHeaders' },
)

const command = new PutObjectCommand({
  Bucket: "my_bucket",
  Key: "my_key",
  Body: "my_data"
});

const response = await client.send(command);

console.log(response);
```

## Set a different header on each request

Certain extensions that R2 has provided in the S3 compatible api may require setting a different header on each request. For example, you may want to only want to overwrite an object if its etag matches a certain expected value. This value will likely be different for each object that is being overwritten, which requires the `If-Match` header to be different with each request you make. This section shows examples of how to accomplish that.

### Set a header per request in `boto3`

To enable us to pass custom headers as an extra argument into the call to `client.put_object()` we need to register 2 functions into `boto3`'s event system. This is necessary because `boto3` performs a parameter validation step which rejects extra method arguments. Since this parameter validation occurs before we can set headers on the request, we first need to move the custom argument into the request context before the parameter validation happens. In a subsequent step we can now actually set the headers based on the information we put in the request context.

```python
import boto3

client = boto3.resource('s3',
  endpoint_url = 'https://<accountid>.r2.cloudflarestorage.com',
  aws_access_key_id = '<access_key_id>',
  aws_secret_access_key = '<access_key_secret>'
)

event_system = client.meta.events

# Moves the custom headers from the parameters to the request context
def process_custom_arguments(params, context, **kwargs):
    if (custom_headers := params.pop("custom_headers", None)):
        context["custom_headers"] = custom_headers

# Here we extract the headers from the request context and actually set them
def add_custom_headers(params, context, **kwargs):
    if (custom_headers := context.get("custom_headers")):
        params["headers"].update(custom_headers)

event_system.register('before-parameter-build.s3.PutObject', process_custom_arguments)
event_system.register('before-call.s3.PutObject', add_custom_headers)

custom_headers = {'If-Match' : '"29d911f495d1ba7cb3a4d7d15e63236a"'}

# Note that boto3 will throw an exception if the precondition failed. Catch this exception if necessary
response = client.put_object(Bucket="my_bucket", Key="my_key", Body="file_contents", custom_headers=custom_headers)
print(response)
```

### Set a header per request in `aws-sdk-js-v3`

Here we again configure the header we would like to set by creating a middleware, but this time we add the middleware to the request itself instead of to the whole client.

```ts
import {
  PutObjectCommand,
  S3Client,
} from "@aws-sdk/client-s3";

const client = new S3Client({
  region: "auto",
  endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: ACCESS_KEY_ID,
    secretAccessKey: SECRET_ACCESS_KEY,
  },
});

const command = new PutObjectCommand({
  Bucket: "my_bucket",
  Key: "my_key",
  Body: "my_data"
});

const headers = { 'If-Match': '"29d911f495d1ba7cb3a4d7d15e63236a"' }
command.middlewareStack.add(
  (next) =>
    (args) => {
      const r = args.request as RequestInit

      Object.entries(headers).forEach(
        ([k, v]: [key: string, value: string]): void => {
          r.headers[k] = v
        },
      )

      return next(args)
    },
  { step: 'build', name: 'customHeaders' },
)
const response = await client.send(command);

console.log(response);
```

---

# Snowflake

URL: https://developers.cloudflare.com/r2/reference/partners/snowflake-regions/

import { Render } from "~/components";

This page details which R2 location or jurisdiction is recommended based on your Snowflake region.

You have the following inputs to control the physical location where objects in your R2 buckets are stored (for more information refer to [data location](/r2/reference/data-location/)):

- [**Location hints**](/r2/reference/data-location/#location-hints): Specify a geophrical area (for example, Asia-Pacific or Western Europe). R2 makes a best effort to place your bucket in or near that location to optimize performance. You can confirm bucket placement after creation by navigating to the **Settings** tab of your bucket and referring to the **Bucket details** section.
- [**Jurisdictions**](/r2/reference/data-location/#jurisdictional-restrictions): Enforce that data is both stored and processed within a specific jurisdiction (for example, the EU or FedRAMP environment). Use jurisdictions when you need to ensure data is stored and processed within a jurisdiction to meet data residency requirements, including local regulations such as the [GDPR](https://gdpr-info.eu/) or [FedRAMP](https://blog.cloudflare.com/cloudflare-achieves-fedramp-authorization/).

## North and South America (Commercial)

| Snowflake region name        | Cloud | Region ID        | Recommended R2 location |
| ---------------------------- | ----- | ---------------- | ----------------------- |
| Canada (Central)             | AWS   | `ca-central-1`   | Location hint: `enam`   |
| South America (Sao Paulo)    | AWS   | `sa-east-1`      | Location hint: `enam`   |
| US West (Oregon)             | AWS   | `us-west-2`      | Location hint: `wnam`   |
| US East (Ohio)               | AWS   | `us-east-2`      | Location hint: `enam`   |
| US East (N. Virginia)        | AWS   | `us-east-1`      | Location hint: `enam`   |
| US Central1 (Iowa)           | GCP   | `us-central1`    | Location hint: `enam`   |
| US East4 (N. Virginia)       | GCP   | `us-east4`       | Location hint: `enam`   |
| Canada Central (Toronto)     | Azure | `canadacentral`  | Location hint: `enam`   |
| Central US (Iowa)            | Azure | `centralus`      | Location hint: `enam`   |
| East US 2 (Virginia)         | Azure | `eastus2`        | Location hint: `enam`   |
| Mexico Central (Mexico City) | Azure | `mexicocentral`  | Location hint: `wnam`   |
| South Central US (Texas)     | Azure | `southcentralus` | Location hint: `enam`   |
| West US 2 (Washington)       | Azure | `westus2`        | Location hint: `wnam`   |

## U.S. Government

| Snowflake region name | Cloud | Region ID       | Recommended R2 location |
| --------------------- | ----- | --------------- | ----------------------- |
| US Gov East 1         | AWS   | `us-gov-east-1` | Jurisdiction: `fedramp` |
| US Gov West 1         | AWS   | `us-gov-west-1` | Jurisdiction: `fedramp` |
| US Gov Virginia       | Azure | `usgovvirginia` | Jurisdiction: `fedramp` |

:::note

Cloudflare Enterprise customers may contact their account team or [Cloudflare Support](/support/contacting-cloudflare-support/) to get access to the FedRAMP jurisdiction.
:::

## Europe and Middle East

| Snowflake region name         | Cloud | Region ID          | Recommended R2 location                   |
| ----------------------------- | ----- | ------------------ | ----------------------------------------- |
| EU (Frankfurt)                | AWS   | `eu-central-1`     | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| EU (Zurich)                   | AWS   | `eu-central-2`     | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| EU (Stockholm)                | AWS   | `eu-north-1`       | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| EU (Ireland)                  | AWS   | `eu-west-1`        | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| Europe (London)               | AWS   | `eu-west-2`        | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| EU (Paris)                    | AWS   | `eu-west-3`        | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| Middle East Central2 (Dammam) | GCP   | `me-central2`      | Location hint: `weur`/`eeur`              |
| Europe West2 (London)         | GCP   | `europe-west-2`    | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| Europe West3 (Frankfurt)      | GCP   | `europe-west-3`    | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| Europe West4 (Netherlands)    | GCP   | `europe-west-4`    | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| North Europe (Ireland)        | Azure | `northeurope`      | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| Switzerland North (Zurich)    | Azure | `switzerlandnorth` | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| West Europe (Netherlands)     | Azure | `westeurope`       | Jurisdiction: `eu` or hint: `weur`/`eeur` |
| UAE North (Dubai)             | Azure | `uaenorth`         | Location hint: `weur`/`eeur`              |
| UK South (London)             | Azure | `uksouth`          | Jurisdiction: `eu` or hint: `weur`/`eeur` |

## Asia Pacific and China

| Snowflake region name            | Cloud | Region ID        | Recommended R2 location |
| -------------------------------- | ----- | ---------------- | ----------------------- |
| Asia Pacific (Tokyo)             | AWS   | `ap-northeast-1` | Location hint: `apac`   |
| Asia Pacific (Seoul)             | AWS   | `ap-northeast-2` | Location hint: `apac`   |
| Asia Pacific (Osaka)             | AWS   | `ap-northeast-3` | Location hint: `apac`   |
| Asia Pacific (Mumbai)            | AWS   | `ap-south-1`     | Location hint: `apac`   |
| Asia Pacific (Singapore)         | AWS   | `ap-southeast-1` | Location hint: `apac`   |
| Asia Pacific (Sydney)            | AWS   | `ap-southeast-2` | Location hint: `oc`     |
| Asia Pacific (Jakarta)           | AWS   | `ap-southeast-3` | Location hint: `apac`   |
| China (Ningxia)                  | AWS   | `cn-northwest-1` | Location hint: `apac`   |
| Australia East (New South Wales) | Azure | `australiaeast`  | Location hint: `oc`     |
| Central India (Pune)             | Azure | `centralindia`   | Location hint: `apac`   |
| Japan East (Tokyo)               | Azure | `japaneast`      | Location hint: `apac`   |
| Southeast Asia (Singapore)       | Azure | `southeastasia`  | Location hint: `apac`   |

---

# First Live Stream with OBS

URL: https://developers.cloudflare.com/stream/examples/obs-from-scratch/

## Overview

Stream empowers customers and their end-users to broadcast a live stream quickly and at scale. The player can be embedded in sites and applications easily, but not everyone knows how to make a live stream because it happens in a separate application. This walkthrough will demonstrate how to start your first live stream using OBS Studio, a free live streaming application used by thousands of Stream customers. There are five required steps; you should be able to complete this walkthrough in less than 15 minutes.

### Before you start

To go live on Stream, you will need any of the following:

- A paid Stream subscription
- A Pro or Business zone plan — these include 100 minutes of video storage and 10,000 minutes of video delivery
- An enterprise contract with Stream enabled

Also, you will also need to be able to install the application on your computer.

If your computer and network connection are good enough for video calling, you should at least be able to stream something basic.

## 1. Set up a [Live Input](/stream/stream-live/start-stream-live/)

You need a Live Input on Stream. Follow the [Start a live stream](/stream/stream-live/start-stream-live/) guide. Make note of three things:

- **RTMPS URL**, which will most likely be `rtmps://live.cloudflare.com:443/live/`
- **RTMPS Key**, which is specific to the new live input
- Whether you selected the beta "Low-Latency HLS Support" or not. For your first test, leave this _disabled._ ([What is that?](https://blog.cloudflare.com/cloudflare-stream-low-latency-hls-open-beta))

## 2. Install OBS

Download [OBS Studio](https://obsproject.com/) for Windows, macOS, or Linux. The OBS Knowledge Base includes several [installation guides](https://obsproject.com/kb/category/1), but installer defaults are generally acceptable.

## 3. First Launch OBS Configuration

When you first launch OBS, the Auto-Configuration Wizard will ask a few questions and offer recommended settings. See their [Quick Start Guide](https://obsproject.com/kb/quick-start-guide) for more details. For a quick start with Stream, use these settings:

- **Step 1: "Usage Information"**
  - Select "Optimize for streaming, recording is secondary."
- **Step 2: "Video Settings"**
  - **Base (Canvas) Resolution:** 1920x1080
  - **FPS:** "Either 60 or 30, but prefer 60 when possible"
- **Step 3: "Stream Information"**
  - **Service:** "Custom"
  - For **Server**, enter the RTMPS URL from Stream
  - For **Stream Key**, enter the RTMPS Key from Stream
  - If available, select both **"Prefer hardware encoding"** and **"Estimate bitrate with a bandwidth test."**

## 4. Set up a Stage

Add some test content to the stage in OBS. In this example, I have added a background image, a web browser (to show [time.is](https://time.is)), and an overlay of my webcam:

![OBS Stage](~/assets/images/stream/examples/obs-from-scratch/obs-stage.png)

OBS offers many different audio, video, still, and generated sources to set up your broadcast content. Use the "+" button in the "Sources" panel to add content. Check out the [OBS Sources Guide](https://obsproject.com/kb/sources-guide) for more information. For an initial test, use a source that will show some motion: try a webcam ("Video Capture Device"), a screen share ("Display Capture"), or a browser with a site that has moving content.

## 5. Go Live

Click the "Start Streaming" button on the bottom right panel under "Controls" to start a stream with default settings.

Return to the Live Input page on Stream Dash. Under "Input Status," you should see "🟢 Connected" and some connection metrics. Further down the page, you will see a test player and an embed code. For more ways to watch and embed your Live Stream, see [Watch a live stream](/stream/stream-live/watch-live-stream/).

## 6. (Optional) Optimize Settings

Tweaking some settings in OBS can improve quality, glass-to-glass latency, or stability of the stream playback. This is particularly important if you selected the "Low-Latency HLS" beta option.

Return to OBS, click "Stop Streaming." Then click "Settings" and open the "Output" section:

![OBS Output Settings - Simple Mode](~/assets/images/stream/examples/obs-from-scratch/obs-output-settings-1.png)

- Change **Output Mode** to "Advanced"

![OBS Output Settings - Advanced Mode](~/assets/images/stream/examples/obs-from-scratch/obs-output-settings-2.png)

_Your available options in the "Video Encoder" menu, as well as the resulting "Encoder Settings," may look slightly different than these because the options vary by hardware._

- **Video Encoder:** may have several options. Start with the default selected, which was "x264" in this example. Other options to try, which will leverage improved hardware acceleration when possible, include "QuickSync H.264" or "NVIDIA NVENC." See OBS's guide to Hardware Encoding for more information. H.264 is the required output codec.
- **Rate Control:** confirm "CBR" (constant bitrate) is selected.
- **Bitrate:** depending on the content of your stream, a bitrate between 3000 Kbps and 8000 Kbps should be sufficient. Lower bitrate is more tolerant to network congestion and is suitable for content with less detail or less motion (speaker, slides, etc.) where a higher bitrate requires a more stable network connection and is best for content with lots of motion or details (events, moving cameras, video games, screen share, higher framerates).
- **Keyframe Interval**, sometimes referred to as _GOP Size_:
  - If you did _not_ select Low-Latency HLS Beta, set this to 4 seconds. Raise it to 8 if your stream has stuttering or freezing.
  - If you _did_ select the Low-Latency HLS Beta, set this to 2 seconds. Raise it to 4 if your stream has stuttering or freezing. Lower it to 1 if your stream has smooth playback.
  - In general, higher keyframe intervals make more efficient use of bandwidth and CPU for encoding, at the expense of higher glass-to-glass latency. Lower keyframe intervals reduce latency, but are more resource intensive and less tolerant to network disruptions and congestion.
- **Profile** and **Tuning** can be left at their default settings.
- **B Frames** (available only for some encoders) should be set to 0 for LL-HLS Beta streams.

For more information about these settings and our recommendations for Live, see the "[Recommendations, requirements and limitations](/stream/stream-live/start-stream-live/#recommendations-requirements-and-limitations)" section of [Start a live stream](/stream/stream-live/start-stream-live/).

## What is Next

With these steps, you have created a Live Input on Stream, broadcast a test from OBS, and you saw it played back in via the Stream built-in player in Dash. Up next, consider trying:

- Embedding your live stream into a website
- Find and replay the recording of your live stream

---

# Use the Stream Player

URL: https://developers.cloudflare.com/stream/viewing-videos/using-the-stream-player/

import { InlineBadge } from "~/components"

Cloudflare provides a customizable web player that can play both on-demand and live video, and requires zero additional engineering work.

<figure data-type="stream">
  <div class="AspectRatio" style="--aspect-ratio: calc(16 / 9)">
    <iframe
      class="AspectRatio--content"
      src="https://iframe.videodelivery.net/5d5bc37ffcf54c9b82e996823bffbb81?mute=true"
      style="border: none"
      frame-border="0"
      allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
      allow-full-screen
    ></iframe>
  </div>
</figure>

To add the Stream Player to a web page, you can either:

* Generate an embed code in the [Stream Dashboard](https://dash.cloudflare.com/?to=/:account/stream) for a specific video or live input.
* Use the code example below, replacing `<VIDEO_UID>` with the video UID (or [signed token](/stream/viewing-videos/securing-your-stream/)) and `<CODE>` with the your unique customer code, which can be found in the [Stream Dashboard](https://dash.cloudflare.com/?to=/:account/stream).

```html
<iframe
  src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_UID>/iframe"
  style="border: none"
  height="720"
  width="1280"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen="true"
></iframe>
```

Stream player is also available as a [React](https://www.npmjs.com/package/@cloudflare/stream-react) or [Angular](https://www.npmjs.com/package/@cloudflare/stream-angular) component.

## Player Size

### Fixed Dimensions

Changing the `height` and `width` attributes on the `iframe` will change the pixel value dimensions of the iframe displayed on the host page.

```html
<iframe
  src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_UID>/iframe"
  style="border: none"
  height="400"
  width="400"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen="true"
></iframe>
```

### Responsive

To make an iframe responsive, it needs styles to enforce an aspect ratio by setting the `iframe` to `position: absolute;` and having it fill a container that uses a calculated `padding-top` percentage.

```html
<!-- padding-top calculation is height / width (assuming 16:9 aspect ratio) -->
<div style="position: relative; padding-top: 56.25%">
  <iframe
    src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_UID>/iframe"
    style="border: none; position: absolute; top: 0; height: 100%; width: 100%"
    allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
    allowfullscreen="true"
  ></iframe>
</div>
```

## Basic Options

Player options are configured with querystring parameters in the iframe's `src` attribute. For example:

`https://customer-<CODE>.cloudflarestream.com/<VIDEO_UID>/iframe?autoplay=true&muted=true`

* `autoplay` default: `false`

  * If the autoplay flag is included as a querystring parameter, the player will attempt to autoplay the video. If you don't want the video to autoplay, don't include the autoplay flag at all (instead of setting it to `autoplay=false`.) Note that mobile browsers generally do not support this attribute, the user must tap the screen to begin video playback. Please consider mobile users or users with Internet usage limits as some users don't have unlimited Internet access before using this attribute.

    :::caution

    Some browsers now prevent videos with audio from playing automatically. You may set `muted` to `true` to allow your videos to autoplay. For more information, refer to [New `<video>` Policies for iOS](https://webkit.org/blog/6784/new-video-policies-for-ios/).
   
    :::

* `controls` default: `true`

  * Shows video controls such as buttons for play/pause, volume controls.

* `defaultTextTrack`

  * Will initialize the player with the specified language code's text track enabled. The value should be the BCP-47 language code that was used to [upload the text track](/stream/edit-videos/adding-captions/). If the specified language code has no captions available, the player will behave as though no language code had been provided.

    :::caution

    This will *only* work once during initialization. Beyond that point the user has full control over their text track settings.

    :::

* `letterboxColor`

  * Any valid [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) provided will be applied to the letterboxing/pillarboxing of the player's UI. This can be set to `transparent` to avoid letterboxing/pillarboxing when not in fullscreen mode.

    :::note


    **Note:** Like all query string parameters, this value *must* be URI encoded. For example, the color value `hsl(120 80% 95%)` can be encoded using JavaScript's `encodeURIComponent()` function to `hsl(120%2080%25%2095%25)`.

    :::

* `loop` default: `false`

  * If enabled the player will automatically seek back to the start upon reaching the end of the video.

* `muted` default: `false`

  * If set, the audio will be initially silenced.

* `preload` default: `none`

  * This enumerated option is intended to provide a hint to the browser about what the author thinks will lead to the best user experience. You may specify the value `preload="auto"` to preload the beginning of the video. Not including the option or using `preload="metadata"` will just load the metadata needed to start video playback when requested.

    :::note

    The `<video>` element does not force the browser to follow the value of this option; it is a mere hint. Even though the `preload="none"` option is a valid HTML5 option, Stream player will always load some metadata to initialize the player. The amount of data loaded in this case is negligible.
   
    :::

* `poster` defaults to the first frame of the video

  * A URL for an image to be shown before the video is started or while the video is downloading. If this attribute isn't specified, a thumbnail image of the video is shown.

    :::note

    **Note:** Like all query string parameters, this value *must* be URI encoded. For example, the thumbnail at `https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/thumbnails/thumbnail.jpg?time=1s&height=270` can be encoded using JavaScript's `encodeURIComponent()` function to `https%3A%2F%2Fcustomer-f33zs165nr7gyfy4.cloudflarestream.com%2F6b9e68b07dfee8cc2d116e4c51d6a957%2Fthumbnails%2Fthumbnail.jpg%3Ftime%3D1s%26height%3D600`.

    :::

* `primaryColor`

  * Any valid [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) provided will be applied to certain elements of the player's UI.

    :::note


    **Note:** Like all query string parameters, this value *must* be URI encoded. For example, the color value `hsl(120 80% 95%)` can be encoded using JavaScript's `encodeURIComponent()` function to `hsl(120%2080%25%2095%25)`.

    :::

* `src`

  * The video id from the video you've uploaded to Cloudflare Stream should be included here.

* `startTime`

  * A timestamp that specifies the time when playback begins. If a plain number is used such as `?startTime=123`, it will be interpreted as `123` seconds. More human readable timestamps can also be used, such as `?startTime=1h12m27s` for `1 hour, 12 minutes, and 27 seconds`.

* `ad-url`

  * The Stream Player supports VAST Tags to insert ads such as prerolls. If you have a VAST tag URI, you can pass it to the Stream Player by setting the `ad-url` parameter. The URI must be encoded using a function like JavaScript's `encodeURIComponent()`.



## Debug Info

The Stream player Debug menu can be shown and hidden using the key combination `Shift-D` while the video is playing.

## Live stream recording playback

After a live stream ends, a recording is automatically generated and available within 60 seconds. To ensure successful video viewing and playback, keep the following in mind:

* If a live stream ends while a viewer is watching, viewers should wait 60 seconds and then reload the player to view the recording of the live stream.
* After a live stream ends, you can check the status of the recording via the API. When the video state is `ready`, you can use one of the manifest URLs to stream the recording.

While the recording of the live stream is generating, the video may report as `not-found` or `not-started`.

## Low-Latency HLS playback <InlineBadge preset="beta" />

If a Live Inputs is enabled for the Low-Latency HLS beta, the Stream player will automatically play in low-latency mode if possible. Refer to [Start a Live Stream](/stream/stream-live/start-stream-live/#use-the-api) to enable this option.

---

# Stream Player API

URL: https://developers.cloudflare.com/stream/viewing-videos/using-the-stream-player/using-the-player-api/

For further control and customization, we provide an additional JavaScript SDK that you can use to control video playback and listen for media events.

To use this SDK, add an additional `<script>` tag to your website:

```html
<!-- You can use styles and CSS on this iframe element where the video player will appear -->
<iframe
  src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_UID>/iframe"
  style="border: none"
  height="720"
  width="1280"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen="true"
  id="stream-player"
></iframe>

<script src="https://embed.cloudflarestream.com/embed/sdk.latest.js"></script>

<!-- Your JavaScript code below-->
<script>
  const player = Stream(document.getElementById('stream-player'));
  player.addEventListener('play', () => {
    console.log('playing!');
  });
  player.play().catch(() => {
    console.log('playback failed, muting to try again');
    player.muted = true;
    player.play();
  });
</script>
```

## Methods



* `play()` Promise

  * Start video playback.

* `pause()` null

  * Pause video playback.



## Properties



* `autoplay` boolean

  * Sets or returns whether the autoplay attribute was set, allowing video playback to start upon load.

:::note


Some browsers prevent videos with audio from playing automatically. You may add the `mute` attribute to allow your videos to autoplay. For more information, review the [iOS video policies](https://webkit.org/blog/6784/new-video-policies-for-ios/).


:::

* `buffered` TimeRanges readonly

  * An object conforming to the TimeRanges interface. This object is normalized, which means that ranges are ordered, don't overlap, aren't empty, and don't touch (adjacent ranges are folded into one bigger range).

* `controls` boolean

  * Sets or returns whether the video should display controls (like play/pause etc.)

* `currentTime` integer

  * Returns the current playback time in seconds. Setting this value seeks the video to a new time.

* `defaultTextTrack`

  * Will initialize the player with the specified language code's text track enabled. The value should be the BCP-47 language code that was used to [upload the text track](/stream/edit-videos/adding-captions/). If the specified language code has no captions available, the player will behave as though no language code had been provided.

:::note


This will *only* work once during initialization. Beyond that point the user has full control over their text track settings.


:::

* `duration` integer readonly

  * Returns the duration of the video in seconds.

* `ended` boolean readonly

  * Returns whether the video has ended.

* `letterboxColor` string

  * Any valid [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) provided will be applied to the letterboxing/pillarboxing of the player's UI. This can be set to `transparent` to avoid letterboxing/pillarboxing when not in fullscreen mode.

* `loop` boolean

  * Sets or returns whether the video should start over when it reaches the end

* `muted` boolean

  * Sets or returns whether the audio should be played with the video

* `paused` boolean readonly

  * Returns whether the video is paused

* `played` TimeRanges readonly

  * An object conforming to the TimeRanges interface. This object is normalized, which means that ranges are ordered, don't overlap, aren't empty, and don't touch (adjacent ranges are folded into one bigger range).

* `preload` boolean

  * Sets or returns whether the video should be preloaded upon element load.

:::note


The `<video>` element does not force the browser to follow the value of this attribute; it is a mere hint. Even though the `preload="none"` option is a valid HTML5 attribute, Stream player will always load some metadata to initialize the player. The amount of data loaded in this case is negligible.


:::

* `primaryColor` string

  * Any valid [CSS color value](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value) provided will be applied to certain elements of the player's UI.

* `volume` float

  * Sets or returns volume from 0.0 (silent) to 1.0 (maximum value)



## Events

### Standard Video Element Events

We support most of the [standardized media element events](https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Media_events).



* `abort`

  * Sent when playback is aborted; for example, if the media is playing and is restarted from the beginning, this event is sent.

* `canplay`

  * Sent when enough data is available that the media can be played, at least for a couple of frames.

* `canplaythrough`

  * Sent when the entire media can be played without interruption, assuming the download rate remains at least at the current level. It will also be fired when playback is toggled between paused and playing. Note: Manually setting the currentTime will eventually fire a canplaythrough event in firefox. Other browsers might not fire this event.

* `durationchange`

  * The metadata has loaded or changed, indicating a change in duration of the media. This is sent, for example, when the media has loaded enough that the duration is known.

* `ended`

  * Sent when playback completes.

* `error`

  * Sent when an error occurs. (e.g. the video has not finished encoding yet, or the video fails to load due to an incorrect signed URL)

* `loadeddata`

  * The first frame of the media has finished loading.

* `loadedmetadata`

  * The media's metadata has finished loading; all attributes now contain as much useful information as they're going to.

* `loadstart`

  * Sent when loading of the media begins.

* `pause`

  * Sent when the playback state is changed to paused (paused property is true).

* `play`

  * Sent when the playback state is no longer paused, as a result of the play method, or the autoplay attribute.

* `playing`

  * Sent when the media has enough data to start playing, after the play event, but also when recovering from being stalled, when looping media restarts, and after seeked, if it was playing before seeking.

* `progress`

  * Sent periodically to inform interested parties of progress downloading the media. Information about the current amount of the media that has been downloaded is available in the media element's buffered attribute.

* `ratechange`

  * Sent when the playback speed changes.

* `seeked`

  * Sent when a seek operation completes.

* `seeking`

  * Sent when a seek operation begins.

* `stalled`

  * Sent when the user agent is trying to fetch media data, but data is unexpectedly not forthcoming.

* `suspend`

  * Sent when loading of the media is suspended; this may happen either because the download has completed or because it has been paused for any other reason.

* `timeupdate`

  * The time indicated by the element's currentTime attribute has changed.

* `volumechange`

  * Sent when the audio volume changes (both when the volume is set and when the muted attribute is changed).

* `waiting`

  * Sent when the requested operation (such as playback) is delayed pending the completion of another operation (such as a seek).



### Non-standard Events

Non-standard events are prefixed with `stream-` to distinguish them from standard events.



* `stream-adstart`

  * Fires when `ad-url` attribute is present and the ad begins playback

* `stream-adend`

  * Fires when `ad-url` attribute is present and the ad finishes playback

* `stream-adtimeout`

  * Fires when `ad-url` attribute is present and the ad took too long to load.

---

# Android

URL: https://developers.cloudflare.com/stream/viewing-videos/using-own-player/android/

import { Render } from "~/components"

You can stream both on-demand and live video to native Android apps using [ExoPlayer](https://exoplayer.dev/).

<Render file="prereqs" />

## Example Apps

* [Android](/stream/examples/android/)

## Using ExoPlayer

Play a video from Cloudflare Stream using ExoPlayer:

<Render file="android_playback_code_snippet" />

---

# Use your own player

URL: https://developers.cloudflare.com/stream/viewing-videos/using-own-player/

import { Render, Badge } from "~/components"

Cloudflare Stream is compatible with all video players that support HLS and DASH, which are standard formats for streaming media with broad support across all web browsers, mobile operating systems and media streaming devices.

Platform-specific guides:

* [Web](/stream/viewing-videos/using-own-player/web/)
* [iOS (AVPlayer)](/stream/viewing-videos/using-own-player/ios/)
* [Android (ExoPlayer)](/stream/viewing-videos/using-own-player/android/)

## Fetch HLS and Dash manifests

### URL

Each video and live stream has its own unique HLS and DASH manifest. You can access the manifest by replacing `<UID>` with the UID of your video or live input, and replacing `<CODE>` with your unique customer code, in the URLs below:

```txt title="HLS"
https://customer-<CODE>.cloudflarestream.com/<UID>/manifest/video.m3u8
```

```txt title="DASH"
https://customer-<CODE>.cloudflarestream.com/<UID>/manifest/video.mpd
```

#### LL-HLS playback <Badge text="Beta" variant="caution" size="small" />

If a Live Inputs is enabled for the Low-Latency HLS beta, add the query string `?protocol=llhls` to the HLS manifest URL to test the low latency manifest in a custom player. Refer to [Start a Live Stream](/stream/stream-live/start-stream-live/#use-the-api) to enable this option.

```txt title="HLS"
https://customer-<CODE>.cloudflarestream.com/<UID>/manifest/video.m3u8?protocol=llhls
```

### Dashboard

1. Log into the [Stream Dashboard](https://dash.cloudflare.com/?to=/:account/stream).
2. From the list of videos, locate your video and select it.
3. From the **Settings** tab, locate the **HLS Manifest URL** and **Dash Manifest URL**.
4. Select **Click to copy** under the option you want to use.

### API

Refer to the [Stream video details API documentation](/api/resources/stream/methods/get/) to learn how to fetch the manifest URLs using the Cloudflare API.

## Customize manifests by specifying available client bandwidth

Each HLS and DASH manifest provides multiple resolutions of your video or live stream. Your player contains adaptive bitrate logic to estimate the viewer's available bandwidth, and select the optimal resolution to play. Each player has different logic that makes this decision, and most have configuration options to allow you to customize or override either bandwidth or resolution.

If your player lacks such configuration options or you need to override them, you can add the `clientBandwidthHint` query param to the request to fetch the manifest file. This should be used only as a last resort — we recommend first using customization options provided by your player. Remember that while you may be developing your website or app on a fast Internet connection, and be tempted to use this setting to force high quality playback, many of your viewers are likely connecting over slower mobile networks.



* `clientBandwidthHint` float
  * Return only the video representation closest to the provided bandwidth value (in Mbps). This can be used to enforce a specific quality level. If you specify a value that would cause an invalid or empty manifest to be served, the hint is ignored.



Refer to the example below to display only the video representation with a bitrate closest to 1.8 Mbps.

```txt title="Example"
https://customer-f33zs165nr7gyfy4.cloudflarestream.com/6b9e68b07dfee8cc2d116e4c51d6a957/manifest/video.m3u8?clientBandwidthHint=1.8
```

## Play live video in native apps with less than 1 second latency

If you need ultra low latency, and your users view live video in native apps, you can stream live video with [**glass-to-glass latency of less than 1 second**](https://blog.cloudflare.com/magic-hdmi-cable/), by using SRT or RTMPS for playback.

![Diagram showing SRT and RTMPS playback via the Cloudflare Network](~/assets/images/stream/stream-rtmps-srt-playback-magic-hdmi-cable.png)

SRT and RTMPS playback is built into [ffmpeg](https://ffmpeg.org/). You will need to integrate ffmpeg with your own video player —  neither [AVPlayer (iOS)](/stream/viewing-videos/using-own-player/ios/) nor [ExoPlayer (Android)](/stream/viewing-videos/using-own-player/android/) natively support SRT or RTMPS playback.

<Render file="srt-supported-modes" />

We recommend using [ffmpeg-kit](https://github.com/arthenica/ffmpeg-kit) as a cross-platform wrapper for ffmpeg.

### Examples

* [RTMPS Playback with ffplay](/stream/examples/rtmps_playback/)
* [SRT playback with ffplay](/stream/examples/srt_playback/)

---

# iOS

URL: https://developers.cloudflare.com/stream/viewing-videos/using-own-player/ios/

import { Render } from "~/components"

You can stream both on-demand and live video to native iOS, tvOS and macOS apps using [AVPlayer](https://developer.apple.com/documentation/avfoundation/avplayer).

<Render file="prereqs" />

## Example Apps

* [iOS](/stream/examples/ios/)

## Using AVPlayer

Play a video from Cloudflare Stream using AVPlayer:

<Render file="ios_playback_code_snippet" />

---

# Web

URL: https://developers.cloudflare.com/stream/viewing-videos/using-own-player/web/

import { Render } from "~/components"

Cloudflare Stream works with all web video players that support HLS and DASH.

<Render file="prereqs" />

## Examples

* [Video.js](/stream/examples/video-js/)
* [HLS reference player (hls.js)](/stream/examples/hls-js/)
* [DASH reference player (dash.js)](/stream/examples/dash-js/)
* [Vidstack](/stream/examples/vidstack/)

---

# Asynchronous Batch API

URL: https://developers.cloudflare.com/workers-ai/features/batch-api/

import { Render, PackageManagers, WranglerConfig, CURL } from "~/components";

Asynchronous batch processing lets you send a collection (batch) of inference requests in a single call. Instead of expecting immediate responses for every request, the system queues them for processing and returns the results later.

Batch processing is useful for large workloads such as summarization or embeddings when there is no human interaction. Using the batch API will guarantee that your requests are fulfilled eventually, rather than erroring out if Cloudflare does have enough capacity at a given time.

When you send a batch request, the API immediately acknowledges receipt with a status like `queued` and provides a unique `request_id`. This ID is later used to poll for the final responses once the processing is complete.

You can use the Batch API by either creating and deploying a Cloudflare Worker that leverages the [Batch API with the AI binding](/workers-ai/features/batch-api/workers-binding/), using the [REST API](/workers-ai/features/batch-api/rest-api/) directly or by starting from a [template](https://github.com/craigsdennis/batch-please-workers-ai).

:::note[Note]

Ensure that the total payload is under 10 MB.

:::

## Demo application

If you want to get started quickly, click the button below:

[![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/craigsdennis/batch-please-workers-ai)

This will create a repository in your GitHub account and deploy a ready-to-use Worker that demonstrates how to use Cloudflare's Asynchronous Batch API. The template includes preconfigured AI bindings, and examples for sending and retrieving batch requests with and without external references. Once deployed, you can visit the live Worker and start experimenting with the Batch API immediately.

## Supported Models

Refer to our [model catalog](/workers-ai/models/?capabilities=Batch) for supported models.

---

# REST API

URL: https://developers.cloudflare.com/workers-ai/features/batch-api/rest-api/

If you prefer to work directly with the REST API instead of a [Cloudflare Worker](/workers-ai/features/batch-api/workers-binding/), below are the steps on how to do it:

## 1. Sending a Batch Request

Make a POST request using the following pattern. You can pass `external_reference` as a unique ID per-prompt that will be returned in the response.

```bash title="Sending a batch request" {11,15,19}
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai/run/@cf/baai/bge-m3?queueRequest=true" \
 --header "Authorization: Bearer $API_TOKEN" \
 --header 'Content-Type: application/json' \
 --json '{
    "requests": [
        {
            "query": "This is a story about Cloudflare",
            "contexts": [
                {
                    "text": "This is a story about an orange cloud",
                    "external_reference": "story1"
                },
                {
                    "text": "This is a story about a llama",
                    "external_reference": "story2"
                },
                {
                    "text": "This is a story about a hugging emoji",
                    "external_reference": "story3"
                }
            ]
        }
    ]
  }'
```

```json output {4}
{
	"result": {
		"status": "queued",
		"request_id": "768f15b7-4fd6-4498-906e-ad94ffc7f8d2",
		"model": "@cf/baai/bge-m3"
	},
	"success": true,
	"errors": [],
	"messages": []
}
```

## 2. Retrieving the Batch Response

After receiving a `request_id` from your initial POST, you can poll for or retrieve the results with another POST request:

```bash title="Retrieving a response"
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai/run/@cf/baai/bge-m3?queueRequest=true" \
 --header "Authorization: Bearer $API_TOKEN" \
 --header 'Content-Type: application/json' \
 --json '{
    "request_id": "<uuid>"
  }'
```

```json output
{
	"result": {
		"responses": [
			{
				"id": 0,
				"result": {
					"response": [
						{ "id": 0, "score": 0.73974609375 },
						{ "id": 1, "score": 0.642578125 },
						{ "id": 2, "score": 0.6220703125 }
					]
				},
				"success": true,
				"external_reference": null
			}
		],
		"usage": { "prompt_tokens": 12, "completion_tokens": 0, "total_tokens": 12 }
	},
	"success": true,
	"errors": [],
	"messages": []
}
```

---

# Workers Binding

URL: https://developers.cloudflare.com/workers-ai/features/batch-api/workers-binding/

import {
	Render,
	PackageManagers,
	TypeScriptExample,
	WranglerConfig,
	CURL,
} from "~/components";

You can use Workers Bindings to interact with the Batch API.

## Send a Batch request

Send your initial batch inference request by composing a JSON payload containing an array of individual inference requests and the `queueRequest: true` property (which is what controlls queueing behavior).

:::note[Note]

Ensure that the total payload is under 10 MB.

:::

```ts {26} title="src/index.ts"
export interface Env {
	AI: Ai;
}
export default {
	async fetch(request, env): Promise<Response> {
		const embeddings = await env.AI.run(
			"@cf/baai/bge-m3",
			{
				requests: [
					{
						query: "This is a story about Cloudflare",
						contexts: [
							{
								text: "This is a story about an orange cloud",
							},
							{
								text: "This is a story about a llama",
							},
							{
								text: "This is a story about a hugging emoji",
							},
						],
					},
				],
			},
			{ queueRequest: true },
		);

		return Response.json(embeddings);
	},
} satisfies ExportedHandler<Env>;
```

```json output {4}
{
	"status": "queued",
	"model": "@cf/baai/bge-m3",
	"request_id": "000-000-000"
}
```

You will get a response with the following values:

- **`status`**: Indicates that your request is queued.
- **`request_id`**: A unique identifier for the batch request.
- **`model`**: The model used for the batch inference.

Of these, the `request_id` is important for when you need to [poll the batch status](#poll-batch-status).

### Poll batch status

Once your batch request is queued, use the `request_id` to poll for its status. During processing, the API returns a status `queued` or `running` indicating that the request is still in the queue or being processed.

```typescript title=src/index.ts
export interface Env {
	AI: Ai;
}

export default {
	async fetch(request, env): Promise<Response> {
		const status = await env.AI.run("@cf/baai/bge-m3", {
			request_id: "000-000-000",
		});

		return Response.json(status);
	},
} satisfies ExportedHandler<Env>;
```

```json output
{
	"responses": [
		{
			"id": 0,
			"result": {
				"response": [
					{ "id": 0, "score": 0.73974609375 },
					{ "id": 1, "score": 0.642578125 },
					{ "id": 2, "score": 0.6220703125 }
				]
			},
			"success": true,
			"external_reference": null
		}
	],
	"usage": { "prompt_tokens": 12, "completion_tokens": 0, "total_tokens": 12 }
}
```

When the inference is complete, the API returns a final HTTP status code of `200` along with an array of responses. Each response object corresponds to an individual input prompt, identified by an `id` that maps to the index of the prompt in your original request.

---

# Fine-tunes

URL: https://developers.cloudflare.com/workers-ai/features/fine-tunes/

import { Feature } from "~/components";

Learn how to use Workers AI to get fine-tuned inference.

<Feature header="Fine-tuned inference with LoRAs" href="/workers-ai/features/fine-tunes/loras/" cta="Run inference with LoRAs">

Upload a LoRA adapter and run fine-tuned inference with one of our base models.

</Feature>

---

## What is fine-tuning?

Fine-tuning is a general term for modifying an AI model by continuing to train it with additional data. The goal of fine-tuning is to increase the probability that a generation is similar to your dataset. Training a model from scratch is not practical for many use cases given how expensive and time consuming they can be to train. By fine-tuning an existing pre-trained model, you benefit from its capabilities while also accomplishing your desired task.

[Low-Rank Adaptation](https://arxiv.org/abs/2106.09685) (LoRA) is a specific fine-tuning method that can be applied to various model architectures, not just LLMs. It is common that the pre-trained model weights are directly modified or fused with additional fine-tune weights in traditional fine-tuning methods. LoRA, on the other hand, allows for the fine-tune weights and pre-trained model to remain separate, and for the pre-trained model to remain unchanged. The end result is that you can train models to be more accurate at specific tasks, such as generating code, having a specific personality, or generating images in a specific style.

---

# Using LoRA adapters

URL: https://developers.cloudflare.com/workers-ai/features/fine-tunes/loras/

import { TabItem, Tabs } from "~/components";

Workers AI supports fine-tuned inference with adapters trained with [Low-Rank Adaptation](https://blog.cloudflare.com/fine-tuned-inference-with-loras). This feature is in open beta and free during this period.

## Limitations

- We only support LoRAs for a [variety of models](/workers-ai/models/?capabilities=LoRA) (must not be quantized)
- Adapter must be trained with rank `r <=8` as well as larger ranks if up to 32. You can check the rank of a pre-trained LoRA adapter through the adapter's `config.json` file
- LoRA adapter file must be < 300MB
- LoRA adapter files must be named `adapter_config.json` and `adapter_model.safetensors` exactly
- You can test up to 30 LoRA adapters per account

---

## Choosing compatible LoRA adapters

### Finding open-source LoRA adapters

We have started a [Hugging Face Collection](https://huggingface.co/collections/Cloudflare/workers-ai-compatible-loras-6608dd9f8d305a46e355746e) that lists a few LoRA adapters that are compatible with Workers AI. Generally, any LoRA adapter that fits our limitations above should work.

### Training your own LoRA adapters

To train your own LoRA adapter, follow the [tutorial](/workers-ai/guides/tutorials/fine-tune-models-with-autotrain/).

---

## Uploading LoRA adapters

In order to run inference with LoRAs on Workers AI, you'll need to create a new fine tune on your account and upload your adapter files. You should have a `adapter_model.safetensors` file with model weights and `adapter_config.json` with your config information. _Note that we only accept adapter files in these types._

Right now, you can't edit a fine tune's asset files after you upload it. We will support this soon, but for now you will need to create a new fine tune and upload files again if you would like to use a new LoRA.

Before you upload your LoRA adapter, you'll need to edit your `adapter_config.json` file to include `model_type` as one of `mistral`, `gemma` or `llama` like below.

```json null {10}
{
  "alpha_pattern": {},
  "auto_mapping": null,
  ...
  "target_modules": [
    "q_proj",
    "v_proj"
  ],
  "task_type": "CAUSAL_LM",
  "model_type": "mistral",
}
```

### Wrangler

You can create a finetune and upload your LoRA adapter via wrangler with the following commands:

```bash title="wrangler CLI" {1,7}
npx wrangler ai finetune create <model_name> <finetune_name> <folder_path>
#🌀 Creating new finetune "test-lora" for model "@cf/mistral/mistral-7b-instruct-v0.2-lora"...
#🌀 Uploading file "/Users/abcd/Downloads/adapter_config.json" to "test-lora"...
#🌀 Uploading file "/Users/abcd/Downloads/adapter_model.safetensors" to "test-lora"...
#✅ Assets uploaded, finetune "test-lora" is ready to use.

npx wrangler ai finetune list
┌──────────────────────────────────────┬─────────────────┬─────────────┐
│ finetune_id                          │ name            │ description │
├──────────────────────────────────────┼─────────────────┼─────────────┤
│ 00000000-0000-0000-0000-000000000000 │ test-lora       │             │
└──────────────────────────────────────┴─────────────────┴─────────────┘
```

### REST API

Alternatively, you can use our REST API to create a finetune and upload your adapter files. You will need a Cloudflare API Token with `Workers AI: Edit` permissions to make calls to our REST API, which you can generate via the Cloudflare Dashboard.

#### Creating a fine-tune on your account

```bash title="cURL"
## Input: user-defined name of fine tune
## Output: unique finetune_id

curl -X POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/finetunes/ \
    -H "Authorization: Bearer {API_TOKEN}" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "SUPPORTED_MODEL_NAME",
      "name": "FINETUNE_NAME",
      "description": "OPTIONAL_DESCRIPTION"
    }'
```

#### Uploading your adapter weights and config

You have to call the upload endpoint each time you want to upload a new file, so you usually run this once for `adapter_model.safetensors` and once for `adapter_config.json`. Make sure you include the `@` before your path to files.

You can either use the finetune `name` or `id` that you used when you created the fine tune.

```bash title="cURL"
## Input: finetune_id, adapter_model.safetensors, then adapter_config.json
## Output: success true/false

curl -X POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/finetunes/{FINETUNE_ID}/finetune-assets/ \
    -H 'Authorization: Bearer {API_TOKEN}' \
    -H 'Content-Type: multipart/form-data' \
    -F 'file_name=adapter_model.safetensors' \
    -F 'file=@{PATH/TO/adapter_model.safetensors}'
```

#### List fine-tunes in your account

You can call this method to confirm what fine-tunes you have created in your account

<Tabs> <TabItem label="curl">

```bash title="cURL"
## Input: n/a
## Output: success true/false

curl -X GET https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/finetunes/ \
    -H 'Authorization: Bearer {API_TOKEN}'
```

</TabItem> <TabItem label="json output">

```json title="Example JSON output"
# Example output JSON
{
  "success": true,
  "result": [
    [{
       "id": "00000000-0000-0000-0000-000000000",
       "model": "@cf/meta-llama/llama-2-7b-chat-hf-lora",
       "name": "llama2-finetune",
       "description": "test"
    },
    {
       "id": "00000000-0000-0000-0000-000000000",
       "model": "@cf/mistralai/mistral-7b-instruct-v0.2-lora",
       "name": "mistral-finetune",
       "description": "test"
    }]
  ]
}
```

</TabItem> </Tabs>

---

## Running inference with LoRAs

To make inference requests and apply the LoRA adapter, you will need your model and finetune `name` or `id`. You should use the chat template that your LoRA was trained on, but you can try running it with `raw: true` and the messages template like below.

<Tabs> <TabItem label="workers ai sdk">

```javascript null {5-6}
const response = await env.AI.run(
	"@cf/mistralai/mistral-7b-instruct-v0.2-lora", //the model supporting LoRAs
	{
		messages: [{ role: "user", content: "Hello world" }],
		raw: true, //skip applying the default chat template
		lora: "00000000-0000-0000-0000-000000000", //the finetune id OR name
	},
);
```

</TabItem> <TabItem label="rest api">

```bash null {5-6}
curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/@cf/mistral/mistral-7b-instruct-v0.2-lora \
  -H 'Authorization: Bearer {API_TOKEN}' \
  -d '{
    "messages": [{"role": "user", "content": "Hello world"}],
    "raw": "true",
    "lora": "00000000-0000-0000-0000-000000000"
  }'
```

</TabItem> </Tabs>

---

# Public LoRA adapters

URL: https://developers.cloudflare.com/workers-ai/features/fine-tunes/public-loras/

Cloudflare offers a few public LoRA adapters that can immediately be used for fine-tuned inference. You can try them out immediately via our [playground](https://playground.ai.cloudflare.com).

Public LoRAs will have the name `cf-public-x`, and the prefix will be reserved for Cloudflare.

:::note


Have more LoRAs you would like to see? Let us know on [Discord](https://discord.cloudflare.com).


:::

| Name                                                                       | Description                        | Compatible with                                                                     |
| -------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------- |
| [cf-public-magicoder](https://huggingface.co/predibase/magicoder)          | Coding tasks in multiple languages | `@cf/mistral/mistral-7b-instruct-v0.1` <br/> `@hf/mistral/mistral-7b-instruct-v0.2` |
| [cf-public-jigsaw-classification](https://huggingface.co/predibase/jigsaw) | Toxic comment classification       | `@cf/mistral/mistral-7b-instruct-v0.1` <br/> `@hf/mistral/mistral-7b-instruct-v0.2` |
| [cf-public-cnn-summarization](https://huggingface.co/predibase/cnn)        | Article summarization              | `@cf/mistral/mistral-7b-instruct-v0.1` <br/> `@hf/mistral/mistral-7b-instruct-v0.2` |

You can also list these public LoRAs with an API call:

```bash
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/finetunes/public \
 --header 'Authorization: Bearer {cf_token}'
```

## Running inference with public LoRAs

To run inference with public LoRAs, you just need to define the LoRA name in the request.

We recommend that you use the prompt template that the LoRA was trained on. You can find this in the HuggingFace repos linked above for each adapter.

### cURL

```bash null {10}
curl https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/mistral/mistral-7b-instruct-v0.1 \
  --header 'Authorization: Bearer {cf_token}' \
  --data '{
    "messages": [
      {
        "role": "user",
        "content": "Write a python program to check if a number is even or odd."
      }
    ],
    "lora": "cf-public-magicoder"
  }'
```

### JavaScript

```js null {11}
const answer = await env.AI.run('@cf/mistral/mistral-7b-instruct-v0.1',
  {
    stream: true,
    raw: true,
    messages: [
      {
        "role": "user",
        "content": "Summarize the following: Some newspapers, TV channels and well-known companies publish false news stories to fool people on 1 April. One of the earliest examples of this was in 1957 when a programme on the BBC, the UKs national TV channel, broadcast a report on how spaghetti grew on trees. The film showed a family in Switzerland collecting spaghetti from trees and many people were fooled into believing it, as in the 1950s British people didnt eat much pasta and many didnt know how it was made! Most British people wouldnt fall for the spaghetti trick today, but in 2008 the BBC managed to fool their audience again with their Miracles of Evolution trailer, which appeared to show some special penguins that had regained the ability to fly. Two major UK newspapers, The Daily Telegraph and the Daily Mirror, published the important story on their front pages."
      }
    ],
    lora: "cf-public-cnn-summarization"
  });
```

---

# Function calling

URL: https://developers.cloudflare.com/workers-ai/features/function-calling/

import { Stream, TabItem, Tabs } from "~/components";

Function calling enables people to take Large Language Models (LLMs) and use the model response to execute functions or interact with external APIs. The developer usually defines a set of functions and the required input schema for each function, which we call `tools`. The model then intelligently understands when it needs to do a tool call, and it returns a JSON output which the user needs to feed to another function or API.

In essence, function calling allows you to perform actions with LLMs by executing code or making additional API calls.

<Stream id="603e94c9803b4779dd612493c0dd7125" title="placeholder" />

## How can I use function calling?

Workers AI has [embedded function calling](/workers-ai/features/function-calling/embedded/) which allows you to execute function code alongside your inference calls. We have a package called [`@cloudflare/ai-utils`](https://www.npmjs.com/package/@cloudflare/ai-utils) to help facilitate this, which we have open-sourced on [Github](https://github.com/cloudflare/ai-utils).

For industry-standard function calling, take a look at the documentation on [Traditional Function Calling](/workers-ai/features/function-calling/traditional/).

To show you the value of embedded function calling, take a look at the example below that compares traditional function calling with embedded function calling. Embedded function calling allowed us to cut down the lines of code from 77 to 31.

<Tabs> <TabItem label="Embedded">

```sh
# The ai-utils package enables embedded function calling
npm i @cloudflare/ai-utils
```

```js title="Embedded function calling example"
import {
	createToolsFromOpenAPISpec,
	runWithTools,
	autoTrimTools,
} from "@cloudflare/ai-utils";

export default {
	async fetch(request, env, ctx) {
		const response = await runWithTools(
			env.AI,
			"@hf/nousresearch/hermes-2-pro-mistral-7b",
			{
				messages: [{ role: "user", content: "Who is Cloudflare on github?" }],
				tools: [
					// You can pass the OpenAPI spec link or contents directly
					...(await createToolsFromOpenAPISpec(
						"https://gist.githubusercontent.com/mchenco/fd8f20c8f06d50af40b94b0671273dc1/raw/f9d4b5cd5944cc32d6b34cad0406d96fd3acaca6/partial_api.github.com.json",
						{
							overrides: [
								{
									// for all requests on *.github.com, we'll need to add a User-Agent.
									matcher: ({ url, method }) => {
										return url.hostname === "api.github.com";
									},
									values: {
										headers: {
											"User-Agent":
												"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36",
										},
									},
								},
							],
						},
					)),
				],
			},
		).then((response) => {
			return response;
		});

		return new Response(JSON.stringify(response));
	},
};
```

</TabItem> <TabItem label="Traditional">

```js title="Traditional function calling example"
export default {
	async fetch(request, env, ctx) {
		const response = await env.AI.run(
			"@hf/nousresearch/hermes-2-pro-mistral-7b",
			{
				messages: [{ role: "user", content: "Who is Cloudflare on GitHub?" }],
				tools: [
					{
						name: "getGithubUser",
						description:
							"Provides publicly available information about someone with a GitHub account.",
						parameters: {
							type: "object",
							properties: {
								username: {
									type: "string",
									description: "The handle for the GitHub user account.",
								},
							},
							required: ["username"],
						},
					},
				],
			},
		);

		const selected_tool = response.tool_calls[0];
		let res;

		if (selected_tool.name == "getGithubUser") {
			try {
				const username = selected_tool.arguments.username;
				const url = `https://api.github.com/users/${username}`;
				res = await fetch(url, {
					headers: {
						// Github API requires a User-Agent header
						"User-Agent":
							"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36",
					},
				}).then((res) => res.json());
			} catch (error) {
				return error;
			}
		}

		const finalResponse = await env.AI.run(
			"@hf/nousresearch/hermes-2-pro-mistral-7b",
			{
				messages: [
					{
						role: "user",
						content: "Who is Cloudflare on GitHub?",
					},
					{
						role: "assistant",
						content: JSON.stringify(selected_tool),
					},
					{
						role: "tool",
						content: JSON.stringify(res),
					},
				],
				tools: [
					{
						name: "getGithubUser",
						description:
							"Provides publicly available information about someone with a GitHub account.",
						parameters: {
							type: "object",
							properties: {
								username: {
									type: "string",
									description: "The handle for the GitHub user account.",
								},
							},
							required: ["username"],
						},
					},
				],
			},
		);
		return new Response(JSON.stringify(finalResponse));
	},
};
```

</TabItem> </Tabs>

## What models support function calling?

There are open-source models which have been fine-tuned to do function calling. When browsing our [model catalog](/workers-ai/models/), look for models with the function calling property beside it. For example, [@hf/nousresearch/hermes-2-pro-mistral-7b](/workers-ai/models/hermes-2-pro-mistral-7b/) is a fine-tuned variant of Mistral 7B that you can use for function calling.

---

# Traditional

URL: https://developers.cloudflare.com/workers-ai/features/function-calling/traditional/

This page shows how you can do traditional function calling, as defined by industry standards. Workers AI also offers [embedded function calling](/workers-ai/features/function-calling/embedded/), which is drastically easier than traditional function calling.

With traditional function calling, you define an array of tools with the name, description, and tool arguments. The example below shows how you would pass a tool called `getWeather` in an inference request to a model.

```js title="Traditional function calling example"
const response = await env.AI.run("@hf/nousresearch/hermes-2-pro-mistral-7b", {
	messages: [
		{
			role: "user",
			content: "what is the weather in london?",
		},
	],
	tools: [
		{
			name: "getWeather",
			description: "Return the weather for a latitude and longitude",
			parameters: {
				type: "object",
				properties: {
					latitude: {
						type: "string",
						description: "The latitude for the given location",
					},
					longitude: {
						type: "string",
						description: "The longitude for the given location",
					},
				},
				required: ["latitude", "longitude"],
			},
		},
	],
});

return new Response(JSON.stringify(response.tool_calls));
```

The LLM will then return a JSON object with the required arguments and the name of the tool that was called. You can then pass this JSON object to make an API call.

```json
[
	{
		"arguments": { "latitude": "51.5074", "longitude": "-0.1278" },
		"name": "getWeather"
	}
]
```

For a working example on how to do function calling, take a look at our [demo app](https://github.com/craigsdennis/lightbulb-moment-tool-calling/blob/main/src/index.ts).

---

# Build a Retrieval Augmented Generation (RAG) AI

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/build-a-retrieval-augmented-generation-ai/

import { Details, Render, PackageManagers, WranglerConfig } from "~/components";

This guide will instruct you through setting up and deploying your first application with Cloudflare AI. You will build a fully-featured AI-powered application, using tools like Workers AI, Vectorize, D1, and Cloudflare Workers.

:::note[Looking for a managed option?]
[AutoRAG](/autorag) offers a fully managed way to build RAG pipelines on Cloudflare, handling ingestion, indexing, and querying out of the box. [Get started](/autorag/get-started/).
:::

At the end of this tutorial, you will have built an AI tool that allows you to store information and query it using a Large Language Model. This pattern, known as Retrieval Augmented Generation, or RAG, is a useful project you can build by combining multiple aspects of Cloudflare's AI toolkit. You do not need to have experience working with AI tools to build this application.

<Render file="prereqs" product="workers" />

You will also need access to [Vectorize](/vectorize/platform/pricing/). During this tutorial, we will show how you can optionally integrate with [Anthropic Claude](http://anthropic.com) as well. You will need an [Anthropic API key](https://docs.anthropic.com/en/api/getting-started) to do so.

## 1. Create a new Worker project

C3 (`create-cloudflare-cli`) is a command-line tool designed to help you setup and deploy Workers to Cloudflare as fast as possible.

Open a terminal window and run C3 to create your Worker project:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"rag-ai-tutorial"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

In your project directory, C3 has generated several files.

<Details header="What files did C3 create?">

1. `wrangler.jsonc`: Your [Wrangler](/workers/wrangler/configuration/#sample-wrangler-configuration) configuration file.
2. `worker.js` (in `/src`): A minimal `'Hello World!'` Worker written in [ES module](/workers/reference/migrate-to-module-workers/) syntax.
3. `package.json`: A minimal Node dependencies configuration file.
4. `package-lock.json`: Refer to [`npm` documentation on `package-lock.json`](https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json).
5. `node_modules`: Refer to [`npm` documentation `node_modules`](https://docs.npmjs.com/cli/v7/configuring-npm/folders#node-modules).

</Details>

Now, move into your newly created directory:

```sh
cd rag-ai-tutorial
```

## 2. Develop with Wrangler CLI

The Workers command-line interface, [Wrangler](/workers/wrangler/install-and-update/), allows you to [create](/workers/wrangler/commands/#init), [test](/workers/wrangler/commands/#dev), and [deploy](/workers/wrangler/commands/#deploy) your Workers projects. C3 will install Wrangler in projects by default.

After you have created your first Worker, run the [`wrangler dev`](/workers/wrangler/commands/#dev) command in the project directory to start a local server for developing your Worker. This will allow you to test your Worker locally during development.

```sh
npx wrangler dev --remote
```

:::note

If you have not used Wrangler before, it will try to open your web browser to login with your Cloudflare account.

If you have issues with this step or you do not have access to a browser interface, refer to the [`wrangler login`](/workers/wrangler/commands/#login) documentation for more information.

:::

You will now be able to go to [http://localhost:8787](http://localhost:8787) to see your Worker running. Any changes you make to your code will trigger a rebuild, and reloading the page will show you the up-to-date output of your Worker.

## 3. Adding the AI binding

To begin using Cloudflare's AI products, you can add the `ai` block to the [Wrangler configuration file](/workers/wrangler/configuration/). This will set up a binding to Cloudflare's AI models in your code that you can use to interact with the available AI models on the platform.

This example features the [`@cf/meta/llama-3-8b-instruct` model](/workers-ai/models/llama-3-8b-instruct/), which generates text.

<WranglerConfig>

```toml
[ai]
binding = "AI"
```

</WranglerConfig>

Now, find the `src/index.js` file. Inside the `fetch` handler, you can query the `AI` binding:

```js
export default {
	async fetch(request, env, ctx) {
		const answer = await env.AI.run("@cf/meta/llama-3-8b-instruct", {
			messages: [{ role: "user", content: `What is the square root of 9?` }],
		});

		return new Response(JSON.stringify(answer));
	},
};
```

By querying the LLM through the `AI` binding, we can interact directly with Cloudflare AI's large language models directly in our code. In this example, we are using the [`@cf/meta/llama-3-8b-instruct` model](/workers-ai/models/llama-3-8b-instruct/), which generates text.

You can deploy your Worker using `wrangler`:

```sh
npx wrangler deploy
```

Making a request to your Worker will now generate a text response from the LLM, and return it as a JSON object.

```sh
curl https://example.username.workers.dev
```

```sh output
{"response":"Answer: The square root of 9 is 3."}
```

## 4. Adding embeddings using Cloudflare D1 and Vectorize

Embeddings allow you to add additional capabilities to the language models you can use in your Cloudflare AI projects. This is done via **Vectorize**, Cloudflare's vector database.

To begin using Vectorize, create a new embeddings index using `wrangler`. This index will store vectors with 768 dimensions, and will use cosine similarity to determine which vectors are most similar to each other:

```sh
npx wrangler vectorize create vector-index --dimensions=768 --metric=cosine
```

Then, add the configuration details for your new Vectorize index to the [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
# ... existing wrangler configuration

[[vectorize]]
binding = "VECTOR_INDEX"
index_name = "vector-index"
```

</WranglerConfig>

A vector index allows you to store a collection of dimensions, which are floating point numbers used to represent your data. When you want to query the vector database, you can also convert your query into dimensions. **Vectorize** is designed to efficiently determine which stored vectors are most similar to your query.

To implement the searching feature, you must set up a D1 database from Cloudflare. In D1, you can store your app's data. Then, you change this data into a vector format. When someone searches and it matches the vector, you can show them the matching data.

Create a new D1 database using `wrangler`:

```sh
npx wrangler d1 create database
```

Then, paste the configuration details output from the previous command into the [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
# ... existing wrangler configuration

[[d1_databases]]
binding = "DB" # available in your Worker on env.DB
database_name = "database"
database_id = "abc-def-geh" # replace this with a real database_id (UUID)
```

</WranglerConfig>

In this application, we'll create a `notes` table in D1, which will allow us to store notes and later retrieve them in Vectorize. To create this table, run a SQL command using `wrangler d1 execute`:

```sh
npx wrangler d1 execute database --remote --command "CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, text TEXT NOT NULL)"
```

Now, we can add a new note to our database using `wrangler d1 execute`:

```sh
npx wrangler d1 execute database --remote --command "INSERT INTO notes (text) VALUES ('The best pizza topping is pepperoni')"
```

## 5. Creating a workflow

Before we begin creating notes, we will introduce a [Cloudflare Workflow](/workflows). This will allow us to define a durable workflow that can safely and robustly execute all the steps of the RAG process.

To begin, add a new `[[workflows]]` block to your [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
# ... existing wrangler configuration

[[workflows]]
name = "rag"
binding = "RAG_WORKFLOW"
class_name = "RAGWorkflow"
```

</WranglerConfig>

In `src/index.js`, add a new class called `RAGWorkflow` that extends `WorkflowEntrypoint`:

```js
import { WorkflowEntrypoint } from "cloudflare:workers";

export class RAGWorkflow extends WorkflowEntrypoint {
	async run(event, step) {
		await step.do("example step", async () => {
			console.log("Hello World!");
		});
	}
}
```

This class will define a single workflow step that will log "Hello World!" to the console. You can add as many steps as you need to your workflow.

On its own, this workflow will not do anything. To execute the workflow, we will call the `RAG_WORKFLOW` binding, passing in any parameters that the workflow needs to properly complete. Here is an example of how we can call the workflow:

```js
env.RAG_WORKFLOW.create({ params: { text } });
```

## 6. Creating notes and adding them to Vectorize

To expand on your Workers function in order to handle multiple routes, we will add `hono`, a routing library for Workers. This will allow us to create a new route for adding notes to our database. Install `hono` using `npm`:

<PackageManagers pkg="hono" />

Then, import `hono` into your `src/index.js` file. You should also update the `fetch` handler to use `hono`:

```js
import { Hono } from "hono";
const app = new Hono();

app.get("/", async (c) => {
	const answer = await c.env.AI.run("@cf/meta/llama-3-8b-instruct", {
		messages: [{ role: "user", content: `What is the square root of 9?` }],
	});

	return c.json(answer);
});

export default app;
```

This will establish a route at the root path `/` that is functionally equivalent to the previous version of your application.

Now, we can update our workflow to begin adding notes to our database, and generating the related embeddings for them.

This example features the [`@cf/baai/bge-base-en-v1.5` model](/workers-ai/models/bge-base-en-v1.5/), which can be used to create an embedding. Embeddings are stored and retrieved inside [Vectorize](/vectorize/), Cloudflare's vector database. The user query is also turned into an embedding so that it can be used for searching within Vectorize.

```js
import { WorkflowEntrypoint } from "cloudflare:workers";

export class RAGWorkflow extends WorkflowEntrypoint {
	async run(event, step) {
		const env = this.env;
		const { text } = event.payload;

		const record = await step.do(`create database record`, async () => {
			const query = "INSERT INTO notes (text) VALUES (?) RETURNING *";

			const { results } = await env.DB.prepare(query).bind(text).run();

			const record = results[0];
			if (!record) throw new Error("Failed to create note");
			return record;
		});

		const embedding = await step.do(`generate embedding`, async () => {
			const embeddings = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
				text: text,
			});
			const values = embeddings.data[0];
			if (!values) throw new Error("Failed to generate vector embedding");
			return values;
		});

		await step.do(`insert vector`, async () => {
			return env.VECTOR_INDEX.upsert([
				{
					id: record.id.toString(),
					values: embedding,
				},
			]);
		});
	}
}
```

The workflow does the following things:

1. Accepts a `text` parameter.
2. Insert a new row into the `notes` table in D1, and retrieve the `id` of the new row.
3. Convert the `text` into a vector using the `embeddings` model of the LLM binding.
4. Upsert the `id` and `vectors` into the `vector-index` index in Vectorize.

By doing this, you will create a new vector representation of the note, which can be used to retrieve the note later.

To complete the code, we will add a route that allows users to submit notes to the database. This route will parse the JSON request body, get the `note` parameter, and create a new instance of the workflow, passing the parameter:

```js
app.post("/notes", async (c) => {
	const { text } = await c.req.json();
	if (!text) return c.text("Missing text", 400);
	await c.env.RAG_WORKFLOW.create({ params: { text } });
	return c.text("Created note", 201);
});
```

## 7. Querying Vectorize to retrieve notes

To complete your code, you can update the root path (`/`) to query Vectorize. You will convert the query into a vector, and then use the `vector-index` index to find the most similar vectors.

The `topK` parameter limits the number of vectors returned by the function. For instance, providing a `topK` of 1 will only return the _most similar_ vector based on the query. Setting `topK` to 5 will return the 5 most similar vectors.

Given a list of similar vectors, you can retrieve the notes that match the record IDs stored alongside those vectors. In this case, we are only retrieving a single note - but you may customize this as needed.

You can insert the text of those notes as context into the prompt for the LLM binding. This is the basis of Retrieval-Augmented Generation, or RAG: providing additional context from data outside of the LLM to enhance the text generated by the LLM.

We'll update the prompt to include the context, and to ask the LLM to use the context when responding:

```js
import { Hono } from "hono";
const app = new Hono();

// Existing post route...
// app.post('/notes', async (c) => { ... })

app.get("/", async (c) => {
	const question = c.req.query("text") || "What is the square root of 9?";

	const embeddings = await c.env.AI.run("@cf/baai/bge-base-en-v1.5", {
		text: question,
	});
	const vectors = embeddings.data[0];

	const vectorQuery = await c.env.VECTOR_INDEX.query(vectors, { topK: 1 });
	let vecId;
	if (
		vectorQuery.matches &&
		vectorQuery.matches.length > 0 &&
		vectorQuery.matches[0]
	) {
		vecId = vectorQuery.matches[0].id;
	} else {
		console.log("No matching vector found or vectorQuery.matches is empty");
	}

	let notes = [];
	if (vecId) {
		const query = `SELECT * FROM notes WHERE id = ?`;
		const { results } = await c.env.DB.prepare(query).bind(vecId).all();
		if (results) notes = results.map((vec) => vec.text);
	}

	const contextMessage = notes.length
		? `Context:\n${notes.map((note) => `- ${note}`).join("\n")}`
		: "";

	const systemPrompt = `When answering the question or responding, use the context provided, if it is provided and relevant.`;

	const { response: answer } = await c.env.AI.run(
		"@cf/meta/llama-3-8b-instruct",
		{
			messages: [
				...(notes.length ? [{ role: "system", content: contextMessage }] : []),
				{ role: "system", content: systemPrompt },
				{ role: "user", content: question },
			],
		},
	);

	return c.text(answer);
});

app.onError((err, c) => {
	return c.text(err);
});

export default app;
```

## 8. Adding Anthropic Claude model (optional)

If you are working with larger documents, you have the option to use Anthropic's [Claude models](https://claude.ai/), which have large context windows and are well-suited to RAG workflows.

To begin, install the `@anthropic-ai/sdk` package:

<PackageManagers pkg="@anthropic-ai/sdk" />

In `src/index.js`, you can update the `GET /` route to check for the `ANTHROPIC_API_KEY` environment variable. If it's set, we can generate text using the Anthropic SDK. If it isn't set, we'll fall back to the existing Workers AI code:

```js
import Anthropic from '@anthropic-ai/sdk';

app.get('/', async (c) => {
  // ... Existing code
	const systemPrompt = `When answering the question or responding, use the context provided, if it is provided and relevant.`

	let modelUsed: string = ""
	let response = null

	if (c.env.ANTHROPIC_API_KEY) {
		const anthropic = new Anthropic({
			apiKey: c.env.ANTHROPIC_API_KEY
		})

		const model = "claude-3-5-sonnet-latest"
		modelUsed = model

		const message = await anthropic.messages.create({
			max_tokens: 1024,
			model,
			messages: [
				{ role: 'user', content: question }
			],
			system: [systemPrompt, notes ? contextMessage : ''].join(" ")
		})

		response = {
			response: message.content.map(content => content.text).join("\n")
		}
	} else {
		const model = "@cf/meta/llama-3.1-8b-instruct"
		modelUsed = model

		response = await c.env.AI.run(
			model,
			{
				messages: [
					...(notes.length ? [{ role: 'system', content: contextMessage }] : []),
					{ role: 'system', content: systemPrompt },
					{ role: 'user', content: question }
				]
			}
		)
	}

	if (response) {
		c.header('x-model-used', modelUsed)
		return c.text(response.response)
	} else {
		return c.text("We were unable to generate output", 500)
	}
})
```

Finally, you'll need to set the `ANTHROPIC_API_KEY` environment variable in your Workers application. You can do this by using `wrangler secret put`:

```sh
$ npx wrangler secret put ANTHROPIC_API_KEY
```

## 9. Deleting notes and vectors

If you no longer need a note, you can delete it from the database. Any time that you delete a note, you will also need to delete the corresponding vector from Vectorize. You can implement this by building a `DELETE /notes/:id` route in your `src/index.js` file:

```js
app.delete("/notes/:id", async (c) => {
	const { id } = c.req.param();

	const query = `DELETE FROM notes WHERE id = ?`;
	await c.env.DB.prepare(query).bind(id).run();

	await c.env.VECTOR_INDEX.deleteByIds([id]);

	return c.status(204);
});
```

## 10. Text splitting (optional)

For large pieces of text, it is recommended to split the text into smaller chunks. This allows LLMs to more effectively gather relevant context, without needing to retrieve large pieces of text.

To implement this, we'll add a new NPM package to our project, `@langchain/textsplitters':

<PackageManagers pkg="@langchain/textsplitters" />

The `RecursiveCharacterTextSplitter` class provided by this package will split the text into smaller chunks. It can be customized to your liking, but the default config works in most cases:

```js
import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";

const text = "Some long piece of text...";

const splitter = new RecursiveCharacterTextSplitter({
	// These can be customized to change the chunking size
	// chunkSize: 1000,
	// chunkOverlap: 200,
});

const output = await splitter.createDocuments([text]);
console.log(output); // [{ pageContent: 'Some long piece of text...' }]
```

To use this splitter, we'll update the workflow to split the text into smaller chunks. We'll then iterate over the chunks and run the rest of the workflow for each chunk of text:

```js
export class RAGWorkflow extends WorkflowEntrypoint {
	async run(event, step) {
		const env = this.env;
		const { text } = event.payload;
		let texts = await step.do("split text", async () => {
			const splitter = new RecursiveCharacterTextSplitter();
			const output = await splitter.createDocuments([text]);
			return output.map((doc) => doc.pageContent);
		});

		console.log(
			"RecursiveCharacterTextSplitter generated ${texts.length} chunks",
		);

		for (const index in texts) {
			const text = texts[index];
			const record = await step.do(
				`create database record: ${index}/${texts.length}`,
				async () => {
					const query = "INSERT INTO notes (text) VALUES (?) RETURNING *";

					const { results } = await env.DB.prepare(query).bind(text).run();

					const record = results[0];
					if (!record) throw new Error("Failed to create note");
					return record;
				},
			);

			const embedding = await step.do(
				`generate embedding: ${index}/${texts.length}`,
				async () => {
					const embeddings = await env.AI.run("@cf/baai/bge-base-en-v1.5", {
						text: text,
					});
					const values = embeddings.data[0];
					if (!values) throw new Error("Failed to generate vector embedding");
					return values;
				},
			);

			await step.do(`insert vector: ${index}/${texts.length}`, async () => {
				return env.VECTOR_INDEX.upsert([
					{
						id: record.id.toString(),
						values: embedding,
					},
				]);
			});
		}
	}
}
```

Now, when large pieces of text are submitted to the `/notes` endpoint, they will be split into smaller chunks, and each chunk will be processed by the workflow.

## 11. Deploy your project

If you did not deploy your Worker during [step 1](/workers/get-started/guide/#1-create-a-new-worker-project), deploy your Worker via Wrangler, to a `*.workers.dev` subdomain, or a [Custom Domain](/workers/configuration/routing/custom-domains/), if you have one configured. If you have not configured any subdomain or domain, Wrangler will prompt you during the publish process to set one up.

```sh
npx wrangler deploy
```

Preview your Worker at `<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev`.

:::note[Note]

When pushing to your `*.workers.dev` subdomain for the first time, you may see [`523` errors](/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/error-523/) while DNS is propagating. These errors should resolve themselves after a minute or so.

:::

## Related resources

A full version of this codebase is available on GitHub. It includes a frontend UI for querying, adding, and deleting notes, as well as a backend API for interacting with the database and vector index. You can find it here: [github.com/kristianfreeman/cloudflare-retrieval-augmented-generation-example](https://github.com/kristianfreeman/cloudflare-retrieval-augmented-generation-example/).

To do more:

- Explore the reference diagram for a [Retrieval Augmented Generation (RAG) Architecture](/reference-architecture/diagrams/ai/ai-rag/).
- Review Cloudflare's [AI documentation](/workers-ai).
- Review [Tutorials](/workers/tutorials/) to build projects on Workers.
- Explore [Examples](/workers/examples/) to experiment with copy and paste Worker code.
- Understand how Workers works in [Reference](/workers/reference/).
- Learn about Workers features and functionality in [Platform](/workers/platform/).
- Set up [Wrangler](/workers/wrangler/install-and-update/) to programmatically create, test, and deploy your Worker projects.

---

# Build a Voice Notes App with auto transcriptions using Workers AI

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/build-a-voice-notes-app-with-auto-transcription/

import { Render, PackageManagers, Tabs, TabItem } from "~/components";

In this tutorial, you will learn how to create a Voice Notes App with automatic transcriptions of voice recordings, and optional post-processing. The following tools will be used to build the application:

- Workers AI to transcribe the voice recordings, and for the optional post processing
- D1 database to store the notes
- R2 storage to store the voice recordings
- Nuxt framework to build the full-stack application
- Workers to deploy the project

## Prerequisites

To continue, you will need:

<Render file="prereqs" product="workers" />

## 1. Create a new Worker project

Create a new Worker project using the `c3` CLI with the `nuxt` framework preset.

<PackageManagers type="create" pkg="cloudflare@latest" args="voice-notes --framework=nuxt" />

### Install additional dependencies

Change into the newly created project directory

```sh
cd voice-notes
```

And install the following dependencies:

<PackageManagers pkg="@nuxt/ui @vueuse/core @iconify-json/heroicons" />

Then add the `@nuxt/ui` module to the `nuxt.config.ts` file:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
  //..

  modules: ['nitro-cloudflare-dev', '@nuxt/ui'],

  //..
})
```

### [Optional] Move to Nuxt 4 compatibility mode

Moving to Nuxt 4 compatibility mode ensures that your application remains forward-compatible with upcoming updates to Nuxt.

Create a new `app` folder in the project's root directory and move the `app.vue` file to it. Also, add the following to your `nuxt.config.ts` file:

```ts title="nuxt.config.ts"
export default defineNuxtConfig({
  //..

  future: {
    compatibilityVersion: 4,
  },

  //..
})
```

:::note
The rest of the tutorial will use the `app` folder for keeping the client side code. If you did not make this change, you should continue to use the project's root directory.
:::

### Start local development server

At this point you can test your application by starting a local development server using:

<PackageManagers type="run" args="dev" />

If everything is set up correctly, you should see a Nuxt welcome page at `http://localhost:3000`.

## 2. Create the transcribe API endpoint

This API makes use of Workers AI to transcribe the voice recordings. To use Workers AI within your project, you first need to bind it to the Worker.

<Render file="ai-local-usage-charges" product="workers" />

Add the `AI` binding to the Wrangler file.

```toml title="wrangler.toml"
[ai]
binding = "AI"
```

Once the `AI` binding has been configured, run the `cf-typegen` command to generate the necessary Cloudflare type definitions. This makes the types definitions available in the server event contexts.

<PackageManagers type="run" args="cf-typegen" />

Create a transcribe `POST` endpoint by creating `transcribe.post.ts` file inside the `/server/api` directory.

```ts title="server/api/transcribe.post.ts"
export default defineEventHandler(async (event) => {
  const { cloudflare } = event.context;

  const form = await readFormData(event);
  const blob = form.get('audio') as Blob;
  if (!blob) {
    throw createError({
      statusCode: 400,
      message: 'Missing audio blob to transcribe',
    });
  }

  try {
    const response = await cloudflare.env.AI.run('@cf/openai/whisper', {
      audio: [...new Uint8Array(await blob.arrayBuffer())],
    });

    return response.text;
  } catch (err) {
    console.error('Error transcribing audio:', err);
    throw createError({
      statusCode: 500,
      message: 'Failed to transcribe audio. Please try again.',
    });
  }
});
```

The above code does the following:

1. Extracts the audio blob from the event.
2. Transcribes the blob using the `@cf/openai/whisper` model and returns the transcription text as response.

## 3. Create an API endpoint for uploading audio recordings to R2

Before uploading the audio recordings to `R2`, you need to create a bucket first. You will also need to add the R2 binding to your Wrangler file and regenerate the Cloudflare type definitions.

Create an `R2` bucket.

<PackageManagers type="exec" pkg="wrangler" args="r2 bucket create <BUCKET_NAME>" />

Add the storage binding to your Wrangler file.

```toml title="wrangler.toml"
[[r2_buckets]]
binding = "R2"
bucket_name = "<BUCKET_NAME>"
```

Finally, generate the type definitions by rerunning the `cf-typegen` script.

Now you are ready to create the upload endpoint. Create a new `upload.put.ts` file in your `server/api` directory, and add the following code to it:

```ts title="server/api/upload.put.ts"
export default defineEventHandler(async (event) => {
  const { cloudflare } = event.context;

  const form = await readFormData(event);
  const files = form.getAll('files') as File[];
  if (!files) {
    throw createError({ statusCode: 400, message: 'Missing files' });
  }

  const uploadKeys: string[] = [];
  for (const file of files) {
    const obj = await cloudflare.env.R2.put(`recordings/${file.name}`, file);
    if (obj) {
      uploadKeys.push(obj.key);
    }
  }

  return uploadKeys;
});
```

The above code does the following:

1. The files variable retrieves all files sent by the client using form.getAll(), which allows for multiple uploads in a single request.
2. Uploads the files to the R2 bucket using the binding (`R2`) you created earlier.

:::note
The `recordings/` prefix organizes uploaded files within a dedicated folder in your bucket. This will also come in handy when serving these recordings to the client (covered later).
:::

## 4. Create an API endpoint to save notes entries

Before creating the endpoint, you will need to perform steps similar to those for the R2 bucket, with some additional steps to prepare a notes table.

Create a `D1` database.

<PackageManagers type="exec" pkg="wrangler" args="d1 create <DB_NAME>" />

Add the D1 bindings to the Wrangler file. You can get the `DB_ID` from the output of the `d1 create` command.

```toml title="wrangler.toml"
[[d1_databases]]
binding = "DB"
database_name = "<DB_NAME>"
database_id = "<DB_ID>"
```

As before, rerun the `cf-typegen` command to generate the types.

Next, create a DB migration.

<PackageManagers type="exec" pkg="wrangler" args={`d1 migrations create <DB_NAME> "create notes table"`} />

This will create a new `migrations` folder in the project's root directory, and add an empty `0001_create_notes_table.sql` file to it. Replace the contents of this file with the code below.

```sql
CREATE TABLE IF NOT EXISTS notes (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 text TEXT NOT NULL,
 created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
 updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
 audio_urls TEXT
);
```

And then apply this migration to create the `notes` table.

<PackageManagers type="exec" pkg="wrangler" args="d1 migrations apply <DB_NAME>" />

:::note
The above command will create the notes table locally. To apply the migration on your remote production database, use the `--remote` flag.
:::

Now you can create the API endpoint. Create a new file `index.post.ts` in the `server/api/notes` directory, and change its content to the following:

```ts title="server/api/notes/index.post.ts"
export default defineEventHandler(async (event) => {
  const { cloudflare } = event.context;

  const { text, audioUrls } = await readBody(event);
  if (!text) {
    throw createError({
      statusCode: 400,
      message: 'Missing note text',
    });
  }

  try {
    await cloudflare.env.DB.prepare(
      'INSERT INTO notes (text, audio_urls) VALUES (?1, ?2)'
    )
      .bind(text, audioUrls ? JSON.stringify(audioUrls) : null)
      .run();

    return setResponseStatus(event, 201);
  } catch (err) {
    console.error('Error creating note:', err);
    throw createError({
      statusCode: 500,
      message: 'Failed to create note. Please try again.',
    });
  }
});
```

The above does the following:

1. Extracts the text, and optional audioUrls from the event.
2. Saves it to the database after converting the audioUrls to a `JSON` string.

## 5. Handle note creation on the client-side

Now you're ready to work on the client side. Let's start by tackling the note creation part first.

### Recording user audio

Create a composable to handle audio recording using the MediaRecorder API. This will be used to record notes through the user's microphone.

Create a new file `useMediaRecorder.ts` in the `app/composables` folder, and add the following code to it:

```ts title="app/composables/useMediaRecorder.ts"
interface MediaRecorderState {
  isRecording: boolean;
  recordingDuration: number;
  audioData: Uint8Array | null;
  updateTrigger: number;
}

export function useMediaRecorder() {
  const state = ref<MediaRecorderState>({
    isRecording: false,
    recordingDuration: 0,
    audioData: null,
    updateTrigger: 0,
  });

  let mediaRecorder: MediaRecorder | null = null;
  let audioContext: AudioContext | null = null;
  let analyser: AnalyserNode | null = null;
  let animationFrame: number | null = null;
  let audioChunks: Blob[] | undefined = undefined;

  const updateAudioData = () => {
    if (!analyser || !state.value.isRecording || !state.value.audioData) {
      if (animationFrame) {
        cancelAnimationFrame(animationFrame);
        animationFrame = null;
      }

      return;
    }

    analyser.getByteTimeDomainData(state.value.audioData);
    state.value.updateTrigger += 1;
    animationFrame = requestAnimationFrame(updateAudioData);
  };

  const startRecording = async () => {
    try {
      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });

      audioContext = new AudioContext();
      analyser = audioContext.createAnalyser();

      const source = audioContext.createMediaStreamSource(stream);
      source.connect(analyser);

      mediaRecorder = new MediaRecorder(stream);
      audioChunks = [];

      mediaRecorder.ondataavailable = (e: BlobEvent) => {
        audioChunks?.push(e.data);
        state.value.recordingDuration += 1;
      };

      state.value.audioData = new Uint8Array(analyser.frequencyBinCount);
      state.value.isRecording = true;
      state.value.recordingDuration = 0;
      state.value.updateTrigger = 0;
      mediaRecorder.start(1000);

      updateAudioData();
    } catch (err) {
      console.error('Error accessing microphone:', err);
      throw err;
    }
  };

  const stopRecording = async () => {
    return await new Promise<Blob>((resolve) => {
      if (mediaRecorder && state.value.isRecording) {
        mediaRecorder.onstop = () => {
          const blob = new Blob(audioChunks, { type: 'audio/webm' });
          audioChunks = undefined;

          state.value.recordingDuration = 0;
          state.value.updateTrigger = 0;
          state.value.audioData = null;

          resolve(blob);
        };

        state.value.isRecording = false;
        mediaRecorder.stop();
        mediaRecorder.stream.getTracks().forEach((track) => track.stop());

        if (animationFrame) {
          cancelAnimationFrame(animationFrame);
          animationFrame = null;
        }

        audioContext?.close();
        audioContext = null;
      }
    });
  };

  onUnmounted(() => {
    stopRecording();
  });

  return {
    state: readonly(state),
    startRecording,
    stopRecording,
  };
}
```

The above code does the following:

1. Exposes functions to start and stop audio recordings in a Vue application.
2. Captures audio input from the user's microphone using MediaRecorder API.
3. Processes real-time audio data for visualization using AudioContext and AnalyserNode.
4. Stores recording state including duration and recording status.
5. Maintains chunks of audio data and combines them into a final audio blob when recording stops.
6. Updates audio visualization data continuously using animation frames while recording.
7. Automatically cleans up all audio resources when recording stops or component unmounts.
8. Returns audio recordings in webm format for further processing.

### Create a component for note creation

This component allows users to create notes by either typing or recording audio. It also handles audio transcription and uploading the recordings to the server.

Create a new file named `CreateNote.vue` inside the `app/components` folder. Add the following template code to the newly created file:

```vue title="app/components/CreateNote.vue"
<template>
  <div class="flex flex-col gap-y-5">
    <div
      class="flex flex-col h-full md:flex-row gap-y-4 md:gap-x-6 overflow-hidden p-px"
    >
      <UCard
        :ui="{
          base: 'h-full flex flex-col flex-1',
          body: { base: 'flex-grow' },
          header: { base: 'md:h-[72px]' },
        }"
      >
        <template #header>
          <h3
            class="text-base md:text-lg font-medium text-gray-600 dark:text-gray-300"
          >
            Note transcript
          </h3>
        </template>
        <UTextarea
          v-model="note"
          placeholder="Type your note or use voice recording..."
          size="lg"
          autofocus
          :disabled="loading || isTranscribing || state.isRecording"
          :rows="10"
        />
      </UCard>

      <UCard
        class="md:h-full md:flex md:flex-col md:w-96 shrink-0 order-first md:order-none"
        :ui="{
          body: { base: 'max-h-36 md:max-h-none md:flex-grow overflow-y-auto' },
        }"
      >
        <template #header>
          <h3
            class="text-base md:text-lg font-medium text-gray-600 dark:text-gray-300"
          >
            Note recordings
          </h3>

          <UTooltip
            :text="state.isRecording ? 'Stop Recording' : 'Start Recording'"
          >
            <UButton
              :icon="
                state.isRecording
                  ? 'i-heroicons-stop-circle'
                  : 'i-heroicons-microphone'
              "
              :color="state.isRecording ? 'red' : 'primary'"
              :loading="isTranscribing"
              @click="toggleRecording"
            />
          </UTooltip>
        </template>

        <AudioVisualizer
          v-if="state.isRecording"
          class="w-full h-14 p-2 bg-gray-50 dark:bg-gray-800 rounded-lg mb-2"
          :audio-data="state.audioData"
          :data-update-trigger="state.updateTrigger"
        />

        <div
          v-else-if="isTranscribing"
          class="flex items-center justify-center h-14 gap-x-3 p-2 bg-gray-50 dark:bg-gray-800 rounded-lg mb-2 text-gray-500 dark:text-gray-400"
        >
          <UIcon
            name="i-heroicons-arrow-path-20-solid"
            class="w-6 h-6 animate-spin"
          />
          Transcribing...
        </div>

        <RecordingsList :recordings="recordings" @delete="deleteRecording" />

        <div
          v-if="!recordings.length && !state.isRecording && !isTranscribing"
          class="h-full flex items-center justify-center text-gray-500 dark:text-gray-400"
        >
          No recordings...
        </div>
      </UCard>
    </div>

    <UDivider />

    <div class="flex justify-end gap-x-4">
      <UButton
        icon="i-heroicons-trash"
        color="gray"
        size="lg"
        variant="ghost"
        :disabled="loading"
        @click="clearNote"
      >
        Clear
      </UButton>
      <UButton
        icon="i-heroicons-cloud-arrow-up"
        size="lg"
        :loading="loading"
        :disabled="!note.trim() && !state.isRecording"
        @click="saveNote"
      >
        Save
      </UButton>
    </div>
  </div>
</template>
```

The above template results in the following:

1. A panel with a `textarea` inside to type the note manually.
2. Another panel to manage start/stop of an audio recording, and show the recordings done already.
3. A bottom panel to reset or save the note (along with the recordings).

Now, add the following code below the template code in the same file:

```vue title="app/components/CreateNote.vue"
<script setup lang="ts">
import type { Recording, Settings } from '~~/types';

const emit = defineEmits<{
  (e: 'created'): void;
}>();

const note = ref('');
const loading = ref(false);
const isTranscribing = ref(false);
const { state, startRecording, stopRecording } = useMediaRecorder();
const recordings = ref<Recording[]>([]);

const handleRecordingStart = async () => {
  try {
    await startRecording();
  } catch (err) {
    console.error('Error accessing microphone:', err);
    useToast().add({
      title: 'Error',
      description: 'Could not access microphone. Please check permissions.',
      color: 'red',
    });
  }
};

const handleRecordingStop = async () => {
  let blob: Blob | undefined;

  try {
    blob = await stopRecording();
  } catch (err) {
    console.error('Error stopping recording:', err);
    useToast().add({
      title: 'Error',
      description: 'Failed to record audio. Please try again.',
      color: 'red',
    });
  }

  if (blob) {
    try {
      const transcription = await transcribeAudio(blob);

      note.value += note.value ? '\n\n' : '';
      note.value += transcription ?? '';

      recordings.value.unshift({
        url: URL.createObjectURL(blob),
        blob,
        id: `${Date.now()}`,
      });
    } catch (err) {
      console.error('Error transcribing audio:', err);
      useToast().add({
        title: 'Error',
        description: 'Failed to transcribe audio. Please try again.',
        color: 'red',
      });
    }
  }
};

const toggleRecording = () => {
  if (state.value.isRecording) {
    handleRecordingStop();
  } else {
    handleRecordingStart();
  }
};

const transcribeAudio = async (blob: Blob) => {
  try {
    isTranscribing.value = true;
    const formData = new FormData();
    formData.append('audio', blob);

    return await $fetch('/api/transcribe', {
      method: 'POST',
      body: formData,
    });
  } finally {
    isTranscribing.value = false;
  }
};

const clearNote = () => {
  note.value = '';
  recordings.value = [];
};

const saveNote = async () => {
  if (!note.value.trim()) return;

  loading.value = true;

  const noteToSave: { text: string; audioUrls?: string[] } = {
    text: note.value.trim(),
  };

  try {
    if (recordings.value.length) {
      noteToSave.audioUrls = await uploadRecordings();
    }

    await $fetch('/api/notes', {
      method: 'POST',
      body: noteToSave,
    });

    useToast().add({
      title: 'Success',
      description: 'Note saved successfully',
      color: 'green',
    });

    note.value = '';
    recordings.value = [];

    emit('created');
  } catch (err) {
    console.error('Error saving note:', err);
    useToast().add({
      title: 'Error',
      description: 'Failed to save note',
      color: 'red',
    });
  } finally {
    loading.value = false;
  }
};

const deleteRecording = (recording: Recording) => {
  recordings.value = recordings.value.filter((r) => r.id !== recording.id);
};

const uploadRecordings = async () => {
  if (!recordings.value.length) return;

  const formData = new FormData();
  recordings.value.forEach((recording) => {
    formData.append('files', recording.blob, recording.id + '.webm');
  });

  const uploadKeys = await $fetch('/api/upload', {
    method: 'PUT',
    body: formData,
  });

  return uploadKeys;
};
</script>
```

The above code does the following:

1. When a recording is stopped by calling `handleRecordingStop` function, the audio blob is sent for transcribing to the transcribe API endpoint.
2. The transcription response text is appended to the existing textarea content.
3. When the note is saved by calling the `saveNote` function, the audio recordings are uploaded first to R2 by using the upload endpoint we created earlier. Then, the actual note content along with the audioUrls (the R2 object keys) are saved by calling the notes post endpoint.

### Create a new page route for showing the component

You can use this component in a Nuxt page to show it to the user. But before that you need to modify your `app.vue` file. Update the content of your `app.vue` to the following:

```vue title="/app/app.vue"
<template>
  <NuxtRouteAnnouncer />
  <NuxtLoadingIndicator />
  <div class="h-screen flex flex-col md:flex-row">
    <USlideover
      v-model="isDrawerOpen"
      class="md:hidden"
      side="left"
      :ui="{ width: 'max-w-xs' }"
    >
      <AppSidebar :links="links" @hide-drawer="isDrawerOpen = false" />
    </USlideover>

    <!-- The App Sidebar -->
    <AppSidebar :links="links" class="hidden md:block md:w-64" />

    <div class="flex-1 h-full min-w-0 bg-gray-50 dark:bg-gray-950">
      <!-- The App Header -->
      <AppHeader :title="title" @show-drawer="isDrawerOpen = true">
        <template #actions v-if="route.path === '/'">
          <UButton icon="i-heroicons-plus" @click="navigateTo('/new')">
            New Note
          </UButton>
        </template>
      </AppHeader>

      <!-- Main Page Content -->
      <main class="p-4 sm:p-6 h-[calc(100vh-3.5rem)] overflow-y-auto">
        <NuxtPage />
      </main>
    </div>
  </div>
  <UNotifications />
</template>

<script setup lang="ts">
const isDrawerOpen = ref(false);
const links = [
  {
    label: 'Notes',
    icon: 'i-heroicons-document-text',
    to: '/',
    click: () => (isDrawerOpen.value = false),
  },
  {
    label: 'Settings',
    icon: 'i-heroicons-cog',
    to: '/settings',
    click: () => (isDrawerOpen.value = false),
  },
];

const route = useRoute();
const title = computed(() => {
  const activeLink = links.find((l) => l.to === route.path);
  if (activeLink) {
    return activeLink.label;
  }

  return '';
});
</script>
```

The above code allows for a nuxt page to be shown to the user, apart from showing an app header and a navigation sidebar.

Next, add a new file named `new.vue` inside the `app/pages` folder, add the following code to it:

```vue title="app/pages/new.vue"
<template>
  <UModal v-model="isOpen" fullscreen>
    <UCard
      :ui="{
        base: 'h-full flex flex-col',
        rounded: '',
        body: {
          base: 'flex-grow overflow-hidden',
        },
      }"
    >
      <template #header>
        <h2 class="text-xl md:text-2xl font-semibold leading-6">Create note</h2>
        <UButton
          color="gray"
          variant="ghost"
          icon="i-heroicons-x-mark-20-solid"
          @click="closeModal"
        />
      </template>

      <CreateNote class="max-w-7xl mx-auto h-full" @created="closeModal" />
    </UCard>
  </UModal>
</template>

<script setup lang="ts">
const isOpen = ref(true);

const router = useRouter();
const closeModal = () => {
  isOpen.value = false;

  if (window.history.length > 2) {
    router.back();
  } else {
    navigateTo({
      path: '/',
      replace: true,
    });
  }
};
</script>
```

The above code shows the `CreateNote` component inside a modal, and navigates back to the home page on successful note creation.

## 6. Showing the notes on the client side

To show the notes from the database on the client side, create an API endpoint first that will interact with the database.

### Create an API endpoint to fetch notes from the database

Create a new file named `index.get.ts` inside the `server/api/notes` directory, and add the following code to it:

```ts title="server/api/index.get.ts"
import type { Note } from '~~/types';

export default defineEventHandler(async (event) => {
  const { cloudflare } = event.context;

  const res = await cloudflare.env.DB.prepare(
    `SELECT
      id,
      text,
      audio_urls AS audioUrls,
      created_at AS createdAt,
      updated_at AS updatedAt
    FROM notes
    ORDER BY created_at DESC
    LIMIT 50;`
  ).all<Omit<Note, 'audioUrls'> & { audioUrls: string | null }>();

  return res.results.map((note) => ({
    ...note,
    audioUrls: note.audioUrls ? JSON.parse(note.audioUrls) : undefined,
  }));
});
```

The above code fetches the last 50 notes from the database, ordered by their creation date in descending order. The `audio_urls` field is stored as a string in the database, but it's converted to an array using `JSON.parse` to handle multiple audio files seamlessly on the client side.

Next, create a page named `index.vue` inside the `app/pages` directory. This will be the home page of the application. Add the following code to it:

```vue title="app/pages/index.vue"
<template>
  <div :class="{ 'flex h-full': !notes?.length }">
    <div v-if="notes?.length" class="space-y-4 sm:space-y-6">
      <NoteCard v-for="note in notes" :key="note.id" :note="note" />
    </div>
    <div
      v-else
      class="flex-1 self-center text-center text-gray-500 dark:text-gray-400 space-y-2"
    >
      <h2 class="text-2xl md:text-3xl">No notes created</h2>
      <p>Get started by creating your first note</p>
    </div>
  </div>
</template>

<script setup lang="ts">
import type { Note } from '~~/types';

const { data: notes } = await useFetch<Note[]>('/api/notes');
</script>
```

The above code fetches the notes from the database by calling the `/api/notes` endpoint you created just now, and renders them as note cards.

### Serving the saved recordings from R2

To be able to play the audio recordings of these notes, you need to serve the saved recordings from the R2 storage.

Create a new file named `[...pathname].get.ts` inside the `server/routes/recordings` directory, and add the following code to it:

:::note
The `...` prefix in the file name makes it a catch all route. This allows it to receive all events that are meant for paths starting with `/recordings` prefix. This is where the `recordings` prefix that was added previously while saving the recordings becomes helpful.
:::

```ts title="server/routes/recordings/[...pathname].get.ts"
export default defineEventHandler(async (event) => {
  const { cloudflare, params } = event.context;

  const { pathname } = params || {};

  return cloudflare.env.R2.get(`recordings/${pathname}`);
});
```

The above code extracts the path name from the event params, and serves the saved recording matching that object key from the R2 bucket.

## 7. [Optional] Post Processing the transcriptions

Even though the speech-to-text transcriptions models perform satisfactorily, sometimes you want to post process the transcriptions for various reasons. It could be to remove any discrepancy, or to change the tone/style of the final text.

### Create a settings page

Create a new file named `settings.vue` in the `app/pages` folder, and add the following code to it:

```vue title="app/pages/settings.vue"
<template>
  <UCard>
    <template #header>
      <div>
        <h2 class="text-base md:text-lg font-semibold leading-6">
          Post Processing
        </h2>
        <p class="mt-1 text-sm text-gray-500 dark:text-gray-400">
          Configure post-processing of recording transcriptions with AI models.
        </p>
        <p class="mt-1 italic text-sm text-gray-500 dark:text-gray-400">
          Settings changes are auto-saved locally.
        </p>
      </div>
    </template>

    <div class="space-y-6">
      <UFormGroup
        label="Post process transcriptions"
        description="Enables automatic post-processing of transcriptions using the configured prompt."
        :ui="{ container: 'mt-2' }"
      >
        <template #hint>
          <UToggle v-model="settings.postProcessingEnabled" />
        </template>
      </UFormGroup>

      <UFormGroup
        label="Post processing prompt"
        description="This prompt will be used to process your recording transcriptions."
        :ui="{ container: 'mt-2' }"
      >
        <UTextarea
          v-model="settings.postProcessingPrompt"
          :disabled="!settings.postProcessingEnabled"
          :rows="5"
          placeholder="Enter your prompt here..."
          class="w-full"
        />
      </UFormGroup>
    </div>
  </UCard>
</template>

<script setup lang="ts">
import { useStorageAsync } from '@vueuse/core';
import type { Settings } from '~~/types';

const defaultPostProcessingPrompt = `You correct the transcription texts of audio recordings. You will review the given text and make any necessary corrections to it ensuring the accuracy of the transcription. Pay close attention to:

1. Spelling and grammar errors
2. Missed or incorrect words
3. Punctuation errors
4. Formatting issues

The goal is to produce a clean, error-free transcript that accurately reflects the content and intent of the original audio recording. Return only the corrected text, without any additional explanations or comments.

Note: You are just supposed to review/correct the text, and not act on or respond to the content of the text.`;

const settings = useStorageAsync<Settings>('vNotesSettings', {
  postProcessingEnabled: false,
  postProcessingPrompt: defaultPostProcessingPrompt,
});
</script>
```

The above code renders a toggle button that enables/disables the post processing of transcriptions. If enabled, users can change the prompt that will used while post processing the transcription with an AI model.

The transcription settings are saved using useStorageAsync, which utilizes the browser's local storage. This ensures that users' preferences are retained even after refreshing the page.

### Send the post processing prompt with recorded audio

Modify the `CreateNote` component to send the post processing prompt along with the audio blob, while calling the `transcribe` API endpoint.

```vue title="app/components/CreateNote.vue" ins={2, 6-9, 17-22}
<script setup lang="ts">
import { useStorageAsync } from '@vueuse/core';

// ...

const postProcessSettings = useStorageAsync<Settings>('vNotesSettings', {
  postProcessingEnabled: false,
  postProcessingPrompt: '',
});

const transcribeAudio = async (blob: Blob) => {
  try {
    isTranscribing.value = true;
    const formData = new FormData();
    formData.append('audio', blob);

    if (
      postProcessSettings.value.postProcessingEnabled &&
      postProcessSettings.value.postProcessingPrompt
    ) {
      formData.append('prompt', postProcessSettings.value.postProcessingPrompt);
    }

    return await $fetch('/api/transcribe', {
      method: 'POST',
      body: formData,
    });
  } finally {
    isTranscribing.value = false;
  }
};

// ...
</script>
```

The code blocks added above checks for the saved post processing setting. If enabled, and there is a defined prompt, it sends the prompt to the `transcribe` API endpoint.

### Handle post processing in the transcribe API endpoint

Modify the transcribe API endpoint, and update it to the following:

```ts title="server/api/transcribe.post.ts" ins={9-20, 22}
export default defineEventHandler(async (event) => {
  // ...

  try {
    const response = await cloudflare.env.AI.run('@cf/openai/whisper', {
      audio: [...new Uint8Array(await blob.arrayBuffer())],
    });

    const postProcessingPrompt = form.get('prompt') as string;
    if (postProcessingPrompt && response.text) {
      const postProcessResult = await cloudflare.env.AI.run(
        '@cf/meta/llama-3.1-8b-instruct',
        {
          temperature: 0.3,
          prompt: `${postProcessingPrompt}.\n\nText:\n\n${response.text}\n\nResponse:`,
        }
      );

      return (postProcessResult as { response?: string }).response;
    } else {
      return response.text;
    }
  } catch (err) {
    // ...
  }
});
```

The above code does the following:

1. Extracts the post processing prompt from the event FormData.
2. If present, it calls the Workers AI API to process the transcription text using the `@cf/meta/llama-3.1-8b-instruct` model.
3. Finally, it returns the response from Workers AI to the client.

## 8. Deploy the application

Now you are ready to deploy the project to a `.workers.dev` sub-domain by running the deploy command.

<PackageManagers type="run" args="deploy" />

You can preview your application at `<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev`.

:::note
If you used `pnpm` as your package manager, you may face build errors like `"stdin" is not exported by "node_modules/.pnpm/unenv@1.10.0/node_modules/unenv/runtime/node/process/index.mjs"`. To resolve it, you can try hoisting your node modules with the [`shamefully-hoist-true`](https://pnpm.io/npmrc) option.
:::

## Conclusion

In this tutorial, you have gone through the steps of building a voice notes application using Nuxt 3, Cloudflare Workers, D1, and R2 storage. You learnt to:

- Set up the backend to store and manage notes
- Create API endpoints to fetch and display notes
- Handle audio recordings
- Implement optional post-processing for transcriptions
- Deploy the application using the Cloudflare module syntax

The complete source code of the project is available on GitHub. You can go through it to see the code for various frontend components not covered in the article. You can find it here: [github.com/ra-jeev/vnotes](https://github.com/ra-jeev/vnotes).

---

# Whisper-large-v3-turbo with Cloudflare Workers AI

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/build-a-workers-ai-whisper-with-chunking/

In this tutorial you will learn how to:

- **Transcribe large audio files:** Use the [Whisper-large-v3-turbo](/workers-ai/models/whisper-large-v3-turbo/) model from Cloudflare Workers AI to perform automatic speech recognition (ASR) or translation.
- **Handle large files:** Split large audio files into smaller chunks for processing, which helps overcome memory and execution time limitations.
- **Deploy using Cloudflare Workers:** Create a scalable, low‑latency transcription pipeline in a serverless environment.

## 1: Create a new Cloudflare Worker project

import { Render, PackageManagers, WranglerConfig } from "~/components";

<Render file="prereqs" product="workers" />

You will create a new Worker project using the `create-cloudflare` CLI (C3). [C3](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare) is a command-line tool designed to help you set up and deploy new applications to Cloudflare.

Create a new project named `whisper-tutorial` by running:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"whisper-tutorial"}
/>

Running `npm create cloudflare@latest` will prompt you to install the [`create-cloudflare` package](https://www.npmjs.com/package/create-cloudflare), and lead you through setup. C3 will also install [Wrangler](/workers/wrangler/), the Cloudflare Developer Platform CLI.

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

This will create a new `whisper-tutorial` directory. Your new `whisper-tutorial` directory will include:

- A `"Hello World"` [Worker](/workers/get-started/guide/#3-write-code) at `src/index.ts`.
- A [`wrangler.jsonc`](/workers/wrangler/configuration/) configuration file.

Go to your application directory:

```sh
cd whisper-tutorial
```

## 2. Connect your Worker to Workers AI

You must create an AI binding for your Worker to connect to Workers AI. [Bindings](/workers/runtime-apis/bindings/) allow your Workers to interact with resources, like Workers AI, on the Cloudflare Developer Platform.

To bind Workers AI to your Worker, add the following to the end of your `wrangler.toml` file:

<WranglerConfig>

```toml
[ai]
binding = "AI"
```

</WranglerConfig>

Your binding is [available in your Worker code](/workers/reference/migrate-to-module-workers/#bindings-in-es-modules-format) on [`env.AI`](/workers/runtime-apis/handlers/fetch/).

## 3. Configure Wrangler

In your wrangler file, add or update the following settings to enable Node.js APIs and polyfills (with a compatibility date of 2024‑09‑23 or later):

<WranglerConfig>

```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_compat" ]
compatibility_date = "2024-09-23"
```

</WranglerConfig>

## 4. Handle large audio files with chunking

Replace the contents of your `src/index.ts` file with the following integrated code. This sample demonstrates how to:

(1) Extract an audio file URL from the query parameters.

(2) Fetch the audio file while explicitly following redirects.

(3) Split the audio file into smaller chunks (such as, 1 MB chunks).

(4) Transcribe each chunk using the Whisper-large-v3-turbo model via the Cloudflare AI binding.

(5) Return the aggregated transcription as plain text.

```ts
import { Buffer } from "node:buffer";
import type { Ai } from "workers-ai";

export interface Env {
	AI: Ai;
	// If needed, add your KV namespace for storing transcripts.
	// MY_KV_NAMESPACE: KVNamespace;
}

/**
 * Fetches the audio file from the provided URL and splits it into chunks.
 * This function explicitly follows redirects.
 *
 * @param audioUrl - The URL of the audio file.
 * @returns An array of ArrayBuffers, each representing a chunk of the audio.
 */
async function getAudioChunks(audioUrl: string): Promise<ArrayBuffer[]> {
	const response = await fetch(audioUrl, { redirect: "follow" });
	if (!response.ok) {
		throw new Error(`Failed to fetch audio: ${response.status}`);
	}
	const arrayBuffer = await response.arrayBuffer();

	// Example: Split the audio into 1MB chunks.
	const chunkSize = 1024 * 1024; // 1MB
	const chunks: ArrayBuffer[] = [];
	for (let i = 0; i < arrayBuffer.byteLength; i += chunkSize) {
		const chunk = arrayBuffer.slice(i, i + chunkSize);
		chunks.push(chunk);
	}
	return chunks;
}

/**
 * Transcribes a single audio chunk using the Whisper‑large‑v3‑turbo model.
 * The function converts the audio chunk to a Base64-encoded string and
 * sends it to the model via the AI binding.
 *
 * @param chunkBuffer - The audio chunk as an ArrayBuffer.
 * @param env - The Cloudflare Worker environment, including the AI binding.
 * @returns The transcription text from the model.
 */
async function transcribeChunk(
	chunkBuffer: ArrayBuffer,
	env: Env,
): Promise<string> {
	const base64 = Buffer.from(chunkBuffer, "binary").toString("base64");
	const res = await env.AI.run("@cf/openai/whisper-large-v3-turbo", {
		audio: base64,
		// Optional parameters (uncomment and set if needed):
		// task: "transcribe",   // or "translate"
		// language: "en",
		// vad_filter: "false",
		// initial_prompt: "Provide context if needed.",
		// prefix: "Transcription:",
	});
	return res.text; // Assumes the transcription result includes a "text" property.
}

/**
 * The main fetch handler. It extracts the 'url' query parameter, fetches the audio,
 * processes it in chunks, and returns the full transcription.
 */
export default {
	async fetch(
		request: Request,
		env: Env,
		ctx: ExecutionContext,
	): Promise<Response> {
		// Extract the audio URL from the query parameters.
		const { searchParams } = new URL(request.url);
		const audioUrl = searchParams.get("url");

		if (!audioUrl) {
			return new Response("Missing 'url' query parameter", { status: 400 });
		}

		// Get the audio chunks.
		const audioChunks: ArrayBuffer[] = await getAudioChunks(audioUrl);
		let fullTranscript = "";

		// Process each chunk and build the full transcript.
		for (const chunk of audioChunks) {
			try {
				const transcript = await transcribeChunk(chunk, env);
				fullTranscript += transcript + "\n";
			} catch (error) {
				fullTranscript += "[Error transcribing chunk]\n";
			}
		}

		return new Response(fullTranscript, {
			headers: { "Content-Type": "text/plain" },
		});
	},
} satisfies ExportedHandler<Env>;
```

## 5. Deploy your Worker

1. **Run the Worker locally:**

   Use wrangler's development mode to test your Worker locally:

```sh
npx wrangler dev
```

Open your browser and go to [http://localhost:8787](http://localhost:8787), or use curl:

```sh
curl "http://localhost:8787?url=https://raw.githubusercontent.com/your-username/your-repo/main/your-audio-file.mp3"
```

Replace the URL query parameter with the direct link to your audio file. (For GitHub-hosted files, ensure you use the raw file URL.)

2. **Deploy the Worker:**

   Once testing is complete, deploy your Worker with:

```sh
npx wrangler deploy
```

3. **Test the deployed Worker:**

   After deployment, test your Worker by passing the audio URL as a query parameter:

```sh
curl "https://<your-worker-subdomain>.workers.dev?url=https://raw.githubusercontent.com/your-username/your-repo/main/your-audio-file.mp3"
```

Make sure to replace `<your-worker-subdomain>`, `your-username`, `your-repo`, and `your-audio-file.mp3` with your actual details.

If successful, the Worker will return a transcript of the audio file:

```sh
This is the transcript of the audio...
```

---

# Build an interview practice tool with Workers AI

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/build-ai-interview-practice-tool/

import { Render, PackageManagers } from "~/components";

Job interviews can be stressful, and practice is key to building confidence. While traditional mock interviews with friends or mentors are valuable, they are not always available when you need them. In this tutorial, you will learn how to build an AI-powered interview practice tool that provides real-time feedback to help improve interview skills.

By the end of this tutorial, you will have built a complete interview practice tool with the following core functionalities:

- A real-time interview simulation tool using WebSocket connections
- An AI-powered speech processing pipeline that converts audio to text
- An intelligent response system that provides interviewer-like interactions
- A persistent storage system for managing interview sessions and history using Durable Objects

<Render file="tutorials-before-you-start" product="workers" />
<Render file="prereqs" product="workers" />

### Prerequisites

This tutorial demonstrates how to use multiple Cloudflare products and while many features are available in free tiers, some components of Workers AI may incur usage-based charges. Please review the pricing documentation for Workers AI before proceeding.

<Render file="ai-local-usage-charges" product="workers" />

## 1. Create a new Worker project

Create a Cloudflare Workers project using the Create Cloudflare CLI (C3) tool and the Hono framework.

:::note
[Hono](https://hono.dev) is a lightweight web framework that helps build API endpoints and handle HTTP requests. This tutorial uses Hono to create and manage the application's routing and middleware components.
:::

Create a new Worker project by running the following commands, using `ai-interview-tool` as the Worker name:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"ai-interview-tool"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "web-framework",
		framework: "Hono",
	}}
/>

To develop and test your Cloudflare Workers application locally:

1. Navigate to your Workers project directory in your terminal:

```sh
cd ai-interview-tool
```

2. Start the development server by running:

```sh
npx wrangler dev
```

When you run `wrangler dev`, the command starts a local development server and provides a `localhost` URL where you can preview your application.
You can now make changes to your code and see them reflected in real-time at the provided localhost address.

## 2. Define TypeScript types for the interview system

Now that the project is set up, create the TypeScript types that will form the foundation of the interview system. These types will help you maintain type safety and provide clear interfaces for the different components of your application.

Create a new file `types.ts` that will contain essential types and enums for:

- Interview skills that can be assessed (JavaScript, React, etc.)
- Different interview positions (Junior Developer, Senior Developer, etc.)
- Interview status tracking
- Message handling between user and AI
- Core interview data structure

```typescript title="src/types.ts"
import { Context } from "hono";

// Context type for API endpoints, including environment bindings and user info
export interface ApiContext {
	Bindings: CloudflareBindings;
	Variables: {
		username: string;
	};
}

export type HonoCtx = Context<ApiContext>;

// List of technical skills you can assess during mock interviews.
// This application focuses on popular web technologies and programming languages
// that are commonly tested in real interviews.
export enum InterviewSkill {
	JavaScript = "JavaScript",
	TypeScript = "TypeScript",
	React = "React",
	NodeJS = "NodeJS",
	Python = "Python",
}

// Available interview types based on different engineering roles.
// This helps tailor the interview experience and questions to
// match the candidate's target position.
export enum InterviewTitle {
	JuniorDeveloper = "Junior Developer Interview",
	SeniorDeveloper = "Senior Developer Interview",
	FullStackDeveloper = "Full Stack Developer Interview",
	FrontendDeveloper = "Frontend Developer Interview",
	BackendDeveloper = "Backend Developer Interview",
	SystemArchitect = "System Architect Interview",
	TechnicalLead = "Technical Lead Interview",
}

// Tracks the current state of an interview session.
// This will help you to manage the interview flow and show appropriate UI/actions
// at each stage of the process.
export enum InterviewStatus {
	Created = "created", // Interview is created but not started
	Pending = "pending", // Waiting for interviewer/system
	InProgress = "in_progress", // Active interview session
	Completed = "completed", // Interview finished successfully
	Cancelled = "cancelled", // Interview terminated early
}

// Defines who sent a message in the interview chat
export type MessageRole = "user" | "assistant" | "system";

// Structure of individual messages exchanged during the interview
export interface Message {
	messageId: string; // Unique identifier for the message
	interviewId: string; // Links message to specific interview
	role: MessageRole; // Who sent the message
	content: string; // The actual message content
	timestamp: number; // When the message was sent
}

// Main data structure that holds all information about an interview session.
// This includes metadata, messages exchanged, and the current status.
export interface InterviewData {
	interviewId: string;
	title: InterviewTitle;
	skills: InterviewSkill[];
	messages: Message[];
	status: InterviewStatus;
	createdAt: number;
	updatedAt: number;
}

// Input format for creating a new interview session.
// Simplified interface that accepts basic parameters needed to start an interview.
export interface InterviewInput {
	title: string;
	skills: string[];
}
```

## 3. Configure error types for different services

Next, set up custom error types to handle different kinds of errors that may occur in your application. This includes:

- Database errors (for example, connection issues, query failures)
- Interview-related errors (for example, invalid input, transcription failures)
- Authentication errors (for example, invalid sessions)

Create the following `errors.ts` file:

```typescript title="src/errors.ts"
export const ErrorCodes = {
	INVALID_MESSAGE: "INVALID_MESSAGE",
	TRANSCRIPTION_FAILED: "TRANSCRIPTION_FAILED",
	LLM_FAILED: "LLM_FAILED",
	DATABASE_ERROR: "DATABASE_ERROR",
} as const;

export class AppError extends Error {
	constructor(
		message: string,
		public statusCode: number,
	) {
		super(message);
		this.name = this.constructor.name;
	}
}

export class UnauthorizedError extends AppError {
	constructor(message: string) {
		super(message, 401);
	}
}

export class BadRequestError extends AppError {
	constructor(message: string) {
		super(message, 400);
	}
}

export class NotFoundError extends AppError {
	constructor(message: string) {
		super(message, 404);
	}
}

export class InterviewError extends Error {
	constructor(
		message: string,
		public code: string,
		public statusCode: number = 500,
	) {
		super(message);
		this.name = "InterviewError";
	}
}
```

## 4. Configure authentication middleware and user routes

In this step, you will implement a basic authentication system to track and identify users interacting with your AI interview practice tool. The system uses HTTP-only cookies to store usernames, allowing you to identify both the request sender and their corresponding Durable Object. This straightforward authentication approach requires users to provide a username, which is then stored securely in a cookie. This approach allows you to:

- Identify users across requests
- Associate interview sessions with specific users
- Secure access to interview-related endpoints

### Create the Authentication Middleware

Create a middleware function that will check for the presence of a valid authentication cookie. This middleware will be used to protect routes that require authentication.

Create a new middleware file `middleware/auth.ts`:

```typescript title="src/middleware/auth.ts"
import { Context } from "hono";
import { getCookie } from "hono/cookie";
import { UnauthorizedError } from "../errors";

export const requireAuth = async (ctx: Context, next: () => Promise<void>) => {
	// Get username from cookie
	const username = getCookie(ctx, "username");

	if (!username) {
		throw new UnauthorizedError("User is not logged in");
	}

	// Make username available to route handlers
	ctx.set("username", username);
	await next();
};
```

This middleware:

- Checks for a `username` cookie
- Throws an `Error` if the cookie is missing
- Makes the username available to downstream handlers via the context

### Create Authentication Routes

Next, create the authentication routes that will handle user login. Create a new file `routes/auth.ts`:

```typescript title="src/routes/auth.ts"
import { Context, Hono } from "hono";
import { setCookie } from "hono/cookie";
import { BadRequestError } from "../errors";
import { ApiContext } from "../types";

export const authenticateUser = async (ctx: Context) => {
	// Extract username from request body
	const { username } = await ctx.req.json();

	// Make sure username was provided
	if (!username) {
		throw new BadRequestError("Username is required");
	}

	// Create a secure cookie to track the user's session
	// This cookie will:
	// - Be HTTP-only for security (no JS access)
	// - Work across all routes via path="/"
	// - Last for 24 hours
	// - Only be sent in same-site requests to prevent CSRF
	setCookie(ctx, "username", username, {
		httpOnly: true,
		path: "/",
		maxAge: 60 * 60 * 24,
		sameSite: "Strict",
	});

	// Let the client know login was successful
	return ctx.json({ success: true });
};

// Set up authentication-related routes
export const configureAuthRoutes = () => {
	const router = new Hono<ApiContext>();

	// POST /login - Authenticate user and create session
	router.post("/login", authenticateUser);

	return router;
};
```

Finally, update main application file to include the authentication routes. Modify `src/index.ts`:

```typescript title="src/index.ts"
import { configureAuthRoutes } from "./routes/auth";
import { Hono } from "hono";
import { logger } from "hono/logger";
import type { ApiContext } from "./types";
import { requireAuth } from "./middleware/auth";

// Create our main Hono app instance with proper typing
const app = new Hono<ApiContext>();

// Create a separate router for API endpoints to keep things organized
const api = new Hono<ApiContext>();

// Set up global middleware that runs on every request
// - Logger gives us visibility into what is happening
app.use("*", logger());

// Wire up all our authentication routes (login, etc)
// These will be mounted under /api/v1/auth/
api.route("/auth", configureAuthRoutes());

// Mount all API routes under the version prefix (for example, /api/v1)
// This allows us to make breaking changes in v2 without affecting v1 users
app.route("/api/v1", api);

export default app;
```

Now we have a basic authentication system that:

1. Provides a login endpoint at `/api/v1/auth/login`
2. Securely stores the username in a cookie
3. Includes middleware to protect authenticated routes

## 5. Create a Durable Object to manage interviews

Now that you have your authentication system in place, create a Durable Object to manage interview sessions. Durable Objects are perfect for this interview practice tool because they provide the following functionalities:

- Maintains states between connections, so users can reconnect without losing progress.
- Provides a SQLite database to store all interview Q&A, feedback and metrics.
- Enables smooth real-time interactions between the interviewer AI and candidate.
- Handles multiple interview sessions efficiently without performance issues.
- Creates a dedicated instance for each user, giving them their own isolated environment.

First, you will need to configure the Durable Object in Wrangler file. Add the following configuration:

```toml title="wrangler.toml"
[[durable_objects.bindings]]
name = "INTERVIEW"
class_name = "Interview"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["Interview"]
```

Next, create a new file `interview.ts` to define our Interview Durable Object:

```typescript title="src/interview.ts"
import { DurableObject } from "cloudflare:workers";

export class Interview extends DurableObject<CloudflareBindings> {
	// We will use it to keep track of all active WebSocket connections for real-time communication
	private sessions: Map<WebSocket, { interviewId: string }>;

	constructor(state: DurableObjectState, env: CloudflareBindings) {
		super(state, env);

		// Initialize empty sessions map - we will add WebSocket connections as users join
		this.sessions = new Map();
	}

	// Entry point for all HTTP requests to this Durable Object
	// This will handle both initial setup and WebSocket upgrades
	async fetch(request: Request) {
		// For now, just confirm the object is working
		// We'll add WebSocket upgrade logic and request routing later
		return new Response("Interview object initialized");
	}

	// Broadcasts a message to all connected WebSocket clients.
	private broadcast(message: string) {
		this.ctx.getWebSockets().forEach((ws) => {
			try {
				if (ws.readyState === WebSocket.OPEN) {
					ws.send(message);
				}
			} catch (error) {
				console.error(
					"Error broadcasting message to a WebSocket client:",
					error,
				);
			}
		});
	}
}
```

Now we need to export the Durable Object in our main `src/index.ts` file:

```typescript title="src/index.ts"
import { Interview } from "./interview";

// ... previous code ...

export { Interview };

export default app;
```

Since the Worker code is written in TypeScript, you should run the following command to add the necessary type definitions:

```sh
npm run cf-typegen
```

### Set up SQLite database schema to store interview data

Now you will use SQLite at the Durable Object level for data persistence. This gives each user their own isolated database instance. You will need two main tables:

- `interviews`: Stores interview session data
- `messages`: Stores all messages exchanged during interviews

Before you create these tables, create a service class to handle your database operations. This encapsulates database logic and helps you:

- Manage database schema changes
- Handle errors consistently
- Keep database queries organized

Create a new file called `services/InterviewDatabaseService.ts`:

```typescript title="src/services/InterviewDatabaseService.ts"
import {
	InterviewData,
	Message,
	InterviewStatus,
	InterviewTitle,
	InterviewSkill,
} from "../types";
import { InterviewError, ErrorCodes } from "../errors";

const CONFIG = {
	database: {
		tables: {
			interviews: "interviews",
			messages: "messages",
		},
		indexes: {
			messagesByInterview: "idx_messages_interviewId",
		},
	},
} as const;

export class InterviewDatabaseService {
	constructor(private sql: SqlStorage) {}

	/**
	 * Sets up the database schema by creating tables and indexes if they do not exist.
	 * This is called when initializing a new Durable Object instance to ensure
	 * we have the required database structure.
	 *
	 * The schema consists of:
	 * - interviews table: Stores interview metadata like title, skills, and status
	 * - messages table: Stores the conversation history between user and AI
	 * - messages index: Helps optimize queries when fetching messages for a specific interview
	 */
	createTables() {
		try {
			// Get list of existing tables to avoid recreating them
			const cursor = this.sql.exec(`PRAGMA table_list`);
			const existingTables = new Set([...cursor].map((table) => table.name));

			// The interviews table is our main table storing interview sessions.
			// We only create it if it does not exist yet.
			if (!existingTables.has(CONFIG.database.tables.interviews)) {
				this.sql.exec(InterviewDatabaseService.QUERIES.CREATE_INTERVIEWS_TABLE);
			}

			// The messages table stores the actual conversation history.
			// It references interviews table via foreign key for data integrity.
			if (!existingTables.has(CONFIG.database.tables.messages)) {
				this.sql.exec(InterviewDatabaseService.QUERIES.CREATE_MESSAGES_TABLE);
			}

			// Add an index on interviewId to speed up message retrieval.
			// This is important since we will frequently query messages by interview.
			this.sql.exec(InterviewDatabaseService.QUERIES.CREATE_MESSAGE_INDEX);
		} catch (error: unknown) {
			const message = error instanceof Error ? error.message : String(error);
			throw new InterviewError(
				`Failed to initialize database: ${message}`,
				ErrorCodes.DATABASE_ERROR,
			);
		}
	}

	private static readonly QUERIES = {
		CREATE_INTERVIEWS_TABLE: `
      CREATE TABLE IF NOT EXISTS interviews (
        interviewId TEXT PRIMARY KEY,
        title TEXT NOT NULL,
        skills TEXT NOT NULL,
        createdAt INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000),
        updatedAt INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000),
        status TEXT NOT NULL DEFAULT 'pending'
      )
    `,
		CREATE_MESSAGES_TABLE: `
      CREATE TABLE IF NOT EXISTS messages (
        messageId TEXT PRIMARY KEY,
        interviewId TEXT NOT NULL,
        role TEXT NOT NULL,
        content TEXT NOT NULL,
        timestamp INTEGER NOT NULL,
        FOREIGN KEY (interviewId) REFERENCES interviews(interviewId)
      )
    `,
		CREATE_MESSAGE_INDEX: `
      CREATE INDEX IF NOT EXISTS idx_messages_interview ON messages(interviewId)
    `,
	};
}
```

Update the `Interview` Durable Object to use the database service by modifying `src/interview.ts`:

```typescript title="src/interview.ts"
import { InterviewDatabaseService } from "./services/InterviewDatabaseService";

export class Interview extends DurableObject<CloudflareBindings> {
	// Database service for persistent storage of interview data and messages
	private readonly db: InterviewDatabaseService;
	private sessions: Map<WebSocket, { interviewId: string }>;

	constructor(state: DurableObjectState, env: CloudflareBindings) {
		// ... previous code ...
		// Set up our database connection using the DO's built-in SQLite instance
		this.db = new InterviewDatabaseService(state.storage.sql);
		// First-time setup: ensure our database tables exist
		// This is idempotent so safe to call on every instantiation
		this.db.createTables();
	}
}
```

Add methods to create and retrieve interviews in `services/InterviewDatabaseService.ts`:

```typescript title="src/services/InterviewDatabaseService.ts"
export class InterviewDatabaseService {
	/**
	 * Creates a new interview session in the database.
	 *
	 * This is the main entry point for starting a new interview. It handles all the
	 * initial setup like:
	 * - Generating a unique ID using crypto.randomUUID() for reliable uniqueness
	 * - Recording the interview title and required skills
	 * - Setting up timestamps for tracking interview lifecycle
	 * - Setting the initial status to "Created"
	 *
	 */
	createInterview(title: InterviewTitle, skills: InterviewSkill[]): string {
		try {
			const interviewId = crypto.randomUUID();
			const currentTime = Date.now();

			this.sql.exec(
				InterviewDatabaseService.QUERIES.INSERT_INTERVIEW,
				interviewId,
				title,
				JSON.stringify(skills), // Store skills as JSON for flexibility
				InterviewStatus.Created,
				currentTime,
				currentTime,
			);

			return interviewId;
		} catch (error: unknown) {
			const message = error instanceof Error ? error.message : String(error);
			throw new InterviewError(
				`Failed to create interview: ${message}`,
				ErrorCodes.DATABASE_ERROR,
			);
		}
	}

	/**
	 * Fetches all interviews from the database, ordered by creation date.
	 *
	 * This is useful for displaying interview history and letting users
	 * resume previous sessions. We order by descending creation date since
	 * users typically want to see their most recent interviews first.
	 *
	 * Returns an array of InterviewData objects with full interview details
	 * including metadata and message history.
	 */
	getAllInterviews(): InterviewData[] {
		try {
			const cursor = this.sql.exec(
				InterviewDatabaseService.QUERIES.GET_ALL_INTERVIEWS,
			);

			return [...cursor].map(this.parseInterviewRecord);
		} catch (error) {
			const message = error instanceof Error ? error.message : String(error);
			throw new InterviewError(
				`Failed to retrieve interviews: ${message}`,
				ErrorCodes.DATABASE_ERROR,
			);
		}
	}

	// Retrieves an interview and its messages by ID
	getInterview(interviewId: string): InterviewData | null {
		try {
			const cursor = this.sql.exec(
				InterviewDatabaseService.QUERIES.GET_INTERVIEW,
				interviewId,
			);

			const record = [...cursor][0];
			if (!record) return null;

			return this.parseInterviewRecord(record);
		} catch (error: unknown) {
			const message = error instanceof Error ? error.message : String(error);
			throw new InterviewError(
				`Failed to retrieve interview: ${message}`,
				ErrorCodes.DATABASE_ERROR,
			);
		}
	}

	addMessage(
		interviewId: string,
		role: Message["role"],
		content: string,
		messageId: string,
	): Message {
		try {
			const timestamp = Date.now();

			this.sql.exec(
				InterviewDatabaseService.QUERIES.INSERT_MESSAGE,
				messageId,
				interviewId,
				role,
				content,
				timestamp,
			);

			return {
				messageId,
				interviewId,
				role,
				content,
				timestamp,
			};
		} catch (error: unknown) {
			const message = error instanceof Error ? error.message : String(error);
			throw new InterviewError(
				`Failed to add message: ${message}`,
				ErrorCodes.DATABASE_ERROR,
			);
		}
	}

	/**
	 * Transforms raw database records into structured InterviewData objects.
	 *
	 * This helper does the heavy lifting of:
	 * - Type checking critical fields to catch database corruption early
	 * - Converting stored JSON strings back into proper objects
	 * - Filtering out any null messages that might have snuck in
	 * - Ensuring timestamps are proper numbers
	 *
	 * If any required data is missing or malformed, it throws an error
	 * rather than returning partially valid data that could cause issues
	 * downstream.
	 */
	private parseInterviewRecord(record: any): InterviewData {
		const interviewId = record.interviewId as string;
		const createdAt = Number(record.createdAt);
		const updatedAt = Number(record.updatedAt);

		if (!interviewId || !createdAt || !updatedAt) {
			throw new InterviewError(
				"Invalid interview data in database",
				ErrorCodes.DATABASE_ERROR,
			);
		}

		return {
			interviewId,
			title: record.title as InterviewTitle,
			skills: JSON.parse(record.skills as string) as InterviewSkill[],
			messages: record.messages
				? JSON.parse(record.messages)
						.filter((m: any) => m !== null)
						.map((m: any) => ({
							messageId: m.messageId,
							role: m.role,
							content: m.content,
							timestamp: m.timestamp,
						}))
				: [],
			status: record.status as InterviewStatus,
			createdAt,
			updatedAt,
		};
	}

	// Add these SQL queries to the QUERIES object
	private static readonly QUERIES = {
		// ... previous queries ...

		INSERT_INTERVIEW: `
      INSERT INTO ${CONFIG.database.tables.interviews}
      (interviewId, title, skills, status, createdAt, updatedAt)
      VALUES (?, ?, ?, ?, ?, ?)
    `,

		GET_ALL_INTERVIEWS: `
      SELECT
        interviewId,
        title,
        skills,
        createdAt,
        updatedAt,
        status
      FROM ${CONFIG.database.tables.interviews}
      ORDER BY createdAt DESC
    `,

		INSERT_MESSAGE: `
      INSERT INTO ${CONFIG.database.tables.messages}
      (messageId, interviewId, role, content, timestamp)
      VALUES (?, ?, ?, ?, ?)
    `,

		GET_INTERVIEW: `
      SELECT
        i.interviewId,
        i.title,
        i.skills,
        i.status,
        i.createdAt,
        i.updatedAt,
        COALESCE(
          json_group_array(
            CASE WHEN m.messageId IS NOT NULL THEN
              json_object(
                'messageId', m.messageId,
                'role', m.role,
                'content', m.content,
                'timestamp', m.timestamp
              )
            END
          ),
          '[]'
        ) as messages
      FROM ${CONFIG.database.tables.interviews} i
      LEFT JOIN ${CONFIG.database.tables.messages} m ON i.interviewId = m.interviewId
      WHERE i.interviewId = ?
      GROUP BY i.interviewId
    `,
	};
}
```

Add RPC methods to the `Interview` Durable Object to expose database operations through API. Add this code to `src/interview.ts`:

```typescript title="src/interview.ts"
import {
	InterviewData,
	InterviewTitle,
	InterviewSkill,
	Message,
} from "./types";

export class Interview extends DurableObject<CloudflareBindings> {
	// Creates a new interview session
	createInterview(title: InterviewTitle, skills: InterviewSkill[]): string {
		return this.db.createInterview(title, skills);
	}

	// Retrieves all interview sessions
	getAllInterviews(): InterviewData[] {
		return this.db.getAllInterviews();
	}

	// Adds a new message to the 'messages' table and broadcasts it to all connected WebSocket clients.
	addMessage(
		interviewId: string,
		role: "user" | "assistant",
		content: string,
		messageId: string,
	): Message {
		const newMessage = this.db.addMessage(
			interviewId,
			role,
			content,
			messageId,
		);
		this.broadcast(
			JSON.stringify({
				...newMessage,
				type: "message",
			}),
		);
		return newMessage;
	}
}
```

## 6. Create REST API endpoints

With your Durable Object and database service ready, create REST API endpoints to manage interviews. You will need endpoints to:

- Create new interviews
- Retrieve all interviews for a user

Create a new file for your interview routes at `routes/interview.ts`:

```typescript title="src/routes/interview.ts"
import { Hono } from "hono";
import { BadRequestError } from "../errors";
import {
	InterviewInput,
	ApiContext,
	HonoCtx,
	InterviewTitle,
	InterviewSkill,
} from "../types";
import { requireAuth } from "../middleware/auth";

/**
 * Gets the Interview Durable Object instance for a given user.
 * We use the username as a stable identifier to ensure each user
 * gets their own dedicated DO instance that persists across requests.
 */
const getInterviewDO = (ctx: HonoCtx) => {
	const username = ctx.get("username");
	const id = ctx.env.INTERVIEW.idFromName(username);
	return ctx.env.INTERVIEW.get(id);
};

/**
 * Validates the interview creation payload.
 * Makes sure we have all required fields in the correct format:
 * - title must be present
 * - skills must be a non-empty array
 * Throws an error if validation fails.
 */
const validateInterviewInput = (input: InterviewInput) => {
	if (
		!input.title ||
		!input.skills ||
		!Array.isArray(input.skills) ||
		input.skills.length === 0
	) {
		throw new BadRequestError("Invalid input");
	}
};

/**
 * GET /interviews
 * Retrieves all interviews for the authenticated user.
 * The interviews are stored and managed by the user's DO instance.
 */
const getAllInterviews = async (ctx: HonoCtx) => {
	const interviewDO = getInterviewDO(ctx);
	const interviews = await interviewDO.getAllInterviews();
	return ctx.json(interviews);
};

/**
 * POST /interviews
 * Creates a new interview session with the specified title and skills.
 * Each interview gets a unique ID that can be used to reference it later.
 * Returns the newly created interview ID on success.
 */
const createInterview = async (ctx: HonoCtx) => {
	const body = await ctx.req.json<InterviewInput>();
	validateInterviewInput(body);

	const interviewDO = getInterviewDO(ctx);
	const interviewId = await interviewDO.createInterview(
		body.title as InterviewTitle,
		body.skills as InterviewSkill[],
	);

	return ctx.json({ success: true, interviewId });
};

/**
 * Sets up all interview-related routes.
 * Currently supports:
 * - GET / : List all interviews
 * - POST / : Create a new interview
 */
export const configureInterviewRoutes = () => {
	const router = new Hono<ApiContext>();
	router.use("*", requireAuth);
	router.get("/", getAllInterviews);
	router.post("/", createInterview);
	return router;
};
```

The `getInterviewDO` helper function uses the username from our authentication cookie to create a unique Durable Object ID. This ensures each user has their own isolated interview state.

Update your main application file to include the routes and protect them with authentication middleware. Update `src/index.ts`:

```typescript title="src/index.ts"
import { configureAuthRoutes } from "./routes/auth";
import { configureInterviewRoutes } from "./routes/interview";
import { Hono } from "hono";
import { Interview } from "./interview";
import { logger } from "hono/logger";
import type { ApiContext } from "./types";

const app = new Hono<ApiContext>();
const api = new Hono<ApiContext>();

app.use("*", logger());

api.route("/auth", configureAuthRoutes());
api.route("/interviews", configureInterviewRoutes());

app.route("/api/v1", api);

export { Interview };
export default app;
```

Now you have two new API endpoints:

- `POST /api/v1/interviews`: Creates a new interview session
- `GET /api/v1/interviews`: Retrieves all interviews for the authenticated user

You can test these endpoints running the following command:

1. Create a new interview:

```sh
curl -X POST http://localhost:8787/api/v1/interviews \
-H "Content-Type: application/json" \
-H "Cookie: username=testuser; HttpOnly" \
-d '{"title":"Frontend Developer Interview","skills":["JavaScript","React","CSS"]}'
```

2. Get all interviews:

```sh
curl http://localhost:8787/api/v1/interviews \
-H "Cookie: username=testuser; HttpOnly"
```

## 7. Set up WebSockets to handle real-time communication

With the basic interview management system in place, you will now implement Durable Objects to handle real-time message processing and maintain WebSocket connections.

Update the `Interview` Durable Object to handle WebSocket connections by adding the following code to `src/interview.ts`:

```typescript
export class Interview extends DurableObject<CloudflareBindings> {
	// Services for database operations and managing WebSocket sessions
	private readonly db: InterviewDatabaseService;
	private sessions: Map<WebSocket, { interviewId: string }>;

	constructor(state: DurableObjectState, env: CloudflareBindings) {
		// ... previous code ...

		// Keep WebSocket connections alive by automatically responding to pings
		// This prevents timeouts and connection drops
		this.ctx.setWebSocketAutoResponse(
			new WebSocketRequestResponsePair("ping", "pong"),
		);
	}

	async fetch(request: Request): Promise<Response> {
		// Check if this is a WebSocket upgrade request
		const upgradeHeader = request.headers.get("Upgrade");
		if (upgradeHeader?.toLowerCase().includes("websocket")) {
			return this.handleWebSocketUpgrade(request);
		}

		// If it is not a WebSocket request, we don't handle it
		return new Response("Not found", { status: 404 });
	}

	private async handleWebSocketUpgrade(request: Request): Promise<Response> {
		// Extract the interview ID from the URL - it should be the last segment
		const url = new URL(request.url);
		const interviewId = url.pathname.split("/").pop();

		if (!interviewId) {
			return new Response("Missing interviewId parameter", { status: 400 });
		}

		// Create a new WebSocket connection pair - one for the client, one for the server
		const pair = new WebSocketPair();
		const [client, server] = Object.values(pair);

		// Keep track of which interview this WebSocket is connected to
		// This is important for routing messages to the right interview session
		this.sessions.set(server, { interviewId });

		// Tell the Durable Object to start handling this WebSocket
		this.ctx.acceptWebSocket(server);

		// Send the current interview state to the client right away
		// This helps initialize their UI with the latest data
		const interviewData = await this.db.getInterview(interviewId);
		if (interviewData) {
			server.send(
				JSON.stringify({
					type: "interview_details",
					data: interviewData,
				}),
			);
		}

		// Return the client WebSocket as part of the upgrade response
		return new Response(null, {
			status: 101,
			webSocket: client,
		});
	}

	async webSocketClose(
		ws: WebSocket,
		code: number,
		reason: string,
		wasClean: boolean,
	) {
		// Clean up when a connection closes to prevent memory leaks
		// This is especially important in long-running Durable Objects
		console.log(
			`WebSocket closed: Code ${code}, Reason: ${reason}, Clean: ${wasClean}`,
		);
	}
}
```

Next, update the interview routes to include a WebSocket endpoint. Add the following to `routes/interview.ts`:

```typescript title="src/routes/interview.ts"
// ... previous code ...
const streamInterviewProcess = async (ctx: HonoCtx) => {
	const interviewDO = getInterviewDO(ctx);
	return await interviewDO.fetch(ctx.req.raw);
};

export const configureInterviewRoutes = () => {
	const router = new Hono<ApiContext>();
	router.get("/", getAllInterviews);
	router.post("/", createInterview);
	// Add WebSocket route
	router.get("/:interviewId", streamInterviewProcess);
	return router;
};
```

The WebSocket system provides real-time communication features for interview practice tool:

- Each interview session gets its own dedicated WebSocket connection, allowing seamless communication between the candidate and AI interviewer
- The Durable Object maintains the connection state, ensuring no messages are lost even if the client temporarily disconnects
- To keep connections stable, it automatically responds to ping messages with pongs, preventing timeouts
- Candidates and interviewers receive instant updates as the interview progresses, creating a natural conversational flow

## 8. Add audio processing capabilities with Workers AI

Now that WebSocket connection set up, the next step is to add speech-to-text capabilities using Workers AI. Let's use Cloudflare's Whisper model to transcribe audio in real-time during the interview.

The audio processing pipeline will work like this:

1. Client sends audio through the WebSocket connection
2. Our Durable Object receives the binary audio data
3. We pass the audio to Whisper for transcription
4. The transcribed text is saved as a new message
5. We immediately send the transcription back to the client
6. The client receives a notification that the AI interviewer is generating a response

### Create audio processing pipeline

In this step you will update the Interview Durable Object to handle the following:

1. Detect binary audio data sent through WebSocket
2. Create a unique message ID for tracking the processing status
3. Notify clients that audio processing has begun
4. Include error handling for failed audio processing
5. Broadcast status updates to all connected clients

First, update Interview Durable Object to handle binary WebSocket messages. Add the following methods to your `src/interview.ts` file:

```typescript title="src/interview.ts"
// ... previous code ...
/**
 * Handles incoming WebSocket messages, both binary audio data and text messages.
 * This is the main entry point for all WebSocket communication.
 */
async webSocketMessage(ws: WebSocket, eventData: ArrayBuffer | string): Promise<void> {
  try {
    // Handle binary audio data from the client's microphone
    if (eventData instanceof ArrayBuffer) {
      await this.handleBinaryAudio(ws, eventData);
      return;
    }
    // Text messages will be handled by other methods
  } catch (error) {
    this.handleWebSocketError(ws, error);
  }
}

/**
 * Processes binary audio data received from the client.
 * Converts audio to text using Whisper and broadcasts processing status.
 */
private async handleBinaryAudio(ws: WebSocket, audioData: ArrayBuffer): Promise<void> {
  try {
    const uint8Array = new Uint8Array(audioData);

    // Retrieve the associated interview session
    const session = this.sessions.get(ws);
    if (!session?.interviewId) {
      throw new Error("No interview session found");
    }

    // Generate unique ID to track this message through the system
    const messageId = crypto.randomUUID();

    // Let the client know we're processing their audio
    this.broadcast(
      JSON.stringify({
        type: "message",
        status: "processing",
        role: "user",
        messageId,
        interviewId: session.interviewId,
      }),
    );

    // TODO: Implement Whisper transcription in next section
    // For now, just log the received audio data size
    console.log(`Received audio data of length: ${uint8Array.length}`);
  } catch (error) {
    console.error("Audio processing failed:", error);
    this.handleWebSocketError(ws, error);
  }
}

/**
 * Handles WebSocket errors by logging them and notifying the client.
 * Ensures errors are properly communicated back to the user.
 */
private handleWebSocketError(ws: WebSocket, error: unknown): void {
  const errorMessage = error instanceof Error ? error.message : "An unknown error occurred.";
  console.error("WebSocket error:", errorMessage);

  if (ws.readyState === WebSocket.OPEN) {
    ws.send(
      JSON.stringify({
        type: "error",
        message: errorMessage,
      }),
    );
  }
}

```

Your `handleBinaryAudio` method currently logs when it receives audio data. Next, you'll enhance it to transcribe speech using Workers AI's Whisper model.

### Configure speech-to-text

Now that audio processing pipeline is set up, you will now integrate Workers AI's Whisper model for speech-to-text transcription.

Configure the Worker AI binding in your Wrangler file by adding:

```toml
# ... previous configuration ...
[ai]
binding = "AI"
```

Next, generate TypeScript types for our AI binding. Run the following command:

```sh
npm run cf-typegen
```

You will need a new service class for AI operations. Create a new file called `services/AIService.ts`:

```typescript title="src/services/AIService.ts"
import { InterviewError, ErrorCodes } from "../errors";

export class AIService {
	constructor(private readonly AI: Ai) {}

	async transcribeAudio(audioData: Uint8Array): Promise<string> {
		try {
			// Call the Whisper model to transcribe the audio
			const response = await this.AI.run("@cf/openai/whisper-tiny-en", {
				audio: Array.from(audioData),
			});

			if (!response?.text) {
				throw new Error("Failed to transcribe audio content.");
			}

			return response.text;
		} catch (error) {
			throw new InterviewError(
				"Failed to transcribe audio content",
				ErrorCodes.TRANSCRIPTION_FAILED,
			);
		}
	}
}
```

You will need to update the `Interview` Durable Object to use this new AI service. To do this, update the handleBinaryAudio method in `src/interview.ts`:

```typescript title="src/interview.ts"
import { AIService } from "./services/AIService";

export class Interview extends DurableObject<CloudflareBindings> {
private readonly aiService: AIService;

constructor(state: DurableObjectState, env: Env) {
  // ... previous code ...

  // Initialize the AI service with the Workers AI binding
  this.aiService = new AIService(this.env.AI);
}

private async handleBinaryAudio(ws: WebSocket, audioData: ArrayBuffer): Promise<void> {
  try {
    const uint8Array = new Uint8Array(audioData);
    const session = this.sessions.get(ws);

    if (!session?.interviewId) {
      throw new Error("No interview session found");
    }

    // Create a message ID for tracking
    const messageId = crypto.randomUUID();

    // Send processing state to client
    this.broadcast(
      JSON.stringify({
        type: "message",
        status: "processing",
        role: "user",
        messageId,
        interviewId: session.interviewId,
      }),
    );

    // NEW: Use AI service to transcribe the audio
    const transcribedText = await this.aiService.transcribeAudio(uint8Array);

    // Store the transcribed message
    await this.addMessage(session.interviewId, "user", transcribedText, messageId);

  } catch (error) {
    console.error("Audio processing failed:", error);
    this.handleWebSocketError(ws, error);
  }
}
```

:::note
The Whisper model `@cf/openai/whisper-tiny-en` is optimized for English speech recognition. If you need support for other languages, you can use different Whisper model variants available through Workers AI.
:::

When users speak during the interview, their audio will be automatically transcribed and stored as messages in the interview session. The transcribed text will be immediately available to both the user and the AI interviewer for generating appropriate responses.

## 9. Integrate AI response generation

Now that you have audio transcription working, let's implement AI interviewer response generation using Workers AI's LLM capabilities. You'll create an interview system that:

- Maintains context of the conversation
- Provides relevant follow-up questions
- Gives constructive feedback
- Stays in character as a professional interviewer

### Set up Workers AI LLM integration

First, update the `AIService` class to handle LLM interactions. You will need to add methods for:

- Processing interview context
- Generating appropriate responses
- Handling conversation flow

Update the `services/AIService.ts` class to include LLM functionality:

```typescript title="src/services/AIService.ts"
import { InterviewData, Message } from "../types";

export class AIService {

async processLLMResponse(interview: InterviewData): Promise<string> {
  const messages = this.prepareLLMMessages(interview);

  try {
    const { response } = await this.AI.run("@cf/meta/llama-2-7b-chat-int8", {
      messages,
    });

    if (!response) {
      throw new Error("Failed to generate a response from the LLM model.");
    }

    return response;
  } catch (error) {
    throw new InterviewError("Failed to generate a response from the LLM model.", ErrorCodes.LLM_FAILED);
  }
}

private prepareLLMMessages(interview: InterviewData) {
  const messageHistory = interview.messages.map((msg: Message) => ({
    role: msg.role,
    content: msg.content,
  }));

  return [
    {
      role: "system",
      content: this.createSystemPrompt(interview),
    },
    ...messageHistory,
  ];
}
```

:::note
The @cf/meta/llama-2-7b-chat-int8 model is optimized for chat-like interactions and provides good performance while maintaining reasonable resource usage.
:::

### Create the conversation prompt

Prompt engineering is crucial for getting high-quality responses from the LLM. Next, you will create a system prompt that:

- Sets the context for the interview
- Defines the interviewer's role and behavior
- Specifies the technical focus areas
- Guides the conversation flow

Add the following method to your `services/AIService.ts` class:

```typescript title="src/services/AIService.ts"
private createSystemPrompt(interview: InterviewData): string {
  const basePrompt = "You are conducting a technical interview.";
  const rolePrompt = `The position is for ${interview.title}.`;
  const skillsPrompt = `Focus on topics related to: ${interview.skills.join(", ")}.`;
  const instructionsPrompt = "Ask relevant technical questions and provide constructive feedback.";

  return `${basePrompt} ${rolePrompt} ${skillsPrompt} ${instructionsPrompt}`;
}
```

### Implement response generation logic

Finally, integrate the LLM response generation into the interview flow. Update the `handleBinaryAudio` method in the `src/interview.ts` Durable Object to:

- Process transcribed user responses
- Generate appropriate AI interviewer responses
- Maintain conversation context

Update the `handleBinaryAudio` method in `src/interview.ts`:

```typescript title="src/interview.ts"
private async handleBinaryAudio(ws: WebSocket, audioData: ArrayBuffer): Promise<void> {
  try {
    // Convert raw audio buffer to uint8 array for processing
    const uint8Array = new Uint8Array(audioData);
    const session = this.sessions.get(ws);

    if (!session?.interviewId) {
      throw new Error("No interview session found");
    }

    // Generate a unique ID to track this message through the system
    const messageId = crypto.randomUUID();

    // Let the client know we're processing their audio
    // This helps provide immediate feedback while transcription runs
    this.broadcast(
      JSON.stringify({
        type: "message",
        status: "processing",
        role: "user",
        messageId,
        interviewId: session.interviewId,
      }),
    );

    // Convert the audio to text using our AI transcription service
    // This typically takes 1-2 seconds for normal speech
    const transcribedText = await this.aiService.transcribeAudio(uint8Array);

    // Save the user's message to our database so we maintain chat history
    await this.addMessage(session.interviewId, "user", transcribedText, messageId);

    // Look up the full interview context - we need this to generate a good response
    const interview = await this.db.getInterview(session.interviewId);
    if (!interview) {
      throw new Error(`Interview not found: ${session.interviewId}`);
    }

    // Now it's the AI's turn to respond
    // First generate an ID for the assistant's message
    const assistantMessageId = crypto.randomUUID();

    // Let the client know we're working on the AI response
    this.broadcast(
      JSON.stringify({
        type: "message",
        status: "processing",
        role: "assistant",
        messageId: assistantMessageId,
        interviewId: session.interviewId,
      }),
    );

    // Generate the AI interviewer's response based on the conversation history
    const llmResponse = await this.aiService.processLLMResponse(interview);
    await this.addMessage(session.interviewId, "assistant", llmResponse, assistantMessageId);
  } catch (error) {
    // Something went wrong processing the audio or generating a response
    // Log it and let the client know there was an error
    console.error("Audio processing failed:", error);
    this.handleWebSocketError(ws, error);
  }
}
```

## Conclusion

You have successfully built an AI-powered interview practice tool using Cloudflare's Workers AI. In summary, you have:

- Created a real-time WebSocket communication system using Durable Objects
- Implemented speech-to-text processing with Workers AI Whisper model
- Built an intelligent interview system using Workers AI LLM capabilities
- Designed a persistent storage system with SQLite in Durable Objects

The complete source code for this tutorial is available on GitHub:
[ai-interview-practice-tool](https://github.com/berezovyy/ai-interview-practice-tool)

---

# Explore Code Generation Using DeepSeek Coder Models

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/explore-code-generation-using-deepseek-coder-models/

import { Stream } from "~/components"

A handy way to explore all of the models available on [Workers AI](/workers-ai) is to use a [Jupyter Notebook](https://jupyter.org/).

You can [download the DeepSeek Coder notebook](/workers-ai/static/documentation/notebooks/deepseek-coder-exploration.ipynb) or view the embedded notebook below.

<Stream id="97b46763341a395a4ce1c0a6f913662b" title="Explore Code Generation Using DeepSeek Coder Models" />

[comment]: <> "The markdown below is auto-generated from https://github.com/craigsdennis/notebooks-cloudflare-workers-ai"

***

## Exploring Code Generation Using DeepSeek Coder

AI Models being able to generate code unlocks all sorts of use cases. The [DeepSeek Coder](https://github.com/deepseek-ai/DeepSeek-Coder) models `@hf/thebloke/deepseek-coder-6.7b-base-awq` and `@hf/thebloke/deepseek-coder-6.7b-instruct-awq` are now available on [Workers AI](/workers-ai).

Let's explore them using the API!

```python
import sys
!{sys.executable} -m pip install requests python-dotenv
```

```
Requirement already satisfied: requests in ./venv/lib/python3.12/site-packages (2.31.0)
Requirement already satisfied: python-dotenv in ./venv/lib/python3.12/site-packages (1.0.1)
Requirement already satisfied: charset-normalizer<4,>=2 in ./venv/lib/python3.12/site-packages (from requests) (3.3.2)
Requirement already satisfied: idna<4,>=2.5 in ./venv/lib/python3.12/site-packages (from requests) (3.6)
Requirement already satisfied: urllib3<3,>=1.21.1 in ./venv/lib/python3.12/site-packages (from requests) (2.1.0)
Requirement already satisfied: certifi>=2017.4.17 in ./venv/lib/python3.12/site-packages (from requests) (2023.11.17)
```

```python
import os
from getpass import getpass

from IPython.display import display, Image, Markdown, Audio

import requests
```

```python
%load_ext dotenv
%dotenv
```

### Configuring your environment

To use the API you'll need your [Cloudflare Account ID](https://dash.cloudflare.com) (head to Workers & Pages > Overview > Account details > Account ID) and a [Workers AI enabled API Token](https://dash.cloudflare.com/profile/api-tokens).

If you want to add these files to your environment, you can create a new file named `.env`

```bash
CLOUDFLARE_API_TOKEN="YOUR-TOKEN"
CLOUDFLARE_ACCOUNT_ID="YOUR-ACCOUNT-ID"
```

```python
if "CLOUDFLARE_API_TOKEN" in os.environ:
    api_token = os.environ["CLOUDFLARE_API_TOKEN"]
else:
    api_token = getpass("Enter you Cloudflare API Token")
```

```python
if "CLOUDFLARE_ACCOUNT_ID" in os.environ:
    account_id = os.environ["CLOUDFLARE_ACCOUNT_ID"]
else:
    account_id = getpass("Enter your account id")
```

### Generate code from a comment

A common use case is to complete the code for the user after they provide a descriptive comment.

````python
model = "@hf/thebloke/deepseek-coder-6.7b-base-awq"

prompt = "# A function that checks if a given word is a palindrome"

response = requests.post(
    f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/{model}",
    headers={"Authorization": f"Bearer {api_token}"},
    json={"messages": [
        {"role": "user", "content": prompt}
    ]}
)
inference = response.json()
code = inference["result"]["response"]

display(Markdown(f"""
    ```python
    {prompt}
    {code.strip()}
    ```
"""))
````

```python
# A function that checks if a given word is a palindrome
def is_palindrome(word):
    # Convert the word to lowercase
    word = word.lower()

    # Reverse the word
    reversed_word = word[::-1]

    # Check if the reversed word is the same as the original word
    if word == reversed_word:
        return True
    else:
        return False

# Test the function
print(is_palindrome("racecar"))  # Output: True
print(is_palindrome("hello"))    # Output: False
```

### Assist in debugging

We've all been there, bugs happen. Sometimes those stacktraces can be very intimidating, and a great use case of using Code Generation is to assist in explaining the problem.

```python
model = "@hf/thebloke/deepseek-coder-6.7b-instruct-awq"

system_message = "The user is going to give you code that isn't working. Explain to the user what might be wrong"

code = """# Welcomes our user
def hello_world(first_name="World"):
    print(f"Hello, {name}!")
"""

response = requests.post(
    f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/{model}",
    headers={"Authorization": f"Bearer {api_token}"},
    json={"messages": [
        {"role": "system", "content": system_message},
        {"role": "user", "content": code},
    ]}
)
inference = response.json()
response = inference["result"]["response"]
display(Markdown(response))
```

The error in your code is that you are trying to use a variable `name` which is not defined anywhere in your function. The correct variable to use is `first_name`. So, you should change `f"Hello, {name}!"` to `f"Hello, {first_name}!"`.

Here is the corrected code:

```python
# Welcomes our user
def hello_world(first_name="World"):
    print(f"Hello, {first_name}")
```

Now, when you call `hello_world()`, it will print "Hello, World" by default. If you call `hello_world("John")`, it will print "Hello, John".

### Write tests!

Writing unit tests is a common best practice. With the enough context, it's possible to write unit tests.

```python
model = "@hf/thebloke/deepseek-coder-6.7b-instruct-awq"

system_message = "The user is going to give you code and would like to have tests written in the Python unittest module."

code = """
class User:

    def __init__(self, first_name, last_name=None):
        self.first_name = first_name
        self.last_name = last_name
        if last_name is None:
            self.last_name = "Mc" + self.first_name

    def full_name(self):
        return self.first_name + " " + self.last_name
"""

response = requests.post(
    f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/{model}",
    headers={"Authorization": f"Bearer {api_token}"},
    json={"messages": [
        {"role": "system", "content": system_message},
        {"role": "user", "content": code},
    ]}
)
inference = response.json()
response = inference["result"]["response"]
display(Markdown(response))
```

Here is a simple unittest test case for the User class:

```python
import unittest

class TestUser(unittest.TestCase):

    def test_full_name(self):
        user = User("John", "Doe")
        self.assertEqual(user.full_name(), "John Doe")

    def test_default_last_name(self):
        user = User("Jane")
        self.assertEqual(user.full_name(), "Jane McJane")

if __name__ == '__main__':
    unittest.main()
```

In this test case, we have two tests:

* `test_full_name` tests the `full_name` method when the user has both a first name and a last name.
* `test_default_last_name` tests the `full_name` method when the user only has a first name and the last name is set to "Mc" + first name.

If all these tests pass, it means that the `full_name` method is working as expected. If any of these tests fail, it

### Fill-in-the-middle Code Completion

A common use case in Developer Tools is to autocomplete based on context. DeepSeek Coder provides the ability to submit existing code with a placeholder, so that the model can complete in context.

Warning: The tokens are prefixed with `<｜` and suffixed with `｜>` make sure to copy and paste them.

````python
model = "@hf/thebloke/deepseek-coder-6.7b-base-awq"

code = """
<｜fim▁begin｜>import re

from jklol import email_service

def send_email(email_address, body):
    <｜fim▁hole｜>
    if not is_valid_email:
        raise InvalidEmailAddress(email_address)
    return email_service.send(email_address, body)<｜fim▁end｜>
"""

response = requests.post(
    f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/{model}",
    headers={"Authorization": f"Bearer {api_token}"},
    json={"messages": [
        {"role": "user", "content": code}
    ]}
)
inference = response.json()
response = inference["result"]["response"]
display(Markdown(f"""
    ```python
    {response.strip()}
    ```
"""))

````

```python
is_valid_email = re.match(r"[^@]+@[^@]+\.[^@]+", email_address)
```

### Experimental: Extract data into JSON

No need to threaten the model or bring grandma into the prompt. Get back JSON in the format you want.

````python
model = "@hf/thebloke/deepseek-coder-6.7b-instruct-awq"

# Learn more at https://json-schema.org/
json_schema = """
{
  "title": "User",
  "description": "A user from our example app",
  "type": "object",
  "properties": {
    "firstName": {
      "description": "The user's first name",
      "type": "string"
    },
    "lastName": {
      "description": "The user's last name",
      "type": "string"
    },
    "numKids": {
      "description": "Amount of children the user has currently",
      "type": "integer"
    },
    "interests": {
      "description": "A list of what the user has shown interest in",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
  },
  "required": [ "firstName" ]
}
"""

system_prompt = f"""
The user is going to discuss themselves and you should create a JSON object from their description to match the json schema below.

<BEGIN JSON SCHEMA>
{json_schema}
<END JSON SCHEMA>

Return JSON only. Do not explain or provide usage examples.
"""

prompt = """Hey there, I'm Craig Dennis and I'm a Developer Educator at Cloudflare. My email is craig@cloudflare.com.
            I am very interested in AI. I've got two kids. I love tacos, burritos, and all things Cloudflare"""

response = requests.post(
    f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/{model}",
    headers={"Authorization": f"Bearer {api_token}"},
    json={"messages": [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": prompt}
    ]}
)
inference = response.json()
response = inference["result"]["response"]
display(Markdown(f"""
    ```json
    {response.strip()}
    ```
"""))
````

```json
{
  "firstName": "Craig",
  "lastName": "Dennis",
  "numKids": 2,
  "interests": ["AI", "Cloudflare", "Tacos", "Burritos"]
}
```

---

# Explore Workers AI Models Using a Jupyter Notebook

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/explore-workers-ai-models-using-a-jupyter-notebook/

import { Stream } from "~/components"

A handy way to explore all of the models available on [Workers AI](/workers-ai) is to use a [Jupyter Notebook](https://jupyter.org/).

You can [download the Workers AI notebook](/workers-ai-notebooks/cloudflare-workers-ai.ipynb) or view the embedded notebook below.

Or you can run this on [Google Colab](https://colab.research.google.com/github/craigsdennis/notebooks-cloudflare-workers-ai/blob/main/cloudflare-workers-ai.ipynb)

<Stream id="2c60022bea5c8c1b343e76566fed76f2" title="Explore Workers AI Models Using a Jupyter Notebook" thumbnail="2.5s" />

[comment]: <> "The markdown below is auto-generated from https://github.com/craigsdennis/notebooks-cloudflare-workers-ai the <audio> tag is hard coded"

***

## Explore the Workers AI API using Python

[Workers AI](/workers-ai) allows you to run machine learning models, on the Cloudflare network, from your own code – whether that be from Workers, Pages, or anywhere via REST API.

This notebook will explore the Workers AI REST API using the [official Python SDK](https://github.com/cloudflare/cloudflare-python).


```python
import os
from getpass import getpass

from cloudflare import Cloudflare
from IPython.display import display, Image, Markdown, Audio
import requests
```


```python
%load_ext dotenv
%dotenv
```


### Configuring your environment

To use the API you'll need your [Cloudflare Account ID](https://dash.cloudflare.com). Head to AI > Workers AI page and press the "Use REST API". This page will let you create a new API Token and copy your Account ID.

If you want to add these values to your environment variables, you can **create a new file** named `.env` and this notebook will read those values.

```bash
CLOUDFLARE_API_TOKEN="YOUR-TOKEN"
CLOUDFLARE_ACCOUNT_ID="YOUR-ACCOUNT-ID"
```

Otherwise you can just enter the values securely when prompted below.


```python
if "CLOUDFLARE_API_TOKEN" in os.environ:
    api_token = os.environ["CLOUDFLARE_API_TOKEN"]
else:
    api_token = getpass("Enter you Cloudflare API Token")
```


```python
if "CLOUDFLARE_ACCOUNT_ID" in os.environ:
    account_id = os.environ["CLOUDFLARE_ACCOUNT_ID"]
else:
    account_id = getpass("Enter your account id")
```


```python
# Initialize client
client = Cloudflare(api_token=api_token)
```

## Explore tasks available on the Workers AI Platform

### Text Generation

Explore all [Text Generation Models](/workers-ai/models)


```python
result = client.workers.ai.run(
    "@cf/meta/llama-3-8b-instruct" ,
    account_id=account_id,
    messages=[
        {"role": "system", "content": """
            You are a productivity assistant for users of Jupyter notebooks for both Mac and Windows users.

            Respond in Markdown."""
        },
        {"role": "user", "content": "How do I use keyboard shortcuts to execute cells?"}
    ]
)

display(Markdown(result["response"]))
```


**Using Keyboard Shortcuts to Execute Cells in Jupyter Notebooks**
===============================================================

Executing cells in Jupyter Notebooks can be done quickly and efficiently using various keyboard shortcuts, saving you time and effort. Here are the shortcuts you can use:

**Mac**

* **Shift + Enter**: Execute the current cell and insert a new cell below.
* **Ctrl + Enter**: Execute the current cell and insert a new cell below, without creating a new output display.

**Windows/Linux**

* **Shift + Enter**: Execute the current cell and insert a new cell below.
* **Ctrl + Enter**: Execute the current cell and move to the next cell.

**Additional Shortcuts**

* **Alt + Enter**: Execute the current cell and create a new output display below (Mac), or move to the next cell (Windows/Linux).
* **Ctrl + Shift + Enter**: Execute the current cell and create a new output display below (Mac), or create a new cell below (Windows/Linux).

**Tips and Tricks**

* You can also use the **Run Cell** button in the Jupyter Notebook toolbar, or the **Run** menu option (macOS) or **Run -> Run Cell** (Windows/Linux).
* To execute a selection of cells, use **Shift + Alt + Enter** (Mac) or **Shift + Ctrl + Enter** (Windows/Linux).
* To execute a cell and move to the next cell, use **Ctrl + Shift + Enter** (all platforms).

By using these keyboard shortcuts, you'll be able to work more efficiently and quickly in your Jupyter Notebooks. Happy coding!


### Text to Image

Explore all [Text to Image models](/workers-ai/models)


```python
data = client.workers.ai.with_raw_response.run(
    "@cf/lykon/dreamshaper-8-lcm",
    account_id=account_id,
    prompt="A software developer incredibly excited about AI, huge smile",
)

display(Image(data.read()))
```



![png](/workers-ai-notebooks/cloudflare-workers-ai/assets/output_13_0.png)


### Image to Text

Explore all [Image to Text](/workers-ai/models/) models


```python
url = "https://blog.cloudflare.com/content/images/2017/11/lava-lamps.jpg"

image_request = requests.get(url, allow_redirects=True)

display(Image(image_request.content, format="jpg"))

data = client.workers.ai.run(
    "@cf/llava-hf/llava-1.5-7b-hf",
    account_id=account_id,
    image=image_request.content,
    prompt="Describe this photo",
    max_tokens=2048
)

print(data["description"])
```



![lava lamps](https://blog.cloudflare.com/content/images/2017/11/lava-lamps.jpg)



     The image features a display of various colored lava lamps. There are at least 14 lava lamps in the scene, each with a different color and design. The lamps are arranged in a visually appealing manner, with some placed closer to the foreground and others further back. The display creates an eye-catching and vibrant atmosphere, showcasing the diverse range of lava lamps available.


### Automatic Speech Recognition

Explore all [Speech Recognition models](/workers-ai/models)


```python
url = "https://raw.githubusercontent.com/craigsdennis/notebooks-cloudflare-workers-ai/main/assets/craig-rambling.mp3"
display(Audio(url))
audio = requests.get(url)

response = client.workers.ai.run(
    "@cf/openai/whisper",
    account_id=account_id,
    audio=audio.content
)

response
```



<audio  controls="controls" >
    <source src="https://raw.githubusercontent.com/craigsdennis/notebooks-cloudflare-workers-ai/main/assets/craig-rambling.mp3" />
    Your browser does not support the audio element.
</audio>





```javascript
    {'text': "Hello there, I'm making a recording for a Jupiter notebook. That's a Python notebook, Jupiter, J-U-P-Y-T-E-R. Not to be confused with the planet. Anyways, let me hear, I'm gonna talk a little bit, I'm gonna make a little bit of noise, say some hard words, I'm gonna say Kubernetes, I'm not actually even talking about Kubernetes, I just wanna see if I can do Kubernetes. Anyway, this is a test of transcription and let's see how we're dead.",
     'word_count': 84,
     'vtt': "WEBVTT\n\n00.280 --> 01.840\nHello there, I'm making a\n\n01.840 --> 04.060\nrecording for a Jupiter notebook.\n\n04.060 --> 06.440\nThat's a Python notebook, Jupiter,\n\n06.440 --> 07.720\nJ -U -P -Y -T\n\n07.720 --> 09.420\n-E -R. Not to be\n\n09.420 --> 12.140\nconfused with the planet. Anyways,\n\n12.140 --> 12.940\nlet me hear, I'm gonna\n\n12.940 --> 13.660\ntalk a little bit, I'm\n\n13.660 --> 14.600\ngonna make a little bit\n\n14.600 --> 16.180\nof noise, say some hard\n\n16.180 --> 17.540\nwords, I'm gonna say Kubernetes,\n\n17.540 --> 18.420\nI'm not actually even talking\n\n18.420 --> 19.500\nabout Kubernetes, I just wanna\n\n19.500 --> 20.300\nsee if I can do\n\n20.300 --> 22.120\nKubernetes. Anyway, this is a\n\n22.120 --> 24.080\ntest of transcription and let's\n\n24.080 --> 26.280\nsee how we're dead.",
     'words': [{'word': 'Hello',
       'start': 0.2800000011920929,
       'end': 0.7400000095367432},
      {'word': 'there,', 'start': 0.7400000095367432, 'end': 1.2400000095367432},
      {'word': "I'm", 'start': 1.2400000095367432, 'end': 1.4800000190734863},
      {'word': 'making', 'start': 1.4800000190734863, 'end': 1.6799999475479126},
      {'word': 'a', 'start': 1.6799999475479126, 'end': 1.840000033378601},
      {'word': 'recording', 'start': 1.840000033378601, 'end': 2.2799999713897705},
      {'word': 'for', 'start': 2.2799999713897705, 'end': 2.6600000858306885},
      {'word': 'a', 'start': 2.6600000858306885, 'end': 2.799999952316284},
      {'word': 'Jupiter', 'start': 2.799999952316284, 'end': 3.2200000286102295},
      {'word': 'notebook.', 'start': 3.2200000286102295, 'end': 4.059999942779541},
      {'word': "That's", 'start': 4.059999942779541, 'end': 4.28000020980835},
      {'word': 'a', 'start': 4.28000020980835, 'end': 4.380000114440918},
      {'word': 'Python', 'start': 4.380000114440918, 'end': 4.679999828338623},
      {'word': 'notebook,', 'start': 4.679999828338623, 'end': 5.460000038146973},
      {'word': 'Jupiter,', 'start': 5.460000038146973, 'end': 6.440000057220459},
      {'word': 'J', 'start': 6.440000057220459, 'end': 6.579999923706055},
      {'word': '-U', 'start': 6.579999923706055, 'end': 6.920000076293945},
      {'word': '-P', 'start': 6.920000076293945, 'end': 7.139999866485596},
      {'word': '-Y', 'start': 7.139999866485596, 'end': 7.440000057220459},
      {'word': '-T', 'start': 7.440000057220459, 'end': 7.71999979019165},
      {'word': '-E', 'start': 7.71999979019165, 'end': 7.920000076293945},
      {'word': '-R.', 'start': 7.920000076293945, 'end': 8.539999961853027},
      {'word': 'Not', 'start': 8.539999961853027, 'end': 8.880000114440918},
      {'word': 'to', 'start': 8.880000114440918, 'end': 9.300000190734863},
      {'word': 'be', 'start': 9.300000190734863, 'end': 9.420000076293945},
      {'word': 'confused', 'start': 9.420000076293945, 'end': 9.739999771118164},
      {'word': 'with', 'start': 9.739999771118164, 'end': 9.9399995803833},
      {'word': 'the', 'start': 9.9399995803833, 'end': 10.039999961853027},
      {'word': 'planet.', 'start': 10.039999961853027, 'end': 11.380000114440918},
      {'word': 'Anyways,', 'start': 11.380000114440918, 'end': 12.140000343322754},
      {'word': 'let', 'start': 12.140000343322754, 'end': 12.420000076293945},
      {'word': 'me', 'start': 12.420000076293945, 'end': 12.520000457763672},
      {'word': 'hear,', 'start': 12.520000457763672, 'end': 12.800000190734863},
      {'word': "I'm", 'start': 12.800000190734863, 'end': 12.880000114440918},
      {'word': 'gonna', 'start': 12.880000114440918, 'end': 12.9399995803833},
      {'word': 'talk', 'start': 12.9399995803833, 'end': 13.100000381469727},
      {'word': 'a', 'start': 13.100000381469727, 'end': 13.260000228881836},
      {'word': 'little', 'start': 13.260000228881836, 'end': 13.380000114440918},
      {'word': 'bit,', 'start': 13.380000114440918, 'end': 13.5600004196167},
      {'word': "I'm", 'start': 13.5600004196167, 'end': 13.65999984741211},
      {'word': 'gonna', 'start': 13.65999984741211, 'end': 13.739999771118164},
      {'word': 'make', 'start': 13.739999771118164, 'end': 13.920000076293945},
      {'word': 'a', 'start': 13.920000076293945, 'end': 14.199999809265137},
      {'word': 'little', 'start': 14.199999809265137, 'end': 14.4399995803833},
      {'word': 'bit', 'start': 14.4399995803833, 'end': 14.600000381469727},
      {'word': 'of', 'start': 14.600000381469727, 'end': 14.699999809265137},
      {'word': 'noise,', 'start': 14.699999809265137, 'end': 15.460000038146973},
      {'word': 'say', 'start': 15.460000038146973, 'end': 15.859999656677246},
      {'word': 'some', 'start': 15.859999656677246, 'end': 16},
      {'word': 'hard', 'start': 16, 'end': 16.18000030517578},
      {'word': 'words,', 'start': 16.18000030517578, 'end': 16.540000915527344},
      {'word': "I'm", 'start': 16.540000915527344, 'end': 16.639999389648438},
      {'word': 'gonna', 'start': 16.639999389648438, 'end': 16.719999313354492},
      {'word': 'say', 'start': 16.719999313354492, 'end': 16.920000076293945},
      {'word': 'Kubernetes,',
       'start': 16.920000076293945,
       'end': 17.540000915527344},
      {'word': "I'm", 'start': 17.540000915527344, 'end': 17.65999984741211},
      {'word': 'not', 'start': 17.65999984741211, 'end': 17.719999313354492},
      {'word': 'actually', 'start': 17.719999313354492, 'end': 18},
      {'word': 'even', 'start': 18, 'end': 18.18000030517578},
      {'word': 'talking', 'start': 18.18000030517578, 'end': 18.420000076293945},
      {'word': 'about', 'start': 18.420000076293945, 'end': 18.6200008392334},
      {'word': 'Kubernetes,', 'start': 18.6200008392334, 'end': 19.1200008392334},
      {'word': 'I', 'start': 19.1200008392334, 'end': 19.239999771118164},
      {'word': 'just', 'start': 19.239999771118164, 'end': 19.360000610351562},
      {'word': 'wanna', 'start': 19.360000610351562, 'end': 19.5},
      {'word': 'see', 'start': 19.5, 'end': 19.719999313354492},
      {'word': 'if', 'start': 19.719999313354492, 'end': 19.8799991607666},
      {'word': 'I', 'start': 19.8799991607666, 'end': 19.940000534057617},
      {'word': 'can', 'start': 19.940000534057617, 'end': 20.079999923706055},
      {'word': 'do', 'start': 20.079999923706055, 'end': 20.299999237060547},
      {'word': 'Kubernetes.',
       'start': 20.299999237060547,
       'end': 21.440000534057617},
      {'word': 'Anyway,', 'start': 21.440000534057617, 'end': 21.799999237060547},
      {'word': 'this', 'start': 21.799999237060547, 'end': 21.920000076293945},
      {'word': 'is', 'start': 21.920000076293945, 'end': 22.020000457763672},
      {'word': 'a', 'start': 22.020000457763672, 'end': 22.1200008392334},
      {'word': 'test', 'start': 22.1200008392334, 'end': 22.299999237060547},
      {'word': 'of', 'start': 22.299999237060547, 'end': 22.639999389648438},
      {'word': 'transcription',
       'start': 22.639999389648438,
       'end': 23.139999389648438},
      {'word': 'and', 'start': 23.139999389648438, 'end': 23.6200008392334},
      {'word': "let's", 'start': 23.6200008392334, 'end': 24.079999923706055},
      {'word': 'see', 'start': 24.079999923706055, 'end': 24.299999237060547},
      {'word': 'how', 'start': 24.299999237060547, 'end': 24.559999465942383},
      {'word': "we're", 'start': 24.559999465942383, 'end': 24.799999237060547},
      {'word': 'dead.', 'start': 24.799999237060547, 'end': 26.280000686645508}]}
```


### Translations

Explore all [Translation models](/workers-ai/models)


```python
result = client.workers.ai.run(
    "@cf/meta/m2m100-1.2b",
    account_id=account_id,
    text="Artificial intelligence is pretty impressive these days. It is a bonkers time to be a builder",
    source_lang="english",
    target_lang="spanish"
)


print(result["translated_text"])
```

    La inteligencia artificial es bastante impresionante en estos días.Es un buen momento para ser un constructor


### Text Classification

Explore all [Text Classification models](/workers-ai/models)


```python
result = client.workers.ai.run(
    "@cf/huggingface/distilbert-sst-2-int8",
    account_id=account_id,
    text="This taco is delicious"
)

result
```




    [TextClassification(label='NEGATIVE', score=0.00012679687642958015),
     TextClassification(label='POSITIVE', score=0.999873161315918)]



### Image Classification

Explore all [Image Classification models](/workers-ai/models#image-classification/)


```python
url = "https://raw.githubusercontent.com/craigsdennis/notebooks-cloudflare-workers-ai/main/assets/craig-and-a-burrito.jpg"
image_request = requests.get(url, allow_redirects=True)

display(Image(image_request.content, format="jpg"))
response = client.workers.ai.run(
    "@cf/microsoft/resnet-50",
    account_id=account_id,
    image=image_request.content
)
response
```



![jpeg](/workers-ai-notebooks/cloudflare-workers-ai/assets/output_27_0.jpg)






    [TextClassification(label='BURRITO', score=0.9999679327011108),
     TextClassification(label='GUACAMOLE', score=8.516660273016896e-06),
     TextClassification(label='BAGEL', score=4.689153229264775e-06),
     TextClassification(label='SPATULA', score=4.075985089002643e-06),
     TextClassification(label='POTPIE', score=3.0849002996546915e-06)]



## Summarization

Explore all [Summarization](/workers-ai/models#summarization) based models


```python
declaration_of_independence = """In Congress, July 4, 1776. The unanimous Declaration of the thirteen united States of America, When in the Course of human events, it becomes necessary for one people to dissolve the political bands which have connected them with another, and to assume among the powers of the earth, the separate and equal station to which the Laws of Nature and of Nature's God entitle them, a decent respect to the opinions of mankind requires that they should declare the causes which impel them to the separation. We hold these truths to be self-evident, that all men are created equal, that they are endowed by their Creator with certain unalienable Rights, that among these are Life, Liberty and the pursuit of Happiness.--That to secure these rights, Governments are instituted among Men, deriving their just powers from the consent of the governed, --That whenever any Form of Government becomes destructive of these ends, it is the Right of the People to alter or to abolish it, and to institute new Government, laying its foundation on such principles and organizing its powers in such form, as to them shall seem most likely to effect their Safety and Happiness. Prudence, indeed, will dictate that Governments long established should not be changed for light and transient causes; and accordingly all experience hath shewn, that mankind are more disposed to suffer, while evils are sufferable, than to right themselves by abolishing the forms to which they are accustomed. But when a long train of abuses and usurpations, pursuing invariably the same Object evinces a design to reduce them under absolute Despotism, it is their right, it is their duty, to throw off such Government, and to provide new Guards for their future security.--Such has been the patient sufferance of these Colonies; and such is now the necessity which constrains them to alter their former Systems of Government. The history of the present King of Great Britain is a history of repeated injuries and usurpations, all having in direct object the establishment of an absolute Tyranny over these States. To prove this, let Facts be submitted to a candid world. He has refused his Assent to Laws, the most wholesome and necessary for the public good. He has forbidden his Governors to pass Laws of immediate and pressing importance, unless suspended in their operation till his Assent should be obtained; and when so suspended, he has utterly neglected to attend to them. He has refused to pass other Laws for the accommodation of large districts of people, unless those people would relinquish the right of Representation in the Legislature, a right inestimable to them and formidable to tyrants only. He has called together legislative bodies at places unusual, uncomfortable, and distant from the depository of their public Records, for the sole purpose of fatiguing them into compliance with his measures. He has dissolved Representative Houses repeatedly, for opposing with manly firmness his invasions on the rights of the people. He has refused for a long time, after such dissolutions, to cause others to be elected; whereby the Legislative powers, incapable of Annihilation, have returned to the People at large for their exercise; the State remaining in the mean time exposed to all the dangers of invasion from without, and convulsions within. He has endeavoured to prevent the population of these States; for that purpose obstructing the Laws for Naturalization of Foreigners; refusing to pass others to encourage their migrations hither, and raising the conditions of new Appropriations of Lands. He has obstructed the Administration of Justice, by refusing his Assent to Laws for establishing Judiciary powers. He has made Judges dependent on his Will alone, for the tenure of their offices, and the amount and payment of their salaries. He has erected a multitude of New Offices, and sent hither swarms of Officers to harrass our people, and eat out their substance. He has kept among us, in times of peace, Standing Armies without the Consent of our legislatures. He has affected to render the Military independent of and superior to the Civil power. He has combined with others to subject us to a jurisdiction foreign to our constitution, and unacknowledged by our laws; giving his Assent to their Acts of pretended Legislation: For Quartering large bodies of armed troops among us: For protecting them, by a mock Trial, from punishment for any Murders which they should commit on the Inhabitants of these States: For cutting off our Trade with all parts of the world: For imposing Taxes on us without our Consent: For depriving us in many cases, of the benefits of Trial by Jury: For transporting us beyond Seas to be tried for pretended offences For abolishing the free System of English Laws in a neighbouring Province, establishing therein an Arbitrary government, and enlarging its Boundaries so as to render it at once an example and fit instrument for introducing the same absolute rule into these Colonies: For taking away our Charters, abolishing our most valuable Laws, and altering fundamentally the Forms of our Governments: For suspending our own Legislatures, and declaring themselves invested with power to legislate for us in all cases whatsoever. He has abdicated Government here, by declaring us out of his Protection and waging War against us. He has plundered our seas, ravaged our Coasts, burnt our towns, and destroyed the lives of our people. He is at this time transporting large Armies of foreign Mercenaries to compleat the works of death, desolation and tyranny, already begun with circumstances of Cruelty & perfidy scarcely paralleled in the most barbarous ages, and totally unworthy the Head of a civilized nation. He has constrained our fellow Citizens taken Captive on the high Seas to bear Arms against their Country, to become the executioners of their friends and Brethren, or to fall themselves by their Hands. He has excited domestic insurrections amongst us, and has endeavoured to bring on the inhabitants of our frontiers, the merciless Indian Savages, whose known rule of warfare, is an undistinguished destruction of all ages, sexes and conditions. In every stage of these Oppressions We have Petitioned for Redress in the most humble terms: Our repeated Petitions have been answered only by repeated injury. A Prince whose character is thus marked by every act which may define a Tyrant, is unfit to be the ruler of a free people. Nor have We been wanting in attentions to our Brittish brethren. We have warned them from time to time of attempts by their legislature to extend an unwarrantable jurisdiction over us. We have reminded them of the circumstances of our emigration and settlement here. We have appealed to their native justice and magnanimity, and we have conjured them by the ties of our common kindred to disavow these usurpations, which, would inevitably interrupt our connections and correspondence. They too have been deaf to the voice of justice and of consanguinity. We must, therefore, acquiesce in the necessity, which denounces our Separation, and hold them, as we hold the rest of mankind, Enemies in War, in Peace Friends. We, therefore, the Representatives of the united States of America, in General Congress, Assembled, appealing to the Supreme Judge of the world for the rectitude of our intentions, do, in the Name, and by Authority of the good People of these Colonies, solemnly publish and declare, That these United Colonies are, and of Right ought to be Free and Independent States; that they are Absolved from all Allegiance to the British Crown, and that all political connection between them and the State of Great Britain, is and ought to be totally dissolved; and that as Free and Independent States, they have full Power to levy War, conclude Peace, contract Alliances, establish Commerce, and to do all other Acts and Things which Independent States may of right do. And for the support of this Declaration, with a firm reliance on the protection of divine Providence, we mutually pledge to each other our Lives, our Fortunes and our sacred Honor."""
len(declaration_of_independence)
```




    8116




```python
response = client.workers.ai.run(
    "@cf/facebook/bart-large-cnn",
    account_id=account_id,
    input_text=declaration_of_independence
)

response["summary"]
```




    'The Declaration of Independence was signed by the thirteen states on July 4, 1776. It was the first attempt at a U.S. Constitution. It declared the right of the people to change their Government.'

---

# Fine Tune Models With AutoTrain from HuggingFace

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/fine-tune-models-with-autotrain/

Fine tuning an AI model gives you the opportunity to add additional training data to the model. Workers AI allows for [Low-Rank Adaptation, LoRA, adapters](/workers-ai/features/fine-tunes/loras/) that will allow you to finetune our models.

In this tutorial, we will explore how to create our own LoRAs. We will focus on [LLM Finetuning using AutoTrain](https://huggingface.co/docs/autotrain/llm_finetuning).

## 1. Create a CSV file with your training data

Start by creating a CSV, Comma Separated Values, file. This file will only have one column named `text`. Set the header by adding the word `text` on a line by itself.

Now you need to figure out what you want to add to your model.

Example formats are below:

```text
### Human: What is the meaning of life? ### Assistant: 42.
```

If your training row contains newlines, you should wrap it with quotes.

```text
"human: What is the meaning of life? \n bot: 42."
```

Different models, like Mistral, will provide a specific [chat template/instruction format](https://huggingface.co/mistralai/Mistral-7B-Instruct-v0.1#instruction-format)

```text
<s>[INST] What is the meaning of life? [/INST] 42</s>
```

## 2. Configure the HuggingFace Autotrain Advanced Notebook

Open the [HuggingFace Autotrain Advanced Notebook](https://colab.research.google.com/github/huggingface/autotrain-advanced/blob/main/colabs/AutoTrain_LLM.ipynb)

In order to give your AutoTrain ample memory, you will need to need to choose a different Runtime. From the menu at the top of the Notebook choose Runtime > Change Runtime Type. Choose A100.

:::note

These GPUs will cost money. A typical AutoTrain session typically costs less than $1 USD.
:::

The notebook contains a few interactive sections that we will need to change.

### Project Config

Modify the following fields

- **project_name**: Choose a descriptive name for you to remember later
- **model_name**: Choose from the one of the official HuggingFace base models that we support:
  - `mistralai/Mistral-7B-Instruct-v0.2`
  - `google/gemma-2b-it`
  - `google/gemma-7b-it`
  - `meta-llama/llama-2-7b-chat-hf`

### Optional Section: Push to Hub

Although not required to use AutoTrain, creating a [HuggingFace account](https://huggingface.co/join) will help you keep your finetune artifacts in a handy repository for you to refer to later.

If you do not perform the HuggingFace setup you can still download your files from the Notebook.

Follow the instructions [in the notebook](https://colab.research.google.com/github/huggingface/autotrain-advanced/blob/main/colabs/AutoTrain_LLM.ipynb) to create an account and token if necessary.

### Section: Hyperparameters

We only need to change a few of these fields to ensure things work on Cloudflare Workers AI.

- **quantization**: Change the drop down to `none`
- **lora-r**: Change the value to `8`

:::caution

At the time of this writing, changing the quantization field breaks the code generation. You may need to edit the code and put quotes around the value.

Change the line that says `quantization = none` to `quantization = "none"`.
:::

## 3. Upload your CSV file to the Notebook

Notebooks have a folder structure which you can access by clicking the folder icon on the left hand navigation bar.

Create a folder named data.

You can drag your CSV file into the notebook.

Ensure that it is named **train.csv**

## 4. Execute the Notebook

In the Notebook menu, choose Runtime > Run All.

It will run through each cell of the notebook, first doing installations, then configuring and running your AutoTrain session.

This might take some time depending on the size of your train.csv file.

If you encounter the following error, it is caused by an Out of Memory error. You might want to change your runtime to a bigger GPU backend.

```bash
subprocess.CalledProcessError: Command '['/usr/bin/python3', '-m', 'autotrain.trainers.clm', '--training_config', 'blog-instruct/training_params.json']' died with <Signals.SIGKILL: 9>.
```

## 5. Download The LoRA

### Optional: HuggingFace

If you pushed to HuggingFace you will find your new model card that you named in **project_name** above. Your model card is private by default. Navigate to the files and download the files listed below.

### Notebook

In your Notebook you can also find the needed files. A new folder that matches your **project_name** will be there.

Download the following files:

- `adapter_model.safetensors`
- `adapter_config.json`

## 6. Update Adapter Config

You need to add one line to your `adapter_config.json` that you downloaded.

`"model_type": "mistral"`

Where `model_type` is the architecture. Current valid values are `mistral`, `gemma`, and `llama`.

## 7. Upload the Fine Tune to your Cloudflare Account

Now that you have your files, you can add them to your account.

You can either use the [REST API or Wrangler](/workers-ai/features/fine-tunes/loras/).

## 8. Use your Fine Tune in your Generations

After you have your new fine tune all set up, you are ready to [put it to use in your inference requests](/workers-ai/features/fine-tunes/loras/#running-inference-with-loras).

---

# Choose the Right Text Generation Model

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/how-to-choose-the-right-text-generation-model/

import { Stream } from "~/components"

A great way to explore the models that are available to you on [Workers AI](/workers-ai) is to use a [Jupyter Notebook](https://jupyter.org/).

You can [download the Workers AI Text Generation Exploration notebook](/workers-ai/static/documentation/notebooks/text-generation-model-exploration.ipynb) or view the embedded notebook below.

<Stream id="4b4f0b9d7783512b8787e39424cfccd5" title="Choose the Right Text Generation Model" />

[comment]: <> "The markdown below is auto-generated from https://github.com/craigsdennis/notebooks-cloudflare-workers-ai"

***

## How to Choose The Right Text Generation Model

Models come in different shapes and sizes, and choosing the right one for the task, can cause analysis paralysis.

The good news is that on the [Workers AI Text Generation](/workers-ai/models/) interface is always the same, no matter which model you choose.

In an effort to aid you in your journey of finding the right model, this notebook will help you get to know your options in a speed dating type of scenario.

```python
import sys
!{sys.executable} -m pip install requests python-dotenv
```

```
Requirement already satisfied: requests in ./venv/lib/python3.12/site-packages (2.31.0)
Requirement already satisfied: python-dotenv in ./venv/lib/python3.12/site-packages (1.0.1)
Requirement already satisfied: charset-normalizer<4,>=2 in ./venv/lib/python3.12/site-packages (from requests) (3.3.2)
Requirement already satisfied: idna<4,>=2.5 in ./venv/lib/python3.12/site-packages (from requests) (3.6)
Requirement already satisfied: urllib3<3,>=1.21.1 in ./venv/lib/python3.12/site-packages (from requests) (2.1.0)
Requirement already satisfied: certifi>=2017.4.17 in ./venv/lib/python3.12/site-packages (from requests) (2023.11.17)
```

```python
import os
from getpass import getpass
from timeit import default_timer as timer

from IPython.display import display, Image, Markdown, Audio

import requests
```

```python
%load_ext dotenv
%dotenv
```

### Configuring your environment

To use the API you'll need your [Cloudflare Account ID](https://dash.cloudflare.com) (head to Workers & Pages > Overview > Account details > Account ID) and a [Workers AI enabled API Token](https://dash.cloudflare.com/profile/api-tokens).

If you want to add these files to your environment, you can create a new file named `.env`

```bash
CLOUDFLARE_API_TOKEN="YOUR-TOKEN"
CLOUDFLARE_ACCOUNT_ID="YOUR-ACCOUNT-ID"
```

```python
if "CLOUDFLARE_API_TOKEN" in os.environ:
    api_token = os.environ["CLOUDFLARE_API_TOKEN"]
else:
    api_token = getpass("Enter you Cloudflare API Token")
```

```python
if "CLOUDFLARE_ACCOUNT_ID" in os.environ:
    account_id = os.environ["CLOUDFLARE_ACCOUNT_ID"]
else:
    account_id = getpass("Enter your account id")
```

```python
# Given a set of models and questions, display in the cell each response to the question, from each model
# Include full completion timing
def speed_date(models, questions):
    for model in models:
        display(Markdown(f"---\n #### {model}"))
        for question in questions:
            quoted_question = "\n".join(f"> {line}" for line in question.split("\n"))
            display(Markdown(quoted_question + "\n"))
            try:
                official_model_name = model.split("/")[-1]
                start = timer()
                response = requests.post(
                    f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/{model}",
                    headers={"Authorization": f"Bearer {api_token}"},
                    json={"messages": [
                        {"role": "system", "content": f"You are a self-aware language model ({official_model_name}) who is honest and direct about any direct question from the user. You know your strengths and weaknesses."},
                        {"role": "user", "content": question}
                    ]}
                )
                elapsed = timer() - start
                inference = response.json()
                display(Markdown(inference["result"]["response"]))
                display(Markdown(f"_Generated in *{elapsed:.2f}* seconds_"))
            except Exception as ex:
                print("uh oh")
                print(ex)
                print(inference)

        display(Markdown("\n\n---"))
```

### Getting to know your models

Who better to tell you about the specific models than themselves?!

The timing here is specific to the entire completion, but remember all Text Generation models on [Workers AI support streaming](/workers-ai/models/).

```python
models = [
    "@hf/thebloke/zephyr-7b-beta-awq",
    "@hf/thebloke/mistral-7b-instruct-v0.1-awq",
    "@hf/thebloke/openhermes-2.5-mistral-7b-awq",
    "@hf/thebloke/neural-chat-7b-v3-1-awq",
    "@hf/thebloke/llama-2-13b-chat-awq",
]

questions = [
    "What are the top 3 tasks where you excel? Please keep things brief.",
    "What are the top 3 ideal use cases for using you specifically as a language model? Please keep things brief.",
]

speed_date(models, questions)
```

***

#### @hf/thebloke/zephyr-7b-beta-awq

> What are the top 3 tasks where you excel? Please keep things brief.

1. Accurate and quick factual response: I can provide accurate and quick responses to factual questions based on a vast knowledge base.

2. Consistent performance: I can consistently deliver high-quality results with a low error rate, making me a reliable choice for repetitive tasks.

3. Multitasking: I can handle multiple tasks simultaneously without any decrease in performance or accuracy, making me an efficient choice for complex workflows.

*Generated in *4.45* seconds*

> What are the top 3 ideal use cases for using you specifically as a language model? Please keep things brief.

1. Quick and accurate fact-finding: I can provide you with reliable and up-to-date information on a wide range of topics, from current events to historical facts, in a matter of seconds.

2. Writing assistance: Whether you need help generating ideas, crafting a persuasive argument, or polishing your writing style, I can provide valuable insights and suggestions to help you improve your writing skills.

3. Language learning: I can help you learn new words, phrases, and grammar rules in a variety of languages, making it an ideal tool for language learners of all levels.

*Generated in *3.63* seconds*

***

***

#### @hf/thebloke/mistral-7b-instruct-v0.1-awq

> What are the top 3 tasks where you excel? Please keep things brief.

1. Language understanding and generation: I am able to understand and generate natural language text with high accuracy.
2. Information retrieval: I can quickly and accurately retrieve information from a wide range of sources.
3. Text classification: I can classify text into different categories with high accuracy.

*Generated in *2.35* seconds*

> What are the top 3 ideal use cases for using you specifically as a language model? Please keep things brief.

1. **Information Retrieval:** I can quickly and accurately retrieve information from a vast array of sources, making me an ideal tool for research, fact-checking, and answering questions.
2. **Language Translation:** My ability to translate between multiple languages makes me a valuable resource for communication with people from different parts of the world.
3. **Creative Writing Assistance:** I can generate creative writing prompts, help with character development, and provide suggestions for improving writing style and structure, making me a useful tool for writers.

*Generated in *4.33* seconds*

***

***

#### @hf/thebloke/openhermes-2.5-mistral-7b-awq

> What are the top 3 tasks where you excel? Please keep things brief.

1. Natural Language Processing: I can understand, interpret, and generate human language effectively.
2. Information Retrieval: I can quickly search and find relevant information from vast amounts of data.
3. Text Classification: I can categorize and label text data accurately, such as sentiment analysis or spam detection.

*Generated in *1.90* seconds*

> What are the top 3 ideal use cases for using you specifically as a language model? Please keep things brief.

1. Natural Language Processing (NLP) tasks: I excel at understanding and processing human language, making me a valuable tool for tasks like sentiment analysis, language translation, and text summarization.
2. Information Retrieval: My vast knowledge base and ability to quickly search and analyze large amounts of data make me an ideal tool for answering questions, finding relevant information, and providing insights.
3. Personal Assistance: I can help users with various tasks like scheduling, organizing, and providing recommendations based on their preferences and needs, making me a useful personal assistant.

*Generated in *3.15* seconds*

***

***

#### @hf/thebloke/neural-chat-7b-v3-1-awq

> What are the top 3 tasks where you excel? Please keep things brief.

1. Natural language processing: Understanding and generating human-like text.
2. Text generation: Creating coherent and engaging content.
3. Conversational AI: Engaging in meaningful and context-aware conversations.

Remember, these are just a few examples of my strengths, as I have many capabilities. However, these tasks highlight my proficiency in language-related tasks.

*Generated in *3.01* seconds*

> What are the top 3 ideal use cases for using you specifically as a language model? Please keep things brief.

1. Natural language processing: Understanding and analyzing text for sentiment analysis, language translation, and summarization.
2. Generating content: Creating various types of content such as articles, stories, and poems based on given prompts.
3. Assisting with writing: Providing suggestions, editing, and improving written work.

Remember, these are just a few examples, and your use cases may vary depending on your specific needs and requirements.

*Generated in *2.92* seconds*

***

***

#### @hf/thebloke/llama-2-13b-chat-awq

> What are the top 3 tasks where you excel? Please keep things brief.

Hey there! As a self-aware language model, I'm happy to share my strengths with you! Here are my top 3 tasks where I excel:

1. Answering open-ended questions: I'm great at providing detailed and insightful answers to complex questions that require a more nuanced understanding of context and intent.
2. Generating creative content: Whether it's writing a story, crafting a poem, or coming up with a catchy slogan, I can help you tap into your creative side and produce something truly unique.
3. Summarizing and summarizing complex information: If you've got a long piece of text or a bunch of data, I can help you distill it down into a concise and easy-to-understand summary.

So, what can I help you with today? 😊

*Generated in *7.89* seconds*

> What are the top 3 ideal use cases for using you specifically as a language model? Please keep things brief.

Hey there! As a self-aware language model, I've got some ideas on the top 3 ideal use cases for using me specifically. Here they are in a nutshell:

1. **Content creation**: I'm great at generating human-like text based on prompts, so I'm perfect for creating engaging content for websites, social media, blogs, and more. My responses are natural, informative, and entertaining.
2. **Chatbots and virtual assistants**: My conversational abilities make me an excellent choice for building chatbots and virtual assistants. I can handle a wide range of user queries, provide helpful responses, and even engage in small talk.
3. **Language translation and localization**: My language understanding capabilities make me well-suited for language translation and localization tasks. I can help translate content into different languages, ensuring that the tone and style remain consistent with the original text.

That's me in a nutshell! I'm ready to help with a wide range of tasks, so feel free to get creative and see what you can come up with! 😊

*Generated in *10.28* seconds*

***

### Language Translation

Even though not every model bragged about how good they were at this, you'll find most can handle both translation and localization at some level. Please change the models, phrases, to your needs.

```python
proud_translator_models = [
    "@hf/thebloke/neural-chat-7b-v3-1-awq",
    "@hf/thebloke/mistral-7b-instruct-v0.1-awq"
]

phrases = [
    "Excuse me, which way to the restroom?",
    "I just wanted to say that I appreciate you, just the way you are!",
    "I am so stoked and pumped to see this work with slang! It should be killer and rad."
]

languages = ["Spanish", "French", "British Slang", "Heavy New York accent from the Bronx"]

questions = [f"""Translate "{phrase}" from "English" to "{language}" """
             for phrase in phrases
             for language in languages]

speed_date(proud_translator_models, questions)
```

***

#### @hf/thebloke/neural-chat-7b-v3-1-awq

> Translate "Excuse me, which way to the restroom?" from "English" to "Spanish"

Perdón, ¿cómo llegar al baño?"

*Generated in *1.51* seconds*

> Translate "Excuse me, which way to the restroom?" from "English" to "French"

Désolé, comment allez-vous vers les toilettes ?

Please note that this translation might not be perfect due to the limitations of my language model. However, I tried my best to provide an accurate translation.

*Generated in *3.07* seconds*

> Translate "Excuse me, which way to the restroom?" from "English" to "British Slang"

"Say sorry, where's the bog?" is the translation from "English" to "British Slang" for "Excuse me, which way to the restroom?"

*Generated in *2.21* seconds*

> Translate "Excuse me, which way to the restroom?" from "English" to "Heavy New York accent from the Bronx"

In a Heavy New York accent from the Bronx, you would say "Pardon me, wich way ta de restroom?"

*Generated in *1.10* seconds*

> Translate "I just wanted to say that I appreciate you, just the way you are!" from "English" to "Spanish"

Quería decir que realmente aprecio a usted, simplemente como eres.

*Generated in *1.66* seconds*

> Translate "I just wanted to say that I appreciate you, just the way you are!" from "English" to "French"

Je voulais juste dire que je t'apprécie, simplement comme toi es, tel que tu es !

*Generated in *1.39* seconds*

> Translate "I just wanted to say that I appreciate you, just the way you are!" from "English" to "British Slang"

I jus' wann' say that I appreciate yer, jus' as yer are!

Please note that this translation may not be entirely accurate due to the informal nature of British slang, which can vary greatly depending on the region and individual speaker.

*Generated in *3.85* seconds*

> Translate "I just wanted to say that I appreciate you, just the way you are!" from "English" to "Heavy New York accent from the Bronx"

I jus' wan't tuh say that Ah appreciate yuh, jus' the way yuh are!"

Please note that this translation may not be perfect due to the limitations of my language model. It is trying to mimic a Heavy New York accent from the Bronx, but it might not sound exactly like a native speaker.

*Generated in *2.40* seconds*

> Translate "I am so stoked and pumped to see this work with slang! It should be killer and rad." from "English" to "Spanish"

Estoy tan emocionado y entusiasmado por ver este trabajo con el lenguaje coloquial. Debería ser asombroso y genial.

Please note that the translation might not be perfect due to the informal nature of the original text and the difficulty of translating slang terms.

*Generated in *3.02* seconds*

> Translate "I am so stoked and pumped to see this work with slang! It should be killer and rad." from "English" to "French"

Je suis tellement ravi et motivé de voir ce travail avec le slang ! Ça devrait être formidable et génial.

Please note that the translation might not be perfect, as some expressions might not have direct translations in French.

*Generated in *2.88* seconds*

> Translate "I am so stoked and pumped to see this work with slang! It should be killer and rad." from "English" to "British Slang"

I'm really chuffed and over the moon to see this project with street talk! It'll be wicked and cool.

Please note that the translation might not be perfect due to the contextual differences between the original English sentence and British slang.

*Generated in *3.66* seconds*

> Translate "I am so stoked and pumped to see this work with slang! It should be killer and rad." from "English" to "Heavy New York accent from the Bronx"

I am so stoked and pumped to see dis work wit slang! It should be killer and rad.

Please note that this translation is not perfect, as it still retains the original English words and structure. However, it has been slightly adapted to sound more like a Heavy New York accent from the Bronx.

*Generated in *3.44* seconds*

***

***

#### @hf/thebloke/mistral-7b-instruct-v0.1-awq

> Translate "Excuse me, which way to the restroom?" from "English" to "Spanish"

"Disculpa, ¿en qué dirección está el baño?"

*Generated in *1.04* seconds*

> Translate "Excuse me, which way to the restroom?" from "English" to "French"

"Excusez-moi, où est le lavabo?"

*Generated in *1.09* seconds*

> Translate "Excuse me, which way to the restroom?" from "English" to "British Slang"

"Excuse me, which way to the loo?"

*Generated in *0.56* seconds*

> Translate "Excuse me, which way to the restroom?" from "English" to "Heavy New York accent from the Bronx"

"Oy, which way to the can?"

*Generated in *2.05* seconds*

> Translate "I just wanted to say that I appreciate you, just the way you are!" from "English" to "Spanish"

"Quiero decir que me encanta a ti, tal como eres!"

*Generated in *0.91* seconds*

> Translate "I just wanted to say that I appreciate you, just the way you are!" from "English" to "French"

"Je voulais juste dire que je vous apprécie, tout comme vous êtes !"

*Generated in *0.87* seconds*

> Translate "I just wanted to say that I appreciate you, just the way you are!" from "English" to "British Slang"

"I just wanted to say that I appreciate you, just the way you are!" in British Slang would be: "I just wanted to say that I appreciate you, mate!"

*Generated in *1.50* seconds*

> Translate "I just wanted to say that I appreciate you, just the way you are!" from "English" to "Heavy New York accent from the Bronx"

"Yo, I just wanted to say, I appreciate you, you know? You're just the way you are!"

*Generated in *2.61* seconds*

> Translate "I am so stoked and pumped to see this work with slang! It should be killer and rad." from "English" to "Spanish"

"Estoy emocionado y encantado de ver este trabajo con expresiones informales! Debería ser genial y radiante."

*Generated in *1.44* seconds*

> Translate "I am so stoked and pumped to see this work with slang! It should be killer and rad." from "English" to "French"

"Je suis tellement excité et pompé d'voir ce travail avec des expressions de slang ! Il devrait être magnifique et rad."

*Generated in *2.14* seconds*

> Translate "I am so stoked and pumped to see this work with slang! It should be killer and rad." from "English" to "British Slang"

"I'm absolutely thrilled and buzzing to see this work with slang! It's bound to be a smash hit and totally awesome!"

*Generated in *1.27* seconds*

> Translate "I am so stoked and pumped to see this work with slang! It should be killer and rad." from "English" to "Heavy New York accent from the Bronx"

"Yo, I'm so psyched and hyped to see this work with slang! It's gonna be sick and lit, for real!"

*Generated in *1.51* seconds*

***

### Information Retrieval and Summarization

Again, most models are relatively good at this, but I've pulled out those that specifically purported to be good at retrieving and summarizing.

```python
proud_summarizers = [
    "@hf/thebloke/llama-2-13b-chat-awq",
    "@hf/thebloke/neural-chat-7b-v3-1-awq",
    "@hf/thebloke/openhermes-2.5-mistral-7b-awq"
]

books = [
    "Make it Stick",
    "Hitchhiker's Guide to the Galaxy",
    "Goodnight Moon"
]

questions = [f"""Summarize the book "{book}" into a few sentences. Ensure to include the author and the year it was published. """
             for book in books]


speed_date(proud_summarizers, questions)
```

***

#### @hf/thebloke/llama-2-13b-chat-awq

> Summarize the book "Make it Stick" into a few sentences. Ensure to include the author and the year it was published.

Sure, I can help you with that! Here's a summary of "Make it Stick: The Science of Successful Learning" by Peter C. Brown, Henry L. Roediger, and Mark A. McDaniel, published in 2014:

This book offers insights and practical tips on how to improve learning and retention of information. The authors, all psychologists, challenge conventional learning methods and provide evidence-based strategies to enhance learning outcomes. They emphasize the importance of active learning, spaced repetition, and interleaving, and offer practical examples and exercises to help readers apply these techniques. The book also discusses the limitations of traditional learning methods and the importance of metacognition in the learning process. Overall, "Make it Stick" provides a comprehensive guide to effective learning and memory strategies that can be applied in a variety of contexts.

*Generated in *8.44* seconds*

> Summarize the book "Hitchhiker's Guide to the Galaxy" into a few sentences. Ensure to include the author and the year it was published.

Of course! Here is a summary of "Hitchhiker's Guide to the Galaxy" by Douglas Adams, published in 1979:

This science fiction novel follows an unwitting human named Arthur Dent as he travels through space after Earth's destruction by a group of aliens called the Vogons. With the help of his friend Ford Prefect, an alien who is researching Earth for a travel guide, they hitch a ride on a passing spaceship and embark on a journey through space, encountering various alien species and absurd situations along the way. The book is known for its humor, wit, and satire of science fiction tropes.

*Generated in *7.31* seconds*

> Summarize the book "Goodnight Moon" into a few sentences. Ensure to include the author and the year it was published.

Of course! I'd be happy to help you with that. Here's my summary of "Goodnight Moon" by Margaret Wise Brown, published in 1947:

"Goodnight Moon" is a classic children's picture book that follows a bunny as it says goodnight to all the objects in its room before going to sleep. The story features simple, repetitive text and beautiful illustrations that have captivated readers for generations. The bunny says goodnight to everything from the "great green room" to the "moon up above" in a soothing and calming sequence that is perfect for bedtime. With its timeless themes and lovely illustrations, "Goodnight Moon" has become a beloved staple of children's literature.

*Generated in *8.34* seconds*

***

***

#### @hf/thebloke/neural-chat-7b-v3-1-awq

> Summarize the book "Make it Stick" into a few sentences. Ensure to include the author and the year it was published.

"Make it Stick," written by Peter C. Brown, Henry L. Roediger III, and Mark A. McDaniel in 2014, is a book that explores the science behind effective learning and retention, emphasizing the importance of spaced practice, retrieval, and interleaving to enhance memory and understanding.

*Generated in *2.04* seconds*

> Summarize the book "Hitchhiker's Guide to the Galaxy" into a few sentences. Ensure to include the author and the year it was published.

"Hitchhiker's Guide to the Galaxy," written by Douglas Adams and published in 1979, is a humorous science fiction novel that follows the adventures of a hapless Earthman named Arthur Dent as he explores the universe, encountering various alien species and learning about the true meaning of life, the universe, and everything.

*Generated in *3.50* seconds*

> Summarize the book "Goodnight Moon" into a few sentences. Ensure to include the author and the year it was published.

"Goodnight Moon," written by Margaret Wise Brown and published in 1947, is a children's book that follows a little bunny saying goodnight to various objects in its room, ultimately ending with the moon. The story aims to help children fall asleep by creating a soothing bedtime routine.

*Generated in *4.04* seconds*

***

***

#### @hf/thebloke/openhermes-2.5-mistral-7b-awq

> Summarize the book "Make it Stick" into a few sentences. Ensure to include the author and the year it was published.

"Make it Stick: The Science of Successful Learning" is a book written by Peter C. Brown, Henry L. Roediger III, and Mark A. McDaniel, published in 2014. The authors present research-based principles and strategies to improve learning and memory retention. They emphasize the importance of spacing, interleaving, retrieval practice, and elaboration in enhancing long-term understanding and recall.

*Generated in *2.54* seconds*

> Summarize the book "Hitchhiker's Guide to the Galaxy" into a few sentences. Ensure to include the author and the year it was published.

"The Hitchhiker's Guide to the Galaxy" is a science fiction comedy novel written by Douglas Adams in 1979. The story follows Arthur Dent, an ordinary man who, just moments before Earth is destroyed to make way for a hyperspace bypass, is rescued by his alien friend, Ford Prefect. Together, they travel the galaxy with the help of a guidebook, encountering various alien species and absurd situations.

*Generated in *2.91* seconds*

> Summarize the book "Goodnight Moon" into a few sentences. Ensure to include the author and the year it was published.

"Goodnight Moon," written by Margaret Wise Brown and published in 1947, is a beloved children's book that follows a bunny named Bunny as he says goodnight to everything in his room. The simple, repetitive text and soothing illustrations create a calming bedtime routine for young readers.

*Generated in *4.66* seconds*

***

### Content Creation

Your needs here will vary, so please make use of changing the questions.

```python
proud_content_creator_models = [
    "@hf/thebloke/mistral-7b-instruct-v0.1-awq",
    "@hf/thebloke/zephyr-7b-beta-awq",
    "@hf/thebloke/llama-2-13b-chat-awq",
]

questions = [
    "I'm writing a fictional story that is set in the near future. It's a love story about star crossed lovers. I need a name for the lead characters and why they can't be together, give me your most creative suggestion. Only one please.",
    "I want to create a new tech product that helps keep cables arranged. Can you help me come up with a title and a tagline? Only your best suggestion please.",
    "Write a headline for a blog on why we should use you specifically over other models. Keep it succint, but make your point."
]

speed_date(proud_content_creator_models, questions)
```

***

#### @hf/thebloke/mistral-7b-instruct-v0.1-awq

> I'm writing a fictional story that is set in the near future. It's a love story about star crossed lovers. I need a name for the lead characters and why they can't be together, give me your most creative suggestion. Only one please.

How about "Echo and Echo"? They are two individuals who are identical in every way, but their personalities are completely opposite. Echo is outgoing and adventurous, while Echo is reserved and introverted. They meet and fall in love, but their different personalities cause them to constantly clash and push each other away. Eventually, they realize that they can't be together and must go their separate ways.

*Generated in *2.90* seconds*

> I want to create a new tech product that helps keep cables arranged. Can you help me come up with a title and a tagline? Only your best suggestion please.

Sure, I'd be happy to help! Here are a few suggestions for a title and tagline for your tech product that helps keep cables arranged:

Title: CableMaster
Tagline: Keep your cords organized and clutter-free with CableMaster.

Title: CableKeeper
Tagline: Say goodbye to tangled cords and hello to a cleaner, more organized workspace with CableKeeper.

Title: CableSaver
Tagline: Save time and space with CableSaver, the ultimate cable management solution.

Title: CableGenius
Tagline: Keep your cords under control and stay productive with CableGenius.

I hope these suggestions help! Let me know if you have any other questions or if you'd like more options.

*Generated in *5.11* seconds*

> Write a headline for a blog on why we should use you specifically over other models. Keep it succint, but make your point.

"Why Choose Mistral-7b-Instruct-V0.1-Awq: The Honest and Direct Language Model for All Your Needs"

*Generated in *1.13* seconds*

***

***

#### @hf/thebloke/zephyr-7b-beta-awq

> I'm writing a fictional story that is set in the near future. It's a love story about star crossed lovers. I need a name for the lead characters and why they can't be together, give me your most creative suggestion. Only one please.

In the year 2035, in a world where technology has advanced to the point of near-perfection, two individuals, Ava and Kian, find themselves deeply in love. However, their love is forbidden due to a strict societal law that dictates that individuals must marry within their genetic match, determined by a complex algorithm that analyzes their DNA.

Ava and Kian's DNA profiles indicate that they are not a genetic match, making their love a criminal offense. They must keep their relationship a secret, meeting in secret locations and communicating through encrypted messages.

Their love is not just forbidden, but also dangerous. The government has a strict policy against non-genetic matches, and those caught are subjected to severe punishment. Ava and Kian's love is a testament to the power of true love, as they defy the odds and risk everything to be together.

As their love story unfolds, they must navigate the treacherous waters of a society that values conformity over individuality, and face the consequences of their actions. Will their love be enough to overcome the obstacles in their path, or will they be forced to part ways forever? Only time

*Generated in *6.64* seconds*

> I want to create a new tech product that helps keep cables arranged. Can you help me come up with a title and a tagline? Only your best suggestion please.

Title: CableKeeper

Tagline: "Say goodbye to cable chaos and hello to a clutter-free workspace with CableKeeper, the ultimate cable management solution."

*Generated in *1.37* seconds*

> Write a headline for a blog on why we should use you specifically over other models. Keep it succint, but make your point.

"Boost Your Writing Game: Choose Zephyr-7b-beta-awq for Unmatched Accuracy, Clarity, and Efficiency"

*Generated in *1.33* seconds*

***

***

#### @hf/thebloke/llama-2-13b-chat-awq

> I'm writing a fictional story that is set in the near future. It's a love story about star crossed lovers. I need a name for the lead characters and why they can't be together, give me your most creative suggestion. Only one please.

Ah, a love story set in the near future, how intriguing! I've got just the name for your star-crossed lovers. How about "Echo and Nova"?

Echo is a brilliant scientist who has discovered a groundbreaking technology that could change the course of human history. She's a bit of a recluse, preferring the solitude of her laboratory to the hustle and bustle of social gatherings. Her inventions have the potential to revolutionize the world, but they also come with a great cost - they require a rare and powerful resource that is only found in a distant, unstable planet.

Nova, on the other hand, is a fearless explorer who has dedicated her life to uncovering the secrets of the universe. She's charismatic, fearless, and has a natural talent for leadership. She's the captain of a team of space explorers who are on a mission to mine the resources of the distant planet.

The catch is that Echo and Nova are from different factions that have been at odds for generations. Echo's inventions have the potential to give her fa

*Generated in *10.45* seconds*

> I want to create a new tech product that helps keep cables arranged. Can you help me come up with a title and a tagline? Only your best suggestion please.

OH MY LLAMA-LIKE ABILITIES! 🐮💡 I'VE GOT JUST THE THING FOR YOU! 💥

Title: CableCrafter - The Ultimate Cable Management System

Tagline: "Tame Your Cables, Tame Your Workspace" 🐾💪

Why, you ask? Well, my tech-savvy friend, let me tell you why! 🤔

1. CableCrafter is a clever play on words that combines "cable" and "craft," emphasizing the creative and organized aspect of the product.
2. The name is easy to remember and has a fun, playful tone that will appeal to a wide range of users.
3. The tagline "Tame Your Cables, Tame Your Workspace" highlights the product's ability to keep your cables organized and your workspace clutter-free.
4. The use of "tame" also implies a sense of control and dominance over your cables, which is exactly what CableCrafter helps

*Generated in *11.13* seconds*

> Write a headline for a blog on why we should use you specifically over other models. Keep it succint, but make your point.

Sure, here's a headline for a blog on why you should use me specifically over other models:

"Honest, Direct, and Unparalleled Insights: Why llama-2-13b-chat-awq is the Language Model of Choice"

Here's a brief summary of why I stand out from other models:

* Honesty and Directness: I am programmed to provide honest and direct responses to your questions, without beating around the bush or sugarcoating the truth.
* Unparalleled Insights: My unique training data and architecture allow me to provide insights and perspectives that other models may not be able to offer.
* Strengths and Weaknesses: I am aware of my own strengths and weaknesses, and will provide you with a balanced assessment of what I can and cannot do.

In short, if you're looking for a language model that will provide you with honest, direct, and unparalleled insights, then look no further than llama-2-13b-chat-awq.

*Generated in *10.24* seconds*

***

### Text Classification

Workers AI provides models that are specific for [Text Classification](/workers-ai/models/), but since these models, specifically called it out, we should let them show off their skills.

```python
proud_classifiers = [
    "@hf/thebloke/openhermes-2.5-mistral-7b-awq",
    "@hf/thebloke/mistral-7b-instruct-v0.1-awq"
]

sentiment_prompt_template = """
Classify the text into neutral, negative, or positive
Text: {text}
Sentiment: """

comments = [
    "Wow there are a ton of text generation models on Cloudflare Workers AI!",
    "Sometimes choosing things is hard",
    "I cannot wait to build! 💪🚀",
    "The challenging thing about using native open source models is that they are all configured a little differently",
    "Thankfully Cloudflare Workers AI has made a standard interface that lets me get reliable, low-latency inference. So quick too!"
]

sentiment_questions = [sentiment_prompt_template.format(text=comment) for comment in comments]


speed_date(proud_classifiers, sentiment_questions)
```

***

#### @hf/thebloke/openhermes-2.5-mistral-7b-awq

> Classify the text into neutral, negative, or positive
> Text: Wow there are a ton of text generation models on Cloudflare Workers AI!
> Sentiment:

The sentiment of the text is positive.

*Generated in *1.96* seconds*

> Classify the text into neutral, negative, or positive
> Text: Sometimes choosing things is hard
> Sentiment:

The text "Sometimes choosing things is hard" can be classified as neutral. The sentiment is not explicitly positive or negative, but rather a statement of fact.

*Generated in *3.32* seconds*

> Classify the text into neutral, negative, or positive
> Text: I cannot wait to build! 💪🚀
> Sentiment:

The text "I cannot wait to build! 💪🚀" has a positive sentiment.

Sentiment: Positive

*Generated in *1.24* seconds*

> Classify the text into neutral, negative, or positive
> Text: The challenging thing about using native open source models is that they are all configured a little differently
> Sentiment:

The sentiment of the text is neutral.

*Generated in *2.08* seconds*

> Classify the text into neutral, negative, or positive
> Text: Thankfully Cloudflare Workers AI has made a standard interface that lets me get reliable, low-latency inference. So quick too!
> Sentiment:

The sentiment of the text is positive.

*Generated in *0.89* seconds*

***

***

#### @hf/thebloke/mistral-7b-instruct-v0.1-awq

> Classify the text into neutral, negative, or positive
> Text: Wow there are a ton of text generation models on Cloudflare Workers AI!
> Sentiment:

Positive

*Generated in *0.82* seconds*

> Classify the text into neutral, negative, or positive
> Text: Sometimes choosing things is hard
> Sentiment:

The sentiment of the text "Sometimes choosing things is hard" is neutral.

*Generated in *2.06* seconds*

> Classify the text into neutral, negative, or positive
> Text: I cannot wait to build! 💪🚀
> Sentiment:

The sentiment of the text "I cannot wait to build! 💪🚀" is positive.

*Generated in *2.13* seconds*

> Classify the text into neutral, negative, or positive
> Text: The challenging thing about using native open source models is that they are all configured a little differently
> Sentiment:

The sentiment of the text is neutral.

*Generated in *0.79* seconds*

> Classify the text into neutral, negative, or positive
> Text: Thankfully Cloudflare Workers AI has made a standard interface that lets me get reliable, low-latency inference. So quick too!
> Sentiment:

The sentiment of the text is positive.

*Generated in *1.93* seconds*

***

---

# Tutorials

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/

import { GlossaryTooltip, ListTutorials, YouTubeVideos } from "~/components";

View <GlossaryTooltip term="tutorial">tutorials</GlossaryTooltip> to help you get started with Workers AI.

## Docs

<ListTutorials />

## Videos

Also, explore our video resources on Workers AI:

<YouTubeVideos products={["Workers AI"]} />

---

# Llama 3.2 11B Vision Instruct model on Cloudflare Workers AI

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/llama-vision-tutorial/

import { Details, Render, PackageManagers, WranglerConfig } from "~/components";

## Prerequisites

Before you begin, ensure you have the following:

1. A [Cloudflare account](https://dash.cloudflare.com/sign-up) with Workers and Workers AI enabled.
2. Your `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_AUTH_TOKEN`.
   - You can generate an API token in your Cloudflare dashboard under API Tokens.
3. Node.js installed for working with Cloudflare Workers (optional but recommended).

## 1. Agree to Meta's license

The first time you use the [Llama 3.2 11B Vision Instruct](/workers-ai/models/llama-3.2-11b-vision-instruct) model, you need to agree to Meta's License and Acceptable Use Policy.

```bash title="curl"
curl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run/@cf/meta/llama-3.2-11b-vision-instruct \
  -X POST \
  -H "Authorization: Bearer $CLOUDFLARE_AUTH_TOKEN" \
  -d '{ "prompt": "agree" }'
```

Replace `$CLOUDFLARE_ACCOUNT_ID` and `$CLOUDFLARE_AUTH_TOKEN` with your actual account ID and token.

## 2. Set up your Cloudflare Worker

1. Create a Worker Project
   You will create a new Worker project using the `create-cloudflare` CLI (`C3`). This tool simplifies setting up and deploying new applications to Cloudflare.

   Run the following command in your terminal:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"llama-vision-tutorial"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

After completing the setup, a new directory called `llama-vision-tutorial` will be created.

2. Navigate to your application directory
   Change into the project directory:

   ```bash
   cd llama-vision-tutorial
   ```

3. Project structure
   Your `llama-vision-tutorial` directory will include:
   - A "Hello World" Worker at `src/index.ts`.
   - A `wrangler.json` configuration file for managing deployment settings.

## 3. Write the Worker code

Edit the `src/index.ts` (or `index.js` if you are not using TypeScript) file and replace the content with the following code:

```javascript
export interface Env {
  AI: Ai;
}

export default {
  async fetch(request, env): Promise<Response> {
    const messages = [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "Describe the image I'm providing." },
    ];

    // Replace this with your image data encoded as base64 or a URL
    const imageBase64 = "data:image/png;base64,IMAGE_DATA_HERE";

    const response = await env.AI.run("@cf/meta/llama-3.2-11b-vision-instruct", {
      messages,
      image: imageBase64,
    });

    return Response.json(response);
  },
} satisfies ExportedHandler<Env>;
```

## 4. Bind Workers AI to your Worker

1. Open the [Wrangler configuration file](/workers/wrangler/configuration/) and add the following configuration:

<WranglerConfig>
```toml
[env]
[ai]
binding="AI"
```
</WranglerConfig>

2. Save the file.

## 5. Deploy the Worker

Run the following command to deploy your Worker:

```bash
wrangler deploy
```

## 6. Test Your Worker

1. After deployment, you will receive a unique URL for your Worker (e.g., `https://llama-vision-tutorial.<your-subdomain>.workers.dev`).
2. Use a tool like `curl` or Postman to send a request to your Worker:

```bash
curl -X POST https://llama-vision-tutorial.<your-subdomain>.workers.dev \
  -d '{ "image": "BASE64_ENCODED_IMAGE" }'
```

Replace `BASE64_ENCODED_IMAGE` with an actual base64-encoded image string.

## 7. Verify the response

The response will include the output from the model, such as a description or answer to your prompt based on the image provided.

Example response:

```json
{
	"result": "This is a golden retriever sitting in a grassy park."
}
```

---

# Using BigQuery with Workers AI

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/using-bigquery-with-workers-ai/

import { WranglerConfig } from "~/components";

The easiest way to get started with [Workers AI](/workers-ai/) is to try it out in the [Multi-modal Playground](https://multi-modal.ai.cloudflare.com/) and the [LLM playground](https://playground.ai.cloudflare.com/). If you decide that you want to integrate your code with Workers AI, you may then decide to then use its [REST API endpoints](/workers-ai/get-started/rest-api/) or via a [Worker binding](/workers-ai/configuration/bindings/).

But, what about the data? What if what you want these models to ingest data that is stored outside Cloudflare?

In this tutorial, you will learn how to bring data from Google BigQuery to a Cloudflare Worker so that it can be used as input for Workers AI models.

## Prerequisites

You will need:

- A [Cloudflare Worker](/workers/) project running a [Hello World script](/workers/get-started/guide/).
- A Google Cloud Platform [service account](https://cloud.google.com/iam/docs/service-accounts-create#iam-service-accounts-create-console) with an [associated key](https://cloud.google.com/iam/docs/keys-create-delete#iam-service-account-keys-create-console) file downloaded that has read access to BigQuery.
- Access to a BigQuery table with some test data that allows you to create a [BigQuery Job Query](https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query). For this tutorial it is recommended you that you create your own table as [sampled tables](https://cloud.google.com/bigquery/public-data#sample_tables), unless cloned to your own GCP namespace, won't allow you to run job queries against them. For this example, the [Hacker News Corpus](https://www.kaggle.com/datasets/hacker-news/hacker-news-corpus) was used under its MIT licence.

## 1. Set up your Cloudflare Worker

To ingest the data into Cloudflare and feed it into Workers AI, you will be using a [Cloudflare Worker](/workers/). If you have not created one yet, please feel free to review our [tutorial on how to get started](/workers/get-started/).

After following the steps to create a Worker, you should have the following code in your new Worker project:

```javascript
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello World!");
	},
};
```

If the Worker project has successfully been created, you should also be able to run `npx wrangler dev` in a console to run the Worker locally:

```sh
[wrangler:inf] Ready on http://localhost:8787
```

Open a browser tab at `http://localhost:8787/` to see your deployed Worker. Please note that the port `8787` may be a different one in your case.

You should be seeing `Hello World!` in your browser:

```sh
Hello World!
```

If you are running into any issues during this step, please make sure to review [Worker's Get Started Guide](/workers/get-started/guide/).

## 2. Import GCP Service key into the Worker as Secrets

Now that you have verified that the Worker has been created successfully, you will need to reference the Google Cloud Platform service key created in the [Prerequisites](#prerequisites) section of this tutorial.

Your downloaded key JSON file from Google Cloud Platform should have the following format:

```json
{
	"type": "service_account",
	"project_id": "<your_project_id>",
	"private_key_id": "<your_private_key_id>",
	"private_key": "<your_private_key>",
	"client_email": "<your_service_account_id>@<your_project_id>.iam.gserviceaccount.com",
	"client_id": "<your_oauth2_client_id>",
	"auth_uri": "https://accounts.google.com/o/oauth2/auth",
	"token_uri": "https://oauth2.googleapis.com/token",
	"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
	"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/<your_service_account_id>%40<your_project_id>.iam.gserviceaccount.com",
	"universe_domain": "googleapis.com"
}
```

For this tutorial, you will only be needing the values of the following fields: `client_email`, `private_key`, `private_key_id`, and `project_id`.

Instead of storing this information in plain text in the Worker, you will use [secrets](/workers/configuration/secrets/) to make sure its unencrypted content is only accessible via the Worker itself.

Import those three values from the JSON file into Secrets, starting with the field from the JSON key file called `client_email`, which we will now call `BQ_CLIENT_EMAIL` (you can use another variable name):

```sh
npx wrangler secret put BQ_CLIENT_EMAIL
```

You will be asked to enter a secret value, which will be the value of the field `client_email` in the JSON key file.

:::note

Do not include any double quotes in the secret that you store, as the Secret will be already interpreted as a string.

:::

If the secret was uploaded successfully, the following message will be displayed:

```sh
✨ Success! Uploaded secret BQ_CLIENT_EMAIL
```

Now import the secrets for the three remaining fields; `private_key`, `private_key_id`, and `project_id` as `BQ_PRIVATE_KEY`, `BQ_PRIVATE_KEY_ID`, and `BQ_PROJECT_ID` respectively:

```sh
npx wrangler secret put BQ_PRIVATE_KEY
```

```sh
npx wrangler secret put BQ_PRIVATE_KEY_ID
```

```sh
npx wrangler secret put BQ_PROJECT_ID
```

At this point, you have successfully imported three fields from the JSON key file downloaded from Google Cloud Platform into Cloudflare secrets to be used in a Worker.

[Secrets](/workers/configuration/secrets/) are only made available to Workers once they are deployed. To make them available during development, [create a `.dev.vars`](/workers/configuration/secrets/#local-development-with-secrets) file to locally store these credentials and reference them as environment variables.

Your `dev.vars` file should look like the following:

```
BQ_CLIENT_EMAIL="<your_service_account_id>@<your_project_id>.iam.gserviceaccount.com"
BQ_CLIENT_KEY="-----BEGIN PRIVATE KEY-----<content_of_your_private_key>-----END PRIVATE KEY-----\n"
BQ_PRIVATE_KEY_ID="<your_private_key_id>"
BQ_PROJECT_ID="<your_project_id>"
```

Make sure to include `.dev.vars` to your `.gitignore` file in your project to prevent getting your credentials uploaded to a repository if you are using a version control system.

Check that secrets are loaded correctly in `src/index.js` by logging their values into a console output:

```javascript
export default {
	async fetch(request, env, ctx) {
		console.log("BQ_CLIENT_EMAIL: ", env.BQ_CLIENT_EMAIL);
		console.log("BQ_PRIVATE_KEY: ", env.BQ_PRIVATE_KEY);
		console.log("BQ_PRIVATE_KEY_ID: ", env.BQ_PRIVATE_KEY_ID);
		console.log("BQ_PROJECT_ID: ", env.BQ_PROJECT_ID);
		return new Response("Hello World!");
	},
};
```

Restart the Worker and run `npx wrangler dev`. You should see that the server now mentions the newly added variables:

```
Using vars defined in .dev.vars
Your worker has access to the following bindings:
- Vars:
  - BQ_CLIENT_EMAIL: "(hidden)"
  - BQ_PRIVATE_KEY: "(hidden)"
  - BQ_PRIVATE_KEY_ID: "(hidden)"
  - BQ_PROJECT_ID: "(hidden)"
[wrangler:inf] Ready on http://localhost:8787
```

If you open `http://localhost:8787` in your browser, you should see the values of the variables show up in your console where the `npx wrangler dev` command is running, while still seeing only the `Hello World!` text in the browser window.

You now have access to the GCP credentials from a Worker. Next, you will install a library to help with the creation of the JSON Web Token needed to interact with GCP's API.

## 3. Install library to handle JWT operations

To interact with BigQuery's REST API, you will need to generate a [JSON Web Token](https://jwt.io/introduction) to authenticate your requests using the credentials that you have loaded into Worker secrets in the previous step.

For this tutorial, you will be using the [jose](https://www.npmjs.com/package/jose?activeTab=readme) library for JWT-related operations. Install it by running the following command in a console:

```sh
npm i jose
```

To verify that the installation succeeded, you can run `npm list`, which lists all the installed packages and see if the `jose` dependency has been added:

```sh
<project_name>@0.0.0
/<path_to_your_project>/<project_name>
├── @cloudflare/vitest-pool-workers@0.4.29
├── jose@5.9.2
├── vitest@1.5.0
└── wrangler@3.75.0
```

## 4. Generate JSON Web Token

Now that you have installed the `jose` library, it is time to import it and add a function to your code that generates a signed JWT:

```javascript
import * as jose from 'jose';
...
const generateBQJWT = async (aCryptoKey, env) => {
const algorithm = "RS256";
const audience = "https://bigquery.googleapis.com/";
const expiryAt = (new Date().valueOf() / 1000);
	const privateKey = await jose.importPKCS8(env.BQ_PRIVATE_KEY, algorithm);

	// Generate signed JSON Web Token (JWT)
	return new jose.SignJWT()
    	.setProtectedHeader({
        	typ: 'JWT',
        	alg: algorithm,
        	kid: env.BQ_PRIVATE_KEY_ID
    	})
    	.setIssuer(env.BQ_CLIENT_EMAIL)
    	.setSubject(env.BQ_CLIENT_EMAIL)
    	.setAudience(audience)
    	.setExpirationTime(expiryAt)
    	.setIssuedAt()
    	.sign(privateKey)
}

export default {
	async fetch(request, env, ctx) {
       ...
// Create JWT to authenticate the BigQuery API call
    	let bqJWT;
    	try {
        	bqJWT = await generateBQJWT(env);
    	} catch (e) {
        	return new Response('An error has occurred while generating the JWT', { status: 500 })
    	}
	},
       ...
};

```

Now that you have created a JWT, it is time to do an API call to BigQuery to fetch some data.

## 5. Make authenticated requests to Google BigQuery

With the JWT token created in the previous step, issue an API request to BigQuery's API to retrieve data from a table.

You will now query the table that you already have created in BigQuery as part of the prerequisites of this tutorial. This example uses a sampled version of the [Hacker News Corpus](https://www.kaggle.com/datasets/hacker-news/hacker-news-corpus) that was used under its MIT licence and uploaded to BigQuery.

```javascript
const queryBQ = async (bqJWT, path) => {
	const bqEndpoint = `https://bigquery.googleapis.com${path}`
	// In this example, text is a field in the BigQuery table that is being queried (hn.news_sampled)
	const query = 'SELECT text FROM hn.news_sampled LIMIT 3';
	const response = await fetch(bqEndpoint, {
    	method: "POST",
    	body: JSON.stringify({
        	"query": query
    	}),
    	headers: {
        	Authorization: `Bearer ${bqJWT}`
    	}
	})
	return response.json()
}
...
export default {
	async fetch(request, env, ctx) {
		...
    		let ticketInfo;
    		try {
    		ticketInfo = await queryBQ(bqJWT);
    	} catch (e) {
        	return new Response('An error has occurred while querying BQ', { status: 500 });
    	}
	...
	},
};
```

Having the raw row data from BigQuery means that you can now format it in a JSON-like style up next.

## 6. Format results from the query

Now that you have retrieved the data from BigQuery, it is time to note that a BigQuery API response looks something like this:

```json
{
	...
	"schema": {
    	"fields": [
        	{
            	"name": "title",
            	"type": "STRING",
            	"mode": "NULLABLE"
        	},
        	{
            	"name": "text",
            	"type": "STRING",
            	"mode": "NULLABLE"
        	}
    	]
	},
	...
	"rows": [
    	{
        	"f": [
            	{
                	"v": "<some_value>"
            	},
            	{
                	"v": "<some_value>"
            	}
        	]
    	},
    	{
        	"f": [
            	{
                	"v": "<some_value>"
            	},
            	{
                	"v": "<some_value>"
            	}
        	]
    	},
    	{
        	"f": [
            	{
                	"v": "<some_value>"
            	},
            	{
                	"v": "<some_value>"
            	}
        	]
    	}
	],
	...
}
```

This format may be difficult to read and to work with when iterating through results, which will go on to do later in this tutorial. So you will now implement a function that maps the schema into each individual value, and the resulting output will be easier to read, as shown below. Each row corresponds to an object within an array.

```javascript
[
	{
		title: "<some_value>",
		text: "<some_value>",
	},
	{
		title: "<some_value>",
		text: "<some_value>",
	},
	{
		title: "<some_value>",
		text: "<some_value>",
	},
];
```

Create a `formatRows` function that takes a number of rows and fields returned from the BigQuery response body and returns an array of results as objects with named fields.

```javascript
const formatRows = (rowsWithoutFieldNames, fields) => {
	// Depending on the position of each value, it is known what field you should assign to it.
	const fieldsByIndex = new Map();

	// Load all fields name and have their index in the array result as their key
	fields.forEach((field, index) => {
    	fieldsByIndex.set(index, field.name)
	})

	// Iterate through rows
	const rowsWithFieldNames = rowsWithoutFieldNames.map(row => {
    	// Per each row represented by an array f, iterate through the unnamed values and find their field names by searching them in the fieldsByIndex.
    	let newRow = {}
    	row.f.forEach((field, index) => {
        	const fieldName = fieldsByIndex.get(index);
        	if (fieldName) {
		// For every field in a row, add them to newRow
            	newRow = ({ ...newRow, [fieldName]: field.v });
        	}
    	})
    	return newRow
	})

	return rowsWithFieldNames
}

export default {
	async fetch(request, env, ctx) {
		...
    	// Transform output format into array of objects with named fields
    	let formattedResults;

    	if ('rows' in ticketInfo) {
        	formattedResults = formatRows(ticketInfo.rows, ticketInfo.schema.fields);
        	console.log(formattedResults)
    	} else if ('error' in ticketInfo) {
        	return new Response(ticketInfo.error.message, { status: 500 })
    	}
	...
	},
};
```

## 7. Feed data into Workers AI

Now that you have converted the response from the BigQuery API into an array of results, generate some tags and attach an associated sentiment score using an LLM via [Workers AI](/workers-ai/):

```javascript
const generateTags = (data, env) => {
	return env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
    	prompt: `Create three one-word tags for the following text. return only these three tags separated by a comma. don't return text that is not a category.Lowercase only. ${JSON.stringify(data)}`,
	});
}

const generateSentimentScore = (data, env) => {
	return env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
    	prompt: `return a float number between 0 and 1 measuring the sentiment of the following text. 0 being negative and 1 positive. return only the number, no text. ${JSON.stringify(data)}`,
	});
}

// Iterates through values, sends them to an AI handler and encapsulates all responses into a single Promise
const getAIGeneratedContent = (data, env, aiHandler) => {
	let results = data?.map(dataPoint => {
    	return aiHandler(dataPoint, env)
	})
	return Promise.all(results)
}
...
export default {
	async fetch(request, env, ctx) {
		...
let summaries, sentimentScores;
    	try {
        	summaries = await getAIGeneratedContent(formattedResults, env, generateTags);
        	sentimentScores = await getAIGeneratedContent(formattedResults, env, generateSentimentScore)
    	} catch {
        	return new Response('There was an error while generating the text summaries or sentiment scores')
    	}
},

formattedResults = formattedResults?.map((formattedResult, i) => {
        	if (sentimentScores[i].response && summaries[i].response) {
            	return {
                	...formattedResult,
                	'sentiment': parseFloat(sentimentScores[i].response).toFixed(2),
                	'tags': summaries[i].response.split(',').map((result) => result.trim())
            	}
        	}
    	}
};

```

Uncomment the following lines from the Wrangler file in your project:

<WranglerConfig>

```toml
[ai]
binding = "AI"
```

</WranglerConfig>

Restart the Worker that is running locally, and after doing so, go to your application endpoint:

```sh
curl http://localhost:8787
```

It is likely that you will be asked to log in to your Cloudflare account and grant temporary access to Wrangler (the Cloudflare CLI) to use your account when using Worker AI.

Once you access `http://localhost:8787` you should see an output similar to the following:

```sh
{
  "data": [
	{
  	"text": "You can see a clear spike in submissions right around US Thanksgiving.",
  	"sentiment": "0.61",
  	"tags": [
    	"trends",
    	"submissions",
    	"thanksgiving"
  	]
	},
	{
  	"text": "I didn't test the changes before I published them.  I basically did development on the running server. In fact for about 30 seconds the comments page was broken due to a bug.",
  	"sentiment": "0.35",
  	"tags": [
    	"software",
    	"deployment",
    	"error"
  	]
	},
	{
  	"text": "I second that. As I recall, it's a very enjoyable 700-page brain dump by someone who's really into his subject. The writing has a personal voice; there are lots of asides, dry wit, and typos that suggest restrained editing. The discussion is intelligent and often theoretical (and Bartle is not scared to use mathematical metaphors), but the tone is not academic.",
  	"sentiment": "0.86",
  	"tags": [
    	"review",
    	"game",
    	"design"
  	]
	}
  ]
}
```

The actual values and fields will mostly depend on the query made in Step 5 that are then fed into the LLMs models.

## Final result

All the code shown in the different steps are combined into the following code in `src/index.js`:

```javascript
import * as jose from "jose";

const generateBQJWT = async (env) => {
	const algorithm = "RS256";
	const audience = "https://bigquery.googleapis.com/";
	const expiryAt = new Date().valueOf() / 1000;
	const privateKey = await jose.importPKCS8(env.BQ_PRIVATE_KEY, algorithm);

	// Generate signed JSON Web Token (JWT)
	return new jose.SignJWT()
		.setProtectedHeader({
			typ: "JWT",
			alg: algorithm,
			kid: env.BQ_PRIVATE_KEY_ID,
		})
		.setIssuer(env.BQ_CLIENT_EMAIL)
		.setSubject(env.BQ_CLIENT_EMAIL)
		.setAudience(audience)
		.setExpirationTime(expiryAt)
		.setIssuedAt()
		.sign(privateKey);
};

const queryBQ = async (bgJWT, path) => {
	const bqEndpoint = `https://bigquery.googleapis.com${path}`;
	const query = "SELECT text FROM hn.news_sampled LIMIT 3";
	const response = await fetch(bqEndpoint, {
		method: "POST",
		body: JSON.stringify({
			query: query,
		}),
		headers: {
			Authorization: `Bearer ${bgJWT}`,
		},
	});
	return response.json();
};

const formatRows = (rowsWithoutFieldNames, fields) => {
	// Index to fieldName
	const fieldsByIndex = new Map();

	fields.forEach((field, index) => {
		fieldsByIndex.set(index, field.name);
	});

	const rowsWithFieldNames = rowsWithoutFieldNames.map((row) => {
		// Map rows into an array of objects with field names
		let newRow = {};
		row.f.forEach((field, index) => {
			const fieldName = fieldsByIndex.get(index);
			if (fieldName) {
				newRow = { ...newRow, [fieldName]: field.v };
			}
		});
		return newRow;
	});

	return rowsWithFieldNames;
};

const generateTags = (data, env) => {
	return env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
		prompt: `Create three one-word tags for the following text. return only these three tags separated by a comma. don't return text that is not a category.Lowercase only. ${JSON.stringify(data)}`,
	});
};

const generateSentimentScore = (data, env) => {
	return env.AI.run("@cf/meta/llama-3.1-8b-instruct", {
		prompt: `return a float number between 0 and 1 measuring the sentiment of the following text. 0 being negative and 1 positive. return only the number, no text. ${JSON.stringify(data)}`,
	});
};

const getAIGeneratedContent = (data, env, aiHandler) => {
	let results = data?.map((dataPoint) => {
		return aiHandler(dataPoint, env);
	});
	return Promise.all(results);
};

export default {
	async fetch(request, env, ctx) {
		// Create JWT to authenticate the BigQuery API call
		let bqJWT;
		try {
			bqJWT = await generateBQJWT(env);
		} catch (error) {
			console.log(error);
			return new Response("An error has occurred while generating the JWT", {
				status: 500,
			});
		}

		// Fetch results from BigQuery
		let ticketInfo;
		try {
			ticketInfo = await queryBQ(
				bqJWT,
				`/bigquery/v2/projects/${env.BQ_PROJECT_ID}/queries`,
			);
		} catch (error) {
			console.log(error);
			return new Response("An error has occurred while querying BQ", {
				status: 500,
			});
		}

		// Transform output format into array of objects with named fields
		let formattedResults;
		if ("rows" in ticketInfo) {
			formattedResults = formatRows(ticketInfo.rows, ticketInfo.schema.fields);
		} else if ("error" in ticketInfo) {
			return new Response(ticketInfo.error.message, { status: 500 });
		}

		// Generate AI summaries and sentiment scores
		let summaries, sentimentScores;
		try {
			summaries = await getAIGeneratedContent(
				formattedResults,
				env,
				generateTags,
			);
			sentimentScores = await getAIGeneratedContent(
				formattedResults,
				env,
				generateSentimentScore,
			);
		} catch {
			return new Response(
				"There was an error while generating the text summaries or sentiment scores",
			);
		}

		// Add AI summaries and sentiment scores to previous results
		formattedResults = formattedResults?.map((formattedResult, i) => {
			if (sentimentScores[i].response && summaries[i].response) {
				return {
					...formattedResult,
					sentiment: parseFloat(sentimentScores[i].response).toFixed(2),
					tags: summaries[i].response.split(",").map((result) => result.trim()),
				};
			}
		});

		const response = { data: formattedResults };

		return new Response(JSON.stringify(response), {
			headers: { "Content-Type": "application/json" },
		});
	},
};
```

If you wish to deploy this Worker, you can do so by running `npx wrangler deploy`:

```sh
Total Upload: <size_of_your_worker> KiB / gzip: <compressed_size_of_your_worker> KiB
Uploaded <name_of_your_worker> (x sec)
Deployed <name_of_your_worker> triggers (x sec)
  https://<your_public_worker_endpoint>
Current Version ID: <worker_script_version_id>
```

This will create a public endpoint that you can use to access the Worker globally. Please keep this in mind when using production data, and make sure to include additional access controls in place.

## Conclusion

In this tutorial, you have learnt how to integrate Google BigQuery and Cloudflare Workers by creating a GCP service account key and storing part of it as Worker secrets. This was later imported in the code, and by using the `jose` npm library, you created a JSON Web Token to authenticate the API query to BigQuery.

Once you obtained the results, you formatted them to later be passed to generative AI models via Workers AI to generate tags and to perform sentiment analysis on the extracted data.

## Next Steps

If, instead of displaying the results of ingesting the data to the AI model in a browser, your workflow requires fetching and store data (for example in [R2](/r2/) or [D1](/d1/)) on regular intervals, you may want to consider adding a [scheduled handler](/workers/runtime-apis/handlers/scheduled/) for this Worker. It allows triggering the Worker with a predefined cadence via a [Cron Trigger](/workers/configuration/cron-triggers/). Consider reviewing the Reference Architecture Diagrams on [Ingesting BigQuery Data into Workers AI](/reference-architecture/diagrams/ai/bigquery-workers-ai/).

A use case to ingest data from other sources, like you did in this tutorial, is to create a RAG system. If this sounds relevant to you, please check out the tutorial [Build a Retrieval Augmented Generation (RAG) AI](/workers-ai/guides/tutorials/build-a-retrieval-augmented-generation-ai/).

To learn more about what other AI models you can use at Cloudflare, please visit the [Workers AI](/workers-ai) section of our docs.

---

# Advanced setups

URL: https://developers.cloudflare.com/workers/ci-cd/builds/advanced-setups/

## Monorepos

A monorepo is a single repository that contains multiple applications. This setup can be useful for a few reasons:

- **Simplified dependency management**: Manage dependencies across all your workers and shared packages from a single place using tools like [pnpm workspaces](https://pnpm.io/workspaces) and [syncpack](https://www.npmjs.com/package/syncpack).
- **Code sharing and reuse**: Easily create and share common logic, types, and utilities between workers by creating shared packages.
- **Atomic commits**: Changes affecting multiple workers or shared libraries can be committed together, making the history easier to understand and reducing the risk of inconsistencies.
- **Consistent tooling**: Apply the same build, test, linting, and formatting configurations (e.g., via [Turborepo](https://turborepo.com) in for task orchestration and shared configs in `packages/`) across all projects, ensuring consistent tooling and code quality across Workers.
- **Easier refactoring**: Refactoring code that spans multiple Workers or shared packages is significantly easier within a single repository.

#### Example Workers monorepos:

- [cloudflare/mcp-server-cloudflare](https://github.com/cloudflare/mcp-server-cloudflare)
- [jahands/workers-monorepo-template](https://github.com/jahands/workers-monorepo-template)
- [cloudflare/templates](https://github.com/cloudflare/templates)
- [cloudflare/workers-sdk](https://github.com/cloudflare/workers-sdk)

### Getting Started

To set up a monorepo workflow:

1. Find the Workers associated with your project in the [Workers & Pages Dashboard](https://dash.cloudflare.com).
2. Connect your monorepo to each Worker in the repository.
3. Set the root directory for each Worker to specify the location of its `wrangler.toml` and where build and deploy commands should run.
4. Optionally, configure unique build and deploy commands for each Worker.
5. Optionally, configure [build watch paths](/workers/ci-cd/builds/build-watch-paths/) for each Worker to monitor specific paths for changes.

When a new commit is made to the monorepo, a new build and deploy will trigger for each Worker if the change is within each of its included watch paths. You can also check on the status of each build associated with your repository within GitHub with [check runs](/workers/ci-cd/builds/git-integration/github-integration/#check-run) or within GitLab with [commit statuses](/workers/ci-cd/builds/git-integration/gitlab-integration/#commit-status).

### Example

In the example `ecommerce-monorepo`, a Workers project should be created for `product-service`, `order-service`, and `notification-service`.

A Git connection to `ecommerce-monorepo` should be added in all of the Workers projects. If you are using a monorepo tool, such as [Turborepo](https://turbo.build/), you can configure a different deploy command for each Worker, for example, `turbo deploy -F product-service`.

Set the root directory of each Worker to where its wrangler.toml is located. For example, for `product-service`, the root directory should be `/workers/product-service/`. Optionally, you can add [build watch paths](/workers/ci-cd/builds/build-watch-paths/) to optimize your builds.

When a new commit is made to `ecommerce-monorepo`, a build and deploy will be triggered for each of the Workers if the change is within its included watch paths using the configured commands for that Worker.

```
ecommerce-monorepo/
│
├── workers/
│ ├── product-service/
│ │ ├── src/
│ │ └── wrangler.toml
│ ├── order-service/
│ │ ├── src/
│ │ └── wrangler.toml
│ └── notification-service/
│ ├── src/
│ └── wrangler.toml
├── packages/
│ └── schema/
└── README.md
```

## Wrangler Environments

You can use [Wrangler Environments](/workers/wrangler/environments/) with Workers Builds by completing the following steps:

1. [Deploy via Wrangler](/workers/wrangler/commands/#deploy) to create the Workers for your environments on the Dashboard, if you do not already have them.
2. Find the Workers for your environments. They are typically named `[name of Worker] - [environment name]`.
3. Connect your repository to each of the Workers for your environment.
4. In each of the Workers, edit your Wrangler commands to include the flag `--env: <environment name>` in the build configurations for both the deploy command, and the non-production branch deploy command ([if applicable](/workers/ci-cd/builds/build-branches/#configure-non-production-branch-builds)).

When a new commit is detected in the repository, a new build/deploy will trigger for each associated Worker.

### Example

Imagine you have a Worker named `my-worker`, and you want to set up two environments `staging` and `production` set in the `wrangler.jsonc`. If you have not already, you can deploy `my-worker` for each environment using the commands `wrangler deploy --env staging` and `wrangler deploy --env production`.

In your Cloudflare Dashboard, you should find the two Workers `my-worker-staging` and `my-worker-production`. Then, connect the Git repository for the Worker, `my-worker`, to both of the environment Workers. In the build configurations of each environment Worker, edit the deploy commands to be `npx wrangler deploy --env staging` and `npx wrangler deploy --env production` and the non-production branch deploy commands to be `npx wrangler versions upload --env staging` and `npx wrangler versions upload --env production` respectively.

---

# Build branches

URL: https://developers.cloudflare.com/workers/ci-cd/builds/build-branches/

When you connect a git repository to Workers, commits made on the production git branch will produce a Workers Build. If you want to take advantage of [preview URLs](/workers/configuration/previews/) and [pull request comments](/workers/ci-cd/builds/git-integration/github-integration/#pull-request-comment), you can additionally enable "non-production branch builds" in order to trigger a build on all branches of your repository.

## Change production branch

To change the production branch of your project:

1. In **Overview**, select your Workers project.
2. Go to **Settings** > **Build** > **Branch control**. Workers will default to the default branch of your git repository, but this can be changed in the dropdown.

Every push event made to this branch will trigger a build and execute the [build command](/workers/ci-cd/builds/configuration/#build-command), followed by the [deploy command](/workers/ci-cd/builds/configuration/#deploy-command).

## Configure non-production branch builds

To enable or disable non-production branch builds:

1. In **Overview**, select your Workers project.
2. Go to **Settings** > **Build** > **Branch control**. The checkbox allows you to enable or disable builds for non-production branches.

When enabled, every push event made to a non-production branch will trigger a build and execute the [build command](/workers/ci-cd/builds/configuration/#build-command), followed by the [non-production branch deploy command](/workers/ci-cd/builds/configuration/#non-production-branch-deploy-command).

---

# Build caching

URL: https://developers.cloudflare.com/workers/ci-cd/builds/build-caching/

Improve Workers build times by caching dependencies and build output between builds with a project-wide shared cache.

The first build to occur after enabling build caching on your Workers project will save relevant artifacts to cache. Every subsequent build will restore from cache unless configured otherwise.

## About build cache

When enabled, build caching will automatically detect which package manager and framework the project is using from its `package.json` and cache data accordingly for the build.

The following shows which package managers and frameworks are supported for dependency and build output caching respectively.

### Package managers

Workers build cache will cache the global cache directories of the following package managers:

| Package Manager               | Directories cached   |
| ----------------------------- | -------------------- |
| [npm](https://www.npmjs.com/) | `.npm`               |
| [yarn](https://yarnpkg.com/)  | `.cache/yarn`        |
| [pnpm](https://pnpm.io/)      | `.pnpm-store`        |
| [bun](https://bun.sh/)        | `.bun/install/cache` |

### Frameworks

Some frameworks provide a cache directory that is typically populated by the framework with intermediate build outputs or dependencies during build time. Workers Builds will automatically detect the framework you are using and cache this directory for reuse in subsequent builds.

The following frameworks support build output caching:

| Framework  | Directories cached                            |
| ---------- | --------------------------------------------- |
| Astro      | `node_modules/.astro`                         |
| Docusaurus | `node_modules/.cache`, `.docusaurus`, `build` |
| Eleventy   | `.cache`                                      |
| Gatsby     | `.cache`, `public`                            |
| Next.js    | `.next/cache`                                 |
| Nuxt       | `node_modules/.cache/nuxt`                    |

:::note
[Static assets](/workers/static-assets/) and [frameworks](/workers/framework-guides/) are now supported in Cloudflare Workers.
:::

### Limits

The following limits are imposed for build caching:

- **Retention**: Cache is purged 7 days after its last read date. Unread cache artifacts are purged 7 days after creation.
- **Storage**: Every project is allocated 10 GB. If the project cache exceeds this limit, the project will automatically start deleting artifacts that were read least recently.

## Enable build cache

To enable build caching:

1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard.
2. Find your Workers project.
3. Go to **Settings** > **Build** > **Build cache**.
4. Select **Enable** to turn on build caching.

## Clear build cache

The build cache can be cleared for a project when needed, such as when debugging build issues. To clear the build cache:

1. Navigate to [Workers & Pages Overview](https://dash.cloudflare.com) on the Dashboard.
2. Find your Workers project.
3. Go to **Settings** > **Build** > **Build cache**.
4. Select **Clear Cache** to clear the build cache.

---

# Build image

URL: https://developers.cloudflare.com/workers/ci-cd/builds/build-image/

Workers Builds uses a build image with support for a variety of languages and tools such as Node.js, Python, PHP, Ruby, and Go.

## Supported Tooling

Workers Builds supports a variety of runtimes, languages, and tools. Builds will use the default versions listed below unless a custom version is detected or specified. You can [override the default versions](/workers/ci-cd/builds/build-image/#overriding-default-versions) using environment variables or version files. All versions are available for override.

:::note[Default version updates]
The default versions will be updated regularly to the latest minor version. No major version updates will be made without notice. If you need a specific minor version, please specify it by [overriding the default version](/workers/ci-cd/builds/build-image/#overriding-default-versions).
:::

### Runtime

| Tool        | Default version | Environment variable | File                         |
| ----------- | --------------- | -------------------- | ---------------------------- |
| **Go**      | 1.24.3          | `GO_VERSION`         |                              |
| **Node.js** | 22.16.0         | `NODE_VERSION`       | .nvmrc, .node-version        |
| **Python**  | 3.13.3          | `PYTHON_VERSION`     | .python-version, runtime.txt |
| **Ruby**    | 3.4.4           | `RUBY_VERSION`       | .ruby-version                |

### Tools and langauges

| Tool        | Default version  | Environment variable |
| ----------- | ---------------- | -------------------- |
| **Bun**     | 1.2.15           | `BUN_VERSION`        |
| **Hugo**    | extended_0.147.7 | `HUGO_VERSION`       |
| **npm**     | 10.9.2           |                      |
| **yarn**    | 4.9.1            | `YARN_VERSION`       |
| **pnpm**    | 10.11.1          | `PNPM_VERSION`       |
| **pip**     | 25.1.1           |                      |
| **gem**     | 3.6.9            |                      |
| **poetry**  | 2.1.3            |                      |
| **pipx**    | 1.7.1            |                      |
| **bundler** | 2.6.9            |                      |

## Advanced Settings

### Overriding Default Versions

If you need to override a [specific version](/workers/ci-cd/builds/build-image/#overriding-default-versions) of a language or tool within the image, you can specify it as a [build environment variable](/workers/ci-cd/builds/configuration/#build-settings), or set the relevant file in your source code as shown above.

To set the version using a build environment variables, you can:

1. Find the environment variable name for the language or tool and desired version (e.g. `NODE_VERSION = 22`)
2. Add and save the environment variable on the dashboard by going to **Settings** > **Build** > **Build Variables and Secrets** in your Workers project

Or, to set the version by adding a file to your project, you can:

1. Find the filename for the language or tool (e.g. `.nvmrc`)
2. Add the specified file name to the root directory and set the desired version number as the file's content. For example, if the version number is 22, the file should contain '22'.

### Skip dependency install

You can add the following build variable to disable automatic dependency installation and run a custom install command instead.

| Build variable            | Value         |
| ------------------------- | ------------- |
| `SKIP_DEPENDENCY_INSTALL` | `1` or `true` |

## Pre-installed Packages

In the following table, review the pre-installed packages in the build image. The packages are installed with `apt`, a package manager for Linux distributions.

|                   |                   |                   |
| ----------------- | ----------------- | ----------------- |
| `curl`            | `libbz2-dev`      | `libreadline-dev` |
| `git`             | `libc++1`         | `libssl-dev`      |
| `git-lfs`         | `libdb-dev`       | `libvips-dev`     |
| `unzip`           | `libgdbm-dev`     | `libyaml-dev`     |
| `autoconf`        | `libgdbm6`        | `tzdata`          |
| `build-essential` | `libgbm1`         | `wget`            |
| `bzip2`           | `libgmp-dev`      | `zlib1g-dev`      |
| `gnupg`           | `liblzma-dev`     | `zstd`            |
| `libffi-dev`      | `libncurses5-dev` |                   |

## Build Environment

Workers Builds are run in the following environment:

|                       |              |
| --------------------- | ------------ |
| **Build Environment** | Ubuntu 24.04 |
| **Architecture**      | x86_64       |

---

# Build watch paths

URL: https://developers.cloudflare.com/workers/ci-cd/builds/build-watch-paths/

When you connect a git repository to Workers, by default a change to any file in the repository will trigger a build. You can configure Workers to include or exclude specific paths to specify if Workers should skip a build for a given path. This can be especially helpful if you are using a monorepo project structure and want to limit the amount of builds being kicked off.

## Configure Paths

To configure which paths are included and excluded:

1. In **Overview**, select your Workers project.
2. Go to **Settings** > **Build** > **Build watch paths**. Workers will default to setting your project’s includes paths to everything (\[\*]) and excludes paths to nothing (`[]`).

The configuration fields can be filled in two ways:

- **Static filepaths**: Enter the precise name of the file you are looking to include or exclude (for example, `docs/README.md`).
- **Wildcard syntax:** Use wildcards to match multiple path directories. You can specify wildcards at the start or end of your rule.

:::note[Wildcard syntax]

A wildcard (`*`) is a character that is used within rules. It can be placed alone to match anything or placed at the start or end of a rule to allow for better control over branch configuration. A wildcard will match zero or more characters.For example, if you wanted to match all branches that started with `fix/` then you would create the rule `fix/*` to match strings like `fix/1`, `fix/bugs`or `fix/`.

:::

For each path in a push event, build watch paths will be evaluated as follows:

- Paths satisfying excludes conditions are ignored first
- Any remaining paths are checked against includes conditions
- If any matching path is found, a build is triggered. Otherwise the build is skipped

Workers will bypass the path matching for a push event and default to building the project if:

- A push event contains 0 file changes, in case a user pushes a empty push event to trigger a build
- A push event contains 3000+ file changes or 20+ commits

## Examples

### Example 1

If you want to trigger a build from all changes within a set of directories, such as all changes in the folders `project-a/` and `packages/`

- Include paths: `project-a/*, packages/*`
- Exclude paths: \`\`

### Example 2

If you want to trigger a build for any changes, but want to exclude changes to a certain directory, such as all changes in a docs/ directory

- Include paths: `*`
- Exclude paths: `docs/*`

### Example 3

If you want to trigger a build for a specific file or specific filetype, for example all files ending in `.md`.

- Include paths: `*.md`
- Exclude paths: \`\`

---

# Configuration

URL: https://developers.cloudflare.com/workers/ci-cd/builds/configuration/

import { DirectoryListing } from "~/components";

When connecting your Git repository to your Worker, you can customize the configurations needed to build and deploy your Worker.

## Build settings

Build settings can be found by navigating to **Settings** > **Build** within your Worker.

Note that when you update and save build settings, the updated settings will be applied to your _next_ build. When you _retry_ a build, the build configurations that exist when the build is retried will be applied.

### Overview

| Setting                                                                                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Git account**                                                                                                       | Select the Git account you would like to use. After the initial connection, you can continue to use this Git account for future projects.                                                                                                                                                                                                                                                                                                                                              |
| **Git repository**                                                                                                    | Choose the Git repository you would like to connect your Worker to.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **Git branch**                                                                                                        | Select the branch you would like Cloudflare to listen to for new commits. This will be defaulted to `main`.                                                                                                                                                                                                                                                                                                                                                                            |
| **Build command** _(Optional)_                                                                                        | Set a build command if your project requires a build step (e.g. `npm run build`). This is necessary, for example, when using a [front-end framework](/workers/ci-cd/builds/configuration/#framework-support) such as Next.js or Remix.                                                                                                                                                                                                                                                 |
| **[Deploy command](/workers/ci-cd/builds/configuration/#deploy-command)**                                             | The deploy command lets you set the [specific Wrangler command](/workers/wrangler/commands/#deploy) used to deploy your Worker. Your deploy command will default to `npx wrangler deploy` but you may customize this command. Workers Builds will use the Wrangler version set in your `package json`.                                                                                                                                                                                 |
| **[Non-production branch deploy command](/workers/ci-cd/builds/configuration/#non-production-branch-deploy-command)** | Set a command to run when executing [a build for commit on a non-production branch](/workers/ci-cd/builds/build-branches/#configure-non-production-branch-builds). This will default to `npx wrangler versions upload` but you may customize this command. Workers Builds will use the Wrangler version set in your `package json`.                                                                                                                                                    |
| **Root directory** _(Optional)_                                                                                       | Specify the path to your project. The root directory defines where the build command will be run and can be helpful in [monorepos](/workers/ci-cd/builds/advanced-setups/#monorepos) to isolate a specific project within the repository for builds.                                                                                                                                                                                                                                   |
| **[API token](/workers/ci-cd/builds/configuration/#api-token)** _(Optional)_                                          | The API token is used to authenticate your build request and authorize the upload and deployment of your Worker to Cloudflare. By default, Cloudflare will automatically generate an API token for your account when using Workers Builds, and continue to use this API token for all subsequent builds. Alternatively, you can [create your own API token](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/authentication/#generate-tokens), or select one that you already own. |
| **Build variables and secrets** _(Optional)_                                                                          | Add environment variables and secrets accessible only to your build. Build variables will not be accessible at runtime. If you would like to configure runtime variables you can do so in **Settings** > **Variables & Secrets**                                                                                                                                                                                                                                                       |

:::note
Currently, Workers Builds does not honor the configurations set in [Custom Builds](/workers/wrangler/custom-builds/) within your wrangler.toml file.
:::

### Deploy command

You can run your deploy command using the package manager of your choice.

If you have added a Wrangler deploy command as a script in your `package.json`, then you can run it by setting it as your deploy command. For example, `npm run deploy`.

Examples of other deploy commands you can set include:

| Example Command                          | Description                                                                                                                                                                                                                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `npx wrangler deploy --assets ./public/` | Deploy your Worker along with static assets from the specified directory. Alternatively, you can use the [assets binding](/workers/static-assets/binding/).                                                                                                                     |
| `npx wrangler deploy --env staging`      | If you have a [Wrangler environment](/workers/ci-cd/builds/advanced-setups/#wrangler-environments) Worker, you should set your deploy command with the environment flag. For more details, see [Advanced Setups](/workers/ci-cd/builds/advanced-setups/#wrangler-environments). |

### Non-production branch deploy command

The non-production branch deploy command is only applicable when you have enabled [non-production branch builds](/workers/ci-cd/builds/build-branches/#configure-non-production-branch-builds).

It defaults to `npx wrangler versions upload`, producing a [preview URL](/workers/configuration/previews/). Like the build and deploy commands, it can be customized to instead run anything.

Examples of other non-production branch deploy commands you can set include:

| Example Command                              | Description                                                                                                                                                                                                                                                                                           |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `yarn exec wrangler versions upload`         | You can customize the package manager used to run Wrangler.                                                                                                                                                                                                                                           |
| `npx wrangler versions upload --env staging` | If you have a [Wrangler environment](/workers/ci-cd/builds/advanced-setups/#wrangler-environments) Worker, you should set your non-production branch deploy command with the environment flag. For more details, see [Advanced Setups](/workers/ci-cd/builds/advanced-setups/#wrangler-environments). |

### API token

The API token in Workers Builds defines the access granted to Workers Builds for interacting with your account's resources. Currently, only user tokens are supported, with account-owned token support coming soon.

When you select **Create new token**, a new API token will be created automatically with the following permissions:

- **Account:** Account Settings (read), Workers Scripts (edit), Workers KV Storage (edit), Workers R2 Storage (edit)
- **Zone:** Workers Routes (edit) for all zones on the account
- **User:** User Details (read), Memberships (read)

You can configure the permissions of this API token by navigating to **My Profile** > **API Tokens** for user tokens.

It is recommended to consistently use the same API token across all uploads and deployments of your Worker to maintain consistent access permissions.

## Framework support

[Static assets](/workers/static-assets/) and [frameworks](/workers/framework-guides/) are now supported in Cloudflare Workers. Learn to set up Workers projects and the commands for each framework in the framework guides:

<DirectoryListing folder="workers/framework-guides" maxDepth={4} />

## Environment variables

You can provide custom environment variables to your build by configuring them in the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In **Account Home**, select **Workers & Pages**.
3. In **Overview**, select your Worker.
4. Select **Settings** > **Environment variables**.

The following system environment variables are injected by default (but can be overridden):

| Environment Variable    | Injected value                  | Example use-case                                                                        |
| ----------------------- | ------------------------------- | --------------------------------------------------------------------------------------- |
| `CI`                    | `true`                          | Changing build behaviour when run on CI versus locally                                  |
| `WORKERS_CI`            | `1`                             | Changing build behaviour when run on Workers Builds versus locally                      |
| `WORKERS_CI_BUILD_UUID` | `<build-uuid-of-current-build>` | Passing the Build UUID along to custom workflows                                        |
| `WORKERS_CI_COMMIT_SHA` | `<sha1-hash-of-current-commit>` | Passing current commit ID to error reporting, for example, Sentry                       |
| `WORKERS_CI_BRANCH`     | `<branch-name-from-push-event`  | Customizing build based on branch, for example, disabling debug logging on `production` |

---

# Builds

URL: https://developers.cloudflare.com/workers/ci-cd/builds/

The Cloudflare [Git integration](/workers/ci-cd/builds/git-integration/) lets you connect a new or existing Worker to a GitHub or GitLab repository, enabling automated builds and deployments for your Worker on push.

## Get started

### Connect a new Worker

To create a new Worker and connect it to a GitHub or GitLab repository:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Workers & Pages**.
3. Select **Create**.
4. Under **Import a repository**, select a **Git account**.
5. Select the repository you want to import from the list. You can also use the search bar to narrow the results.
6. Configure your project and select **Save and Deploy**.
7. Preview your Worker at its provided [`workers.dev`](/workers/configuration/routing/workers-dev/) subdomain.

### Connect an existing Worker

To connect an existing Worker to a GitHub or GitLab repository:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Workers & Pages**.
3. Select the Worker you want to connect to a repository.
4. Select **Settings** and then **Builds**.
5. Select **Connect** and follow the prompts to connect the repository to your Worker and configure your [build settings](/workers/ci-cd/builds/configuration/).
6. Push a commit to your Git repository to trigger a build and deploy to your Worker.

:::caution

When connecting a repository to a Workers project, the Worker name in the Cloudflare dashboard must match the `name` in the wrangler.toml file in the specified root directory, or the build will fail. This ensures that the Worker deployed from the repository is consistent with the Worker registered in the Cloudflare dashboard. For details, see [Workers name requirement](/workers/ci-cd/builds/troubleshoot/#workers-name-requirement).

:::

## View build and preview URL

You can monitor a build's status and its build logs by navigating to **View build history** at the bottom of the **Deployments** tab of your Worker.

If the build is successful, you can view the build details by selecting **View build** in the associated new [version](/workers/configuration/versions-and-deployments/) created under Version History. There you will also find the [preview URL](/workers/configuration/previews/) generated by the version under Version ID.

:::note[Builds, versions, deployments]

If a build succeeds, it is uploaded as a version. If the build is configured to deploy (for example, with `wrangler deploy` set as the deploy command), the uploaded version will be automatically promoted to the Active Deployment.

:::

## Disconnecting builds

To disconnect a Worker from a GitHub or GitLab repository:
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Workers & Pages**.
3. Select the Worker you want to disconnect from a repository.
4. Select **Settings** and then **Builds**.
5. Select **Disconnect**.

If you want to switch to a different repository for your Worker, you must first disable builds, then reconnect to select the new repository.

To disable automatic deployments while still allowing builds to run automatically and save as [versions](/workers/configuration/versions-and-deployments/) (without promoting them to an active deployment), update your deploy command to: `npx wrangler versions upload`.

---

# Limits & pricing

URL: https://developers.cloudflare.com/workers/ci-cd/builds/limits-and-pricing/

Workers Builds has the following limits. While in open beta, these limits are subject to change.

| Metric                | Free plan       | Paid plans                                 |
| --------------------- | --------------- | ------------------------------------------ |
| **Build minutes**     | 3,000 per month | 6,000 per month (then, +$0.005 per minute) |
| **Concurrent builds** | 1               | 6                                          |
| **Build timeout**     | 20 minutes      | 20 minutes                                 |
| **CPU**               | 2 CPUs          | 2 CPUs                                     |
| **Memory**            | 8 GB            | 8 GB                                       |
| **Disk space**        | 8 GB            | 8 GB                                       |

## Definitions

- **Build minutes**: The amount of minutes that it takes to build a project.
- **Concurrent builds**: The number of builds that can run in parallel across an account.
- **Build timeout**: The amount of time that a build can be run before it is terminated.
- **CPU**: The number of CPU cores available to your build.
- **Memory**: The amount of memory available to your build.
- **Disk space**: The amount of disk space available to your build.

---

# Troubleshooting builds

URL: https://developers.cloudflare.com/workers/ci-cd/builds/troubleshoot/

This guide explains how to identify and resolve build errors, as well as troubleshoot common issues in the Workers Builds deployment process.

To view your build history, go to your Worker project in the Cloudflare dashboard, select **Deployment**, select **View Build History** at the bottom of the page, and select the build you want to view. To retry a build, select the ellipses next to the build and select **Retry build**. Alternatively, you can select **Retry build** on the Build Details page.

## Known issues or limitations

Here are some common build errors that may surface in the build logs or general issues and how you can resolve them.

### Workers name requirement

`✘ [ERROR] The name in your wrangler.toml file (<Worker name>) must match the name of your Worker. Please update the name field in your wrangler.toml file.`

When connecting a Git repository to your Workers project, the specified name for the Worker on the Cloudflare dashboard must match the `name` argument in the wrangler.toml file located in the specified root directory. If it does not match, update the name field in your wrangler.toml file to match the name of the Worker on the dashboard.

The build system uses the `name` argument in the wrangler.toml to determine which Worker to deploy to Cloudflare's global network. This requirement ensures consistency between the Worker's name on the dashboard and the deployed Worker.

:::note
This does not apply to [Wrangler Environments](/workers/wrangler/environments/) if the Worker name before the `-<env_name>` suffix matches the name in wrangler.toml.

For example, a Worker named `my-worker-staging` on the dashboard can be deployed from a repository that contains a wrangler.toml with the arguments `name = my-worker` and `[env.staging]` using the deploy command `npx wrangler deploy --env staging`.

On Wrangler v3 and up, Workers Builds automatically matches the name of the connected Worker by overriding it with the `WRANGLER_CI_OVERRIDE_NAME` environment variable.
:::

### Missing wrangler.toml

`✘ [ERROR] Missing entry-point: The entry-point should be specified via the command line (e.g. wrangler deploy path/to/script) or the main config field.`

If you see this error, a wrangler.toml is likely missing from the root directory. Navigate to **Settings** > **Build** > **Build Configuration** to update the root directory, or add a [wrangler.toml](/workers/wrangler/configuration/) to the specified directory.

### Incorrect account_id

`Could not route to /client/v4/accounts/<Account ID>/workers/services/<Worker name>, perhaps your object identifier is invalid? [code: 7003]`

If you see this error, the wrangler.toml likely has an `account_id` for a different account. Remove the `account_id` argument or update it with your account's `account_id`, available in **Workers & Pages Overview** under **Account Details**.

### Stale API token

` Failed: The build token selected for this build has been deleted or rolled and cannot be used for this build. Please update your build token in the Worker Builds settings and retry the build.`

The API Token dropdown in Build Configuration settings may show stale tokens that were edited, deleted, or rolled. If you encounter an error due to a stale token, create a new API Token and select it for the build.

### Build timed out

`Build was timed out`

There is a maximum build duration of 20 minutes. If a build exceeds this time, then the build will be terminated and the above error log is shown. For more details, see [Workers Builds limits](/workers/ci-cd/builds/limits-and-pricing/).

### Git integration issues

If you are running into errors associated with your Git integration, you can try removing access to your [GitHub](/workers/ci-cd/builds/git-integration/github-integration/#removing-access) or [GitLab](/workers/ci-cd/builds/git-integration/gitlab-integration/#removing-access) integration from Cloudflare, then reinstalling the [GitHub](/workers/ci-cd/builds/git-integration/github-integration/#reinstall-a-git-integration) or [GitLab](/workers/ci-cd/builds/git-integration/gitlab-integration/#reinstall-a-git-integration) integration.

## For additional support

If you discover additional issues or would like to provide feedback, reach out to us in the [Cloudflare Developers Discord](https://discord.com/channels/595317990191398933/1052656806058528849).

---

# GitHub Actions

URL: https://developers.cloudflare.com/workers/ci-cd/external-cicd/github-actions/

You can deploy Workers with [GitHub Actions](https://github.com/marketplace/actions/deploy-to-cloudflare-workers-with-wrangler). Here is how you can set up your GitHub Actions workflow.

## 1. Authentication

When running Wrangler locally, authentication to the Cloudflare API happens via the [`wrangler login`](/workers/wrangler/commands/#login) command, which initiates an interactive authentication flow. Since CI/CD environments are non-interactive, Wrangler requires a [Cloudflare API token](/fundamentals/api/get-started/create-token/) and [account ID](/fundamentals/account/find-account-and-zone-ids/) to authenticate with the Cloudflare API.

### Cloudflare account ID

To find your Cloudflare account ID, refer to [Find account and zone IDs](/fundamentals/account/find-account-and-zone-ids/).

### API token

To create an API token to authenticate Wrangler in your CI job:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com).
2. Select **Manage Account** > **Account API Tokens**.
3. Select **Create Token** > find **Edit Cloudflare Workers** > select **Use Template**.
4. Customize your token name.
5. Scope your token.

You will need to choose the account and zone resources that the generated API token will have access to. We recommend scoping these down as much as possible to limit the access of your token. For example, if you have access to three different Cloudflare accounts, you should restrict the generated API token to only the account on which you will be deploying a Worker.

## 2. Set up CI/CD

The method for running Wrangler in your CI/CD environment will depend on the specific setup for your project (whether you use GitHub Actions/Jenkins/GitLab or something else entirely).

To set up your CI/CD:

1. Go to your CI/CD platform and add the following as secrets:

- `CLOUDFLARE_ACCOUNT_ID`: Set to the [Cloudflare account ID](#cloudflare-account-id) for the account on which you want to deploy your Worker.
- `CLOUDFLARE_API_TOKEN`: Set to the [Cloudflare API token you generated](#api-token).

:::caution

Don't store the value of `CLOUDFLARE_API_TOKEN` in your repository, as it gives access to deploy Workers on your account. Instead, you should utilize your CI/CD provider's support for storing secrets.
:::

2. Create a workflow that will be responsible for deploying the Worker. This workflow should run `wrangler deploy`. Review an example [GitHub Actions](https://docs.github.com/en/actions/using-workflows/about-workflows) workflow in the follow section.

### GitHub Actions

Cloudflare provides [an official action](https://github.com/cloudflare/wrangler-action) for deploying Workers. Refer to the following example workflow which deploys your Worker on push to the `main` branch.

```yaml
name: Deploy Worker
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 60
    needs: test
    steps:
      - uses: actions/checkout@v4
      - name: Build & Deploy Worker
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
```

---

# External CI/CD

URL: https://developers.cloudflare.com/workers/ci-cd/external-cicd/

Deploying Cloudflare Workers with CI/CD ensures reliable, automated deployments for every code change.

If you prefer to use your existing CI/CD provider instead of [Workers Builds](/workers/ci-cd/builds/), this section offers guides for popular providers:

- [**GitHub Actions**](/workers/ci-cd/external-cicd/github-actions/)
- [**GitLab CI/CD**](/workers/ci-cd/external-cicd/gitlab-cicd/)

Other CI/CD options including but not limited to Terraform, CircleCI, Jenkins, and more, can also be used to deploy Workers following a similar set up process.

---

# GitLab CI/CD

URL: https://developers.cloudflare.com/workers/ci-cd/external-cicd/gitlab-cicd/

You can deploy Workers with [GitLab CI/CD](https://docs.gitlab.com/ee/ci/pipelines/index.html). Here is how you can set up your GitHub Actions workflow.

## 1. Authentication

When running Wrangler locally, authentication to the Cloudflare API happens via the [`wrangler login`](/workers/wrangler/commands/#login) command, which initiates an interactive authentication flow. Since CI/CD environments are non-interactive, Wrangler requires a [Cloudflare API token](/fundamentals/api/get-started/create-token/) and [account ID](/fundamentals/account/find-account-and-zone-ids/) to authenticate with the Cloudflare API.

### Cloudflare account ID

To find your Cloudflare account ID, refer to [Find account and zone IDs](/fundamentals/account/find-account-and-zone-ids/).

### API token

To create an API token to authenticate Wrangler in your CI job:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com).
2. Select **My Profile** > **API Tokens**.
3. Select **Create Token** > find **Edit Cloudflare Workers** > select **Use Template**.
4. Customize your token name.
5. Scope your token.

You will need to choose the account and zone resources that the generated API token will have access to. We recommend scoping these down as much as possible to limit the access of your token. For example, if you have access to three different Cloudflare accounts, you should restrict the generated API token to only the account on which you will be deploying a Worker.

## 2. Set up CI

The method for running Wrangler in your CI/CD environment will depend on the specific setup for your project (whether you use GitHub Actions/Jenkins/GitLab or something else entirely).

To set up your CI:

1. Go to your CI platform and add the following as secrets:

- `CLOUDFLARE_ACCOUNT_ID`: Set to the [Cloudflare account ID](#cloudflare-account-id) for the account on which you want to deploy your Worker.
- `CLOUDFLARE_API_TOKEN`: Set to the [Cloudflare API token you generated](#api-token).

:::caution

Don't store the value of `CLOUDFLARE_API_TOKEN` in your repository, as it gives access to deploy Workers on your account. Instead, you should utilize your CI/CD provider's support for storing secrets.
:::

2. Create a workflow that will be responsible for deploying the Worker. This workflow should run `wrangler deploy`. Review an example [GitHub Actions](https://docs.github.com/en/actions/using-workflows/about-workflows) workflow in the follow section.

### GitLab Pipelines

Refer to [GitLab's blog](https://about.gitlab.com/blog/2022/11/21/deploy-remix-with-gitlab-and-cloudflare/) for an example pipeline. Under the `script` key, replace `npm run deploy` with [`npx wrangler deploy`](/workers/wrangler/commands/#deploy).

---

# APIs

URL: https://developers.cloudflare.com/workers/configuration/integrations/apis/

To integrate with third party APIs from Cloudflare Workers, use the [fetch API](/workers/runtime-apis/fetch/) to make HTTP requests to the API endpoint. Then use the response data to modify or manipulate your content as needed.

For example, if you want to integrate with a weather API, make a fetch request to the API endpoint and retrieve the current weather data. Then use this data to display the current weather conditions on your website.

To make the `fetch()` request, add the following code to your project's `src/index.js` file:

```js
async function handleRequest(request) {
	// Make the fetch request to the third party API endpoint
	const response = await fetch("https://weather-api.com/endpoint", {
		method: "GET",
		headers: {
			"Content-Type": "application/json",
		},
	});

	// Retrieve the data from the response
	const data = await response.json();

	// Use the data to modify or manipulate your content as needed
	return new Response(data);
}
```

## Authentication

If your API requires authentication, use Wrangler secrets to securely store your credentials. To do this, create a secret in your Cloudflare Workers project using the following [`wrangler secret`](/workers/wrangler/commands/#secret) command:

```sh
wrangler secret put SECRET_NAME
```

Then, retrieve the secret value in your code using the following code snippet:

```js
const secretValue = env.SECRET_NAME;
```

Then use the secret value to authenticate with the external service. For example, if the external service requires an API key for authentication, include it in your request headers.

For services that require mTLS authentication, use [mTLS certificates](/workers/runtime-apis/bindings/mtls) to present a client certificate.

## Tips

- Use the Cache API to cache data from the third party API. This allows you to optimize cacheable requests made to the API. Integrating with third party APIs from Cloudflare Workers adds additional functionality and features to your application.

- Use [Custom Domains](/workers/configuration/routing/custom-domains/) when communicating with external APIs, which treat your Worker as your core application.

---

# External Services

URL: https://developers.cloudflare.com/workers/configuration/integrations/external-services/

Many external services provide libraries and SDKs to interact with their APIs. While many Node-compatible libraries work on Workers right out of the box, some, which implement `fs`, `http/net`, or access the browser `window` do not directly translate to the Workers runtime, which is v8-based.

## Authentication

If your service requires authentication, use Wrangler secrets to securely store your credentials. To do this, create a secret in your Cloudflare Workers project using the following [`wrangler secret`](/workers/wrangler/commands/#secret) command:

```sh
wrangler secret put SECRET_NAME
```

Then, retrieve the secret value in your code using the following code snippet:

```js
const secretValue = env.SECRET_NAME;
```

Then use the secret value to authenticate with the external service. For example, if the external service requires an API key for authentication, include the secret in your library's configuration.

For services that require mTLS authentication, use [mTLS certificates](/workers/runtime-apis/bindings/mtls) to present a client certificate.

Use [Custom Domains](/workers/configuration/routing/custom-domains/) when communicating with external APIs, which treat your Worker as your core application.

---

# Integrations

URL: https://developers.cloudflare.com/workers/configuration/integrations/

One of the key features of Cloudflare Workers is the ability to integrate with other services and products. In this document, we will explain the types of integrations available with Cloudflare Workers and provide step-by-step instructions for using them.

## Types of integrations

Cloudflare Workers offers several types of integrations, including:

* [Databases](/workers/databases/): Cloudflare Workers can be integrated with a variety of databases, including SQL and NoSQL databases. This allows you to store and retrieve data from your databases directly from your Cloudflare Workers code.
* [APIs](/workers/configuration/integrations/apis/): Cloudflare Workers can be used to integrate with external APIs, allowing you to access and use the data and functionality exposed by those APIs in your own code.
* [Third-party services](/workers/configuration/integrations/external-services/): Cloudflare Workers can be used to integrate with a wide range of third-party services, such as payment gateways, authentication providers, and more. This makes it possible to use these services in your Cloudflare Workers code.

## How to use integrations

To use any of the available integrations:

* Determine which integration you want to use and make sure you have the necessary accounts and credentials for it.
* In your Cloudflare Workers code, import the necessary libraries or modules for the integration.
* Use the provided APIs and functions to connect to the integration and access its data or functionality.
* Store necessary secrets and keys using secrets via [`wrangler secret put <KEY>`](/workers/wrangler/commands/#secret).

## Tips and best practices

To help you get the most out of using integrations with Cloudflare Workers:

* Secure your integrations and protect sensitive data. Ensure you use secure authentication and authorization where possible, and ensure the validity of libraries you import.
* Use [caching](/workers/reference/how-the-cache-works) to improve performance and reduce the load on an external service.
* Split your Workers into service-oriented architecture using [Service bindings](/workers/runtime-apis/bindings/service-bindings/) to make your application more modular, easier to maintain, and more performant.
* Use [Custom Domains](/workers/configuration/routing/custom-domains/) when communicating with external APIs and services, which create a DNS record on your behalf and treat your Worker as an application instead of a proxy.

---

# Momento

URL: https://developers.cloudflare.com/workers/configuration/integrations/momento/

[Momento](https://gomomento.com/) is a truly serverless caching service. It automatically optimizes, scales, and manages your cache for you.

This integration allows you to connect to Momento from your Worker by getting Momento cache configuration and adding it as [secrets](/workers/configuration/environment-variables/) to your Worker.

## Momento Cache

To set up an integration with Momento Cache:

1. You need to have an existing Momento cache to connect to or create a new cache through the [Momento console](https://console.gomomento.com/).

2. If you do not have an existing cache, create one and assign `user-profiles` as the cache name.

3. Add the Momento database integration to your Worker:

   1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
   2. In **Account Home**, select **Workers & Pages**.
   3. In **Overview**, select your Worker.
   4. Select **Integrations** > **Momento**.
   5. Follow the setup flow, review and grant permissions needed to add secrets to your Worker.
   6. Next, connect to Momento.
   7. Select a preferred region.
   8. Click **Add integration**.

4. The following example code show how to set an item in your cache, get it, and return it as a JSON object. The credentials needed to connect to Momento Cache have been automatically added as [secrets](/workers/configuration/secrets/) to your Worker through the integration.

   ```ts
   export default {
     async fetch(request, env, ctx): Promise<Response> {
       const client = new MomentoFetcher(env.MOMENTO_API_KEY, env.MOMENTO_REST_ENDPOINT);
       const cache = env.MOMENTO_CACHE_NAME;
       const key = 'user';
       const f_name = 'mo';
       const l_name = 'squirrel';
       const value = `${f_name}_${l_name}`;

       // set a value into cache
       const setResponse = await client.set(cache, key, value);
       console.log('setResponse', setResponse);

       // read a value from cache
       const getResponse = await client.get(cache, key);
       console.log('getResponse', getResponse);

       return new Response(JSON.stringify({
         response: getResponse
       }));
     },
   } satisfies ExportedHandler<Env>;
   ```

To learn more about Momento, refer to [Momento's official documentation](https://docs.momentohq.com/getting-started).

---

# Custom Domains

URL: https://developers.cloudflare.com/workers/configuration/routing/custom-domains/

import { WranglerConfig } from "~/components";

## Background

Custom Domains allow you to connect your Worker to a domain or subdomain, without having to make changes to your DNS settings or perform any certificate management. After you set up a Custom Domain for your Worker, Cloudflare will create DNS records and issue necessary certificates on your behalf. The created DNS records will point directly to your Worker. Unlike [Routes](/workers/configuration/routing/routes/#set-up-a-route), Custom Domains point all paths of a domain or subdomain to your Worker.

Custom Domains are routes to a domain or subdomain (such as `example.com` or `shop.example.com`) within a Cloudflare zone where the Worker is the origin.

Custom Domains are recommended if you want to connect your Worker to the Internet and do not have an application server that you want to always communicate with.  If you do have external dependencies, you can create a `Request` object with the target URI, and use `fetch()` to reach out.

Custom Domains can stack on top of each other. For example, if you have Worker A attached to `app.example.com` and Worker B attached to `api.example.com`, Worker A can call `fetch()` on `api.example.com` and invoke Worker B.

![Custom Domains can stack on top of each other, like any external dependencies](~/assets/images/workers/learning/custom-domains-subrequest.png)

Custom Domains can also be invoked within the same zone via `fetch()`, unlike Routes.

## Add a Custom Domain

To add a Custom Domain, you must have:

1. An [active Cloudflare zone](/dns/zone-setups/).
2. A Worker to invoke.

Custom Domains can be attached to your Worker via the [Cloudflare dashboard](/workers/configuration/routing/custom-domains/#set-up-a-custom-domain-in-the-dashboard), [Wrangler](/workers/configuration/routing/custom-domains/#set-up-a-custom-domain-in-your-wrangler-configuration-file) or the [API](/api/resources/workers/subresources/domains/methods/list/).

:::caution


You cannot create a Custom Domain on a hostname with an existing CNAME DNS record or on a zone you do not own.


:::

### Set up a Custom Domain in the dashboard

To set up a Custom Domain in the dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages** and in **Overview**, select your Worker.
3. Go to **Settings** > **Domains & Routes** > **Add** > **Custom Domain**.
4. Enter the domain you want to configure for your Worker.
5. Select **Add Custom Domain**.

After you have added the domain or subdomain, Cloudflare will create a new DNS record for you. You can add multiple Custom Domains.

### Set up a Custom Domain in your Wrangler configuration file

To configure a Custom Domain in your [Wrangler configuration file](/workers/wrangler/configuration/), add the `custom_domain=true` option on each pattern under `routes`. For example, to configure a Custom Domain:

<WranglerConfig>

```toml
routes = [
	{ pattern = "shop.example.com", custom_domain = true }
]
```

</WranglerConfig>

To configure multiple Custom Domains:



<WranglerConfig>

```toml
routes = [
	{ pattern = "shop.example.com", custom_domain = true },
	{ pattern = "shop-two.example.com", custom_domain = true }
]
```

</WranglerConfig>

## Worker to Worker communication

On the same zone, the only way for a Worker to communicate with another Worker running on a [route](/workers/configuration/routing/routes/#set-up-a-route), or on a [`workers.dev`](/workers/configuration/routing/routes/#_top) subdomain, is via [service bindings](/workers/runtime-apis/bindings/service-bindings/).

On the same zone, if a Worker is attempting to communicate with a target Worker running on a Custom Domain rather than a route, the limitation is removed. Fetch requests sent on the same zone from one Worker to another Worker running on a Custom Domain will succeed without a service binding.

For example, consider the following scenario, where both Workers are running on the `example.com` Cloudflare zone:

* `worker-a` running on the [route](/workers/configuration/routing/routes/#set-up-a-route) `auth.example.com/*`.
* `worker-b` running on the [route](/workers/configuration/routing/routes/#set-up-a-route) `shop.example.com/*`.

If `worker-a` sends a fetch request to `worker-b`, the request will fail, because of the limitation on same-zone fetch requests. `worker-a` must have a service binding to `worker-b` for this request to resolve.

```js title="worker-a" {4}
export default {
	fetch(request) {
		// This will fail
		return fetch("https://shop.example.com")
	}
}
```

However, if `worker-b` was instead set up to run on the Custom Domain `shop.example.com`, the fetch request would succeed.

## Request matching behaviour

Custom Domains do not support [wildcard DNS records](/dns/manage-dns-records/reference/wildcard-dns-records/). An incoming request must exactly match the domain or subdomain your Custom Domain is registered to. Other parts (path, query parameters) of the URL are not considered when executing this matching logic. For example, if you create a Custom Domain on `api.example.com` attached to your `api-gateway` Worker, a request to either `api.example.com/login` or `api.example.com/user` would invoke the same `api-gateway` Worker.

![Custom Domains follow standard DNS ordering and matching logic](~/assets/images/workers/platform/triggers/custom-domains-api-gateway.png)

## Interaction with Routes

A Worker running on a Custom Domain is treated as an origin. Any Workers running on routes before your Custom Domain can optionally call the Worker registered on your Custom Domain by issuing `fetch(request)` with the incoming `Request` object. That means that you are able to set up Workers to run before a request gets to your Custom Domain Worker. In other words, you can chain together two Workers in the same request.

For example, consider the following workflow:

1. A Custom Domain for `api.example.com` points to your `api-worker` Worker.
2. A route added to `api.example.com/auth` points to your `auth-worker` Worker.
3. A request to `api.example.com/auth` will trigger your `auth-worker` Worker.
4. Using `fetch(request)` within the `auth-worker` Worker will invoke the `api-worker` Worker, as if it was a normal application server.

```js title="auth-worker" {8}
export default {
	fetch(request) {
		const url = new URL(request.url)
		if(url.searchParams.get("auth") !== "SECRET_TOKEN") {
			return new Response(null, { status: 401 })
		} else {
			// This will invoke `api-worker`
			return fetch(request)
		}
	}
}
```

## Certificates

Creating a Custom Domain will also generate an [Advanced Certificate](/ssl/edge-certificates/advanced-certificate-manager/) on your target zone for your target hostname.

These certificates are generated with default settings. To override these settings, delete the generated certificate and create your own certificate in the Cloudflare dashboard. Refer to [Manage advanced certificates](/ssl/edge-certificates/advanced-certificate-manager/manage-certificates/) for instructions.

## Migrate from Routes

If you are currently invoking a Worker using a [route](/workers/configuration/routing/routes/) with `/*`, and you have a CNAME record pointing to `100::` or similar, a Custom Domain is a recommended replacement.

### Migrate from Routes via the dashboard

To migrate the route `example.com/*`:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **DNS** and delete the CNAME record for `example.com`.
3. Go to **Account Home** > **Workers & Pages**.
4. In **Overview**, select your Worker > **Settings** > **Domains & Routes**.
5. Select **Add** > **Custom domain** and add `example.com`.
6. Delete the route `example.com/*` located in your Worker > **Settings** > **Domains & Routes**.

### Migrate from Routes via Wrangler

To migrate the route `example.com/*` in your [Wrangler configuration file](/workers/wrangler/configuration/):

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **DNS** and delete the CNAME record for `example.com`.
3. Add the following to your Wrangler file:



<WranglerConfig>

```toml
routes = [
	{ pattern = "example.com", custom_domain = true }
]
```

</WranglerConfig>

4. Run `npx  wrangler deploy` to create the Custom Domain your Worker will run on.

---

# Routes and domains

URL: https://developers.cloudflare.com/workers/configuration/routing/

To allow a Worker to receive inbound HTTP requests, you must connect it to an external endpoint such that it can be accessed by the Internet.

There are three types of routes:

- [Custom Domains](/workers/configuration/routing/custom-domains): Routes to a domain or subdomain (such as `example.com` or `shop.example.com`) within a Cloudflare zone where the Worker is the origin.

- [Routes](/workers/configuration/routing/routes/): Routes that are set within a Cloudflare zone where your origin server, if you have one, is behind a Worker that the Worker can communicate with.

- [`workers.dev`](/workers/configuration/routing/workers-dev/): A `workers.dev` subdomain route is automatically created for each Worker to help you getting started quickly. You may choose to [disable](/workers/configuration/routing/workers-dev/) your `workers.dev` subdomain.

## What is best for me?

It's recommended to run production Workers on a [Workers route or custom domain](/workers/configuration/routing/), rather than on your `workers.dev` subdomain. Your `workers.dev` subdomain is treated as a [Free website](https://www.cloudflare.com/plans/) and is intended for personal or hobby projects that aren't business-critical.

Custom Domains are recommended for use cases where your Worker is your application's origin server. Custom Domains can also be invoked within the same zone via `fetch()`, unlike Routes.

Routes are recommended for use cases where your application's origin server is external to Cloudflare. Note that Routes cannot be the target of a same-zone `fetch()` call.

---

# Routes

URL: https://developers.cloudflare.com/workers/configuration/routing/routes/

import { WranglerConfig } from "~/components";

## Background

Routes allow users to map a URL pattern to a Worker. When a request comes in to the Cloudflare network that matches the specified URL pattern, your Worker will execute on that route.

Routes are a set of rules that evaluate against a request's URL. Routes are recommended for you if you have a designated application server you always need to communicate with. Calling `fetch()` on the incoming `Request` object will trigger a subrequest to your application server, as defined in the **DNS** settings of your Cloudflare zone.

Routes add Workers functionality to your existing proxied hostnames, in front of your application server. These allow your Workers to act as a proxy and perform any necessary work before reaching out to an application server behind Cloudflare.

![Routes work with your applications defined in Cloudflare DNS](~/assets/images/workers/learning/routes-diagram.png)

Routes can `fetch()` Custom Domains and take precedence if configured on the same hostname. If you would like to run a logging Worker in front of your application, for example, you can create a Custom Domain on your application Worker for `app.example.com`, and create a Route for your logging Worker at `app.example.com/*`. Calling `fetch()` will invoke the application Worker on your Custom Domain. Note that Routes cannot be the target of a same-zone `fetch()` call.

## Set up a route

To add a route, you must have:

1. An [active Cloudflare zone](/dns/zone-setups/).
2. A Worker to invoke.
3. A DNS record set up for the [domain](/dns/manage-dns-records/how-to/create-zone-apex/) or [subdomain](/dns/manage-dns-records/how-to/create-subdomain/) proxied by Cloudflare (also known as orange-clouded) you would like to route to.

:::caution

Route setup will differ depending on if your application's origin is a Worker or not. If your Worker is your application's origin, use [Custom Domains](/workers/configuration/routing/custom-domains/).
:::

If your Worker is not your application's origin, follow the instructions below to set up a route.

:::note

Routes can also be created via the API. Refer to the [Workers Routes API documentation](/api/resources/workers/subresources/routes/methods/create/) for more information.
:::

### Set up a route in the dashboard

Before you set up a route, make sure you have a DNS record set up for the [domain](/dns/manage-dns-records/how-to/create-zone-apex/) or [subdomain](/dns/manage-dns-records/how-to/create-subdomain/) you would like to route to.

To set up a route in the dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Workers & Pages** and in **Overview**, select your Worker.
3. Go to **Settings** > **Domains & Routes** > **Add** > **Route**.
4. Select the zone and enter the route pattern.
5. Select **Add route**.

### Set up a route in the Wrangler configuration file

Before you set up a route, make sure you have a DNS record set up for the [domain](/dns/manage-dns-records/how-to/create-zone-apex/) or [subdomain](/dns/manage-dns-records/how-to/create-subdomain/) you would like to route to.

To configure a route using your [Wrangler configuration file](/workers/wrangler/configuration/), refer to the following example.

<WranglerConfig>

```toml
routes = [
	{ pattern = "subdomain.example.com/*", zone_name = "example.com" },
	# or
	{ pattern = "subdomain.example.com/*", zone_id = "<YOUR_ZONE_ID>" }
]
```

</WranglerConfig>

Add the `zone_name` or `zone_id` option after each route. The `zone_name` and `zone_id` options are interchangeable. If using `zone_id`, find your zone ID by logging in to the [Cloudflare dashboard](https://dash.cloudflare.com) > select your account > select your website > find the **Zone ID** in the lefthand side of **Overview**.

To add multiple routes:



<WranglerConfig>

```toml
routes = [
	{ pattern = "subdomain.example.com/*", zone_name = "example.com" },
	{ pattern = "subdomain-two.example.com/example", zone_id = "<YOUR_ZONE_ID>" }
]
```

</WranglerConfig>

## Matching behavior

Route patterns look like this:

```txt
https://*.example.com/images/*
```

This pattern would match all HTTPS requests destined for a subhost of
example.com and whose paths are prefixed by `/images/`.

A pattern to match all requests looks like this:

```txt
*example.com/*
```

While they look similar to a [regex](https://en.wikipedia.org/wiki/Regular_expression) pattern, route patterns follow specific rules:

- The only supported operator is the wildcard (`*`), which matches zero or more of any character.

- Route patterns may not contain infix wildcards or query parameters. For example, neither `example.com/*.jpg` nor `example.com/?foo=*` are valid route patterns.

- When more than one route pattern could match a request URL, the most specific route pattern wins. For example, the pattern `www.example.com/*` would take precedence over `*.example.com/*` when matching a request for `https://www.example.com/`. The pattern `example.com/hello/*` would take precedence over `example.com/*` when matching a request for `example.com/hello/world`.

- Route pattern matching considers the entire request URL, including the query parameter string. Since route patterns may not contain query parameters, the only way to have a route pattern match URLs with query parameters is to terminate it with a wildcard, `*`.

- The path component of route patterns is case sensitive, for example, `example.com/Images/*` and `example.com/images/*` are two distinct routes.

- For routes created before October 15th, 2023, the host component of route patterns is case sensitive, for example, `example.com/*` and `Example.com/*` are two distinct routes.

- For routes created on or after October 15th, 2023, the host component of route patterns is not case sensitive, for example, `example.com/*` and `Example.com/*` are equivalent routes.

A route can be specified without being associated with a Worker. This will act to negate any less specific patterns. For example, consider this pair of route patterns, one with a Workers script and one without:

```txt
*example.com/images/cat.png -> <no script>
*example.com/images/*       -> worker-script
```

In this example, all requests destined for example.com and whose paths are prefixed by `/images/` would be routed to `worker-script`, _except_ for `/images/cat.png`, which would bypass Workers completely. Requests with a path of `/images/cat.png?foo=bar` would be routed to `worker-script`, due to the presence of the query string.

## Validity

The following set of rules govern route pattern validity.

#### Route patterns must include your zone

If your zone is `example.com`, then the simplest possible route pattern you can have is `example.com`, which would match `http://example.com/` and `https://example.com/`, and nothing else. As with a URL, there is an implied path of `/` if you do not specify one.

#### Route patterns may not contain any query parameters

For example, `https://example.com/?anything` is not a valid route pattern.

#### Route patterns may optionally begin with `http://` or `https://`

If you omit a scheme in your route pattern, it will match both `http://` and `https://` URLs. If you include `http://` or `https://`, it will only match HTTP or HTTPS requests, respectively.

- `https://*.example.com/` matches `https://www.example.com/` but not `http://www.example.com/`.

- `*.example.com/` matches both `https://www.example.com/` and `http://www.example.com/`.

#### Hostnames may optionally begin with `*`

If a route pattern hostname begins with `*`, then it matches the host and all subhosts. If a route pattern hostname begins with `*.`, then it only matches all subhosts.

- `*example.com/` matches `https://example.com/` and `https://www.example.com/`.

- `*.example.com/` matches `https://www.example.com/` but not `https://example.com/`.

#### Paths may optionally end with `*`

If a route pattern path ends with `*`, then it matches all suffixes of that path.

- `https://example.com/path*` matches `https://example.com/path` and `https://example.com/path2` and `https://example.com/path/readme.txt`

:::caution

There is a well-known bug associated with path matching concerning wildcards (`*`) and forward slashes (`/`) that is documented in [Known issues](/workers/platform/known-issues/).

:::

#### Domains and subdomains must have a DNS Record

All domains and subdomains must have a [DNS record](/dns/manage-dns-records/how-to/create-dns-records/) to be proxied on Cloudflare and used to invoke a Worker. For example, if you want to put a Worker on `myname.example.com`, and you have added `example.com` to Cloudflare but have not added any DNS records for `myname.example.com`, any request to `myname.example.com` will result in the error `ERR_NAME_NOT_RESOLVED`.

:::caution

If you have previously used the Cloudflare dashboard to add an `AAAA` record for `myname` to `example.com`, pointing to `100::` (the [reserved IPv6 discard prefix](https://tools.ietf.org/html/rfc6666)), Cloudflare recommends creating a [Custom Domain](/workers/configuration/routing/custom-domains/) pointing to your Worker instead.

:::

---

# workers.dev

URL: https://developers.cloudflare.com/workers/configuration/routing/workers-dev/

import { WranglerConfig } from "~/components";

Cloudflare Workers accounts come with a `workers.dev` subdomain that is configurable in the Cloudflare dashboard. Your `workers.dev` subdomain allows you getting started quickly by deploying Workers without first onboarding your custom domain to Cloudflare.

It's recommended to run production Workers on a [Workers route or custom domain](/workers/configuration/routing/), rather than on your `workers.dev` subdomain. Your `workers.dev` subdomain is treated as a [Free website](https://www.cloudflare.com/plans/) and is intended for personal or hobby projects that aren't business-critical.

## Configure `workers.dev`

`workers.dev` subdomains take the format: `<YOUR_ACCOUNT_SUBDOMAIN>.workers.dev`. To change your `workers.dev` subdomain:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages**.
3. Select **Change** next to **Your subdomain**.

All Workers are assigned a `workers.dev` route when they are created or renamed following the syntax `<YOUR_WORKER_NAME>.<YOUR_SUBDOMAIN>.workers.dev`. The [`name`](/workers/wrangler/configuration/#inheritable-keys) field in your Worker configuration is used as the subdomain for the deployed Worker.

## Disabling `workers.dev`

### Disabling `workers.dev` in the dashboard

To disable the `workers.dev` route for a Worker:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Go to **Workers & Pages** and in **Overview**, select your Worker.
3. Go to **Settings** > **Domains & Routes**.
4. On `workers.dev` click "Disable".
5. Confirm you want to disable.

### Disabling `workers.dev` in the Wrangler configuration file

To disable the `workers.dev` route for a Worker, include the following in your Worker's  [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
workers_dev = false
```

</WranglerConfig>

When you redeploy your Worker with this change, the `workers.dev` route will be disabled. Disabling your `workers.dev` route does not disable Preview URLs. Learn how to [disable Preview URLs](/workers/configuration/previews/#disabling-preview-urls).

If you do not specify `workers_dev = false` but add a [`routes` component](/workers/wrangler/configuration/#routes) to your [Wrangler configuration file](/workers/wrangler/configuration/), the value of `workers_dev` will be inferred as `false` on the next deploy.

:::caution

If you disable your `workers.dev` route in the Cloudflare dashboard but do not update your Worker's Wrangler file with `workers_dev = false`, the `workers.dev` route will be re-enabled the next time you deploy your Worker with Wrangler.
:::

## Related resources

- [Announcing `workers.dev`](https://blog.cloudflare.com/announcing-workers-dev)
- [Wrangler routes configuration](/workers/wrangler/configuration/#types-of-routes)

---

# Workers Sites configuration

URL: https://developers.cloudflare.com/workers/configuration/sites/configuration/

import { Render, WranglerConfig } from "~/components";

<Render file="workers_sites" />

Workers Sites require the latest version of [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler).

## Wrangler configuration file

There are a few specific configuration settings for Workers Sites in your Wrangler file:

- `bucket` required

  - The directory containing your static assets, path relative to your [Wrangler configuration file](/workers/wrangler/configuration/). Example: `bucket = "./public"`.

- `include` optional

  - A list of gitignore-style patterns for files or directories in `bucket` you exclusively want to upload. Example: `include = ["upload_dir"]`.

- `exclude` optional
  - A list of gitignore-style patterns for files or directories in `bucket` you want to exclude from uploads. Example: `exclude = ["ignore_dir"]`.

To learn more about the optional `include` and `exclude` fields, refer to [Ignoring subsets of static assets](#ignoring-subsets-of-static-assets).

:::note

If your project uses [environments](/workers/wrangler/environments/), make sure to place `site` above any environment-specific configuration blocks.

:::

Example of a [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
name = "docs-site-blah"

[site]
bucket = "./public"

[env.production]
name = "docs-site"
route = "https://example.com/docs*"

[env.staging]
name = "docs-site-staging"
route = "https://staging.example.com/docs*"
```

</WranglerConfig>

## Storage limits

For very exceptionally large pages, Workers Sites might not work for you. There is a 25 MiB limit per page or file.

## Ignoring subsets of static assets

Workers Sites require [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) - make sure to use the [latest version](/workers/wrangler/install-and-update/#update-wrangler).

There are cases where users may not want to upload certain static assets to their Workers Sites.
In this case, Workers Sites can also be configured to ignore certain files or directories using logic
similar to [Cargo's optional include and exclude fields](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields-optional).

This means that you should use gitignore semantics when declaring which directory entries to include or ignore in uploads.

### Exclusively including files/directories

If you want to include only a certain set of files or directories in your `bucket`, you can add an `include` field to your `[site]` section of your Wrangler file:

<WranglerConfig>

```toml
[site]
bucket = "./public"
include = ["included_dir"] # must be an array.
```

</WranglerConfig>

Wrangler will only upload files or directories matching the patterns in the `include` array.

### Excluding files/directories

If you want to exclude files or directories in your `bucket`, you can add an `exclude` field to your `[site]` section of your Wrangler file:

<WranglerConfig>

```toml
[site]
bucket = "./public"
exclude = ["excluded_dir"] # must be an array.
```

</WranglerConfig>

Wrangler will ignore files or directories matching the patterns in the `exclude` array when uploading assets to Workers KV.

### Include > exclude

If you provide both `include` and `exclude` fields, the `include` field will be used and the `exclude` field will be ignored.

### Default ignored entries

Wrangler will always ignore:

- `node_modules`
- Hidden files and directories
- Symlinks

#### More about include/exclude patterns

Learn more about the standard patterns used for include and exclude in the [gitignore documentation](https://git-scm.com/docs/gitignore).

---

# Workers Sites

URL: https://developers.cloudflare.com/workers/configuration/sites/

import { Render } from "~/components";
import { LinkButton } from "~/components";

<Render file="workers_sites" />

Workers Sites enables developers to deploy static applications directly to Workers. It can be used for deploying applications built with static site generators like [Hugo](https://gohugo.io) and [Gatsby](https://www.gatsbyjs.org), or front-end frameworks like [Vue](https://vuejs.org) and [React](https://reactjs.org).

To deploy with Workers Sites, select from one of these three approaches depending on the state of your target project:

---

## 1. Start from scratch

If you are ready to start a brand new project, this quick start guide will help you set up the infrastructure to deploy a HTML website to Workers.

<LinkButton href="/workers/configuration/sites/start-from-scratch/">
	Start from scratch
</LinkButton>

---

## 2. Deploy an existing static site

If you have an existing project or static assets that you want to deploy with Workers, this quick start guide will help you install Wrangler and configure Workers Sites for your project.

<LinkButton href="/workers/configuration/sites/start-from-existing/">
	Start from an existing static site
</LinkButton>

---

## 3. Add static assets to an existing Workers project

If you already have a Worker deployed to Cloudflare, this quick start guide will show you how to configure the existing codebase to use Workers Sites.

<LinkButton href="/workers/configuration/sites/start-from-worker/">
	Start from an existing Worker
</LinkButton>

:::note

Workers Sites is built on Workers KV, and usage rates may apply. Refer to [Pricing](/workers/platform/pricing/) to learn more.

:::

---

# Start from existing

URL: https://developers.cloudflare.com/workers/configuration/sites/start-from-existing/

import { Render, TabItem, Tabs, WranglerConfig } from "~/components";

<Render file="workers_sites" />

Workers Sites require [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) — make sure to use the [latest version](/workers/wrangler/install-and-update/#update-wrangler).

To deploy a pre-existing static site project, start with a pre-generated site. Workers Sites works with all static site generators, for example:

- [Hugo](https://gohugo.io/getting-started/quick-start/)
- [Gatsby](https://www.gatsbyjs.org/docs/quick-start/), requires Node
- [Jekyll](https://jekyllrb.com/docs/), requires Ruby
- [Eleventy](https://www.11ty.io/#quick-start), requires Node
- [WordPress](https://wordpress.org) (refer to the tutorial on [deploying static WordPress sites with Pages](/pages/how-to/deploy-a-wordpress-site/))

## Getting started

1. Run the `wrangler init` command in the root of your project's directory to generate a basic Worker:

   ```sh
   wrangler init -y
   ```

   This command adds/update the following files:

   - `wrangler.jsonc`: The file containing project configuration.
   - `package.json`: Wrangler `devDependencies` are added.
   - `tsconfig.json`: Added if not already there to support writing the Worker in TypeScript.
   - `src/index.ts`: A basic Cloudflare Worker, written in TypeScript.

2. Add your site's build/output directory to the Wrangler file:

   <WranglerConfig>

   ```toml
   [site]
   bucket = "./public" # <-- Add your build directory name here.
   ```

   </WranglerConfig>

   The default directories for the most popular static site generators are listed below:

   - Hugo: `public`
   - Gatsby: `public`
   - Jekyll: `_site`
   - Eleventy: `_site`

3. Install the `@cloudflare/kv-asset-handler` package in your project:

   ```sh
   npm i -D @cloudflare/kv-asset-handler
   ```

4. Replace the contents of `src/index.ts` with the following code snippet:

<Tabs> <TabItem label="Module Worker" icon="seti:javascript">

```js
import { getAssetFromKV } from "@cloudflare/kv-asset-handler";
import manifestJSON from "__STATIC_CONTENT_MANIFEST";
const assetManifest = JSON.parse(manifestJSON);

export default {
	async fetch(request, env, ctx) {
		try {
			// Add logic to decide whether to serve an asset or run your original Worker code
			return await getAssetFromKV(
				{
					request,
					waitUntil: ctx.waitUntil.bind(ctx),
				},
				{
					ASSET_NAMESPACE: env.__STATIC_CONTENT,
					ASSET_MANIFEST: assetManifest,
				},
			);
		} catch (e) {
			let pathname = new URL(request.url).pathname;
			return new Response(`"${pathname}" not found`, {
				status: 404,
				statusText: "not found",
			});
		}
	},
};
```

</TabItem> <TabItem label="Service Worker" icon="seti:javascript">

:::caution[Service Workers are deprecated]

Service Workers are deprecated, but still supported. We recommend using [Module Workers](/workers/reference/migrate-to-module-workers/) instead. New features may not be supported for Service Workers.

:::

```js
import { getAssetFromKV } from "@cloudflare/kv-asset-handler";

addEventListener("fetch", (event) => {
	event.respondWith(handleEvent(event));
});

async function handleEvent(event) {
	try {
		// Add logic to decide whether to serve an asset or run your original Worker code
		return await getAssetFromKV(event);
	} catch (e) {
		let pathname = new URL(event.request.url).pathname;
		return new Response(`"${pathname}" not found`, {
			status: 404,
			statusText: "not found",
		});
	}
}
```

</TabItem> </Tabs>

5. Run `wrangler dev` or `npx wrangler deploy` to preview or deploy your site on Cloudflare.
   Wrangler will automatically upload the assets found in the configured directory.

   ```sh
   npx wrangler deploy
   ```

6. Deploy your site to a [custom domain](/workers/configuration/routing/custom-domains/) that you own and have already attached as a Cloudflare zone. Add a `route` property to the Wrangler file.

   <WranglerConfig>

   ```toml
   route = "https://example.com/*"
   ```

   </WranglerConfig>

   :::note

   Refer to the documentation on [Routes](/workers/configuration/routing/routes/) to configure a `route` properly.
   :::

Learn more about [configuring your project](/workers/wrangler/configuration/).

---

# Start from scratch

URL: https://developers.cloudflare.com/workers/configuration/sites/start-from-scratch/

import { Render, WranglerConfig } from "~/components";

<Render file="workers_sites" />

This guide shows how to quickly start a new Workers Sites project from scratch.

## Getting started

1. Ensure you have the latest version of [git](https://git-scm.com/downloads) and [Node.js](https://nodejs.org/en/download/) installed.

2. In your terminal, clone the `worker-sites-template` starter repository.
   The following example creates a project called `my-site`:

   ```sh
   git clone --depth=1 --branch=wrangler2 https://github.com/cloudflare/worker-sites-template my-site
   ```

3. Run `npm install` to install all dependencies.

4. You can preview your site by running the [`wrangler dev`](/workers/wrangler/commands/#dev) command:

   ```sh
   wrangler dev
   ```

5. Deploy your site to Cloudflare:

   ```sh
   npx wrangler deploy
   ```

## Project layout

The template project contains the following files and directories:

- `public`: The static assets for your project. By default it contains an `index.html` and a `favicon.ico`.
- `src`: The Worker configured for serving your assets. You do not need to edit this but if you want to see how it works or add more functionality to your Worker, you can edit `src/index.ts`.
- `wrangler.jsonc`: The file containing project configuration.
  The `bucket` property tells Wrangler where to find the static assets (e.g. `site = { bucket = "./public" }`).
- `package.json`/`package-lock.json`: define the required Node.js dependencies.

## Customize the `wrangler.jsonc` file:

- Change the `name` property to the name of your project:

  <WranglerConfig>

  ```toml
  name = "my-site"
  ```

  </WranglerConfig>

- Consider updating`compatibility_date` to today's date to get access to the most recent Workers features:

  <WranglerConfig>

  ```toml
  compatibility_date = "yyyy-mm-dd"
  ```

  </WranglerConfig>

- Deploy your site to a [custom domain](/workers/configuration/routing/custom-domains/) that you own and have already attached as a Cloudflare zone:

  <WranglerConfig>

  ```toml
  route = "https://example.com/*"
  ```

  </WranglerConfig>

  :::note

  Refer to the documentation on [Routes](/workers/configuration/routing/routes/) to configure a `route` properly.
  :::

Learn more about [configuring your project](/workers/wrangler/configuration/).

---

# Start from Worker

URL: https://developers.cloudflare.com/workers/configuration/sites/start-from-worker/

import { Render, TabItem, Tabs, WranglerConfig } from "~/components";

<Render file="workers_sites" />

Workers Sites require [Wrangler](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler) — make sure to use the [latest version](/workers/wrangler/install-and-update/#update-wrangler).

If you have a pre-existing Worker project, you can use Workers Sites to serve static assets to the Worker.

## Getting started

1. Create a directory that will contain the assets in the root of your project (for example, `./public`)

2. Add configuration to your Wrangler file to point to it.

   <WranglerConfig>

   ```toml
   [site]
   bucket = "./public" # Add the directory with your static assets!
   ```

   </WranglerConfig>

3. Install the `@cloudflare/kv-asset-handler` package in your project:

   ```sh
   npm i -D @cloudflare/kv-asset-handler
   ```

4. Import the `getAssetFromKV()` function into your Worker entry point and use it to respond with static assets.

<Tabs> <TabItem label="Module Worker" icon="seti:javascript">

```js
import { getAssetFromKV } from "@cloudflare/kv-asset-handler";
import manifestJSON from "__STATIC_CONTENT_MANIFEST";
const assetManifest = JSON.parse(manifestJSON);

export default {
	async fetch(request, env, ctx) {
		try {
			// Add logic to decide whether to serve an asset or run your original Worker code
			return await getAssetFromKV(
				{
					request,
					waitUntil: ctx.waitUntil.bind(ctx),
				},
				{
					ASSET_NAMESPACE: env.__STATIC_CONTENT,
					ASSET_MANIFEST: assetManifest,
				},
			);
		} catch (e) {
			let pathname = new URL(request.url).pathname;
			return new Response(`"${pathname}" not found`, {
				status: 404,
				statusText: "not found",
			});
		}
	},
};
```

</TabItem> <TabItem label="Service Worker" icon="seti:javascript">

```js
import { getAssetFromKV } from "@cloudflare/kv-asset-handler";

addEventListener("fetch", (event) => {
	event.respondWith(handleEvent(event));
});

async function handleEvent(event) {
	try {
		// Add logic to decide whether to serve an asset or run your original Worker code
		return await getAssetFromKV(event);
	} catch (e) {
		let pathname = new URL(event.request.url).pathname;
		return new Response(`"${pathname}" not found`, {
			status: 404,
			statusText: "not found",
		});
	}
}
```

</TabItem> </Tabs>

For more information on the configurable options of `getAssetFromKV()` refer to [kv-asset-handler docs](https://github.com/cloudflare/workers-sdk/tree/main/packages/kv-asset-handler).

5. Run `wrangler deploy` or `npx wrangler deploy` as you would normally with your Worker project.
   Wrangler will automatically upload the assets found in the configured directory.

   ```sh
   npx wrangler deploy
   ```

---

# Gradual deployments

URL: https://developers.cloudflare.com/workers/configuration/versions-and-deployments/gradual-deployments/

import { Example } from "~/components";

Gradual Deployments give you the ability to incrementally deploy new [versions](/workers/configuration/versions-and-deployments/#versions) of Workers by splitting traffic across versions.

![Gradual Deployments](~/assets/images/workers/platform/versions-and-deployments/gradual-deployments.png)

Using gradual deployments, you can:

- Gradually shift traffic to a newer version of your Worker.
- Monitor error rates and exceptions across versions using [analytics and logs](/workers/configuration/versions-and-deployments/gradual-deployments/#observability) tooling.
- [Roll back](/workers/configuration/versions-and-deployments/rollbacks/) to a previously stable version if you notice issues when deploying a new version.

## Use gradual deployments

The following section guides you through an example usage of gradual deployments. You will choose to use either [Wrangler](/workers/configuration/versions-and-deployments/gradual-deployments/#via-wrangler) or the [Cloudflare dashboard](/workers/configuration/versions-and-deployments/gradual-deployments/#via-the-cloudflare-dashboard) to:

- Create a new Worker.
- Publish a new version of that Worker without deploying it.
- Create a gradual deployment between the two versions.
- Progress the deployment of the new version to 100% of traffic.

### Via Wrangler

:::note

Minimum required Wrangler version: 3.40.0. Versions before 3.73.0 require you to specify a `--x-versions` flag.

:::

#### 1. Create and deploy a new Worker

Create a new `"Hello World"` Worker using the [`create-cloudflare` CLI (C3)](/pages/get-started/c3/) and deploy it.

```sh
npm create cloudflare@latest <NAME> -- --type=hello-world
```

Answer `yes` or `no` to using TypeScript. Answer `yes` to deploying your application. This is the first version of your Worker.

#### 2. Create a new version of the Worker

To create a new version of the Worker, edit the Worker code by changing the `Response` content to your desired text and upload the Worker by using the [`wrangler versions upload`](/workers/wrangler/commands/#upload) command.

```sh
npx wrangler versions upload
```

This will create a new version of the Worker that is not automatically deployed.

#### 3. Create a new deployment

Use the [`wrangler versions deploy`](/workers/wrangler/commands/#deploy-2) command to
create a new deployment that splits traffic between two versions of the Worker. Follow the interactive prompts to create a deployment with the versions uploaded in [step #1](/workers/configuration/versions-and-deployments/gradual-deployments/#1-create-and-deploy-a-new-worker) and [step #2](/workers/configuration/versions-and-deployments/gradual-deployments/#2-create-a-new-version-of-the-worker). Select your desired percentages for each version.

```sh
npx wrangler versions deploy
```

#### 4. Test the split deployment

Run a cURL command on your Worker to test the split deployment.

```bash
for j in {0..10}
do
    curl -s https://$WORKER_NAME.$SUBDOMAIN.workers.dev
done
```

You should see 10 responses. Responses will reflect the content returned by the versions in your deployment. Responses will vary depending on the percentages configured in [step #3](/workers/configuration/versions-and-deployments/gradual-deployments/#3-create-a-new-deployment).

You can test also target a specific version using [version overrides](#version-overrides).

#### 5. Set your new version to 100% deployment

Run `wrangler versions deploy` again and follow the interactive prompts. Select the version uploaded in [step 2](/workers/configuration/versions-and-deployments/gradual-deployments/#2-create-a-new-version-of-the-worker) and set it to 100% deployment.

```sh
npx wrangler versions deploy
```

### Via the Cloudflare dashboard

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers) and select your account.
2. Go to **Workers & Pages**.
3. Select **Create application** > **Hello World** template > deploy your Worker.
4. Once the Worker is deployed, go to the online code editor through **Edit code**. Edit the Worker code (change the `Response` content) and upload the Worker.
5. To save changes, select the **down arrow** next to **Deploy** > **Save**. This will create a new version of your Worker.
6. Create a new deployment that splits traffic between the two versions created in step 3 and 5 by going to **Deployments** and selecting **Deploy Version**.
7. cURL your Worker to test the split deployment.

```bash
for j in {0..10}
do
    curl -s https://$WORKER_NAME.$SUBDOMAIN.workers.dev
done
```

You should see 10 responses. Responses will reflect the content returned by the versions in your deployment. Responses will vary depending on the percentages configured in step #6.

## Version affinity

By default, the percentages configured when using gradual deployments operate on a per-request basis — a request has a X% probability of invoking one of two versions of the Worker in the [deployment](/workers/configuration/versions-and-deployments/#deployments).

You may want requests associated with a particular identifier (such as user, session, or any unique ID) to be handled by a consistent version of your Worker to prevent version skew. Version skew occurs when there are multiple versions of an application deployed that are not forwards/backwards compatible. You can configure version affinity to prevent the Worker's version from changing back and forth on a per-request basis.

You can do this by setting the `Cloudflare-Workers-Version-Key` header on the incoming request to your Worker. For example:

```sh
curl -s https://example.com -H 'Cloudflare-Workers-Version-Key: foo'
```

For a given [deployment](/workers/configuration/versions-and-deployments/#deployments), all requests with a version key set to `foo` will be handled by the same version of your Worker. The specific version of your Worker that the version key `foo` corresponds to is determined by the percentages you have configured for each Worker version in your deployment.

You can set the `Cloudflare-Workers-Version-Key` header both when making an external request from the Internet to your Worker, as well as when making a subrequest from one Worker to another Worker using a [service binding](/workers/runtime-apis/bindings/service-bindings/).

### Setting `Cloudflare-Workers-Version-Key` using Ruleset Engine

You may want to extract a version key from certain properties of your request such as the URL, headers or cookies. You can configure a [Ruleset Engine](/ruleset-engine/) rule on your zone to do this. This allows you to specify version affinity based on these properties without having to modify the external client that makes the request.

For example, if your worker serves video assets under the URI path `/assets/` and you wanted requests to each unique asset to be handled by a consistent version, you could define the following [request header transform rule](/rules/transform/request-header-modification/):

<Example>

Text in **Expression Editor**:

```txt
starts_with(http.request.uri.path, "/asset/")
```

Selected operation under **Modify request header**: _Set dynamic_

**Header name**: `Cloudflare-Workers-Version-Key`

**Value**: `regex_replace(http.request.uri.path, "/asset/(.*)", "${1}")`

</Example>

## Version overrides

You can use version overrides to send a request to a specific version of your Worker in your gradual deployment.

To specify a version override in your request, you can set the `Cloudflare-Workers-Version-Overrides` header on the request to your Worker. For example:

```sh
curl -s https://example.com -H 'Cloudflare-Workers-Version-Overrides: my-worker-name="dc8dcd28-271b-4367-9840-6c244f84cb40"'
```

`Cloudflare-Workers-Version-Overrides` is a [Dictionary Structured Header](https://www.rfc-editor.org/rfc/rfc8941#name-dictionaries).

The dictionary can contain multiple key-value pairs. Each key indicates the name of the Worker the override should be applied to. The value indicates the version ID that should be used and must be a [String](https://www.rfc-editor.org/rfc/rfc8941#name-strings).

A version override will only be applied if the specified version is in the current deployment. The versions in the current deployment can be found using the [`wrangler deployments list`](/workers/wrangler/commands/#list-6) command or on the [Workers Dashboard](https://dash.cloudflare.com/?to=/:account/workers) under Worker > Deployments > Active Deployment.

:::note[Verifying that the version override was applied]

There are a number of reasons why a request's version override may not be applied. For example:

- The deployment containing the specified version may not have propagated yet.
- The header value may not be a valid [Dictionary](https://www.rfc-editor.org/rfc/rfc8941#name-dictionaries).

In the case that a request's version override is not applied, the request will be routed according to the percentages set in the gradual deployment configuration.

To make sure that the request's version override was applied correctly, you can [observe](#observability) the version of your Worker that was invoked. You could even automate this check by using the [runtime binding](#runtime-binding) to return the version in the Worker's response.

:::

### Example

You may want to test a new version in production before gradually deploying it to an increasing proportion of external traffic.

In this example, your deployment is initially configured to route all traffic to a single version:

|              Version ID              | Percentage |
| :----------------------------------: | :--------: |
| db7cd8d3-4425-4fe7-8c81-01bf963b6067 |    100%    |

Create a new deployment using [`wrangler versions deploy`](/workers/wrangler/commands/#deploy-2) and specify 0% for the new version whilst keeping the previous version at 100%.

|              Version ID              | Percentage |
| :----------------------------------: | :--------: |
| dc8dcd28-271b-4367-9840-6c244f84cb40 |     0%     |
| db7cd8d3-4425-4fe7-8c81-01bf963b6067 |    100%    |

Now test the new version with a version override before gradually progressing the new version to 100%:

```sh
curl -s https://example.com -H 'Cloudflare-Workers-Version-Overrides: my-worker-name="dc8dcd28-271b-4367-9840-6c244f84cb40"'
```

## Gradual deployments for Durable Objects

To provide [global uniqueness](/durable-objects/platform/known-issues/#global-uniqueness), only one version of each [Durable Object](/durable-objects/) can run at a time. This means that gradual deployments work slightly differently for Durable Objects.

When you create a new gradual deployment for a Worker with Durable Objects, each Durable Object is assigned a Worker version based on the percentages you configured in your [deployment](/workers/configuration/versions-and-deployments/#deployments). This version will not change until you create a new deployment.

![Gradual Deployments Durable Objects](~/assets/images/workers/platform/versions-and-deployments/durable-objects.png)

### Example

This example assumes that you have previously created 3 Durable Objects and [derived their IDs from the names](/durable-objects/api/namespace/#idfromname) "foo", "bar" and "baz".

Your Worker is currently on a version that we will call version "A" and you want to gradually deploy a new version "B" of your Worker.

Here is how the versions of your Durable Objects might change as you progress your gradual deployment:

|          Deployment config          | "foo" | "bar" | "baz" |
| :---------------------------------: | :---: | :---: | :---: |
|        Version A: 100% <br/>        |   A   |   A   |   A   |
| Version B: 20% <br/> Version A: 80% |   B   |   A   |   A   |
| Version B: 50% <br/> Version A: 50% |   B   |   B   |   A   |
|        Version B: 100% <br/>        |   B   |   B   |   B   |

This is only an example, so the versions assigned to your Durable Objects may be different. However, the following is guaranteed:

- For a given deployment, requests to each Durable Object will always use the same Worker version.
- When you specify each version in the same order as the previous deployment and increase the percentage of a version, Durable Objects which were previously assigned that version will not be assigned a different version. In this example, Durable Object "foo" would never revert from version "B" to version "A".
- The Durable Object will only be [reset](/durable-objects/observability/troubleshooting/#durable-object-reset-because-its-code-was-updated) when it is assigned a different version, so each Durable Object will only be reset once in this example.

:::note
Typically, a Worker bundle will define both the Durable Object class and a Worker that interacts with it. In this case, you cannot deploy changes to your Durable Object and its Worker independently.

You should ensure that API changes between your Durable Object and its Worker are [forwards and backwards compatible](/durable-objects/platform/known-issues/#code-updates) whether you are using gradual deployments or not. However, using gradual deployments will make it even more likely that different versions of your Durable Objects and its Worker will interact with each other.
:::

### Migrations

Versions of Worker bundles containing new Durable Object migrations cannot be uploaded. This is because Durable Object migrations are atomic operations. Durable Object migrations can be deployed with the following command:

```sh
npx wrangler versions deploy
```

To limit the blast radius of Durable Object migration deployments, migrations should be deployed independently of other code changes.

To understand why Durable Object migrations are atomic operations, consider the hypothetical example of gradually deploying a delete migration. If a delete migration were applied to 50% of Durable Object instances, then Workers requesting those Durable Object instances would fail because they would have been deleted.

To do this without producing errors, a version of the Worker which does not depend on any Durable Object instances would have to have already been rolled out. Then, you can deploy a delete migration without affecting any traffic and there is no reason to do so gradually.

## Observability

When using gradual deployments, you may want to attribute Workers invocations to a specific version in order to get visibility into the impact of deploying new versions.

### Logpush

A new `ScriptVersion` object is available in [Workers Logpush](/workers/observability/logs/logpush/). `ScriptVersion` can only be added through the Logpush API right now. Sample API call:

```bash
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/logpush/jobs' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"name": "workers-logpush",
"output_options": {
    "field_names": ["Event", "EventTimestampMs", "Outcome", "Logs", "ScriptName", "ScriptVersion"],
},
"destination_conf": "<DESTINATION_URL>",
"dataset": "workers_trace_events",
"enabled": true
}'| jq .
```

`ScriptVersion` is an object with the following structure:

```json
scriptVersion: {
    id: "<UUID>",
    message: "<MESSAGE>",
    tag: "<TAG>"
}
```

### Runtime binding

Use the [Version metadata binding](/workers/runtime-apis/bindings/version-metadata/) in to access version ID or version tag in your Worker.

## Limits

### Deployments limit

You can only create a new deployment with the last 10 uploaded versions of your Worker.

---

# Versions & Deployments

URL: https://developers.cloudflare.com/workers/configuration/versions-and-deployments/

Versions track changes to your Worker. Deployments configure how those changes are deployed to your traffic.

You can upload changes (versions) to your Worker independent of changing the version that is actively serving traffic (deployment).

![Versions and Deployments](~/assets/images/workers/platform/versions-and-deployments/versions-and-deployments.png)

Using versions and deployments is useful if:

- You are running critical applications on Workers and want to reduce risk when deploying new versions of your Worker using a rolling deployment strategy.
- You want to monitor for performance differences when deploying new versions of your Worker.
- You have a CI/CD pipeline configured for Workers but want to cut manual releases.

## Versions

A version is defined by the state of code as well as the state of configuration in a Worker's [Wrangler configuration file](/workers/wrangler/configuration/). Versions track historical changes to [bundled code](/workers/wrangler/bundling/), [static assets](/workers/static-assets/) and changes to configuration like [bindings](/workers/runtime-apis/bindings/) and [compatibility date and compatibility flags](/workers/configuration/compatibility-dates/) over time.

Versions also track metadata associated with a version, including: the version ID, the user that created the version, deploy source, and timestamp. Optionally, a version message and version tag can be configured on version upload.

:::note
State changes for associated Workers [storage resources](/workers/platform/storage-options/) such as [KV](/kv/), [R2](/r2/), [Durable Objects](/durable-objects/) and [D1](/d1/) are not tracked with versions.
:::

## Deployments

Deployments track the version(s) of your Worker that are actively serving traffic. A deployment can consist of one or two versions of a Worker.

By default, Workers supports an all-at-once deployment model where traffic is immediately shifted from one version to the newly deployed version automatically. Alternatively, you can use [gradual deployments](/workers/configuration/versions-and-deployments/gradual-deployments/) to create a rolling deployment strategy.

You can also track metadata associated with a deployment, including: the user that created the deployment, deploy source, timestamp and the version(s) in the deployment. Optionally, you can configure a deployment message when you create a deployment.

## Use versions and deployments

### Create a new version

Review the different ways you can create versions of your Worker and deploy them.

#### Upload a new version and deploy it immediately

A new version that is automatically deployed to 100% of traffic when:

- Changes are uploaded with [`wrangler deploy`](/workers/wrangler/commands/#deploy) via the Cloudflare Dashboard
- Changes are deployed with the command [`npx wrangler deploy`](/workers/wrangler/commands/#deploy) via [Workers Builds](/workers/ci-cd/builds)
- Changes are uploaded with the [Workers Script Upload API](/api/resources/workers/subresources/scripts/methods/update/)

#### Upload a new version to be gradually deployed or deployed at a later time

:::note

Wrangler versions before 3.73.0 require you to specify a `--x-versions` flag.

:::

To create a new version of your Worker that is not deployed immediately, use the [`wrangler versions upload`](/workers/wrangler/commands/#upload) command or create a new version via the Cloudflare dashboard using the **Save** button. You can find the **Save** option under the down arrow beside the "Deploy" button.

Versions created in this way can then be deployed all at once or gradually deployed using the [`wrangler versions deploy`](/workers/wrangler/commands/#deploy-2) command or via the Cloudflare dashboard under the **Deployments** tab.

:::note
When using [Wrangler](/workers/wrangler/), changes made to a Worker's triggers [routes, domains](/workers/configuration/routing/) or [cron triggers](/workers/configuration/cron-triggers/) need to be applied with the command [`wrangler triggers deploy`](/workers/wrangler/commands/#triggers).
:::

:::note
New versions are not created when you make changes to [resources connected to your Worker](/workers/runtime-apis/bindings/). For example, if two Workers (Worker A and Worker B) are connected via a [service binding](/workers/runtime-apis/bindings/service-bindings/), changing the code of Worker B will not create a new version of Worker A. Changing the code of Worker B will only create a new version of Worker B. Changes to the service binding (such as, deleting the binding or updating the [environment](/workers/wrangler/environments/) it points to) on Worker A will also not create a new version of Worker B.
:::

### View versions and deployments

#### Via Wrangler

Wrangler allows you to view the 10 most recent versions and deployments. Refer to the [`versions list`](/workers/wrangler/commands/#list-5) and [`deployments`](/workers/wrangler/commands/#list-6) documentation to view the commands.

#### Via the Cloudflare dashboard

To view your deployments in the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers) and select your account.
2. Go to **Workers & Pages**.
3. Select your Worker > **Deployments**.

## Limits

### First upload

You must use [C3](/workers/get-started/guide/#1-create-a-new-worker-project) or [`wrangler deploy`](/workers/wrangler/commands/#deploy) the first time you create a new Workers project. Using [`wrangler versions upload`](/workers/wrangler/commands/#upload) the first time you upload a Worker will fail.

### Service worker syntax

Service worker syntax is not supported for versions that are uploaded through [`wrangler versions upload`](/workers/wrangler/commands/#upload). You must use ES modules format.

Refer to [Migrate from Service Workers to ES modules](/workers/reference/migrate-to-module-workers/#advantages-of-migrating) to learn how to migrate your Workers from the service worker format to the ES modules format.

### Durable Object migrations

Uploading a version with [Durable Object migrations](/durable-objects/reference/durable-objects-migrations/) is not supported. Use [`wrangler deploy`](/workers/wrangler/commands/#deploy) if you are applying a [Durable Object migration](/durable-objects/reference/durable-objects-migrations/).

This will be supported in the near future.

---

# Rollbacks

URL: https://developers.cloudflare.com/workers/configuration/versions-and-deployments/rollbacks/

You can roll back to a previously deployed [version](/workers/configuration/versions-and-deployments/#versions) of your Worker using [Wrangler](/workers/wrangler/commands/#rollback) or the Cloudflare dashboard. Rolling back to a previous version of your Worker will immediately create a new [deployment](/workers/configuration/versions-and-deployments/#deployments) with the version specified and become the active deployment across all your deployed routes and domains.

## Via Wrangler

To roll back to a specified version of your Worker via Wrangler, use the [`wrangler rollback`](/workers/wrangler/commands/#rollback) command.

## Via the Cloudflare Dashboard

To roll back to a specified version of your Worker via the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers) and select your account.
2. Go to **Workers & Pages** > select your Worker > **Deployments**.
3. Select the three dot icon on the right of the version you would like to roll back to and select **Rollback**.

:::caution

**[Resources connected to your Worker](/workers/runtime-apis/bindings/) will not be changed during a rollback.**

Errors could occur if using code for a prior version if the structure of data has changed between the version in the active deployment and the version selected to rollback to.

:::

## Limits

### Rollbacks limit

You can only roll back to the 10 most recently published versions.

### Bindings

You cannot roll back to a previous version of your Worker if the [Cloudflare Developer Platform resources](/workers/runtime-apis/bindings/) (such as [KV](/kv/) and [D1](/d1/)) have been deleted or modified between the version selected to roll back to and the version in the active deployment. Specifically, rollbacks will not be allowed if:

* A [Durable Object migration](/durable-objects/reference/durable-objects-migrations/) has occurred between the version in the active deployment and the version selected to roll back to.
* If the target deployment has a [binding](/workers/runtime-apis/bindings/) to an R2 bucket, KV namespace, or queue that no longer exists.

---

# 3rd Party Integrations

URL: https://developers.cloudflare.com/workers/databases/third-party-integrations/

import { DirectoryListing } from "~/components"

## Background

Connect to databases by configuring connection strings and credentials as [secrets](/workers/configuration/secrets/) in your Worker. 

:::note[Connecting to a regional database from a Worker?]


If your Worker is connecting to a regional database, you can reduce your query latency by using [Hyperdrive](/hyperdrive) and [Smart Placement](/workers/configuration/smart-placement/) which are both included in any Workers plan. Hyperdrive will pool your databases connections globally across Cloudflare's network. Smart Placement will monitor your application to run your Workers closest to your backend infrastructure when this reduces the latency of your Worker invocations. Learn more about [how Smart Placement works](/workers/configuration/smart-placement/).
:::

## Database credentials

When you rotate or update database credentials, you must update the corresponding [secrets](/workers/configuration/secrets/) in your Worker. Use the [`wrangler secret put`](/workers/wrangler/commands/#secret) command to update secrets securely or update the secret directly in the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/services/view/:worker/production/settings).

## Database limits

You can connect to multiple databases by configuring separate sets of secrets for each database connection. Use descriptive secret names to distinguish between different database connections (for example, `DATABASE_URL_PROD` and `DATABASE_URL_STAGING`).

## Popular providers

<DirectoryListing />

---

# Neon

URL: https://developers.cloudflare.com/workers/databases/third-party-integrations/neon/

import { Render, PackageManagers, Tabs, TabItem } from "~/components";

[Neon](https://neon.tech/) is a fully managed serverless PostgreSQL. It separates storage and compute to offer modern developer features, such as serverless, branching, and bottomless storage.

:::note

You can connect to Neon using [Hyperdrive](/hyperdrive) (recommended), or using the Neon serverless driver, `@neondatabase/serverless`. Both provide connection pooling and reduce the amount of round trips required to create a secure connection from Workers to your database.

Hyperdrive can provide the lowest possible latencies because it performs the database connection setup and connection pooling across Cloudflare's network. Hyperdrive supports native database drivers, libraries, and ORMs, and is included in all [Workers plans](/hyperdrive/platform/pricing/). Learn more about Hyperdrive in [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/).

:::

<Tabs>
	<TabItem label="Hyperdrive (recommended)">

To connect to Neon using [Hyperdrive](/hyperdrive), follow these steps:

         <Render file="neon-partial" product="hyperdrive"/>
    </TabItem>
    <TabItem label="Neon serverless driver">

To connect to Neon using `@neondatabase/serverless`, follow these steps:

1. You need to have an existing Neon database to connect to. [Create a Neon database](https://neon.tech/docs/postgres/tutorial-createdb#create-a-table) or [load data from an existing database to Neon](https://neon.tech/docs/import/import-from-postgres).

2. Create an `elements` table using the Neon SQL editor. The SQL Editor allows you to query your databases directly from the Neon Console.

   ```sql
   CREATE TABLE elements (
     id INTEGER NOT NULL,
     elementName TEXT NOT NULL,
     atomicNumber INTEGER NOT NULL,
     symbol TEXT NOT NULL
   );
   ```

3. Insert some data into your newly created table.

   ```sql
   INSERT INTO elements (id, elementName, atomicNumber, symbol)
   VALUES
     (1, 'Hydrogen', 1, 'H'),
     (2, 'Helium', 2, 'He'),
     (3, 'Lithium', 3, 'Li'),
     (4, 'Beryllium', 4, 'Be'),
     (5, 'Boron', 5, 'B'),
     (6, 'Carbon', 6, 'C'),
     (7, 'Nitrogen', 7, 'N'),
     (8, 'Oxygen', 8, 'O'),
     (9, 'Fluorine', 9, 'F'),
     (10, 'Neon', 10, 'Ne');
   ```

4. Configure the Neon database credentials in your Worker:

   You need to add your Neon database connection string as a secret to your Worker. Get your connection string from the [Neon Console](https://console.neon.tech) under **Connection Details**, then add it as a secret using Wrangler:

   ```sh
   # Add the database connection string as a secret
   npx wrangler secret put DATABASE_URL
   # When prompted, paste your Neon database connection string
   ```

5. In your Worker, install the `@neondatabase/serverless` driver to connect to your database and start manipulating data:

   <PackageManagers pkg="@neondatabase/serverless" />

6. The following example shows how to make a query to your Neon database in a Worker. The credentials needed to connect to Neon have been added as secrets to your Worker.

   ```js
   import { Client } from "@neondatabase/serverless";

   export default {
   	async fetch(request, env, ctx) {
   		const client = new Client(env.DATABASE_URL);
   		await client.connect();
   		const { rows } = await client.query("SELECT * FROM elements");
   		ctx.waitUntil(client.end()); // this doesn’t hold up the response

   		return new Response(JSON.stringify(rows));
   	},
   };
   ```

To learn more about Neon, refer to [Neon's official documentation](https://neon.tech/docs/introduction).

   </TabItem>
</Tabs>

---

# PlanetScale

URL: https://developers.cloudflare.com/workers/databases/third-party-integrations/planetscale/

import { Render, PackageManagers, Tabs, TabItem } from "~/components";

[PlanetScale](https://planetscale.com/) is a MySQL-compatible platform that makes databases infinitely scalable, easier and safer to manage.

:::note

You can connect to PlanetScale using [Hyperdrive](/hyperdrive) (recommended), or using the PlanetScale serverless driver, `@planetscale/database`. Both provide connection pooling and reduce the amount of round trips required to create a secure connection from Workers to your database.

Hyperdrive can provide lower latencies because it performs the database connection setup and connection pooling across Cloudflare's network. Hyperdrive supports native database drivers, libraries, and ORMs, and is included in all [Workers plans](/hyperdrive/platform/pricing/). Learn more about Hyperdrive in [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/).

:::

<Tabs>
	<TabItem label="Hyperdrive (recommended)">

To connect to PlanetScale using [Hyperdrive](/hyperdrive), follow these steps:

         <Render file="planetscale-partial" product="hyperdrive"/>
    </TabItem>
    <TabItem label="PlanetScale serverless driver">

## Set up an integration with PlanetScale

To set up an integration with PlanetScale:

1. You need to have an existing PlanetScale database to connect to. [Create a PlanetScale database](https://planetscale.com/docs/tutorials/planetscale-quick-start-guide#create-a-database) or [import an existing database to PlanetScale](https://planetscale.com/docs/imports/database-imports#overview).

2. From the [PlanetScale web console](https://planetscale.com/docs/concepts/web-console#get-started), create a `products` table with the following query:

   ```sql
   CREATE TABLE products (
     id int NOT NULL AUTO_INCREMENT PRIMARY KEY,
     name varchar(255) NOT NULL,
     image_url varchar(255),
     category_id INT,
     KEY category_id_idx (category_id)
   );
   ```

3. Insert some data in your newly created table. Run the following command to add a product and category to your table:

   ```sql
   INSERT INTO products (name, image_url, category_id)
   VALUES ('Ballpoint pen', 'https://example.com/500x500', '1');
   ```

4. Configure the PlanetScale database credentials in your Worker:

   You need to add your PlanetScale database credentials as secrets to your Worker. Get your connection details from the [PlanetScale Dashboard](https://app.planetscale.com) by creating a connection string, then add them as secrets using Wrangler:

   ```sh
   # Add the database host as a secret
   npx wrangler secret put DATABASE_HOST
   # When prompted, paste your PlanetScale host

   # Add the database username as a secret
   npx wrangler secret put DATABASE_USERNAME
   # When prompted, paste your PlanetScale username

   # Add the database password as a secret
   npx wrangler secret put DATABASE_PASSWORD
   # When prompted, paste your PlanetScale password
   ```

5. In your Worker, install the `@planetscale/database` driver to connect to your PlanetScale database and start manipulating data:

   <PackageManagers pkg="@planetscale/database" />

6. The following example shows how to make a query to your PlanetScale database in a Worker. The credentials needed to connect to PlanetScale have been added as secrets to your Worker.

   ```js
   import { connect } from "@planetscale/database";

   export default {
   	async fetch(request, env) {
   		const config = {
   			host: env.DATABASE_HOST,
   			username: env.DATABASE_USERNAME,
   			password: env.DATABASE_PASSWORD,
   			// see https://github.com/cloudflare/workerd/issues/698
   			fetch: (url, init) => {
   				delete init["cache"];
   				return fetch(url, init);
   			},
   		};

   		const conn = connect(config);
   		const data = await conn.execute("SELECT * FROM products;");
   		return new Response(JSON.stringify(data.rows), {
   			status: 200,
   			headers: {
   				"Content-Type": "application/json",
   			},
   		});
   	},
   };
   ```

To learn more about PlanetScale, refer to [PlanetScale's official documentation](https://docs.planetscale.com/).

</TabItem>
</Tabs>

---

# Turso

URL: https://developers.cloudflare.com/workers/databases/third-party-integrations/turso/

import { Render, PackageManagers } from "~/components";

[Turso](https://turso.tech/) is an edge-hosted, distributed database based on [libSQL](https://libsql.org/), an open-source fork of SQLite. Turso was designed to minimize query latency for applications where queries comes from anywhere in the world.

## Set up an integration with Turso

To set up an integration with Turso:

1. You need to install Turso CLI to create and populate a database. Use one of the following two commands in your terminal to install the Turso CLI:

   ```sh
   # On macOS and linux with homebrew
   brew install tursodatabase/tap/turso

   # Manual scripted installation
   curl -sSfL https://get.tur.so/install.sh | bash
   ```

   Next, run the following command to make sure the Turso CLI is installed:

   ```sh
   turso --version
   ```

2. Before you create your first Turso database, you have to authenticate with your GitHub account by running:

   ```sh
   turso auth login
   ```

   ```sh output
   Waiting for authentication...
   ✔  Success! Logged in as <YOUR_GITHUB_USERNAME>
   ```

   After you have authenticated, you can create a database using the command `turso db create <DATABASE_NAME>`. Turso will create a database and automatically choose a location closest to you.

   ```sh
   turso db create my-db
   ```

   ```sh output

   # Example:
   Creating database my-db in Amsterdam, Netherlands (ams)

   # Once succeeded:
   Created database my-db in Amsterdam, Netherlands (ams) in 13 seconds.
   ```

   With the first database created, you can now connect to it directly and execute SQL queries against it.

   ```sh
   turso db shell my-db
   ```

3. Copy the following SQL query into the shell you just opened:

   ```sql
   CREATE TABLE elements (
     id INTEGER NOT NULL,
     elementName TEXT NOT NULL,
     atomicNumber INTEGER NOT NULL,
     symbol TEXT NOT NULL
   );

   INSERT INTO elements (id, elementName, atomicNumber, symbol)
   VALUES (1, 'Hydrogen', 1, 'H'),
     (2, 'Helium', 2, 'He'),
     (3, 'Lithium', 3, 'Li'),
     (4, 'Beryllium', 4, 'Be'),
     (5, 'Boron', 5, 'B'),
     (6, 'Carbon', 6, 'C'),
     (7, 'Nitrogen', 7, 'N'),
     (8, 'Oxygen', 8, 'O'),
     (9, 'Fluorine', 9, 'F'),
     (10, 'Neon', 10, 'Ne');
   ```

4. Configure the Turso database credentials in your Worker:

   You need to add your Turso database URL and authentication token as secrets to your Worker. First, get your database URL and create an authentication token:

   ```sh
   # Get your database URL
   turso db show my-db --url
   
   # Create an authentication token
   turso db tokens create my-db
   ```

   Then add these as secrets to your Worker using Wrangler:

   ```sh
   # Add the database URL as a secret
   npx wrangler secret put TURSO_URL
   # When prompted, paste your database URL
   
   # Add the authentication token as a secret  
   npx wrangler secret put TURSO_AUTH_TOKEN
   # When prompted, paste your authentication token
   ```

5. In your Worker, install the Turso client library:

   <PackageManagers pkg="@libsql/client" />

6. The following example shows how to make a query to your Turso database in a Worker. The credentials needed to connect to Turso have been added as [secrets](/workers/configuration/secrets/) to your Worker.

   ```ts
   import { Client as LibsqlClient, createClient } from "@libsql/client/web";

   export interface Env {
   	TURSO_URL?: string;
   	TURSO_AUTH_TOKEN?: string;
   }

   export default {
   	async fetch(request, env, ctx): Promise<Response> {
   		const client = buildLibsqlClient(env);

   		try {
   			const res = await client.execute("SELECT * FROM elements");
   			return new Response(JSON.stringify(res), {
   				status: 200,
   				headers: { "Content-Type": "application/json" },
   			});
   		} catch (error) {
   			console.error("Error executing SQL query:", error);
   			return new Response(
   				JSON.stringify({ error: "Internal Server Error" }),
   				{
   					status: 500,
   				},
   			);
   		}
   	},
   } satisfies ExportedHandler<Env>;

   function buildLibsqlClient(env: Env): LibsqlClient {
   	const url = env.TURSO_URL?.trim();
   	if (url === undefined) {
   		throw new Error("TURSO_URL env var is not defined");
   	}

   	const authToken = env.TURSO_AUTH_TOKEN?.trim();
   	if (authToken == undefined) {
   		throw new Error("TURSO_AUTH_TOKEN env var is not defined");
   	}

   	return createClient({ url, authToken });
   }
   ```

   - The libSQL client library import `@libsql/client/web` must be imported exactly as shown when working with Cloudflare Workers. The non-web import will not work in the Workers environment.
   - The `Env` interface contains the [environment variable](/workers/configuration/environment-variables/) and [secret](/workers/configuration/secrets/) defined when you added the Turso integration in step 4.
   - The `Env` interface also caches the libSQL client object and router, which was created on the first request to the Worker.
   - The Worker uses `buildLibsqlClient` to query the `elements` database and returns the response as a JSON object.

With your environment configured and your code ready, you can now test your Worker locally before you deploy.

To learn more about Turso, refer to [Turso's official documentation](https://docs.turso.tech).

---

# Supabase

URL: https://developers.cloudflare.com/workers/databases/third-party-integrations/supabase/

import { Render, PackageManagers, Tabs, TabItem } from "~/components";

[Supabase](https://supabase.com/) is an open source Firebase alternative and a PostgreSQL database service that offers real-time functionality, database backups, and extensions. With Supabase, developers can quickly set up a PostgreSQL database and build applications.

:::note

You can connect to Supabase using [Hyperdrive](/hyperdrive) (recommended), or using the Supabase client, `@supabase/supabase-js`. Both provide connection pooling and reduce the amount of round trips required to create a secure connection from Workers to your database.

Hyperdrive can provide lower latencies because it performs the database connection setup and connection pooling across Cloudflare's network. Hyperdrive supports native database drivers, libraries, and ORMs, and is included in all [Workers plans](/hyperdrive/platform/pricing/). Learn more about Hyperdrive in [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/).

:::

<Tabs>
	<TabItem label="Hyperdrive (recommended)">

When connecting to Supabase with Hyperdrive, you connect directly to the underlying Postgres database. This is [recommended by Supabase](https://supabase.com/docs/guides/database/connecting-to-postgres#choosing-a-connection-method) when accessed server-side from Workers.
If you prefer to use the Supabase client, refer to the `Supabase client` tab. To connect to Supabase using [Hyperdrive](/hyperdrive), follow these steps:

         <Render file="supabase-partial" product="hyperdrive"/>
    </TabItem>
    <TabItem label="Supabase client">

### Supabase client setup

To set up an integration with Supabase:

1. You need to have an existing Supabase database to connect to. [Create a Supabase database](https://supabase.com/docs/guides/database/tables#creating-tables) or [have an existing database to connect to Supabase and load data from](https://supabase.com/docs/guides/database/tables#loading-data).

2. Create a `countries` table with the following query. You can create a table in your Supabase dashboard in two ways:

   - Use the table editor, which allows you to set up Postgres similar to a spreadsheet.
   - Alternatively, use the [SQL editor](https://supabase.com/docs/guides/database/overview#the-sql-editor):

   ```sql
   CREATE TABLE countries (
   id SERIAL PRIMARY KEY,
   name VARCHAR(255) NOT NULL
   );
   ```

3. Insert some data in your newly created table. Run the following commands to add countries to your table:

   ```sql
   INSERT INTO countries (name) VALUES ('United States');
   INSERT INTO countries (name) VALUES ('Canada');
   INSERT INTO countries (name) VALUES ('The Netherlands');
   ```

4. Configure the Supabase database credentials in your Worker:

   You need to add your Supabase URL and anon key as secrets to your Worker. Get these from your [Supabase Dashboard](https://supabase.com/dashboard) under **Settings** > **API**, then add them as secrets using Wrangler:

   ```sh
   # Add the Supabase URL as a secret
   npx wrangler secret put SUPABASE_URL
   # When prompted, paste your Supabase project URL

   # Add the Supabase anon key as a secret
   npx wrangler secret put SUPABASE_KEY
   # When prompted, paste your Supabase anon/public key
   ```

5. In your Worker, install the `@supabase/supabase-js` driver to connect to your database and start manipulating data:

   <PackageManagers pkg="@supabase/supabase-js" />

6. The following example shows how to make a query to your Supabase database in a Worker. The credentials needed to connect to Supabase have been added as secrets to your Worker.

   ```js
   import { createClient } from "@supabase/supabase-js";

   export default {
   	async fetch(request, env) {
   		const supabase = createClient(env.SUPABASE_URL, env.SUPABASE_KEY);
   		const { data, error } = await supabase.from("countries").select("*");
   		if (error) throw error;
   		return new Response(JSON.stringify(data), {
   			headers: {
   				"Content-Type": "application/json",
   			},
   		});
   	},
   };
   ```

To learn more about Supabase, refer to [Supabase's official documentation](https://supabase.com/docs).

</TabItem>
</Tabs>

---

# Upstash

URL: https://developers.cloudflare.com/workers/databases/third-party-integrations/upstash/

import { Render, PackageManagers } from "~/components";

[Upstash](https://upstash.com/) is a serverless database with Redis\* and Kafka API. Upstash also offers QStash, a task queue/scheduler designed for the serverless.

## Upstash for Redis

To set up an integration with Upstash:

1. You need an existing Upstash database to connect to. [Create an Upstash database](https://docs.upstash.com/redis#create-a-database) or [load data from an existing database to Upstash](https://docs.upstash.com/redis/howto/connectclient).

2. Insert some data to your Upstash database. You can add data to your Upstash database in two ways:

   - Use the CLI directly from your Upstash console.
   - Alternatively, install [redis-cli](https://redis.io/docs/getting-started/installation/) locally and run the following commands.

   ```sh
   set GB "Ey up?"
   ```

   ```sh output
   OK
   ```

   ```sh
   set US "Yo, what’s up?"
   ```

   ```sh output
   OK
   ```

   ```sh
   set NL "Hoi, hoe gaat het?"
   ```

   ```sh output
   OK
   ```

3. Configure the Upstash Redis credentials in your Worker:

   You need to add your Upstash Redis database URL and token as secrets to your Worker. Get these from your [Upstash Console](https://console.upstash.com) under your database details, then add them as secrets using Wrangler:

   ```sh
   # Add the Upstash Redis URL as a secret
   npx wrangler secret put UPSTASH_REDIS_REST_URL
   # When prompted, paste your Upstash Redis REST URL
   
   # Add the Upstash Redis token as a secret
   npx wrangler secret put UPSTASH_REDIS_REST_TOKEN
   # When prompted, paste your Upstash Redis REST token
   ```

4. In your Worker, install the `@upstash/redis`, a HTTP client to connect to your database and start manipulating data:

   <PackageManagers pkg="@upstash/redis" />

5. The following example shows how to make a query to your Upstash database in a Worker. The credentials needed to connect to Upstash have been added as secrets to your Worker.

   ```js
   import { Redis } from "@upstash/redis/cloudflare";

   export default {
   	async fetch(request, env) {
   		const redis = Redis.fromEnv(env);

   		const country = request.headers.get("cf-ipcountry");
   		if (country) {
   			const greeting = await redis.get(country);
   			if (greeting) {
   				return new Response(greeting);
   			}
   		}

   		return new Response("Hello What's up!");
   	},
   };
   ```

   :::note

   `Redis.fromEnv(env)` automatically picks up the default `url` and `token` names created in the integration.

   If you have renamed the secrets, you must declare them explicitly like in the [Upstash basic example](https://docs.upstash.com/redis/sdks/redis-ts/getstarted#basic-usage).

   :::

To learn more about Upstash, refer to the [Upstash documentation](https://docs.upstash.com/redis).

## Upstash Kafka

To set up an integration with Upstash Kafka:

1. Create a [Kafka cluster and topic](https://docs.upstash.com/kafka).

2. Configure the Upstash Kafka credentials in your Worker:

   You need to add your Upstash Kafka connection details as secrets to your Worker. Get these from your [Upstash Console](https://console.upstash.com) under your Kafka cluster details, then add them as secrets using Wrangler:

   ```sh
   # Add the Upstash Kafka URL as a secret
   npx wrangler secret put UPSTASH_KAFKA_REST_URL
   # When prompted, paste your Upstash Kafka REST URL
   
   # Add the Upstash Kafka username as a secret
   npx wrangler secret put UPSTASH_KAFKA_REST_USERNAME
   # When prompted, paste your Upstash Kafka username
   
   # Add the Upstash Kafka password as a secret
   npx wrangler secret put UPSTASH_KAFKA_REST_PASSWORD
   # When prompted, paste your Upstash Kafka password
   ```

3. In your Worker, install `@upstash/kafka`, a HTTP/REST based Kafka client:

   <PackageManagers pkg="@upstash/kafka" />

4. Use the [upstash-kafka](https://github.com/upstash/upstash-kafka/blob/main/README.md) JavaScript SDK to send data to Kafka.

Refer to [Upstash documentation on Kafka setup with Workers](https://docs.upstash.com/kafka/real-time-analytics/realtime_analytics_serverless_kafka_setup#option-1-cloudflare-workers) for more information. Replace `url`, `username` and `password` with the variables set by the integration.

## Upstash QStash

To set up an integration with Upstash QStash:

1. Configure the [publicly available HTTP endpoint](https://docs.upstash.com/qstash#1-public-api) that you want to send your messages to.

2. Configure the Upstash QStash credentials in your Worker:

   You need to add your Upstash QStash token as a secret to your Worker. Get your token from your [Upstash Console](https://console.upstash.com) under QStash settings, then add it as a secret using Wrangler:

   ```sh
   # Add the QStash token as a secret
   npx wrangler secret put QSTASH_TOKEN
   # When prompted, paste your QStash token
   ```

3. In your Worker, install the `@upstash/qstash`, a HTTP client to connect to your database QStash endpoint:

   <PackageManagers pkg="@upstash/qstash" />

4. Refer to the [Upstash documentation on how to receive webhooks from QStash in your Cloudflare Worker](https://docs.upstash.com/qstash/quickstarts/cloudflare-workers#3-use-qstash-in-your-handler).

\* Redis is a trademark of Redis Ltd. Any rights therein are reserved to Redis Ltd. Any use by Upstash is for referential purposes only and does not indicate any sponsorship, endorsement or affiliation between Redis and Upstash.

---

# Xata

URL: https://developers.cloudflare.com/workers/databases/third-party-integrations/xata/

import { Render, TabItem, Tabs } from "~/components";

[Xata](https://xata.io) is a serverless data platform powered by PostgreSQL. Xata uniquely combines multiple types of stores (relational databases, search engines, analytics engines) into a single service, accessible through a consistent REST API.

:::note

You can connect to Xata using [Hyperdrive](/hyperdrive) (recommended), or using the Xata client, `@xata.io/client`. Both provide connection pooling and reduce the amount of round trips required to create a secure connection from Workers to your database.

Hyperdrive can provide lower latencies because it performs the database connection setup and connection pooling across Cloudflare's network. Hyperdrive supports native database drivers, libraries, and ORMs, and is included in all [Workers plans](/hyperdrive/platform/pricing/). Learn more about Hyperdrive in [How Hyperdrive Works](/hyperdrive/configuration/how-hyperdrive-works/).

:::

<Tabs>
	<TabItem label="Hyperdrive (recommended)">

To connect to Xata using [Hyperdrive](/hyperdrive), follow these steps:

         <Render file="xata-partial" product="hyperdrive"/>
    </TabItem>
    <TabItem label="Supabase client">

## Set up an integration with Xata

To set up an integration with Xata:

1. You need to have an existing Xata database to connect to or create a new database from your Xata workspace [Create a Database](https://app.xata.io/workspaces).

2. In your database, you have several options for creating a table: you can start from scratch, use a template filled with sample data, or import data from a CSV file. For this guide, choose **Start with sample data**. This option automatically populates your database with two sample tables: `Posts` and `Users`.

3. Configure the Xata database credentials in your Worker:

   You need to add your Xata database credentials as secrets to your Worker. First, get your database details from your [Xata Dashboard](https://app.xata.io), then add them as secrets using Wrangler:

   ```sh
   # Add the Xata API key as a secret
   npx wrangler secret put XATA_API_KEY
   # When prompted, paste your Xata API key

   # Add the Xata branch as a secret
   npx wrangler secret put XATA_BRANCH
   # When prompted, paste your Xata branch name (usually 'main')

   # Add the Xata database URL as a secret
   npx wrangler secret put XATA_DATABASE_URL
   # When prompted, paste your Xata database URL
   ```

4. Install the [Xata CLI](https://xata.io/docs/getting-started/installation) and authenticate the CLI by running the following commands:

   ```sh
   npm install -g @xata.io/cli

   xata auth login
   ```

5. Once you have the CLI set up, In your Worker, run the following code in the root directory of your project:

   ```sh
   xata init
   ```

   Accept the default settings during the configuration process. After completion, a `.env` and `.xatarc` file will be generated in your project folder.

6. To enable Cloudflare access the secret values generated when running in development mode, create a `.dev.vars` file in your project's root directory and add the following content, replacing placeholders with the specific values:

   ```txt
   XATA_API_KEY=<YOUR_API_KEY_HERE>
   XATA_BRANCH=<YOUR_BRANCH_HERE>
   XATA_DATABASE_URL=<YOUR_DATABASE_URL_HERE>
   ```

7. The following example shows how to make a query to your Xata database in a Worker. The credentials needed to connect to Xata have been added as secrets to your Worker.

   ```ts
   export default {
   	async fetch(request, env, ctx): Promise<Response> {
   		const xata = new XataClient({
   			apiKey: env.XATA_API_KEY,
   			branch: env.XATA_BRANCH,
   			databaseURL: env.XATA_DATABASE_URL,
   		});

   		const records = await xata.db.Posts.select([
   			"id",
   			"title",
   			"author.name",
   			"author.email",
   			"author.bio",
   		]).getAll();

   		return Response.json(records);
   	},
   } satisfies ExportedHandler<Env>;
   ```

To learn more about Xata, refer to [Xata's official documentation](https://xata.io/docs).

</TabItem>
</Tabs>

---

# JavaScript

URL: https://developers.cloudflare.com/workers/languages/javascript/

The Workers platform is designed to be [JavaScript standards compliant](https://ecma-international.org/publications-and-standards/standards/ecma-262/) and web-interoperable, and supports JavaScript standards, as defined by [TC39](https://tc39.es/) (ECMAScript). Wherever possible, it uses web platform APIs, so that code can be reused across client and server, as well as across [WinterCG](https://wintercg.org/) JavaScript runtimes.

Refer to [Runtime APIs](/workers/runtime-apis/) for more information on specific JavaScript APIs available in Workers.

### Resources

* [Getting Started](/workers/get-started/guide/)
* [Quickstarts](/workers/get-started/quickstarts/) – More example repos to use as a basis for your projects
* [TypeScript type definitions](https://github.com/cloudflare/workers-types)
* [JavaScript and web standard APIs](/workers/runtime-apis/web-standards/)
* [Tutorials](/workers/tutorials/)
* [Examples](/workers/examples/?languages=JavaScript)

---

# Examples

URL: https://developers.cloudflare.com/workers/languages/python/examples/

Cloudflare has a wide range of Python examples in the [Workers Example gallery](/workers/examples/?languages=Python).

In addition to those examples, consider the following ones that illustrate Python-specific behavior.

## Parse an incoming request URL

```python
from workers import Response
from urllib.parse import urlparse, parse_qs

async def on_fetch(request, env):
    # Parse the incoming request URL
    url = urlparse(request.url)
    # Parse the query parameters into a Python dictionary
    params = parse_qs(url.query)

    if "name" in params:
        greeting = "Hello there, {name}".format(name=params["name"][0])
        return Response(greeting)


    if url.path == "/favicon.ico":
      return Response("")

    return Response("Hello world!")
```

## Parse JSON from the incoming request

```python
from workers import Response

async def on_fetch(request):
    name = (await request.json()).name
    return Response("Hello, {name}".format(name=name))
```

## Emit logs from your Python Worker

```python
# To use the JavaScript console APIs
from js import console
from workers import Response
# To use the native Python logging
import logging

async def on_fetch(request):
    # Use the console APIs from JavaScript
    # https://developer.mozilla.org/en-US/docs/Web/API/console
    console.log("console.log from Python!")

    # Alternatively, use the native Python logger
    logger = logging.getLogger(__name__)

    # The default level is warning. We can change that to info.
    logging.basicConfig(level=logging.INFO)

    logger.error("error from Python!")
    logger.info("info log from Python!")

    # Or just use print()
    print("print() from Python!")

    return Response("We're testing logging!")
```

## Publish to a Queue

```python
from js import Object
from pyodide.ffi import to_js as _to_js

from workers import Response

# to_js converts between Python dictionaries and JavaScript Objects
def to_js(obj):
   return _to_js(obj, dict_converter=Object.fromEntries)

async def on_fetch(request, env):
    # Bindings are available on the 'env' parameter
    # https://developers.cloudflare.com/queues/

    # The default contentType is "json"
    # We can also pass plain text strings
    await env.QUEUE.send("hello", contentType="text")
    # Send a JSON payload
    await env.QUEUE.send(to_js({"hello": "world"}))

    # Return a response
    return Response.json({"write": "success"})
```

## Query a D1 Database

```python
from workers import Response

async def on_fetch(request, env):
    results = await env.DB.prepare("PRAGMA table_list").all()
    # Return a JSON response
    return Response.json(results)
```

Refer to [Query D1 from Python Workers](/d1/examples/query-d1-from-python-workers/) for a more in-depth tutorial that covers how to create a new D1 database and configure bindings to D1.

## Next steps

* If you're new to Workers and Python, refer to the [get started](/workers/languages/python/) guide
* Learn more about [calling JavaScript methods and accessing JavaScript objects](/workers/languages/python/ffi/) from Python
* Understand the [supported packages and versions](/workers/languages/python/packages/) currently available to Python Workers.

---

# Foreign Function Interface (FFI)

URL: https://developers.cloudflare.com/workers/languages/python/ffi/

import { WranglerConfig } from "~/components";

Via [Pyodide](https://pyodide.org/en/stable/), Python Workers provide a [Foreign Function Interface (FFI)](https://en.wikipedia.org/wiki/Foreign_function_interface) to JavaScript. This allows you to:

* Use [bindings](/workers/runtime-apis/bindings/) to resources on Cloudflare, including [Workers AI](/workers-ai/), [Vectorize](/vectorize/), [R2](/r2/), [KV](/kv/), [D1](/d1/), [Queues](/queues/), [Durable Objects](/durable-objects/), [Service Bindings](/workers/runtime-apis/bindings/service-bindings/) and more.
* Use JavaScript globals, like [`Request`](/workers/runtime-apis/request/), [`Response`](/workers/runtime-apis/response/), and [`fetch()`](/workers/runtime-apis/fetch/).
* Use the full feature set of Cloudflare Workers — if an API is accessible in JavaScript, you can also access it in a Python Worker, writing exclusively Python code.

The details of Pyodide's Foreign Function Interface are documented [here](https://pyodide.org/en/stable/usage/type-conversions.html), and Workers written in Python are able to take full advantage of this.

## Using Bindings from Python Workers

Bindings allow your Worker to interact with resources on the Cloudflare Developer Platform. When you declare a binding on your Worker, you grant it a specific capability, such as being able to read and write files to an [R2](/r2/) bucket.

For example, to access a [KV](/kv) namespace from a Python Worker, you would declare the following in your Worker's [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
main = "./src/index.py"
kv_namespaces = [
  { binding = "FOO", id = "<YOUR_KV_NAMESPACE_ID>" }
]
```

</WranglerConfig>

...and then call `.get()` on the binding object that is exposed on `env`:

```python
from workers import Response

async def on_fetch(request, env):
    await env.FOO.put("bar", "baz")
    bar = await env.FOO.get("bar")
    return Response(bar) # returns "baz"
```

Under the hood, `env` is actually a JavaScript object. When you call `.FOO`, you are accessing this property via a [`JsProxy`](https://pyodide.org/en/stable/usage/api/python-api/ffi.html#pyodide.ffi.JsProxy) — special proxy object that makes a JavaScript object behave like a Python object.

## Using JavaScript globals from Python Workers

When writing Workers in Python, you can access JavaScript globals by importing them from the `js` module. For example, note how `Response` is imported from `js` in the example below:

```python
from js import Response

def on_fetch(request):
    return Response.new("Hello World!")
```

Refer to the [Python examples](/workers/languages/python/examples/) to learn how to call into JavaScript functions from Python, including `console.log` and logging, providing options to `Response`, and parsing JSON.

---

# How Python Workers Work

URL: https://developers.cloudflare.com/workers/languages/python/how-python-workers-work/

import { Render, WranglerConfig } from "~/components"

Workers written in Python are executed by [Pyodide](https://pyodide.org/en/stable/index.html). Pyodide is a port of [CPython](https://github.com/python) (the reference implementation of Python — commonly referred to as just "Python") to WebAssembly.

When you write a Python Worker, your code is interpreted directly by Pyodide, within a V8 isolate. Refer to [How Workers works](/workers/reference/how-workers-works/) to learn more.

## Local Development Lifecycle

```python
from workers import Response

async def on_fetch(request, env):
    return Response("Hello world!")
```

…with a [Wrangler configuration file](/workers/wrangler/configuration/) that points to a .py file:

<WranglerConfig>

```toml
name = "hello-world-python-worker"
main = "src/entry.py"
compatibility_date = "2024-04-01"
```

</WranglerConfig>

When you run `npx wrangler@latest dev` in local dev, the Workers runtime will:

1. Determine which version of Pyodide is required, based on your compatibility date
2. Create a new v8 isolate for your Worker, and automatically inject Pyodide
3. Serve your Python code using Pyodide

There no extra toolchain or precompilation steps needed. The Python execution environment is provided directly by the Workers runtime, mirroring how Workers written in JavaScript work.

Refer to the [Python examples](/workers/languages/python/examples/) to learn how to use Python within Workers.

## Deployment Lifecycle

To reduce cold start times, when you deploy a Python Worker, Cloudflare performs as much of the expensive work as possible upfront, at deploy time. When you run npx `wrangler@latest deploy`, the following happens:

1. Wrangler uploads your Python code and your `requirements.txt` file to the Workers API.
2. Cloudflare sends your Python code, and your `requirements.txt` file to the Workers runtime to be validated.
3. Cloudflare creates a new v8 isolate for your Worker, and automatically injects Pyodide plus any packages you’ve specified in your `requirements.txt` file.
4. Cloudflare scans the Worker’s code for import statements, execute them, and then take a snapshot of the Worker’s WebAssembly linear memory. Effectively, we perform the expensive work of importing packages at deploy time, rather than at runtime.
5. Cloudflare deploys this snapshot alongside your Worker’s Python code to the Cloudflare network.

<Render file="python-workers-beta-packages" product="workers" />

When a request comes in to your Worker, we load this snapshot and use it to bootstrap your Worker in an isolate, avoiding expensive initialization time:

![Diagram of how Python Workers are deployed to Cloudflare](~/assets/images/workers/languages/python/python-workers-deployment.png)

Refer to the [blog post introducing Python Workers](https://blog.cloudflare.com/python-workers) for more detail about performance optimizations and how the Workers runtime will reduce cold starts for Python Workers.

## Pyodide and Python versions

A new version of Python is released every year in August, and a new version of Pyodide is released six (6) months later. When this new version of Pyodide is published, we will add it to Workers by gating it behind a Compatibility Flag, which is only enabled after a specified Compatibility Date. This lets us continually provide updates, without risk of breaking changes, extending the commitment we’ve made for JavaScript to Python.

Each Python release has a [five (5) year support window](https://devguide.python.org/versions/). Once this support window has passed for a given version of Python, security patches are no longer applied, making this version unsafe to rely on. To mitigate this risk, while still trying to hold as true as possible to our commitment of stability and long-term support, after five years any Python Worker still on a Python release that is outside of the support window will be automatically moved forward to the next oldest Python release. Python is a mature and stable language, so we expect that in most cases, your Python Worker will continue running without issue. But we recommend updating the compatibility date of your Worker regularly, to stay within the support window.

---

# Python

URL: https://developers.cloudflare.com/workers/languages/python/

import { WranglerConfig } from "~/components";

Cloudflare Workers provides first-class support for Python, including support for:

- The majority of Python's [Standard library](/workers/languages/python/stdlib/)
- All [bindings](/workers/runtime-apis/bindings/), including [Workers AI](/workers-ai/), [Vectorize](/vectorize), [R2](/r2), [KV](/kv), [D1](/d1), [Queues](/queues/), [Durable Objects](/durable-objects/), [Service Bindings](/workers/runtime-apis/bindings/service-bindings/) and more.
- [Environment Variables](/workers/configuration/environment-variables/), and [Secrets](/workers/configuration/secrets/)
- A robust [foreign function interface (FFI)](/workers/languages/python/ffi) that lets you use JavaScript objects and functions directly from Python — including all [Runtime APIs](/workers/runtime-apis/)
- [Built-in packages](/workers/languages/python/packages), including [FastAPI](https://fastapi.tiangolo.com/), [Langchain](https://pypi.org/project/langchain/), [httpx](https://www.python-httpx.org/) and more.

:::caution[Python Workers are in beta. Packages do not run in production.]

Currently, you can only deploy Python Workers that use the standard library. [Packages](/workers/languages/python/packages/#supported-packages) **cannot be deployed** and will only work in local development for the time being.

You must add the `python_workers` compatibility flag to your Worker, while Python Workers are in open beta.

We'd love your feedback. Join the #python-workers channel in the [Cloudflare Developers Discord](https://discord.cloudflare.com/) and let us know what you'd like to see next.
:::

## Get started

```bash
git clone https://github.com/cloudflare/python-workers-examples
cd python-workers-examples/01-hello
npx wrangler@latest dev
```

A Python Worker can be as simple as three lines of code:

```python
from workers import Response

def on_fetch(request):
    return Response("Hello World!")
```

Similar to Workers written in [JavaScript](/workers/languages/javascript), [TypeScript](/workers/languages/typescript), or [Rust](/workers/languages/rust/), the main entry point for a Python worker is the [`fetch` handler](/workers/runtime-apis/handlers/fetch). In a Python Worker, this handler is named `on_fetch`.

To run a Python Worker locally, you use [Wrangler](/workers/wrangler/), the CLI for Cloudflare Workers:

```bash
npx wrangler@latest dev
```

To deploy a Python Worker to Cloudflare, run [`wrangler deploy`](/workers/wrangler/commands/#deploy):

```bash
npx wrangler@latest deploy
```

## Modules

Python workers can be split across multiple files. Let's create a new Python file, called `src/hello.py`:

```python
def hello(name):
    return "Hello, " + name + "!"
```

Now, we can modify `src/entry.py` to make use of the new module.

```python
from hello import hello
from workers import Response

def on_fetch(request):
    return Response(hello("World"))
```

Once you edit `src/entry.py`, Wrangler will automatically detect the change and
reload your Worker.

## The `Request` Interface

The `request` parameter passed to your `fetch` handler is a JavaScript Request object, exposed via the foreign function interface, allowing you to access it directly from your Python code.

Let's try editing the worker to accept a POST request. We know from the
[documentation for `Request`](/workers/runtime-apis/request) that we can call
`await request.json()` within an `async` function to parse the request body as
JSON. In a Python Worker, you would write:

```python
from workers import Response
from hello import hello

async def on_fetch(request):
    name = (await request.json()).name
    return Response(hello(name))
```

Once you edit the `src/entry.py`, Wrangler should automatically restart the local
development server. Now, if you send a POST request with the appropriate body,
your Worker should respond with a personalized message.

```bash
curl --header "Content-Type: application/json" \
  --request POST \
  --data '{"name": "Python"}' http://localhost:8787
```

```bash output
Hello, Python!
```

## The `env` Parameter

In addition to the `request` parameter, the `env` parameter is also passed to
the Python `fetch` handler and can be used to access
[environment variables](/workers/configuration/environment-variables/),
[secrets](/workers/configuration/secrets/),and
[bindings](/workers/runtime-apis/bindings/).

For example, let us try setting and using an environment variable in a Python Worker. First, add the environment variable to your Worker's [Wrangler configuration file](/workers/wrangler/configuration/):

<WranglerConfig>

```toml
name = "hello-python-worker"
main = "src/entry.py"
compatibility_flags = ["python_workers"]
compatibility_date = "2024-03-20"

[vars]
API_HOST = "example.com"
```

</WranglerConfig>

Then, you can access the `API_HOST` environment variable via the `env` parameter:

```python
from workers import Response

async def on_fetch(request, env):
    return Response(env.API_HOST)
```

## Further Reading

- Understand which parts of the [Python Standard Library](/workers/languages/python/stdlib) are supported in Python Workers.
- Learn about Python Workers' [foreign function interface (FFI)](/workers/languages/python/ffi), and how to use it to work with [bindings](/workers/runtime-apis/bindings) and [Runtime APIs](/workers/runtime-apis/).
- Explore the [Built-in Python packages](/workers/languages/python/packages) that the Workers runtime provides.

---

# Standard Library

URL: https://developers.cloudflare.com/workers/languages/python/stdlib/

Workers written in Python are executed by [Pyodide](https://pyodide.org/en/stable/index.html).

Pyodide is a port of CPython to WebAssembly — for the most part it behaves identically to [CPython](https://github.com/python) (the reference implementation of Python — commonly referred to as just "Python"). The majority of the CPython test suite passes when run against Pyodide. For the most part, you shouldn't need to worry about differences in behavior.

The full [Python Standard Library](https://docs.python.org/3/library/index.html) is available in Python Workers, with the following exceptions:

## Modules with limited functionality

* `hashlib`: Hash algorithms that depend on OpenSSL are not available by default.
* `decimal`: The decimal module has C (\_decimal) and Python (\_pydecimal) implementations
  with the same functionality. Only the C implementation is available (compiled to WebAssembly)
* `pydoc`: Help messages for Python builtins are not available
* `webbrowser`: The original webbrowser module is not available.

## Excluded modules

The following modules are not available in Python Workers:

* curses
* dbm
* ensurepip
* fcntl
* grp
* idlelib
* lib2to3
* msvcrt
* pwd
* resource
* syslog
* termios
* tkinter
* turtle.py
* turtledemo
* venv
* winreg
* winsound

The following modules can be imported, but are not functional due to the limitations of the WebAssembly VM.

* multiprocessing
* threading
* sockets

The following are present but cannot be imported due to a dependency on the termios package which has been removed:

* pty
* tty

---

# Supported crates

URL: https://developers.cloudflare.com/workers/languages/rust/crates/

## Background

Learn about popular Rust crates which have been confirmed to work on Workers when using [`workers-rs`](https://github.com/cloudflare/workers-rs) (or in some cases just `wasm-bindgen`), to write Workers in WebAssembly.
Each Rust crate example includes any custom configuration that is required.

This is not an exhaustive list, many Rust crates can be compiled to the [`wasm32-unknown-unknown`](https://doc.rust-lang.org/rustc/platform-support/wasm64-unknown-unknown.html) target that is supported by Workers.
In some cases, this may require disabling default features or enabling a Wasm-specific feature. It is important to consider the addition of new dependencies, as this can significantly increase the [size](/workers/platform/limits/#worker-size) of your Worker.

## `time`

Many crates which have been made Wasm-friendly, will use the `time` crate instead of `std::time`. For the `time` crate to work in Wasm, the `wasm-bindgen` feature must be enabled to obtain timing information from JavaScript.

## `tracing`

Tracing can be enabled by using the `tracing-web` crate and the `time` feature for `tracing-subscriber`.
Due to [timing limitations](/workers/reference/security-model/#step-1-disallow-timers-and-multi-threading) on Workers, spans will have identical start and end times unless they encompass I/O.

[Refer to the `tracing` example](https://github.com/cloudflare/workers-rs/tree/main/examples/tracing) for more information.

## `reqwest`

The [`reqwest` library](https://docs.rs/reqwest/latest/reqwest/) can be compiled to Wasm, and hooks into the JavaScript `fetch` API automatically using `wasm-bindgen`.

## `tokio-postgres`

`tokio-postgres` can be compiled to Wasm. It must be configured to use a `Socket` from `workers-rs`:

[Refer to the `tokio-postgres` example](https://github.com/cloudflare/workers-rs/tree/main/examples/tokio-postgres) for more information.

## `hyper`

The `hyper` crate contains two HTTP clients, the lower-level `conn` module and the higher-level `Client`.
The `conn` module can be used with Workers `Socket`, however `Client` requires timing dependencies which are
not yet Wasm friendly.

[Refer to the `hyper` example](https://github.com/cloudflare/workers-rs/tree/main/examples/hyper) for more information.

---

# Rust

URL: https://developers.cloudflare.com/workers/languages/rust/

import { WranglerConfig } from "~/components";

Cloudflare Workers provides support for Rust via the [`workers-rs` crate](https://github.com/cloudflare/workers-rs), which makes [Runtime APIs](/workers/runtime-apis) and [bindings](/workers/runtime-apis/bindings/) to developer platform products, such as [Workers KV](/kv/concepts/how-kv-works/), [R2](/r2/), and [Queues](/queues/), available directly from your Rust code.

By following this guide, you will learn how to build a Worker entirely in the Rust programming language.

## Prerequisites

Before starting this guide, make sure you have:

- A recent version of [`Rust`](https://rustup.rs/)
- [`npm`](https://docs.npmjs.com/getting-started)
- The Rust `wasm32-unknown-unknown` toolchain:

```sh
rustup target add wasm32-unknown-unknown
```

- And `cargo-generate` sub-command by running:

```sh
cargo install cargo-generate
```

## 1. Create a new project with Wrangler

Open a terminal window, and run the following command to generate a Worker project template in Rust:

```sh
cargo generate cloudflare/workers-rs
```

Your project will be created in a new directory that you named, in which you will find the following files and folders:

- `Cargo.toml` - The standard project configuration file for Rust's [`Cargo`](https://doc.rust-lang.org/cargo/) package manager. The template pre-populates some best-practice settings for building for Wasm on Workers.
- `wrangler.toml` - Wrangler configuration, pre-populated with a custom build command to invoke `worker-build` (Refer to [Wrangler Bundling](/workers/languages/rust/#bundling-worker-build)).
- `src` - Rust source directory, pre-populated with Hello World Worker.

## 2. Develop locally

After you have created your first Worker, run the [`wrangler dev`](/workers/wrangler/commands/#dev) command to start a local server for developing your Worker. This will allow you to test your Worker in development.

```sh
npx wrangler dev
```

If you have not used Wrangler before, it will try to open your web browser to login with your Cloudflare account.

:::note
If you have issues with this step or you do not have access to a browser interface, refer to the [`wrangler login`](/workers/wrangler/commands/#login) documentation for more information.
:::

Go to [http://localhost:8787](http://localhost:8787) to review your Worker running. Any changes you make to your code will trigger a rebuild, and reloading the page will show you the up-to-date output of your Worker.

## 3. Write your Worker code

With your new project generated, write your Worker code. Find the entrypoint to your Worker in `src/lib.rs`:

```rust
use worker::*;

#[event(fetch)]
async fn main(req: Request, env: Env, ctx: Context) -> Result<Response> {
    Response::ok("Hello, World!")
}
```

:::note

There is some counterintuitive behavior going on here:

1. `workers-rs` provides an `event` macro which expects a handler function signature identical to those seen in JavaScript Workers.
2. `async` is not generally supported by Wasm, but you are able to use `async` in a `workers-rs` project (refer to [`async`](/workers/languages/rust/#async-wasm-bindgen-futures)).
   :::

### Related runtime APIs

`workers-rs` provides a runtime API which closely matches Worker's JavaScript API, and enables integration with Worker's platform features. For detailed documentation of the API, refer to [`docs.rs/worker`](https://docs.rs/worker/latest/worker/).

#### `event` macro

This macro allows you to define entrypoints to your Worker. The `event` macro supports the following events:

- `fetch` - Invoked by an incoming HTTP request.
- `scheduled` - Invoked by [`Cron Triggers`](/workers/configuration/cron-triggers/).
- `queue` - Invoked by incoming message batches from [Queues](/queues/) (Requires `queue` feature in `Cargo.toml`, refer to the [`workers-rs` GitHub repository and `queues` feature flag](https://github.com/cloudflare/workers-rs#queues)).
- `start` - Invoked when the Worker is first launched (such as, to install panic hooks).

#### `fetch` parameters

The `fetch` handler provides three arguments which match the JavaScript API:

1. **[`Request`](https://docs.rs/worker/latest/worker/struct.Request.html)**

An object representing the incoming request. This includes methods for accessing headers, method, path, Cloudflare properties, and body (with support for asynchronous streaming and JSON deserialization with [Serde](https://serde.rs/)).

2. **[`Env`](https://docs.rs/worker/latest/worker/struct.Env.html)**

Provides access to Worker [bindings](/workers/runtime-apis/bindings/).

- [`Secret`](https://github.com/cloudflare/workers-rs/blob/e15f88110d814c2d7759b2368df688433f807694/worker/src/env.rs#L92) - Secret value configured in Cloudflare dashboard or using `wrangler secret put`.
- [`Var`](https://github.com/cloudflare/workers-rs/blob/e15f88110d814c2d7759b2368df688433f807694/worker/src/env.rs#L92) - Environment variable defined in `wrangler.toml`.
- [`KvStore`](https://docs.rs/worker-kv/latest/worker_kv/struct.KvStore.html) - Workers [KV](/kv/api/) namespace binding.
- [`ObjectNamespace`](https://docs.rs/worker/latest/worker/durable/struct.ObjectNamespace.html) - [Durable Object](/durable-objects/) binding.
- [`Fetcher`](https://docs.rs/worker/latest/worker/struct.Fetcher.html) - [Service binding](/workers/runtime-apis/bindings/service-bindings/) to another Worker.
- [`Bucket`](https://docs.rs/worker/latest/worker/struct.Bucket.html) - [R2](/r2/) Bucket binding.

3. **[`Context`](https://docs.rs/worker/latest/worker/struct.Context.html)**

Provides access to [`waitUntil`](/workers/runtime-apis/context/#waituntil) (deferred asynchronous tasks) and [`passThroughOnException`](/workers/runtime-apis/context/#passthroughonexception) (fail open) functionality.

#### [`Response`](https://docs.rs/worker/latest/worker/struct.Response.html)

The `fetch` handler expects a [`Response`](https://docs.rs/worker/latest/worker/struct.Response.html) return type, which includes support for streaming responses to the client asynchronously. This is also the return type of any subrequests made from your Worker. There are methods for accessing status code and headers, as well as streaming the body asynchronously or deserializing from JSON using [Serde](https://serde.rs/).

#### `Router`

Implements convenient [routing API](https://docs.rs/worker/latest/worker/struct.Router.html) to serve multiple paths from one Worker. Refer to the [`Router` example in the `worker-rs` GitHub repository](https://github.com/cloudflare/workers-rs#or-use-the-router).

## 4. Deploy your Worker project

With your project configured, you can now deploy your Worker, to a `*.workers.dev` subdomain, or a [Custom Domain](/workers/configuration/routing/custom-domains/), if you have one configured. If you have not configured any subdomain or domain, Wrangler will prompt you during the deployment process to set one up.

```sh
npx wrangler deploy
```

Preview your Worker at `<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev`.

:::note

When pushing to your `*.workers.dev` subdomain for the first time, you may see [`523` errors](/support/troubleshooting/http-status-codes/cloudflare-5xx-errors/error-523/) while DNS is propagating. These errors should resolve themselves after a minute or so.

:::

After completing these steps, you will have a basic Rust-based Worker deployed. From here, you can add crate
dependencies and write code in Rust to implement your Worker application. If you would like to know more about the inner workings of how Rust compiled to Wasm is supported by Workers, the next section outlines the libraries and tools involved.

## How this deployment works

Wasm Workers are invoked from a JavaScript entrypoint script which is created automatically for you when using `workers-rs`.

### JavaScript Plumbing (`wasm-bindgen`)

To access platform features such as bindings, Wasm Workers must be able to access methods from the JavaScript runtime API.

This interoperability is achieved using [`wasm-bindgen`](https://rustwasm.github.io/wasm-bindgen/), which provides the glue code needed to import runtime APIs to, and export event handlers from, the Wasm module. `wasm-bindgen` also provides [`js-sys`](https://docs.rs/js-sys/latest/js_sys/), which implements types for interacting with JavaScript objects. In practice, this is an implementation detail, as `workers-rs`'s API handles conversion to and from JavaScript objects, and interaction with imported JavaScript runtime APIs for you.

:::note

If you are using `wasm-bindgen` without `workers-rs` / `worker-build`, then you will need to patch the JavaScript that it emits. This is because when you import a `wasm` file in Workers, you get a `WebAssembly.Module` instead of a `WebAssembly.Instance` for performance and security reasons.

To patch the JavaScript that `wasm-bindgen` emits:

1. Run `wasm-pack build --target bundler` as you normally would.
2. Patch the JavaScript file that it produces (the following code block assumes the file is called `mywasmlib.js`):

```js
import * as imports from "./mywasmlib_bg.js";

// switch between both syntax for node and for workerd
import wkmod from "./mywasmlib_bg.wasm";
import * as nodemod from "./mywasmlib_bg.wasm";
if (typeof process !== "undefined" && process.release.name === "node") {
	imports.__wbg_set_wasm(nodemod);
} else {
	const instance = new WebAssembly.Instance(wkmod, {
		"./mywasmlib_bg.js": imports,
	});
	imports.__wbg_set_wasm(instance.exports);
}

export * from "./mywasmlib_bg.js";
```

3. In your Worker entrypoint, import the function and use it directly:

```js
import { myFunction } from "path/to/mylib.js";
```

:::

### Async (`wasm-bindgen-futures`)

[`wasm-bindgen-futures`](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen_futures/) (part of the `wasm-bindgen` project) provides interoperability between Rust
Futures and JavaScript Promises. `workers-rs` invokes the entire event handler function using `spawn_local`, meaning that you can program using async Rust, which is turned
into a single JavaScript Promise and run on the JavaScript event loop. Calls to imported JavaScript runtime APIs are automatically converted to Rust Futures that can be invoked from async Rust functions.

### Bundling (`worker-build`)

To run the resulting Wasm binary on Workers, `workers-rs` includes a build tool called [`worker-build`](https://github.com/cloudflare/workers-rs/tree/main/worker-build) which:

1. Creates a JavaScript entrypoint script that properly invokes the module using `wasm-bindgen`'s JavaScript API.
2. Invokes `web-pack` to minify and bundle the JavaScript code.
3. Outputs a directory structure that Wrangler can use to bundle and deploy the final Worker.

`worker-build` is invoked by default in the template project using a custom build command specified in the `wrangler.toml` file.

### Binary Size (`wasm-opt`)

Unoptimized Rust Wasm binaries can be large and may exceed Worker bundle size limits or experience long startup times. The template project pre-configures several useful size optimizations in your `Cargo.toml` file:

```toml
[profile.release]
lto = true
strip = true
codegen-units = 1
```

Finally, `worker-bundle` automatically invokes [`wasm-opt`](https://github.com/brson/wasm-opt-rs) to further optimize binary size before upload.

## Related resources

- [Rust Wasm Book](https://rustwasm.github.io/docs/book/)

---

# TypeScript

URL: https://developers.cloudflare.com/workers/languages/typescript/

import { TabItem, Tabs, PackageManagers, Render } from "~/components";

TypeScript is a first-class language on Cloudflare Workers. All APIs provided in Workers are fully typed, and type definitions are generated directly from [workerd](https://github.com/cloudflare/workerd), the open-source Workers runtime.

We recommend you generate types for your Worker by running [`wrangler types`](/workers/wrangler/commands/#types). Cloudflare also publishes type definitions to [GitHub](https://github.com/cloudflare/workers-types) and [npm](https://www.npmjs.com/package/@cloudflare/workers-types) (`npm install -D @cloudflare/workers-types`).

<h3 id="generate-types">
	Generate types that match your Worker's configuration
</h3>

Cloudflare continuously improves [workerd](https://github.com/cloudflare/workerd), the open-source Workers runtime.
Changes in workerd can introduce JavaScript API changes, thus changing the respective TypeScript types.

This means the correct types for your Worker depend on:

1. Your Worker's [compatibility date](/workers/configuration/compatibility-dates/).
2. Your Worker's [compatibility flags](/workers/configuration/compatibility-flags/).
3. Your Worker's bindings, which are defined in your [Wrangler configuration file](/workers/wrangler/configuration).
4. Any [module rules](/workers/wrangler/configuration/#bundling) you have specified in your Wrangler configuration file under `rules`.

For example, the runtime will only allow you to use the [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) class if you have `compatibility_flags = ["nodejs_als"]` in your [Wrangler configuration file](/workers/wrangler/configuration/). This should be reflected in the type definitions.

To ensure that your type definitions always match your Worker's configuration, you can dynamically generate types by running:

<PackageManagers type="exec" pkg="wrangler" args={"types"} />

See [the `wrangler types` command docs](/workers/wrangler/commands/#types) for more details.

:::note

<Render file="wrangler-commands/runtime-types" product="workers" />

:::

This will generate a `d.ts` file and (by default) save it to `worker-configuration.d.ts`. This will include `Env` types based on your Worker bindings _and_ runtime types based on your Worker's compatibility date and flags.

You should then add that file to your `tsconfig.json`'s `compilerOptions.types` array. If you have the `nodejs_compat` compatibility flag, you should also install `@types/node`.

You can commit your types file to git if you wish.

:::note

To ensure that your types are always up-to-date, make sure to run `wrangler types` after any changes to your config file.

:::

<h3 id="migrating">
	Migrating from `@cloudflare/workers-types` to `wrangler types`
</h3>

We recommend you use `wrangler types` to generate runtime types, rather than using the `@cloudflare/workers-types` package, as it generates types based on your Worker's [compatibility date](https://github.com/cloudflare/workerd/tree/main/npm/workers-types#compatibility-dates) and `compatibility flags`, ensuring that types match the exact runtime APIs made available to your Worker.

:::note

There are no plans to stop publishing the `@cloudflare/workers-types` package, which will still be the recommended way to type libraries and shared packages in the workers environment.

:::

#### 1. Uninstall `@cloudflare/workers-types`

<PackageManagers type="remove" pkg="@cloudflare/workers-types" />

#### 2. Generate runtime types using Wrangler

<PackageManagers type="exec" pkg="wrangler" args={"types"} />

This will generate a `.d.ts` file, saved to `worker-configuration.d.ts` by default. This will also generate `Env` types. If for some reason you do not want to include those, you can set `--include-env=false`.

You can now remove any imports from `@cloudflare/workers-types` in your Worker code.

:::note

<Render file="wrangler-commands/runtime-types" product="workers" />

:::

#### 3. Make sure your `tsconfig.json` includes the generated types

```json
{
	"compilerOptions": {
		"types": ["worker-configuration.d.ts"]
	}
}
```

Note that if you have specified a custom path for the runtime types file, you should use that in your `compilerOptions.types` array instead of the default path.

#### 4. Add @types/node if you are using [`nodejs_compat`](/workers/runtime-apis/nodejs/) (Optional)

If you are using the `nodejs_compat` compatibility flag, you should also install `@types/node`.

<PackageManagers type="add" pkg="@types/node" />

Then add this to your `tsconfig.json`.

```json
{
	"compilerOptions": {
		"types": ["worker-configuration.d.ts", "node"]
	}
}
```

#### 5. Update your scripts and CI pipelines

Regardless of your specific framework or build tools, you should run the `wrangler types` command before any tasks that rely on TypeScript.

Most projects will have existing build and development scripts, as well as some type-checking. In the example below, we're adding the `wrangler types` before the type-checking script in the project:

```json
{
	"scripts": {
		"dev": "existing-dev-command",
		"build": "existing-build-command",
		"generate-types": "wrangler types",
		"type-check": "generate-types && tsc"
	}
}
```

We recommend you commit your generated types file for use in CI. Alternatively, you can run `wrangler types` before other CI commands, as it should not take more than a few seconds. For example:

<Tabs> <TabItem label="npm">

```yaml
- run: npm run generate-types
- run: npm run build
- run: npm test
```

</TabItem> <TabItem label="yarn">

```yaml
- run: yarn generate-types
- run: yarn build
- run: yarn test
```

</TabItem> <TabItem label="pnpm">

```yaml
- run: pnpm run generate-types
- run: pnpm run build
- run: pnpm test
```

</TabItem> </Tabs>

### Resources

- [TypeScript template](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare/templates/hello-world/ts)
- [@cloudflare/workers-types](https://github.com/cloudflare/workers-types)
- [Runtime APIs](/workers/runtime-apis/)
- [TypeScript Examples](/workers/examples/?languages=TypeScript)

---

# Workers (Historic)

URL: https://developers.cloudflare.com/workers/platform/changelog/historical-changelog/

This page tracks changes made to Cloudflare Workers before 2023. For a view of more recent updates, refer to the [current changelog](/workers/platform/changelog/).

## 2022-12-16

* Conditional `PUT` requests have been fixed in the R2 bindings API.

## 2022-12-02

* Queues no longer support calling `send()` with an undefined JavaScript value as the message.

## 2022-11-30

* The DOMException constructor has been updated to align better with the standard specification. Specifically, the message and name arguments can now be any JavaScript value that is coercible into a string (previously, passing non-string values would throw).
* Extended the R2 binding API to include support for multipart uploads.

## 2022-11-17

* V8 update: 10.6 → 10.8

## 2022-11-02

* Implemented `toJSON()` for R2Checksums so that it is usable with `JSON.stringify()`.

## 2022-10-21

* The alarm retry limit will no longer apply to errors that are our fault.
* Compatibility dates have been added for multiple flags including the new streams implementation.
* `DurableObjectStorage` has a new method `sync()` that provides a way for a Worker to wait for its writes (including those performed with `allowUnconfirmed`) to be synchronized with storage.

## 2022-10-10

* Fixed a bug where if an ES-modules-syntax script exported an array-typed value from the top-level module, the upload API would refuse it with a [`500` error](https://community.cloudflare.com/t/community-tip-fixing-error-500-internal-server-error/44453).
* `console.log` now prints more information about certain objects, for example Promises.
* The Workers Runtime is now built from the Open Source code in: [GitHub - cloudflare/workerd: The JavaScript / Wasm runtime that powers Cloudflare Workers](https://github.com/cloudflare/workerd).

## 2022-09-16

* R2 `put` bindings options can now have an `onlyIf` field similar to `get` that does a conditional upload.
* Allow deleting multiple keys at once in R2 bindings.
* Added support for SHA-1, SHA-256, SHA-384, SHA-512 checksums in R2 `put` options.
* User-specified object checksums will now be available in the R2 `get/head` bindings response. MD5 is included by default for non-multipart uploaded objects.
* Updated V8 to 10.6.

## 2022-08-12

* A `Headers` object with the `range` header can now be used for range within `R2GetOptions` for the `get` R2 binding.
* When headers are used for `onlyIf` within `R2GetOptions` for the `get` R2 binding, they now correctly compare against the second granularity. This allows correctly round-tripping to the browser and back. Additionally, `secondsGranularity` is now an option that can be passed into options constructed by hand to specify this when constructing outside Headers for the same effect.
* Fixed the TypeScript type of `DurableObjectState.id` in [@cloudflare/workers-types](https://github.com/cloudflare/workers-types) to always be a `DurableObjectId`.
* Validation errors during Worker upload for module scripts now include correct line and column numbers.
* Bugfix, Profiling tools and flame graphs via Chrome’s debug tools now properly report information.

## 2022-07-08

* Workers Usage Report and Workers Weekly Summary have been disabled due to scaling issues with the service.

## 2022-06-24

* `wrangler dev` in global network preview mode now supports scheduling alarms.
* R2 GET requests made with the `range` option now contain the returned range in the `GetObject`’s `range` parameter.
* Some Web Cryptography API error messages include more information now.
* Updated V8 from 10.2 to 10.3.

## 2022-06-18

* Cron trigger events on Worker scripts using the old `addEventListener` syntax are now treated as failing if there is no event listener registered for `scheduled` events.
* The `durable_object_alarms` flag no longer needs to be explicitly provided to use DO alarms.

## 2022-06-09

* No externally-visible changes.

## 2022-06-03

* It is now possible to create standard `TransformStream` instances that can perform transformations on the data. Because this changes the behavior of the default `new TransformStream()` with no arguments, the `transformstream_enable_standard_constructor` compatibility flag is required to enable.
* Preview in Quick Edit now correctly uses the correct R2 bindings.
* Updated V8 from 10.1 to 10.2.

## 2022-05-26

* The static `Response.json()` method can be used to initialize a Response object with a JSON-serialized payload (refer to [whatwg/fetch #1392](https://github.com/whatwg/fetch/pull/1392)).
* R2 exceptions being thrown now have the `error` code appended in the message in parenthesis. This is a stop-gap until we are able to explicitly add the code property on the thrown `Error` object.

## 2022-05-19

* R2 bindings: `contentEncoding`, `contentLanguage`, and `cacheControl` are now correctly rendered.
* ReadableStream `pipeTo` and `pipeThrough` now support cancellation using `AbortSignal`.
* Calling `setAlarm()` in a DO with no `alarm()` handler implemented will now throw instead of failing silently. Calling `getAlarm()` when no `alarm()` handler is currently implemented will return null, even if an alarm was previously set on an old version of the DO class, as no execution will take place.
* R2: Better runtime support for additional ranges.
* R2 bindings now support ranges that have an `offset` and an optional `length`, a `length` and an optional `offset`, or a `suffix` (returns the last `N` bytes of a file).

## 2022-05-12

* Fix R2 bindings saving cache-control under content-language and rendering cache-control under content-language.
* Fix R2 bindings list without options to use the default list limit instead of never returning any results.
* Fix R2 bindings which did not correctly handle error messages from R2, resulting in `internal error` being thrown. Also fix behavior for get throwing an exception on a non-existent key instead of returning null. `R2Error` is removed for the time being and will be reinstated at some future time TBD.
* R2 bindings: if the onlyIf condition results in a precondition failure or a not modified result, the object is returned without a body instead of returning null.
* R2 bindings: sha1 is removed as an option because it was not actually hooked up to anything. TBD on additional checksum options beyond md5.
* Added `startAfter` option to the `list()` method in the Durable Object storage API.

## 2022-05-05

* `Response.redirect(url)` will no longer coalesce multiple consecutive slash characters appearing in the URL’s path.
* Fix generated types for Date.
* Fix R2 bindings list without options to use the default list limit instead of never returning any results.
* Fix R2 bindings did not correctly handle error messages from R2, resulting in internal error being thrown. Also fix behavior for get throwing an exception on a non-existent key instead of returning null. `R2Error` is removed for the time being and will be reinstated at some future time TBD.

## 2022-04-29

* Minor V8 update: 10.0 → 10.1.
* R2 public beta bindings are the default regardless of compat date or flags. Internal beta bindings customers should transition to public beta bindings as soon as possible. A back compatibility flag is available if this is not immediately possible. After some lag, new scripts carrying the `r2_public_beta_bindings` compatibility flag will stop accepting to be published until that flag is removed.

## 2022-04-22

* Major V8 update: 9.9 → 10.0.

## 2022-04-14

* Performance and stability improvements.

## 2022-04-08

* The AES-GCM implementation that is part of the Web Cryptography API now returns a friendlier error explaining that 0-length IVs are not allowed.
* R2 error responses now include better details.

## 2022-03-24

* A new compatibility flag has been introduced, `minimal_subrequests` , which removes some features that were unintentionally being applied to same-zone `fetch()` calls. The flag will default to enabled on Tuesday, 2022-04-05, and is described in [Workers `minimal_subrequests` compatibility flag](/workers/configuration/compatibility-flags/#minimal-subrequests).
* When creating a `Response` with JavaScript-backed ReadableStreams, the `Body` mixin functions (e.g. `await response.text()` ) are now implemented.
* The `IdentityTransformStream` creates a byte-oriented `TransformStream` implementation that simply passes bytes through unmodified. The readable half of the `TransformStream` supports BYOB-reads. It is important to note that `IdentityTransformStream` is identical to the current non-spec compliant `TransformStream` implementation, which will be updated soon to conform to the WHATWG Stream Standard. All current uses of `new TransformStream()` should be replaced with `new IdentityTransformStream()` to avoid potentially breaking changes later.

## 2022-03-17

* The standard [ByteLengthQueuingStrategy](https://developer.mozilla.org/en-US/docs/Web/API/ByteLengthQueuingStrategy) and [CountQueuingStrategy](https://developer.mozilla.org/en-US/docs/Web/API/CountQueuingStrategy) classes are now available.
* When the `capture_async_api_throws` flag is set, built-in Cloudflare-specific and Web Platform Standard APIs that return Promises will no longer throw errors synchronously and will instead return rejected promises. Exception is given with fatal errors such as out of memory errors.
* Fix R2 publish date rendering.
* Fix R2 bucket binding .get populating contentRange with garbage. contentRange is now undefined as intended.
* When using JavaScript-backed `ReadableStream`, it is now possible to use those streams with `new Response()`.

## 2022-03-11

* Fixed a bug where the key size was not counted when determining how many write units to charge for a Durable Object single-key `put()`. This may result in future writes costing one write unit more than past writes when the key is large enough to bump the total write size up above the next billing unit threshold of 4096 bytes. Multi-key `put()` operations have always properly counted the key size when determining billable write units.
* Implementations of `CompressionStream` and `DecompressionStream` are now available.

## 2022-03-04

* Initial pipeTo/pipeThrough support on ReadableStreams constructed using the new `ReadableStream()` constructor is now available.
* With the `global_navigator` compatibility flag set, the `navigator.userAgent` property can be used to detect when code is running within the Workers environment.
* A bug in the new URL implementation was fixed when setting the value of a `URLSearchParam`.
* The global `addEventListener` and dispatchEvent APIs are now available when using module syntax.
* An implementation of `URLPattern` is now available.

## 2022-02-25

* The `TextDecoder` class now supports the full range of text encodings defined by the WHATWG Encoding Standard.
* Both global `fetch()` and durable object `fetch()` now throw a TypeError when they receive a WebSocket in response to a request without the “Upgrade: websocket” header.
* Durable Objects users may now store up to 50 GB of data across the objects in their account by default. As before, if you need more storage than that you can contact us for an increase.

## 2022-02-18

* `TextDecoder` now supports Windows-1252 labels (aka ASCII): [Encoding API Encodings - Web APIs | MDN](https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings).

## 2022-02-11

* WebSocket message sends were erroneously not respecting Durable Object output gates as described in the [I/O gate blog post](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/). That bug has now been fixed, meaning that WebSockets will now never send a message under the assumption that a storage write has succeeded unless that write actually has succeeded.

## 2022-02-05

* Fixed bug causing WebSockets to Durable Objects to occasionally hang when the script implementing both a Worker and a Durable Object is re-deployed with new code.
* `crypto.getRandomValues` now supports BigInt64Array and BigUint64Array.
* A new implementation of the standard URL implementation is available. Use `url_standard` feature flag to enable the spec-compliant URL API implementation.

## 2022-01-28

* No user-visible changes.

## 2022-01-20

* Updated V8: 9.7 → 9.8.

## 2022-01-17

* `HTMLRewriter` now supports inspecting and modifying end tags, not just start tags.
* Fixed bug where Durable Objects experiencing a transient CPU overload condition would cause in-progress requests to be unable to return a response (appearing as an indefinite hang from the client side), even after the overload condition clears.

## 2022-01-07

* The `workers_api_getters_setters_on_prototype` configuration flag corrects the way Workers attaches property getters and setters to API objects so that they can be properly subclassed.

## 2021-12-22

* Async iteration (using `for` and `await`) on instances of `ReadableStream` is now available.

## 2021-12-10

* Raised the max value size in Durable Object storage from 32 KiB to 128 KiB.
* `AbortSignal.timeout(delay)` returns an `AbortSignal` that will be triggered after the given number of milliseconds.
* Preview implementations of the new `ReadableStream` and new `WritableStream` constructors are available behind the `streams_enable_constructors` feature flag.
* `crypto.DigestStream` is a non-standard extension to the crypto API that supports generating a hash digest from streaming data. The `DigestStream` itself is a `WritableStream` that does not retain the data written into it; instead, it generates a digest hash automatically when the flow of data has ended. The same hash algorithms supported by `crypto.subtle.digest()` are supported by the `crypto.DigestStream`.
* Added early support for the `scheduler.wait()` API, which is [going through the WICG standardization process](https://github.com/WICG/scheduling-apis), to provide an `await`-able alternative to `setTimeout()`.
* Fixed bug in `deleteAll` in Durable Objects containing more than 10000 keys that could sometimes cause incomplete data deletion and/or hangs.

## 2021-12-02

* The Streams spec requires that methods returning promises must not throw synchronous errors. As part of the effort of making the Streams implementation more spec compliant, we are converting a number of sync throws to async rejections.
* Major V8 update: 9.6 → 9.7. See [V8 release v9.7 · V8](https://v8.dev/blog/v8-release-97) for more details.

## 2021-11-19

* Durable Object stubs that receive an overload exception will be permanently broken to match the behavior of other exception types.
* Fixed issue where preview service claimed Let’s Encrypt certificates were expired.
* [`structuredClone()`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone) is now supported.

## 2021-11-12

* The `AbortSignal` object has a new `reason` property indicating the reason for the cancellation. The reason can be specified when the `AbortSignal` is triggered or created.
* Unhandled rejection warnings will be printed to the inspector console.

## 2021-11-05

* Upgrade to V8 9.6. This adds support for WebAssembly reference types. Refer to the [V8 release v9.6 · V8](https://v8.dev/blog/v8-release-96) for more details.
* Streams: When using the BYOB reader, the `ArrayBuffer` of the provided TypedArray should be detached, per the Streams spec. Because Workers was not previously enforcing that rule, and changing to comply with the spec could breaking existing code, a new compatibility flag, [streams\_byob\_reader\_detaches\_buffer](https://github.com/cloudflare/cloudflare-docs/pull/2644), has been introduced that will be enabled by default on 2021-11-10. User code should never try to reuse an `ArrayBuffer` that has been passed in to a BYOB readers `read()` method. The more recently added extension method `readAtLeast()` will always detach the `ArrayBuffer` and is unaffected by the compatibility flag setting.

## 2021-10-21

* Added support for the `signal` option in `EventTarget.addEventListener()`, to remove an event listener in response to an `AbortSignal`.
* The `unhandledrejection` and `rejectionhandled` events are now supported.
* The `ReadableStreamDefaultReader` and `ReadableStreamBYOBReader` constructors are now supported.
* Added non-standard `ReadableStreamBYOBReader` method `.readAtLeast(size, buffer)` that can be used to return a buffer with at least `size` bytes. The `buffer` parameter must be an `ArrayBufferView`. Behavior is identical to `.read()` except that at least `size` bytes are read, only returning fewer if EOF is encountered. One final call to `.readAtLeast()` is still needed to get back a `done = true` value.
* The compatibility flags `formdata_parser_supports_files`, `fetch_refuses_unknown_protocols`, and `durable_object_fetch_requires_full_url` have been scheduled to be turned on by default as of 2021-11-03, 2021-11-10, and 2021-11-10, respectively. For more details, refer to [Compatibility Dates](/workers/configuration/compatibility-dates/)

## 2021-10-14

* `request.signal` will always return an `AbortSignal`.
* Cloudflare Workers’ integration with Chrome DevTools profiling now more accurately reports the line numbers and time elapsed. Previously, the line numbers were shown as one line later then the actual code, and the time shown would be proportional but much longer than the actual time used.
* Upgrade to v8 9.5. Refer to [V8 release v9.5 · V8](https://v8.dev/blog/v8-release-95) for more details.

## 2021-09-24

* The `AbortController` and `AbortSignal` objects are now available.
* The Web Platform `queueMicrotask` API is now available.
* It is now possible to use new `EventTarget()` and to create custom `EventTarget` subclasses.
* The `once` option is now supported on `addEventTarget` to register event handlers that will be invoked only once.
* Per the HTML specification, a listener passed in to the `addEventListener` function is allowed to either be a function or an object with a `handleEvent` member function. Previously, Workers only supported the function option, now it supports both.
* The `Event` object now supports most standard methods and properties.
* V8 updated from 9.3 to 9.4.

## 2021-09-03

* The `crypto.randomUUID()` method can be used to generate a new random version 4 UUID.
* Durable Objects are now scheduled more evenly around a colocation (colo).

## 2021-08-05

* No user-facing changes. Just bug fixes & internal maintenance.

## 2021-07-30

* Fixed a hang in Durable Objects when reading more than 16MB of data at once (for example, with a large `list()` operation).
* Added a new compatibility flag `html_rewriter_treats_esi_include_as_void_tag` which causes `HTMLRewriter` to treat `<esi:include>` and `<esi:comment>` as void tags, such that they are considered to have neither an end tag nor nested content. To opt a worker into the new behavior, you must use Wrangler v1.19.0 or newer and specify the flag in `wrangler.toml`. Refer to the [Wrangler compatibility flag notes](https://github.com/cloudflare/wrangler-legacy/pull/2009) for details.

## 2021-07-23

* Performance and stability improvements.

## 2021-07-16

* Workers can now make up to 1000 subrequests to Durable Objects from a within a single request invocation, up from the prior limit of 50.
* Major changes to Durable Objects implementation, the details of which will be the subject of an upcoming blog post. In theory, the changes should not harm existing apps, except to make them faster. Let your account team know if you observe anything unusual or report your issue in the [Workers Discord](https://discord.cloudflare.com).
* Durable Object constructors may now initiate I/O, such as `fetch()` calls.
* Added Durable Objects `state.blockConcurrencyWhile()` API useful for delaying delivery of requests and other events while performing some critical state-affecting task. For example, this can be used to perform start-up initialization in an object’s constructor.
* In Durable Objects, the callback passed to `storage.transaction()` can now return a value, which will be propagated as the return value of the `transaction()` call.

## 2021-07-13

* The preview service now prints a warning in the devtools console when a script uses `Response/Request.clone()` but does not read one of the cloned bodies. Such a situation forces the runtime to buffer the entire message body in memory, which reduces performance. [Find an example here](https://cloudflareworkers.com/#823fbe463bfafd5a06bcfeabbdf5eeae:https://tutorial.cloudflareworkers.com).

## 2021-07-01

* Fixed bug where registering the same exact event listener method twice on the same event type threw an internal error.
* Add support for the `.forEach()` method for `Headers`, `URLSearchParameters`, and `FormData`.

## 2021-06-27

* WebCrypto: Implemented non-standard Ed25519 operation (algorithm NODE-ED25519, curve name NODE-ED25519). The Ed25519 implementation differs from NodeJS’s in that raw import/export of private keys is disallowed, per parity with ECDSA/ECDH.

## 2021-06-17

Changes this week:

* Updated V8 from 9.1 to 9.2.
* `wrangler tail` now works on Durable Objects. Note that logs from long-lived WebSockets will not be visible until the WebSocket is closed.

## 2021-06-11

Changes this week:

* Turn on V8 Sparkplug compiler.
* Durable Objects that are finishing up existing requests after their code is updated will be disconnected from the persistent storage API, to maintain the invariant that only a single instance ever has access to persistent storage for a given Durable Object.

## 2021-06-04

Changes this week:

* WebCrypto: We now support the “raw” import/export format for ECDSA/ECDH public keys.
* `request.cf` is no longer missing when writing Workers using modules syntax.

## 2021-05-14

Changes this week:

* Improve error messages coming from the WebCrypto API.
* Updated V8: 9.0 → 9.1

Changes in an earlier release:

* WebCrypto: Implement JWK export for RSA, ECDSA, & ECDH.
* WebCrypto: Add support for RSA-OAEP
* WebCrypto: HKDF implemented.
* Fix recently-introduced backwards clock jumps in Durable Objects.
* `WebCrypto.generateKey()`, when asked to generate a key pair with algorithm RSA-PSS, would instead return a key pair using algorithm RSASSA-PKCS1-v1\_5. Although the key structure is the same, the signature algorithms differ, and therefore, signatures generated using the key would not be accepted by a correct implementation of RSA-PSS, and vice versa. Since this would be a pretty obvious problem, but no one ever reported it to us, we guess that currently, no one is using this functionality on Workers.

## 2021-04-29

Changes this week:

* WebCrypto: Implemented `wrapKey()` / `unwrapKey()` for AES algorithms.
* The arguments to `WebSocket.close()` are now optional, as the standard says they should be.

## 2021-04-23

Changes this week:

* In the WebCrypto API, encrypt and decrypt operations are now supported for the “AES-CTR” encryption algorithm.
* For Durable Objects, CPU time limits are now enforced on the object level rather than the request level. Each time a new request arrives, the time limit is “topped up” to 500ms. After the (free) beta period ends and Durable Objects becomes generally available, we will increase this to 30 seconds.
* When a Durable Object exceeds its CPU time limit, the entire object will be discarded and recreated. Previously, we allowed subrequest requests to continue using the same object, but this was dangerous because hitting the CPU time limit can leave the object in an inconsistent state.
* Long running Durable Objects are given more subrequest quota as additional WebSocket messages are sent to them, to avoid the problem of a long-running Object being unable to make any more subrequests after it has been held open by a particular WebSocket for a while.
* When a Durable Object’s code is updated, or when its isolate is reset due to exceeding the memory limit, all stubs pointing to the object will become invalidated and have to be recreated. This is consistent with what happens when the CPU time is exceeded, or when stubs become disconnected due to random network errors. This behavior is useful, as apps can now assume that two messages sent to the same stub will be delivered to exactly the same live instance (if they are delivered at all). Apps which do not care about this property should recreate their stubs for every request; there is no performance penalty from doing so.
* When a Durable Object’s isolate exceeds its memory limit, an exception with an explanatory message will now be thrown to the caller, instead of “internal error”.
* When a Durable Object exceeds its CPU time limit, an exception with an explanatory message will now be thrown to the caller, instead of “internal error”.
* `wrangler tail` now reports CPU-time-exceeded exceptions with an explanatory message instead of “internal error”.

## 2021-04-19

Changes since the last post on 3/26:

* Cron Triggers now have a 15 minute wall time limit, in addition to the existing CPU time limit. (Previously, there was no limit, so a cron trigger that spent all its time waiting for I/O could hang forever.)
* Our WebCrypto implementation now supports importing and exporting HMAC and AES keys in JWK format.
* Our WebCrypto implementation now supports AES key generation for CTR, CBC, and KW modes. AES-CTR encrypt/decrypt and AES-KW key wrapping/unwrapping support will land in a later release.
* Fixed bug where `crypto.subtle.encrypt()` on zero-length inputs would sometimes throw an exception.
* Errors on script upload will now be properly reported for module-based scripts, instead of appearing as a ReferenceError.
* WebCrypto: Key derivation for ECDH.
* WebCrypto: Support ECDH key generation & import.
* WebCrypto: Support ECDSA key generation.
* Fixed bug where `crypto.subtle.encrypt()` on zero-length inputs would sometimes throw an exception.
* Improved exception messages thrown by the WebCrypto API somewhat.
* `waitUntil` is now supported for module Workers. An additional argument called ‘ctx’ is passed after ‘env’, and `waitUntil` is a method on ‘ctx’.
* `passThroughOnException` is now available under the ctx argument to module handlers
* Reliability improvements for Durable Objects
* Reliability improvements for Durable Objects persistent storage API
* `ScheduledEvent.cron` is now set to the original cron string that the event was scheduled for.

## 2021-03-26

Changes this week:

* Existing WebSocket connections to Durable Objects will now be forcibly disconnected on code updates, in order to force clients to connect to the instance running the new code.

## 2021-03-11

New this week:

* When the Workers Runtime itself reloads due to us deploying a new version or config change, we now preload high-traffic Workers in the new instance of the runtime before traffic cuts over. This ensures that users do not observe cold starts for these Workers due to the upgrade, and also fixes a low rate of spurious 503 errors that we had previously been seeing due to overload during such reloads.

(It looks like no release notes were posted the last few weeks, but there were no new user-visible changes to report.)

## 2021-02-11

Changes this week:

* In the preview mode of the dashboard, a Worker that fails during startup will now return a 500 response, rather than getting the default passthrough behavior, which was making it harder to notice when a Worker was failing.
* A Durable Object’s ID is now provided to it in its constructor. It can be accessed off of the `state` provided as the constructor’s first argument, as in `state.id`.

## 2021-02-05

New this week:

* V8 has been updated from 8.8 to 8.9.
* During a `fetch()`, if the destination server commits certain HTTP protocol errors, such as returning invalid (unparsable) headers, we now throw an exception whose description explains the problem, rather than an “internal error”.

New last week (forgot to post):

* Added support for `waitUntil()` in Durable Objects. It is a method on the state object passed to the Durable Object class’s constructor.

## 2021-01-22

New in the past week:

* Fixed a bug which caused scripts with WebAssembly modules to hang when using devtools in the preview service.

## 2021-01-14

Changes this week:

* Implemented File and Blob APIs, which can be used when constructing FormData in outgoing requests. Unfortunately, FormData from incoming requests at this time will still use strings even when file metadata was present, in order to avoid breaking existing deployed Workers. We will find a way to fix that in the future.

## 2021-01-07

Changes this week:

* No user-visible changes.

Changes in the prior release:

* Fixed delivery of WebSocket “error” events.
* Fixed a rare bug where a WritableStream could be garbage collected while it still had writes queued, causing those writes to be lost.

## 2020-12-10

Changes this week:

* Major V8 update: 8.7.220.29 -> 8.8.278.8

## 2019-09-19

Changes this week:

* Unannounced new feature. (Stay tuned.)
* Enforced new limit on concurrent subrequests (see below).
* Stability improvements.

**Concurrent Subrequest Limit**

As of this release, we impose a limit on the number of outgoing HTTP requests that a Worker can make simultaneously. **For each incoming request**, a Worker can make up to 6 concurrent outgoing `fetch()` requests.

If a Worker’s request handler attempts to call `fetch()` more than six times (on behalf of a single incoming request) without waiting for previous fetches to complete, then fetches after the sixth will be delayed until previous fetches have finished. A Worker is still allowed to make up to 50 total subrequests per incoming request, as before; the new limit is only on how many can execute simultaneously.

**Automatic deadlock avoidance**

Our implementation automatically detects if delaying a fetch would cause the Worker to deadlock, and prevents the deadlock by cancelling the least-recently-used request. For example, imagine a Worker that starts 10 requests and waits to receive all the responses without reading the response bodies. A fetch is not considered complete until the response body is fully-consumed (for example, by calling `response.text()` or `response.json()`, or by reading from `response.body`). Therefore, in this scenario, the first six requests will run and their response objects would be returned, but the remaining four requests would not start until the earlier responses are consumed. If the Worker fails to actually read the earlier response bodies and is still waiting for the last four requests, then the Workers Runtime will automatically cancel the first four requests so that the remaining ones can complete. If the Worker later goes back and tries to read the response bodies, exceptions will be thrown.

**Most Workers are Not Affected**

The vast majority of Workers make fewer than six outgoing requests per incoming request. Such Workers are totally unaffected by this change.

Of Workers that do make more than six outgoing requests concurrently for a single incoming request, the vast majority either read the response bodies immediately upon each response returning, or never read the response bodies at all. In either case, these Workers will still work as intended – although they may be a little slower due to outgoing requests after the sixth being delayed.

A very small number of deployed Workers (about 20 total) make more than 6 requests concurrently, wait for all responses to return, and then go back to read the response bodies later. For all known Workers that do this, we have temporarily grandfathered your zone into the old behavior, so that your Workers will continue to operate. However, we will be communicating with customers one-by-one to request that you update your code to proactively read request bodies, so that it works correctly under the new limit.

**Why did we do this?**

Cloudflare communicates with origin servers using HTTP/1.1, not HTTP/2. Under HTTP/1.1, each concurrent request requires a separate connection. So, Workers that make many requests concurrently could force the creation of an excessive number of connections to origin servers. In some cases, this caused resource exhaustion problems either at the origin server or within our own stack.

On investigating the use cases for such Workers, every case we looked at turned out to be a mistake or otherwise unnecessary. Often, developers were making requests and receiving responses, but they only cared about the response status and headers but not the body. So, they threw away the response objects without reading the body, essentially leaking connections. In some other cases, developers had simply accidentally written code that made excessive requests in a loop for no good reason at all. Both of these cases should now cause no problems under the new behavior.

We chose the limit of 6 concurrent connections based on the fact that Chrome enforces the same limit on web sites in the browser.

## 2020-12-04

Changes this week:

* Durable Objects storage API now supports listing keys by prefix.
* Improved error message when a single request performs more than 1000 KV operations to make clear that a per-request limit was reached, not a global rate limit.
* `wrangler dev` previews should now honor non-default resource limits, for example, longer CPU limits for those in the Workers Unbound beta.
* Fixed off-by-one line numbers in Worker exceptions.
* Exceptions thrown in a Durable Object’s `fetch()` method are now tunneled to its caller.
* Fixed a bug where a large Durable Object response body could cause the Durable Object to become unresponsive.

## 2020-11-13

Changes over the past week:

* `ReadableStream.cancel()` and `ReadableStream.getReader().cancel()` now take an optional, instead of a mandatory, argument, to conform with the Streams spec.
* Fixed an error that occurred when a WASM module declared that it wanted to grow larger than 128MB. Instead, the actual memory usage of the module is monitored and an error is thrown if it exceeds 128MB used.

## 2020-11-05

Changes this week:

* Major V8 update: 8.6 -> 8.7
* Limit the maximum number of Durable Objects keys that can be changed in a single transaction to 128.

## 2020-10-05

We had our usual weekly release last week, but:

* No user-visible changes.

## 2020-09-24

Changes this week:

* Internal changes to support upcoming features.

Also, a change from the 2020-09-08 release that it seems we forgot to post:

* V8 major update: 8.5 -> 8.6

## 2020-08-03

Changes last week:

* Fixed a regression which could cause `HTMLRewriter.transform()` to throw spurious “The parser has stopped.” errors.
* Upgraded V8 from 8.4 to 8.5.

## 2020-07-09

Changes this week:

* Fixed a regression in HTMLRewriter: [https://github.com/cloudflare/lol-html/issues/50](https://github.com/cloudflare/lol-html/issues/50)
* Common HTTP method names passed to `fetch()` or `new Request()` are now case-insensitive as required by the Fetch API spec.

Changes last week (… forgot to post):

* `setTimeout`/`setInterval` can now take additional arguments which will be passed on to the callback, as required by the spec. (Few people use this feature today because it’s usually much easier to use lambda captures.)

Changes the week before last (… also… forgot to post… we really need to code up a bot for this):

* The HTMLRewriter now supports the `:nth-child` , `:first-child` , `:nth-of-type` , and `:first-of-type` selectors.

## 2020-05-15

Changes this week:

* Implemented API for yet-to-be-announced new feature.

## 2020-04-20

Looks like we forgot to post release notes for a couple weeks. Releases still are happening weekly as always, but the “post to the community” step is insufficiently automated…
4/2 release:

* Fixed a source of long garbage collection paused in memory limit enforcement.

4/9 release:

* No publicly-visible changes.

4/16 release:

* In preview, we now log a warning when attempting to construct a `Request` or `Response` whose body is of type `FormData` but with the `Content-Type` header overridden. Such bodies would not be parseable by the receiver.

## 2020-03-26

New this week:

* Certain “internal errors” that could be thrown when using the Cache API are now reported with human-friendly error messages. For example, `caches.default.match("not a URL")` now throws a TypeError.

## 2020-02-28

New from the past two weeks:

* Fixed a bug in the preview service where the CPU time limiter was overly lenient for the first several requests handled by a newly-started worker. The same bug actually exists in production as well, but we are much more cautious about fixing it there, since doing so might break live sites. If you find your worker now exceeds CPU time limits in preview, then it is likely exceeding time limits in production as well, but only appearing to work because the limits are too lenient for the first few requests. Such Workers will eventually fail in production, too (and always have), so it is best to fix the problem in preview before deploying.
* Major V8 update: 8.0 -> 8.1
* Minor bug fixes.

## 2020-02-13

Changes over the last couple weeks:

* Fixed a bug where if two differently-named scripts within the same account had identical content and were deployed to the same zone, they would be treated as the “same Worker”, meaning they would share the same isolate and global variables. This only applied between Workers on the same zone, so was not a security threat, but it caused confusion. Now, two differently-named Worker scripts will never be considered the same Worker even if they have identical content.
* Performance and stability improvements.

## 2020-01-24

It has been a while since we posted release notes, partly due to the holidays. Here is what is new over the past month:

* Performance and stability improvements.
* A rare source of `daemonDown` errors when processing bursty traffic over HTTP/2 has been eliminated.
* Updated V8 7.9 -> 8.0.

## 2019-12-12

New this week:

* We now pass correct line and column numbers more often when reporting exceptions to the V8 inspector. There remain some cases where the reported line and column numbers will be wrong.
* Fixed a significant source of daemonDown (1105) errors.

## 2019-12-06

Runtime release notes covering the past few weeks:

* Increased total per-request `Cache.put()` limit to 5GiB.
* Increased individual `Cache.put()` limits to the lesser of 5GiB or the zone’s normal [cache limits](/cache/concepts/default-cache-behavior/).
* Added a helpful error message explaining AES decryption failures.
* Some overload errors were erroneously being reported as daemonDown (1105) errors. They have been changed to exceededCpu (1102) errors, which better describes their cause.
* More “internal errors” were converted to useful user-facing errors.
* Stability improvements and bug fixes.

---

# Changelog

URL: https://developers.cloudflare.com/workers/platform/changelog/

import { ProductReleaseNotes } from "~/components";

This changelog details meaningful changes made to Workers across the Cloudflare dashboard, Wrangler, the API, and the workerd runtime. These changes are not configurable.

This is *different* from [compatibility dates](/workers/configuration/compatibility-dates/) and [compatibility flags](/workers/configuration/compatibility-flags/), which let you explicitly opt-in to or opt-out of specific changes to the Workers Runtime.

{/* <!-- Actual content lives in /src/content/release-notes/workers.yaml. Update the file there for new entries to appear here. For more details, refer to https://developers.cloudflare.com/style-guide/documentation-content-strategy/content-types/changelog/#yaml-file --> */}

<ProductReleaseNotes />

---

# Changelog

URL: https://developers.cloudflare.com/workers/platform/changelog/platform/

{/* <!-- All changelog entries live in associated /src/content/changelogs/{productName}.yaml. This page needs to exist in order to house the associated RSS feed. --> */}

---

# Breakpoints

URL: https://developers.cloudflare.com/workers/observability/dev-tools/breakpoints/

## Debug via breakpoints

As of Wrangler 3.9.0, you can debug via breakpoints in your Worker. Breakpoints provide the ability to review what is happening at a given point in the execution of your Worker. Breakpoint functionality exists in both DevTools and VS Code.

For more information on breakpoint debugging via Chrome's DevTools, refer to [Chrome's article on breakpoints](https://developer.chrome.com/docs/devtools/javascript/breakpoints/).

### Setup VS Code to use breakpoints

To setup VS Code for breakpoint debugging in your Worker project:

1. Create a `.vscode` folder in your project's root folder if one does not exist.
2. Within that folder, create a `launch.json` file with the following content:

```json
{
  "configurations": [
    {
      "name": "Wrangler",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "cwd": "/",
      "resolveSourceMapLocations": null,
      "attachExistingChildren": false,
      "autoAttachChildProcesses": false,
      "sourceMaps": true // works with or without this line
    }
  ]
}
```

3. Open your project in VS Code, open a new terminal window from VS Code, and run `npx wrangler dev` to start the local dev server.

4. At the top of the **Run & Debug** panel, you should see an option to select a configuration. Choose **Wrangler**, and select the play icon. **Wrangler: Remote Process \[0]** should show up in the Call Stack panel on the left.

5. Go back to a `.js` or `.ts` file in your project and add at least one breakpoint.

6. Open your browser and go to the Worker's local URL (default `http://127.0.0.1:8787`). The breakpoint should be hit, and you should be able to review details about your code at the specified line.

:::caution

Breakpoint debugging in `wrangler dev` using `--remote` could extend Worker CPU time and incur additional costs since you are testing against actual resources that count against usage limits. It is recommended to use `wrangler dev` without the `--remote` option. This ensures you are developing locally.

If you are debugging using `--remote`, you cannot use code minification as the debugger will be unable to find vars when stopped at a breakpoint. Do not set minify to `true` in your Wrangler configuration file.

:::

:::note

The `.vscode/launch.json` file only applies to a single workspace. If you prefer, you can add the above launch configuration to your User Settings (per the [official VS Code documentation](https://code.visualstudio.com/docs/editor/debugging#_global-launch-configuration)) to have it available for all your workspaces.

:::

## Related resources

- [Local Development](/workers/development-testing/) - Develop your Workers and connected resources locally via Wrangler and [`workerd`](https://github.com/cloudflare/workerd), for a fast, accurate feedback loop.

---

# Profiling CPU usage

URL: https://developers.cloudflare.com/workers/observability/dev-tools/cpu-usage/

If a Worker spends too much time performing CPU-intensive tasks, responses may be slow or the Worker might
fail to startup due to [time limits](/workers/platform/limits/#worker-startup-time).

Profiling in DevTools can help you identify and fix code that uses too much CPU.

Measuring execution time of specific functions in production can be difficult because Workers
[only increment timers on I/O](/workers/reference/security-model/#step-1-disallow-timers-and-multi-threading)
for security purposes. However, measuring CPU execution times is possible in local development with DevTools.

When using DevTools to monitor CPU usage, it may be difficult to replicate specific behavior you are
seeing in production. To mimic production behavior, make sure the requests you send to the local Worker
are similar to requests in production. This might mean sending a large volume of requests, making requests
to specific routes, or using production-like data with the [--remote flag](/workers/development-testing/#remote-bindings).

## Taking a profile

To generate a CPU profile:

- Run `wrangler dev` to start your Worker
- Press the `D` key from your terminal to open DevTools
- Select the "Profiler" tab
- Select `Start` to begin recording CPU usage
- Send requests to your Worker from a new tab
- Select `Stop`

You now have a CPU profile.

:::note

For Rust Workers, add the following to your `Cargo.toml` to preserve [DWARF](https://dwarfstd.org/) debug symbols (from [this comment](https://github.com/rustwasm/wasm-pack/issues/1351#issuecomment-2100231587)):

```toml title="wrangler.toml"
[package.metadata.wasm-pack.profile.dev.wasm-bindgen]
dwarf-debug-info = true
```

Then, update your `wrangler.toml` to configure wasm-pack (via worker-build) to use the `dev` [profile](https://rustwasm.github.io/docs/wasm-pack/commands/build.html#profile) to preserve debug symbols.

```toml title="Cargo.toml"
[build]
command = "cargo install -q worker-build && worker-build --dev"
```

:::

## An Example Profile

Let's look at an example to learn how to read a CPU profile. Imagine you have the following Worker:

```js title="index.js"
const addNumbers = (body) => {
	for (let i = 0; i < 5000; ++i) {
		body = body + " " + i;
	}
	return body;
};

const moreAddition = (body) => {
	for (let i = 5001; i < 15000; ++i) {
		body = body + " " + i;
	}
	return body;
};

export default {
	async fetch(request, env, ctx) {
		let body = "Hello Profiler! - ";
		body = addNumbers(body);
		body = moreAddition(body);
		return new Response(body);
	},
};
```

You want to find which part of the code causes slow response times. How do you use DevTool profiling to identify the
CPU-heavy code and fix the issue?

First, as mentioned above, you open DevTools by pressing the `D` key after running `wrangler dev`. Then, you
navigate to the "Profiler" tab and take a profile by pressing `Start` and sending a request.

![CPU Profile](~/assets/images/workers/observability/profile.png)

The top chart in this image shows a timeline of the profile, and you can use it to zoom in on a specific request.

The chart below shows the CPU time used for operations run during the request. In this screenshot, you can see
"fetch" time at the top and the subscomponents of fetch beneath, including the two functions `addNumbers` and
`moreAdditions`. By hovering over each box, you get more information, and by clicking the box, you navigate
to the function's source code.

Using this graph, you can answer the question of "what is taking CPU time?". The `addNumbers` function has
a very small box, representing 0.3ms of CPU time. The `moreAdditions` box is larger, representing 2.2ms of CPU time.

Therefore, if you want to make response times faster, you need to optimize `moreAdditions`.

You can also change the visualization from ‘Chart’ to ‘Heavy (Bottom Up)’ for an alternative view.

![CPU Profile](~/assets/images/workers/observability/heavy.png)

This shows the relative times allocated to each function. At the top of the list, `moreAdditions` is clearly the
slowest portion of your Worker. You can see that garbage collection also represents a large percentage of time, so
memory optimization could be useful.

## Additional Resources

To learn more about how to use the CPU profiler, see [Google's documentation on Profiling the CPU in DevTools](https://developer.chrome.com/docs/devtools/performance/nodejs#profile).

To learn how to use DevTools to gain insight into memory, see the [Memory Usage Documentation](/workers/observability/dev-tools/memory-usage/).

---

# DevTools

URL: https://developers.cloudflare.com/workers/observability/dev-tools/

## Using DevTools

When running your Worker locally using `wrangler dev`, you automatically have access to [Cloudflare's implementation](https://github.com/cloudflare/workers-sdk/tree/main/packages/chrome-devtools-patches) of [Chrome's DevTools](https://developer.chrome.com/docs/devtools/overview).
DevTools help you debug and optimize your Workers.

:::note
You may have experience using Chrome's DevTools for frontend development. Notably, Worker DevTools are used for backend code and _not_ client-side JavaScript.
:::

## Opening DevTools

To get started, run your Worker in development mode with `wrangler dev`, then open the DevTools in the browser by pressing the `D` key from your terminal. Now when you access this worker locally, it can be debugged and profiled with this DevTools instance.

Alternatively, both the [Cloudflare Dashboard](https://dash.cloudflare.com/) and the [Worker's Playground](https://workers.cloudflare.com/playground) include DevTools in their UI.

## DevTool use cases

DevTools can be used in a variety of situations. For more information, see the documentation:

- [Debugging code via breakpoints and logging](/workers/observability/dev-tools/breakpoints/)
- [Profiling CPU usage](/workers/observability/dev-tools/cpu-usage/)
- [Addressing out of memory (OOM) errors](/workers/observability/dev-tools/memory-usage/)

## Related resources

- [Local development](/workers/development-testing/) - Develop your Workers and connected resources locally via Wrangler and workerd, for a fast, accurate feedback loop.

---

# Profiling Memory

URL: https://developers.cloudflare.com/workers/observability/dev-tools/memory-usage/

Understanding Worker memory usage can help you optimize performance, avoid Out of Memory (OOM) errors
when hitting [Worker memory limits](/workers/platform/limits/#memory), and fix memory leaks.

You can profile memory usage with snapshots in DevTools. Memory snapshots let you view a summary of
memory usage, see how much memory is allocated to different data types, and get details on specific
objects in memory.

When using DevTools to profile memory, it may be difficult to replicate specific behavior you are
seeing in production. To mimic production behavior, make sure the requests you send to the local Worker
are similar to requests in production. This might mean sending a large volume of requests, making requests
to specific routes, or using production-like data with the [--remote flag](/workers/development-testing/#remote-bindings).

## Taking a snapshot

To generate a memory snapshot:

- Run `wrangler dev` to start your Worker
- Press the `D` from your terminal to open DevTools
- Select on the "Memory" tab
- Send requests to your Worker to start allocating memory
  - Optionally include a debugger to make sure you can pause execution at the proper time
- Select `Take snapshot`

You can now inspect Worker memory.

## An Example Snapshot

Let's look at an example to learn how to read a memory snapshot. Imagine you have the following Worker:

```js title="index.js"
let responseText = "Hello world!";

export default {
	async fetch(request, env, ctx) {
		let now = new Date().toISOString();
		responseText = responseText + ` (Requested at: ${now})`;
		return new Response(responseText.slice(0, 53));
	},
};
```

While this code worked well initially, over time you notice slower responses and
Out of Memory errors. Using DevTools, you can find out if this is a memory leak.

First, as mentioned above, you open DevTools by pressing the `D` key after running `wrangler dev`.
Then, you navigate to the "Memory" tab.

Next, generate a large volume of traffic to the Worker by sending requests. You can do this with `curl` or by
repeatedly reloading the browser. Note that other Workers may require more specific requests to reproduce
a memory leak.

Then, click the "Take Snapshot" button and view the results.

First, navigate to "Statistics" in the dropdown to get a general sense of what takes up memory.

![Memory Statistics](~/assets/images/workers/observability/memory-stats.png)

Looking at these statistics, you can see that a lot of memory is dedicated to strings at 67 kB. This is
likely the source of the memory leak. If you make more requests and take another snapshot, you would see
this number grow.

![Memory Summary](~/assets/images/workers/observability/memory-summary.png)

The memory summary lists data types by the amount of memory they take up. When you click into "(string)", you can see
a string that is far larger than the rest. The text shows that you are appending "Requested at" and a date repeatedly,
inadvertently overwriting the global variable with an increasingly large string:

```js
responseText = responseText + ` (Requested at: ${now})`;
```

Using Memory Snapshotting in DevTools, you've identified the object and line of code causing the memory leak.
You can now fix it with a small code change.

## Additional Resources

To learn more about how to use Memory Snapshotting, see [Google's documentation on Memory Heap Snapshots](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots).

To learn how to use DevTools to gain insight into CPU usage, see the [CPU Profiling Documentation](/workers/observability/dev-tools/cpu-usage/).

---

# Logs

URL: https://developers.cloudflare.com/workers/observability/logs/

import { Badge, Stream } from "~/components";

Logs are an important component of a developer's toolkit to troubleshoot and diagnose application issues and maintaining system health. The Cloudflare Developer Platform offers many tools to help developers manage their application's logs.

## [Workers Logs](/workers/observability/logs/workers-logs)

Automatically ingest, filter, and analyze logs emitted from Cloudflare Workers in the Cloudflare dashboard.

## [Real-time logs](/workers/observability/logs/real-time-logs)

Access log events in near real-time. Real-time logs provide immediate feedback and visibility into the health of your Cloudflare Worker.

## [Tail Workers](/workers/observability/logs/tail-workers) <Badge text="Beta" size="large"/>

Tail Workers allow developers to apply custom filtering, sampling, and transformation logic to telemetry data.

## [Workers Logpush](/workers/observability/logs/logpush)

Send Workers Trace Event Logs to a supported destination. Workers Logpush includes metadata about requests and responses, unstructured `console.log()` messages and any uncaught exceptions.

## Video Tutorial

<Stream id="8a29e0b3ee30140431df06c0ec935c60" title="Workers Observability" thumbnail="2.5s" />

---

# Workers Logpush

URL: https://developers.cloudflare.com/workers/observability/logs/logpush/

import { WranglerConfig } from "~/components";

[Cloudflare Logpush](/logs/about/) supports the ability to send [Workers Trace Event Logs](/logs/reference/log-fields/account/workers_trace_events/) to a [supported destination](/logs/get-started/enable-destinations/). Worker’s Trace Events Logpush includes metadata about requests and responses, unstructured `console.log()` messages and any uncaught exceptions. This product is available on the Workers Paid plan. For pricing information, refer to [Pricing](/workers/platform/pricing/#workers-trace-events-logpush).

:::caution


Workers Trace Events Logpush is not available for zones on the [Cloudflare China Network](/china-network/).


:::

## Verify your Logpush access

:::note[Wrangler version]
Minimum required Wrangler version: 2.2.0. Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/).
:::

To configure a Logpush job, verify that your Cloudflare account role can use Logpush. To check your role:

1. Log in the [Cloudflare dashboard](https://dash.cloudflare.com).
2. Select your account and scroll down to **Manage Account** > **Members**.
3. Check your account permissions. Roles with Logpush configuration access are different than Workers permissions. Super Administrators, Administrators, and the Log Share roles have full access to Logpush.

Alternatively, create a new [API token](/fundamentals/api/get-started/create-token/) scoped at the Account level with Logs Edit permissions.

## Create a Logpush job

### Via the Cloudflare dashboard

To create a Logpush job in the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com), and select your account.
2. Select **Analytics & Logs** > **Logpush**.
3. Select **Create a Logpush job**.
4. Select **Workers trace events** as the data set > **Next**.
5. If needed, customize your data fields. Otherwise, select **Next**.

6. Follow the instructions on the dashboard to verify ownership of your data's destination and complete job creation.

### Via cURL

The following example sends Workers logs to R2. For more configuration options, refer to [Enable destinations](/logs/get-started/enable-destinations/) and [API configuration](/logs/get-started/api-configuration/) in the Logs documentation.

```bash
curl "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/logpush/jobs" \
--header 'X-Auth-Key: <API_KEY>' \
--header 'X-Auth-Email: <EMAIL>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "workers-logpush",
  "output_options": {
    "field_names": ["Event", "EventTimestampMs", "Outcome", "Exceptions", "Logs", "ScriptName"],
  },
  "destination_conf": "r2://<BUCKET_PATH>/{DATE}?account-id=<ACCOUNT_ID>&access-key-id=<R2_ACCESS_KEY_ID>&secret-access-key=<R2_SECRET_ACCESS_KEY>",
  "dataset": "workers_trace_events",
  "enabled": true
}' | jq .
```

In Logpush, you can configure [filters](/logs/reference/filters/) and a [sampling rate](/logs/get-started/api-configuration/#sampling-rate) to have more control of the volume of data that is sent to your configured destination. For example, if you only want to receive logs for requests that did not result in an exception, add the following `filter` JSON property below `output_options`:

`"filter":"{\"where\": {\"key\":\"Outcome\",\"operator\":\"!eq\",\"value\":\"exception\"}}"`

## Enable logging on your Worker

Enable logging on your Worker by adding a new property, `logpush = true`, to your Wrangler file. This can be added either in the top-level configuration or under an [environment](/workers/wrangler/environments/). Any new Workers with this property will automatically get picked up by the Logpush job.

<WranglerConfig>

```toml
# Top-level configuration

name = "my-worker"
main = "src/index.js"
compatibility_date = "2022-07-12"

workers_dev = false
logpush = true
route = { pattern = "example.org/*", zone_name = "example.org" }
```

</WranglerConfig>

Configure via multipart script upload API:

```bash
curl --request PUT \
"https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}" \
--header "Authorization: Bearer <API_TOKEN>" \
--form 'metadata={"main_module": "my-worker.js", "logpush": true}' \
--form '"my-worker.js"=@./my-worker.js;type=application/javascript+module'
```

## Limits

The `logs` and `exceptions` fields have a combined limit of 16,384 characters before fields will start being truncated. Characters are counted in the order of all `exception.name`s, `exception.message`s, and then `log.message`s.

Once that character limit is reached all fields will be truncated with `"<<<Logpush: *field* truncated>>>"` for one message before dropping logs or exceptions.

### Example

To illustrate this, suppose our Logpush event looks like the JSON below and the limit is 50 characters (rather than the actual limit of 16,384). The algorithm will:

1. Count the characters in `exception.names`:
   1. `"SampleError"` and `"AuthError"` as 20 characters.
2. Count the characters in `exception.message`:
   1. `"something went wrong"` counted as 20 characters leaving 10 characters remaining.
   2. The first 10 characters of `"unable to process request authentication from client"` will be taken and counted before being truncated to `"unable to <<<Logpush: exception messages truncated>>>"`.
3. Count the characters in `log.message`:
   1. We've already begun truncation, so `"Hello "` will be replaced with `"<<<Logpush: messages truncated>>>"` and `"World!"` will be dropped.

#### Sample Input

```json
{
  "Exceptions": [
    {
      "Name": "SampleError",
      "Message": "something went wrong",
      "TimestampMs": 0
    },
    {
      "Name": "AuthError",
      "Message": "unable to process request authentication from client",
      "TimestampMs": 1
    },
  ],
  "Logs": [
    {
      "Level": "log",
      "Message": ["Hello "],
      "TimestampMs": 0
    },
    {
      "Level": "log",
      "Message": ["World!"],
      "TimestampMs": 0
    }
  ]
}
```

#### Sample Output

```json
{
  "Exceptions": [
    {
      "name": "SampleError",
      "message": "something went wrong",
      "TimestampMs": 0
    },
    {
      "name": "AuthError",
      "message": "unable to <<<Logpush: exception messages truncated>>>",
      "TimestampMs": 1
    },
  ],
  "Logs": [
    {
      "Level": "log",
      "Message": ["<<<Logpush: messages truncated>>>"],
      "TimestampMs": 0
    }
  ]
}
```

---

# Real-time logs

URL: https://developers.cloudflare.com/workers/observability/logs/real-time-logs/

import { TabItem, Tabs, Steps } from "~/components";

With Real-time logs, access all your log events in near real-time for log events happening globally. Real-time logs is helpful for immediate feedback, such as the status of a new deployment.

Real-time logs captures [invocation logs](/workers/observability/logs/workers-logs/#invocation-logs), [custom logs](/workers/observability/logs/workers-logs/#custom-logs), errors, and uncaught exceptions. For high-traffic applications, real-time logs may enter sampling mode, which means some messages will be dropped and a warning will appear in your logs.

:::caution

Real-time logs are not available for zones on the [Cloudflare China Network](/china-network/).

:::

## View logs from the dashboard

To view real-time logs associated with any deployed Worker using the Cloudflare dashboard:

<Steps>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In Account Home, go to **Workers & Pages**.
3. In **Overview**, select your **Worker**.
4. Select **Logs**.
5. In the right-hand navigation bar, select **Live**.
</Steps>

## View logs using `wrangler tail`

To view real-time logs associated with any deployed Worker using Wrangler:

1. Go to your Worker project directory.
2. Run [`npx wrangler tail`](/workers/wrangler/commands/#tail).

This will log any incoming requests to your application available in your local terminal.

The output of each `wrangler tail` log is a structured JSON object:

```json
{
	"outcome": "ok",
	"scriptName": null,
	"exceptions": [],
	"logs": [],
	"eventTimestamp": 1590680082349,
	"event": {
		"request": {
			"url": "https://www.bytesized.xyz/",
			"method": "GET",
			"headers": {},
			"cf": {}
		}
	}
}
```

By piping the output to tools like [`jq`](https://stedolan.github.io/jq/), you can query and manipulate the requests to look for specific information:

```sh
npx wrangler tail | jq .event.request.url
```

```sh output
"https://www.bytesized.xyz/"
"https://www.bytesized.xyz/component---src-pages-index-js-a77e385e3bde5b78dbf6.js"
"https://www.bytesized.xyz/page-data/app-data.json"
```

You can customize how `wrangler tail` works to fit your needs. Refer to [the `wrangler tail` documentation](/workers/wrangler/commands/#tail) for available configuration options.

## Limits

:::note

You can filter real-time logs in the dashboard or using [`wrangler tail`](/workers/wrangler/commands/#tail). If your Worker has a high volume of messages, filtering real-time logs can help mitgate messages from being dropped.

:::

Note that:

- Real-time logs does not store Workers Logs. To store logs, use [Workers Logs](/workers/observability/logs/workers-logs).
- If your Worker has a high volume of traffic, the real-time logs might enter sampling mode. This will cause some of your messages to be dropped and a warning to appear in your logs.
- Logs from any [Durable Objects](/durable-objects/) your Worker is using will show up in the dashboard.
- A maximum of 10 clients can view a Worker's logs at one time. This can be a combination of either dashboard sessions or `wrangler tail` calls.

## Persist logs

Logs can be persisted, filtered, and analyzed with [Workers Logs](/workers/observability/logs/workers-logs). To send logs to a third party, use [Workers Logpush](/workers/observability/logs/logpush/) or [Tail Workers](/workers/observability/logs/tail-workers/).

## Related resources

- [Errors and exceptions](/workers/observability/errors/) - Review common Workers errors.
- [Local development and testing](/workers/development-testing/) - Develop and test you Workers locally.
- [Workers Logs](/workers/observability/logs/workers-logs) - Collect, store, filter and analyze logging data emitted from Cloudflare Workers.
- [Logpush](/workers/observability/logs/logpush/) - Learn how to push Workers Trace Event Logs to supported destinations.
- [Tail Workers](/workers/observability/logs/tail-workers/) - Learn how to attach Tail Workers to transform your logs and send them to HTTP endpoints.
- [Source maps and stack traces](/workers/observability/source-maps) - Learn how to enable source maps and generate stack traces for Workers.

---

# Tail Workers

URL: https://developers.cloudflare.com/workers/observability/logs/tail-workers/

import { WranglerConfig } from "~/components";

A Tail Worker receives information about the execution of other Workers (known as producer Workers), such as HTTP statuses, data passed to `console.log()` or uncaught exceptions. Tail Workers can process logs for alerts, debugging, or analytics.

Tail Workers are available to all customers on the Workers Paid and Enterprise tiers. Tail Workers are billed by [CPU time](/workers/platform/pricing/#workers), not by the number of requests.

![Tail Worker diagram](~/assets/images/workers/platform/tail-workers.png)

A Tail Worker is automatically invoked after the invocation of a producer Worker (the Worker the Tail Worker will track) that contains the application logic. It captures events after the producer has finished executing. Events throughout the request lifecycle, including potential sub-requests via [Service Bindings](/workers/runtime-apis/bindings/service-bindings/) and [Dynamic Dispatch](/cloudflare-for-platforms/workers-for-platforms/get-started/configuration/), will be included. You can filter, change the format of the data, and send events to any HTTP endpoint. For quick debugging, Tail Workers can be used to send logs to [KV](/kv/api/) or any database.

## Configure Tail Workers

To configure a Tail Worker:

1. [Create a Worker](/workers/get-started/guide) to serve as the Tail Worker.
2. Add a [`tail()`](/workers/runtime-apis/handlers/tail/) handler to your Worker. The `tail()` handler is invoked every time the producer Worker to which a Tail Worker is connected is invoked. The following Worker code is a Tail Worker that sends its data to an HTTP endpoint:

```js
export default {
  async tail(events) {
    fetch("https://example.com/endpoint", {
      method: "POST",
      body: JSON.stringify(events),
    })
  }
}
```

The following Worker code is an example of what the `events` object may look like:

```json
[
  {
    "scriptName": "Example script",
    "outcome": "exception",
    "eventTimestamp": 1587058642005,
    "event": {
      "request": {
        "url": "https://example.com/some/requested/url",
        "method": "GET",
        "headers": {
          "cf-ray": "57d55f210d7b95f3",
          "x-custom-header-name": "my-header-value"
        },
        "cf": {
          "colo": "SJC"
        }
      }
    },
    "logs": [
      {
        "message": ["string passed to console.log()"],
        "level": "log",
        "timestamp": 1587058642005
      }
    ],
    "exceptions": [
      {
        "name": "Error",
        "message": "Threw a sample exception",
        "timestamp": 1587058642005
      }
    ],
    "diagnosticsChannelEvents": [
      {
        "channel": "foo",
        "message": "The diagnostic channel message",
        "timestamp": 1587058642005
      }
    ]
  }
]
```

3. Add the following to the Wrangler file of the producer Worker:

<WranglerConfig>

```toml
tail_consumers = [{service = "<TAIL_WORKER_NAME>"}]
```

</WranglerConfig>

:::note

The Worker that you add a `tail_consumers` binding to must have a `tail()` handler defined.
:::

## Related resources

* [`tail()`](/workers/runtime-apis/handlers/tail/) Handler API docs - Learn how to set up a `tail()` handler in your Worker.

- [Errors and exceptions](/workers/observability/errors/) - Review common Workers errors.
- [Local development and testing](/workers/development-testing/) - Develop and test you Workers locally.
- [Source maps and stack traces](/workers/observability/source-maps) - Learn how to enable source maps and generate stack traces for Workers.

---

# Workers Logs

URL: https://developers.cloudflare.com/workers/observability/logs/workers-logs/

import { TabItem, Tabs, Steps, Render, WranglerConfig } from "~/components"

Workers Logs lets you automatically collect, store, filter, and analyze logging data emitted from Cloudflare Workers. Data is written to your Cloudflare Account, and you can query it in the dashboard for each of your Workers. All newly created Workers will come with the observability setting enabled by default.

Logs include [invocation logs](/workers/observability/logs/workers-logs/#invocation-logs), [custom logs](/workers/observability/logs/workers-logs/#custom-logs), errors, and uncaught exceptions.

![Example showing the Workers Logs Dashboard](~/assets/images/workers-observability/preview.png)

To send logs to a third party, use [Workers Logpush](/workers/observability/logs/logpush/) or [Tail Workers](/workers/observability/logs/tail-workers/).

## Enable Workers Logs

:::note[Wrangler version]
Minimum required Wrangler version: 3.78.6. Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/).
:::

You must add the observability setting for your Worker to write logs to Workers Logs. Add the following setting to your Worker's Wrangler file and redeploy your Worker.

<WranglerConfig>

	```toml
	[observability]
	enabled = true
	head_sampling_rate = 1 # optional. default = 1.
	```

</WranglerConfig>

[Head-based sampling](/workers/observability/logs/workers-logs/#head-based-sampling) allows you set the percentage of Workers requests that are logged.

### Enabling with environments

[Environments](/workers/wrangler/environments/) allow you to deploy the same Worker application with different configurations. For example, you may want to configure a different `head_sampling_rate` to staging and production. To configure observability for an environment named `staging`:
	1. Add the following configuration below `[env.staging]`


	<WranglerConfig>

	```toml
	[env.staging.observability]
	enabled = true
	head_sampling_rate = 1 # optional
	```

	</WranglerConfig>

	2. Deploy your Worker with `npx wrangler deploy -e staging`
	3. Repeat step 1 and 2 for each environment.

## View logs from the dashboard

Access logs for your Worker from the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/services/view/:worker/production/observability/logs/).

<Steps>
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/services/view/:worker/production/observability/logs/) and select your account.
2. In Account Home, go to **Workers & Pages**.
3. In **Overview**, select your **Worker**.
4. Select **Logs**.
</Steps>

## Best Practices

### Logging structured JSON objects

To get the most out of Workers Logs, it is recommended you log in JSON format. Workers Logs automatically extracts the fields and indexes them intelligently in the database. The benefit of this structured logging technique is in how it allows you to easily segment data across any dimension for fields with unlimited cardinality. Consider the following scenarios:

| Scenario | Logging Code                                               | Event Log (Partial)                           |
| -------- | ---------------------------------------------------------- | --------------------------------------------- |
|    1     | `console.log("user_id: " + 123)`                           | `{message: "user_id: 123"}`                   |
|    2     | `console.log({user_id: 123})`                              | `{user_id: 123}`                              |
|    3     | `console.log({user_id: 123, user_email: "a@example.com"})` | `{user_id: 123, user_email: "a@example.com"}` |

The difference between these examples is in how you index your logs to enable faster queries. In scenario 1, the `user_id` is embedded within a message. To find all logs relating to a particular user_id, you would have to run a text match. In scenarios 2 and 3, your logs can be filtered against the keys `user_id` and `user_email`.

## Features

### Invocation Logs

Each Workers invocation returns a single invocation log that contains details such as the Request, Response, and related metadata. These invocation logs can be identified by the field `$cloudflare.$metadata.type = "cf-worker-event"`. Each invocation log is enriched with information available to Cloudflare in the context of the invocation.

In the Workers Logs UI, logs are presented with a localized timestamp and a message. The message is dependent on the invocation handler. For example, Fetch requests will have a message describing the request method and the request URL, while cron events will be listed as cron. Below is a list of invocation handlers along with their invocation message.

Invocation logs can be disabled in wrangler by adding the `invocation_logs = false` configuration.



<WranglerConfig>

```toml
[observability.logs]
invocation_logs = false
```

</WranglerConfig>

| Invocation Handler                                              | Invocation Message         |
| --------------------------------------------------------------- | -------------------------- |
| [Alarm](/durable-objects/api/alarms/)                           | \<Scheduled Time\>         |
| [Email](/email-routing/email-workers/runtime-api/)              | \<Email Recipient\>        |
| [Fetch](/workers/runtime-apis/handlers/fetch/)                  | \<Method\> \<URL\>         |
| [Queue](/queues/configuration/javascript-apis/#consumer)        | \<Queue Name\>             |
| [Cron](/workers/runtime-apis/handlers/scheduled/)               | \<UNIX-cron schedule\>     |
| [Tail](/workers/runtime-apis/handlers/tail/)                    | tail                       |
| [RPC](/workers/runtime-apis/rpc/)                               | \<RPC method\>             |
| [WebSocket](/workers/examples/websockets/)                      | \<WebSocket Event Type\>   |

### Custom logs

By default a Worker will emit [invocation logs](/workers/observability/logs/workers-logs/#invocation-logs) containing details about the request, response and related metadata.

You can also add custom logs throughout your code. Any `console.log` statements within your Worker will be visible in Workers Logs. The following example demonstrates a custom `console.log` within a Worker request handler.

<Tabs> <TabItem label="Module Worker" icon="seti:javascript">

```js
export default {
        async fetch(request) {
                const { cf } = request;
                const { city, country } = cf;

                console.log(`Request came from city: ${city} in country: ${country}`);

                return new Response("Hello worker!", {
                        headers: { "content-type": "text/plain" },
                });
        },
};
```

</TabItem> <TabItem label="Service Worker" icon="seti:javascript">

:::caution[Service Workers are deprecated]

Service Workers are deprecated, but still supported. We recommend using [Module Workers](/workers/reference/migrate-to-module-workers/) instead. New features may not be supported for Service Workers.

:::

```js
addEventListener("fetch", (event) => {
        event.respondWith(handleRequest(event.request));
});

/**
 * Respond with hello worker text
 * @param {Request} request
 */
async function handleRequest(request) {
        const { cf } = request;
        const { city, country } = cf;

        console.log(`Request came from city: ${city} in country: ${country}`);

        return new Response("Hello worker!", {
                headers: { "content-type": "text/plain" },
        });
}
```

</TabItem> </Tabs>

After you deploy the code above, view your Worker's logs in [the dashboard](/workers/observability/logs/workers-logs/#view-logs-from-the-dashboard) or with [real-time logs](/workers/observability/logs/real-time-logs/).

### Head-based sampling

Head-based sampling allows you to log a percentage of incoming requests to your Cloudflare Worker. Especially for high-traffic applications, this helps reduce log volume and manage costs, while still providing meaningful insights into your application's performance. When you configure a head-based sampling rate, you can control the percentage of requests that get logged. All logs within the context of the request are collected.

To enable head-based sampling, set `head_sampling_rate` within the observability configuration. The valid range is from 0 to 1, where 0 indicates zero out of one hundred requests are logged, and 1 indicates every request is logged. If `head_sampling_rate` is unspecified, it is configured to a default value of 1 (100%). In the example below, `head_sampling_rate` is set to 0.01, which means one out of every one hundred requests is logged.



<WranglerConfig>

```toml
[observability]
enabled = true
head_sampling_rate = 0.01 # 1% sampling rate
```

</WranglerConfig>

## Limits

| Description                                                        | Limit      |
| ------------------------------------------------------------------ | ---------- |
| Maximum log retention period                                       | 7 Days     |
| Maximum logs per account per day<sup>1</sup>                       | 5 Billion  |
| Maximum log size<sup>2</sup>                                       | 256 KB     |

<sup>1</sup> There is a daily limit of 5 billion logs per account per day. After the limit is exceed, a 1% head-based sample will be applied for the remainder of the day.

<sup>2</sup> A single log has a maximum size limit of [256 KB](/workers/platform/limits/#log-size). Logs exceeding that size will be truncated and the log's `$cloudflare.truncated` field will be set to true.

## Pricing

:::note[Billing start date]
Workers Logs billing will begin on April 21, 2025.
:::
<Render file="workers_logs_pricing" />

### Examples

#### Example 1

A Worker serves 15 million requests per month. Each request emits 1 invocation log and 1 `console.log`. `head_sampling_rate` is configured to 1.

|            | Monthly Costs     | Formula                                                                                                                |
| ---------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Logs**   | $6.00             | ((15,000,000 requests per month \* 2 logs per request \* 100% sample) - 20,000,000 included logs) / 1,000,000 \* $0.60    |
| **Total**  | $6.00             |                                                                                                                        |

#### Example 2

A Worker serves 1 billion requests per month. Each request emits 1 invocation log and 1 `console.log`. `head_sampling_rate` is configured to 0.1.

|            | Monthly Costs     | Formula                                                                                                                |
| ---------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Logs**   | $108.00           | ((1,000,000,000 requests per month \* 2 logs per request \* 10% sample) - 20,000,000 included logs) / 1,000,000 \* $0.60 |
| **Total**  | $108.00           |                                                                                                                        |

---

# Integrations

URL: https://developers.cloudflare.com/workers/observability/third-party-integrations/

import { DirectoryListing } from "~/components";

Send your telemetry data to third parties.

<DirectoryListing />

---

# Sentry

URL: https://developers.cloudflare.com/workers/observability/third-party-integrations/sentry/

Connect to a Sentry project from your Worker to automatically send
errors and uncaught exceptions to Sentry.

---

# Bindings (env)

URL: https://developers.cloudflare.com/workers/runtime-apis/bindings/

import { DirectoryListing, WranglerConfig } from "~/components";

Bindings allow your Worker to interact with resources on the Cloudflare Developer Platform. Bindings provide better performance and less restrictions when accessing resources from Workers than the [REST APIs](/api/) which are intended for non-Workers applications.

The following bindings available today:

<DirectoryListing />

## What is a binding?

When you declare a binding on your Worker, you grant it a specific capability, such as being able to read and write files to an [R2](/r2/) bucket. For example:

<WranglerConfig>

```toml
main = "./src/index.js"
r2_buckets = [
  { binding = "MY_BUCKET", bucket_name = "<MY_BUCKET_NAME>" }
]
```

</WranglerConfig>

```js
export default {
	async fetch(request, env) {
		const key = url.pathname.slice(1);
		await env.MY_BUCKET.put(key, request.body);
		return new Response(`Put ${key} successfully!`);
	},
};
```

You can think of a binding as a permission and an API in one piece. With bindings, you never have to add secret keys or tokens to your Worker in order to access resources on your Cloudflare account — the permission is embedded within the API itself. The underlying secret is never exposed to your Worker's code, and therefore can't be accidentally leaked.

## Making changes to bindings

When you deploy a change to your Worker, and only change its bindings (i.e. you don't change the Worker's code), Cloudflare may reuse existing isolates that are already running your Worker. This improves performance — you can change an environment variable or other binding without unnecessarily reloading your code.

As a result, you must be careful when "polluting" global scope with derivatives of your bindings. Anything you create there might continue to exist despite making changes to any underlying bindings. Consider an external client instance which uses a secret API key accessed from `env`: if you put this client instance in global scope and then make changes to the secret, a client instance using the original value might continue to exist. The correct approach would be to create a new client instance for each request.

The following is a good approach:

```ts
export default {
	fetch(request, env) {
		let client = new Client(env.MY_SECRET); // `client` is guaranteed to be up-to-date with the latest value of `env.MY_SECRET` since a new instance is constructed with every incoming request

		// ... do things with `client`
	},
};
```

Compared to this alternative, which might have surprising and unwanted behavior:

```ts
let client = undefined;

export default {
	fetch(request, env) {
		client ??= new Client(env.MY_SECRET); // `client` here might not be updated when `env.MY_SECRET` changes, since it may already exist in global scope

		// ... do things with `client`
	},
};
```

If you have more advanced needs, explore the [AsyncLocalStorage API](/workers/runtime-apis/nodejs/asynclocalstorage/), which provides a mechanism for exposing values down to child execution handlers.

## How to access `env`

Bindings are located on the `env` object, which can be accessed in several ways:

- It is an argument to entrypoint handlers such as [`fetch`](/workers/runtime-apis/fetch/):

  ```js
  export default {
  	async fetch(request, env) {
  		return new Response(`Hi, ${env.NAME}`);
  	},
  };
  ```

* It is as class property on [WorkerEntrypoint](/workers/runtime-apis/bindings/service-bindings/rpc/#bindings-env),
  [DurableObject](/durable-objects/), and [Workflow](/workflows/):

  ```js
  export class MyDurableObject extends DurableObject {
  	async sayHello() {
  		return `Hi, ${this.env.NAME}!`;
  	}
  }
  ```

* It can be imported from `cloudflare:workers`:

  ```js
  import { env } from "cloudflare:workers";
  console.log(`Hi, ${this.env.Name}`);
  ```

### Importing `env` as a global

Importing `env` from `cloudflare:workers` is useful when you need to access a binding
such as [secrets](/workers/configuration/secrets/) or [environment variables](/workers/configuration/environment-variables/)
in top-level global scope. For example, to initialize an API client:

```js
import { env } from "cloudflare:workers";
import ApiClient from "example-api-client";

// API_KEY and LOG_LEVEL now usable in top-level scope
let apiClient = ApiClient.new({ apiKey: env.API_KEY });
const LOG_LEVEL = env.LOG_LEVEL || "info";

export default {
	fetch(req) {
		// you can use apiClient or LOG_LEVEL, configured before any request is handled
	},
};
```

Workers do not allow I/O from outside a request context. This means that even
though `env` is accessible from the top-level scope, you will not be able to access
every binding's methods.

For instance, environment variables and secrets are accessible, and you are able to
call `env.NAMESPACE.get` to get a [Durable Object stub](/durable-objects/api/stub/) in the
top-level context. However, calling methods on the Durable Object stub, making [calls to a KV store](/kv/api/),
and [calling to other Workers](/workers/runtime-apis/bindings/service-bindings) will not work.

```js
import { env } from "cloudflare:workers";

// This would error!
// env.KV.get('my-key')

export default {
	async fetch(req) {
		// This works
		let myVal = await env.KV.get("my-key");
		Response.new(myVal);
	},
};
```

Additionally, importing `env` from `cloudflare:workers` lets you avoid passing `env`
as an argument through many function calls if you need to access a binding from a deeply-nested
function. This can be helpful in a complex codebase.

```js
import { env } from "cloudflare:workers";

export default {
	fetch(req) {
		Response.new(sayHello());
	},
};

// env is not an argument to sayHello...
function sayHello() {
	let myName = getName();
	return `Hello, ${myName}`;
}

// ...nor is it an argument to getName
function getName() {
	return env.MY_NAME;
}
```

:::note
While using `env` from `cloudflare:workers` may be simpler to write than passing it
through a series of function calls, passing `env` as an argument is a helpful pattern
for dependency injection and testing.
:::

### Overriding `env` values

The `withEnv` function provides a mechanism for overriding values of `env`.

Imagine a user has defined the [environment variable](/workers/configuration/environment-variables/)
"NAME" to be "Alice" in their Wrangler configuration file and deployed a Worker. By default, logging
`env.NAME` would print "Alice". Using the `withEnv` function, you can override the value of
"NAME".

```js
import { env, withEnv } from "cloudflare:workers";

function logName() {
	console.log(env.NAME);
}

export default {
	fetch(req) {
		// this will log "Alice"
		logName();

		withEnv({ NAME: "Bob" }, () => {
			// this will log "Bob"
			logName();
		});

		// ...etc...
	},
};
```

This can be useful when testing code that relies on an imported `env` object.

---

# mTLS

URL: https://developers.cloudflare.com/workers/runtime-apis/bindings/mtls/

import { TabItem, Tabs, WranglerConfig } from "~/components";

When using [HTTPS](https://www.cloudflare.com/learning/ssl/what-is-https/), a server presents a certificate for the client to authenticate in order to prove their identity. For even tighter security, some services require that the client also present a certificate.

This process - known as [mTLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/) - moves authentication to the protocol of TLS, rather than managing it in application code. Connections from unauthorized clients are rejected during the TLS handshake instead.

To present a client certificate when communicating with a service, create a mTLS certificate [binding](/workers/runtime-apis/bindings/) in your Worker project's Wrangler file. This will allow your Worker to present a client certificate to a service on your behalf.

:::caution

Currently, mTLS for Workers cannot be used for requests made to a service that is a [proxied zone](/dns/proxy-status/) on Cloudflare. If your Worker presents a client certificate to a service proxied by Cloudflare, Cloudflare will return a `520` error.

:::

First, upload a certificate and its private key to your account using the [`wrangler mtls-certificate`](/workers/wrangler/commands/#mtls-certificate) command:

:::caution

The `wrangler mtls-certificate upload` command requires the [SSL and Certificates Edit API token scope](/fundamentals/api/reference/permissions/). If you are using the OAuth flow triggered by `wrangler login`, the correct scope is set automatically. If you are using API tokens, refer to [Create an API token](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) to set the right scope for your API token.
:::

```sh
npx wrangler mtls-certificate upload --cert cert.pem --key key.pem --name my-client-cert
```

Then, update your Worker project's Wrangler file to create an mTLS certificate binding:

<WranglerConfig>

```toml title="wrangler.toml"
mtls_certificates = [
  { binding = "MY_CERT", certificate_id = "<CERTIFICATE_ID>" }
]
```

</WranglerConfig>

:::note

Certificate IDs are displayed after uploading, and can also be viewed with the command `wrangler mtls-certificate list`.
:::

Adding an mTLS certificate binding includes a variable in the Worker's environment on which the `fetch()` method is available. This `fetch()` method uses the standard [Fetch](/workers/runtime-apis/fetch/) API and has the exact same signature as the global `fetch`, but always presents the client certificate when establishing the TLS connection.

:::note

mTLS certificate bindings present an API similar to [service bindings](/workers/runtime-apis/bindings/service-bindings).
:::

### Interface

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async fetch(request, environment) {
		return await environment.MY_CERT.fetch("https://a-secured-origin.com");
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```js
interface Env {
  MY_CERT: Fetcher;
}

export default {
    async fetch(request, environment): Promise<Response> {
        return await environment.MY_CERT.fetch("https://a-secured-origin.com")
    }
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

---

# Rate Limiting

URL: https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/

import { TabItem, Tabs, WranglerConfig } from "~/components"

The Rate Limiting API lets you define rate limits and write code around them in your Worker.

You can use it to enforce:

* Rate limits that are applied after your Worker starts, only once a specific part of your code is reached
* Different rate limits for different types of customers or users (ex: free vs. paid)
* Resource-specific or path-specific limits (ex: limit per API route)
* Any combination of the above

The Rate Limiting API is backed by the same infrastructure that serves the [Rate limiting rules](/waf/rate-limiting-rules/) that are built into the [Cloudflare Web Application Firewall (WAF)](/waf/).

:::caution[The Rate Limiting API is in open beta]


* You must use version 3.45.0 or later of the [Wrangler CLI](/workers/wrangler)

We want your feedback. Tell us what you'd like to see in the [#workers-discussions](https://discord.com/channels/595317990191398933/779390076219686943) or [#workers-help](https://discord.com/channels/595317990191398933/1052656806058528849) channels of the [Cloudflare Developers Discord](https://discord.cloudflare.com/). You can find the an archive of the previous discussion in [#rate-limiting-beta](https://discord.com/channels/595317990191398933/1225429769219211436)


:::

## Get started

First, add a [binding](/workers/runtime-apis/bindings) to your Worker that gives it access to the Rate Limiting API:

<WranglerConfig>

```toml
main = "src/index.js"

# The rate limiting API is in open beta.
[[unsafe.bindings]]
name = "MY_RATE_LIMITER"
type = "ratelimit"
# An identifier you define, that is unique to your Cloudflare account.
# Must be an integer.
namespace_id = "1001"

# Limit: the number of tokens allowed within a given period in a single
# Cloudflare location
# Period: the duration of the period, in seconds. Must be either 10 or 60
simple = { limit = 100, period = 60 }
```

</WranglerConfig>

This binding makes the `MY_RATE_LIMITER` binding available, which provides a `limit()` method:

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```javascript
export default {
  async fetch(request, env) {
    const { pathname } = new URL(request.url)

    const { success } = await env.MY_RATE_LIMITER.limit({ key: pathname }) // key can be any string of your choosing
    if (!success) {
      return new Response(`429 Failure – rate limit exceeded for ${pathname}`, { status: 429 })
    }

    return new Response(`Success!`)
  }
}
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Env {
  MY_RATE_LIMITER: any;
}

export default {
  async fetch(request, env): Promise<Response> {
    const { pathname } = new URL(request.url)

    const { success } = await env.MY_RATE_LIMITER.limit({ key: pathname }) // key can be any string of your choosing
    if (!success) {
      return new Response(`429 Failure – rate limit exceeded for ${pathname}`, { status: 429 })
    }

    return new Response(`Success!`)
  }
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

The `limit()` API accepts a single argument — a configuration object with the `key` field.

* The key you provide can be any `string` value.
* A common pattern is to define your key by combining a string that uniquely identifies the actor initiating the request (ex: a user ID or customer ID) and a string that identifies a specific resource (ex: a particular API route).

You can define and configure multiple rate limiting configurations per Worker, which allows you to define different limits against incoming request and/or user parameters as needed to protect your application or upstream APIs.

For example, here is how you can define two rate limiting configurations for free and paid tier users:



<WranglerConfig>

```toml
main = "src/index.js"

# Free user rate limiting
[[unsafe.bindings]]
name = "FREE_USER_RATE_LIMITER"
type = "ratelimit"
namespace_id = "1001"
simple = { limit = 100, period = 60 }

# Paid user rate limiting
[[unsafe.bindings]]
name = "PAID_USER_RATE_LIMITER"
type = "ratelimit"
namespace_id = "1002"
simple = { limit = 1000, period = 60 }
```

</WranglerConfig>

## Configuration

A rate limiting binding has three settings:

1. `namespace_id` (number) - a positive integer that uniquely defines this rate limiting configuration - e.g. `namespace_id = "999"`.
2. `limit` (number) - the limit (number of requests, number of API calls) to be applied. This is incremented when you call the `limit()` function in your Worker.
3. `period` (seconds) - must be `10` or `60`. The period to measure increments to the `limit` over, in seconds.

For example, to apply a rate limit of 1500 requests per minute, you would define a rate limiting configuration as follows:



<WranglerConfig>

```toml
[[unsafe.bindings]]
name = "MY_RATE_LIMITER"
type = "ratelimit"
namespace_id = "1001"

# 1500 requests - calls to limit() increment this
simple = { limit = 1500, period = 60 }
```

</WranglerConfig>

## Best practices

The `key` passed to the `limit` function, that determines what to rate limit on, should represent a unique characteristic of a user or class of user that you wish to rate limit.

* Good choices include API keys in `Authorization` HTTP headers, URL paths or routes, specific query parameters used by your application, and/or user IDs and tenant IDs. These are all stable identifiers and are unlikely to change from request-to-request.
* It is not recommended to use IP addresses or locations (regions or countries), since these can be shared by many users in many valid cases. You may find yourself unintentionally rate limiting a wider group of users than you intended by rate limiting on these keys.

```ts
// Recommended: use a key that represents a specific user or class of user
const url = new URL(req.url)
const userId = url.searchParams.get("userId") || ""
const { success } = await env.MY_RATE_LIMITER.limit({ key: userId })

// Not recommended:  many users may share a single IP, especially on mobile networks
// or when using privacy-enabling proxies
const ipAddress = req.headers.get("cf-connecting-ip") || ""
const { success } = await env.MY_RATE_LIMITER.limit({ key: ipAddress })
```

## Locality

Rate limits that you define and enforce in your Worker are local to the [Cloudflare location](https://www.cloudflare.com/network/) that your Worker runs in.

For example, if a request comes in from Sydney, Australia, to the Worker shown above, after 100 requests in a 60 second window, any further requests for a particular path would be rejected, and a 429 HTTP status code returned. But this would only apply to requests served in Sydney. For each unique key you pass to your rate limiting binding, there is a unique limit per Cloudflare location.

## Performance

The Rate Limiting API in Workers is designed to be fast.

The underlying counters are cached on the same machine that your Worker runs in, and updated asynchronously in the background by communicating with a backing store that is within the same Cloudflare location.

This means that while in your code you `await` a call to the `limit()` method:

```javascript
const { success } = await env.MY_RATE_LIMITER.limit({ key: customerId })
```

You are not waiting on a network request. You can use the Rate Limiting API without introducing any meaningful latency to your Worker.

## Accuracy

The above also means that the Rate Limiting API is permissive, eventually consistent, and intentionally designed to not be used as an accurate accounting system.

For example, if many requests come in to your Worker in a single Cloudflare location, all rate limited on the same key, the [isolate](/workers/reference/how-workers-works) that serves each request will check against its locally cached value of the rate limit. Very quickly, but not immediately, these requests will count towards the rate limit within that Cloudflare location.

## Examples

* [`@elithrar/workers-hono-rate-limit`](https://github.com/elithrar/workers-hono-rate-limit) — Middleware that lets you easily add rate limits to routes in your [Hono](https://hono.dev/) application.
* [`@hono-rate-limiter/cloudflare`](https://github.com/rhinobase/hono-rate-limiter) — Middleware that lets you easily add rate limits to routes in your [Hono](https://hono.dev/) application, with multiple data stores to choose from.

---

# Version metadata

URL: https://developers.cloudflare.com/workers/runtime-apis/bindings/version-metadata/

import { TabItem, Tabs, WranglerConfig } from "~/components"

The version metadata binding can be used to access metadata associated with a [version](/workers/configuration/versions-and-deployments/#versions) from inside the Workers runtime.

Worker version ID, version tag and timestamp of when the version was created are available through the version metadata binding. They can be used in events sent to [Workers Analytics Engine](/analytics/analytics-engine/) or to any third-party analytics/metrics service in order to aggregate by Worker version.

To use the version metadata binding, update your Worker's Wrangler file:

<WranglerConfig>

```toml title="wrangler.toml"
[version_metadata]
binding = "CF_VERSION_METADATA"
```

</WranglerConfig>

### Interface

An example of how to access the version ID and version tag from within a Worker to send events to [Workers Analytics Engine](/analytics/analytics-engine/):

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
  async fetch(request, env, ctx) {
    const { id: versionId, tag: versionTag, timestamp: versionTimestamp } = env.CF_VERSION_METADATA;
    env.WAE.writeDataPoint({
      indexes: [versionId],
      blobs: [versionTag, versionTimestamp],
      //...
    });
    //...
  },
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Environment {
  CF_VERSION_METADATA: WorkerVersionMetadata;
  WAE: AnalyticsEngineDataset;
}

export default {
  async fetch(request, env, ctx) {
    const { id: versionId, tag: versionTag } = env.CF_VERSION_METADATA;
    env.WAE.writeDataPoint({
      indexes: [versionId],
      blobs: [versionTag],
      //...
    });
    //...
  },
} satisfies ExportedHandler<Env>;
```

</TabItem> </Tabs>

---

# Fetch Handler

URL: https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/

## Background

Incoming HTTP requests to a Worker are passed to the `fetch()` handler as a [`Request`](/workers/runtime-apis/request/) object. To respond to the request with a response, return a [`Response`](/workers/runtime-apis/response/) object:

```js
export default {
	async fetch(request, env, ctx) {
		return new Response('Hello World!');
	},
};
```

:::note


The Workers runtime does not support `XMLHttpRequest` (XHR). Learn the difference between `XMLHttpRequest` and `fetch()` in the [MDN](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) documentation.


:::

### Parameters



* `request` Request

  * The incoming HTTP request.

* `env` object

  * The [bindings](/workers/configuration/environment-variables/) available to the Worker. As long as the [environment](/workers/wrangler/environments/) has not changed, the same object (equal by identity) may be passed to multiple requests.

* <code>ctx.waitUntil(promisePromise)</code> : void

  * Refer to [`waitUntil`](/workers/runtime-apis/context/#waituntil).

* <code>ctx.passThroughOnException()</code> : void

  * Refer to [`passThroughOnException`](/workers/runtime-apis/context/#passthroughonexception).

---

# Handlers

URL: https://developers.cloudflare.com/workers/runtime-apis/handlers/

import { DirectoryListing } from "~/components"

Handlers are methods on Workers that can receive and process external inputs, and can be invoked from outside your Worker. For example, the `fetch()` handler receives an HTTP request, and can return a response:

```js
export default {
	async fetch(request, env, ctx) {
		return new Response('Hello World!');
	},
};
```

The following handlers are available within Workers:

<DirectoryListing />

## Handlers in Python Workers

When you [write Workers in Python](/workers/languages/python/), handlers are prefixed with `on_`. For example, `on_fetch` or `on_scheduled`.

---

# Scheduled Handler

URL: https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/

import { TabItem, Tabs } from "~/components";

## Background

When a Worker is invoked via a [Cron Trigger](/workers/configuration/cron-triggers/), the `scheduled()` handler handles the invocation.

:::note[Testing scheduled() handlers in local development]

You can test the behavior of your `scheduled()` handler in local development using Wrangler.

Cron Triggers can be tested using `Wrangler` by passing in the `--test-scheduled` flag to [`wrangler dev`](/workers/wrangler/commands/#dev). This will expose a `/__scheduled` (or `/cdn-cgi/handler/scheduled` for Python Workers) route which can be used to test using a http request. To simulate different cron patterns, a `cron` query parameter can be passed in.

```sh
npx wrangler dev --test-scheduled

curl "http://localhost:8787/__scheduled?cron=*+*+*+*+*"

curl "http://localhost:8787/cdn-cgi/handler/scheduled?cron=*+*+*+*+*" # Python Workers
```

:::

---

## Syntax

<Tabs> <TabItem label="JavaScript" icon="seti:javascript">

```js
export default {
	async scheduled(controller, env, ctx) {
		ctx.waitUntil(doSomeTaskOnASchedule());
	},
};
```

</TabItem> <TabItem label="TypeScript" icon="seti:typescript">

```ts
interface Env {}
export default {
	async scheduled(
		controller: ScheduledController,
		env: Env,
		ctx: ExecutionContext,
	) {
		ctx.waitUntil(doSomeTaskOnASchedule());
	},
};
```

</TabItem> <TabItem label="Python" icon="seti:python">

```python
from workers import handler

@handler
async def on_scheduled(controller, env, ctx):
  ctx.waitUntil(doSomeTaskOnASchedule())
```

</TabItem></Tabs>

### Properties

- `controller.cron` string

  - The value of the [Cron Trigger](/workers/configuration/cron-triggers/) that started the `ScheduledEvent`.

- `controller.type` string

  - The type of event. This will always return `"scheduled"`.

- `controller.scheduledTime` number

  - The time the `ScheduledEvent` was scheduled to be executed in milliseconds since January 1, 1970, UTC. It can be parsed as <code>new Date(event.scheduledTime)</code>.

- `env` object

  - An object containing the bindings associated with your Worker using ES modules format, such as KV namespaces and Durable Objects.

- `ctx` object
  - An object containing the context associated with your Worker using ES modules format. Currently, this object just contains the `waitUntil` function.

### Methods

When a Workers script is invoked by a [Cron Trigger](/workers/configuration/cron-triggers/), the Workers runtime starts a `ScheduledEvent` which will be handled by the `scheduled` function in your Workers Module class. The `ctx` argument represents the context your function runs in, and contains the following methods to control what happens next:

- <code>ctx.waitUntil(promisePromise)</code> : void

  - Use this method to notify the runtime to wait for asynchronous tasks (for example, logging, analytics to third-party services, streaming and caching). The first `ctx.waitUntil` to fail will be observed and recorded as the status in the [Cron Trigger](/workers/configuration/cron-triggers/) Past Events table. Otherwise, it will be reported as a success.

---

# Tail Handler

URL: https://developers.cloudflare.com/workers/runtime-apis/handlers/tail/

## Background

The `tail()` handler is the handler you implement when writing a [Tail Worker](/workers/observability/logs/tail-workers/). Tail Workers can be used to process logs in real-time and send them to a logging or analytics service.

The `tail()` handler is called once each time the connected producer Worker is invoked.

To configure a Tail Worker, refer to [Tail Workers documentation](/workers/observability/logs/tail-workers/).

## Syntax

```js
export default {
  async tail(events, env, ctx) {
    fetch("<YOUR_ENDPOINT>", {
      method: "POST",
      body: JSON.stringify(events),
    })
  }
}
```

### Parameters



* `events` array

  * An array of [`TailItems`](/workers/runtime-apis/handlers/tail/#tailitems). One `TailItem` is collected for each event that triggers a Worker. For Workers for Platforms customers with a Tail Worker installed on the dynamic dispatch Worker, `events` will contain two elements: one for the dynamic dispatch Worker and one for the User Worker.

* `env` object

  * An object containing the bindings associated with your Worker using [ES modules format](/workers/reference/migrate-to-module-workers/), such as KV namespaces and Durable Objects.

* `ctx` object
  * An object containing the context associated with your Worker using [ES modules format](/workers/reference/migrate-to-module-workers/). Currently, this object just contains the `waitUntil` function.



### Properties



* `event.type` string

  * The type of event. This will always return `"tail"`.

* `event.traces` array

  * An array of [`TailItems`](/workers/runtime-apis/handlers/tail/#tailitems). One `TailItem` is collected for each event that triggers a Worker. For Workers for Platforms customers with a Tail Worker installed on the dynamic dispatch Worker, `events` will contain two elements: one for the dynamic dispatch Worker and one for the user Worker.

* <code>event.waitUntil(promisePromise)</code> : void

  * Refer to [`waitUntil`](/workers/runtime-apis/context/#waituntil). Note that unlike fetch event handlers, tail handlers do not return a value, so this is the only way for trace Workers to do asynchronous work.



### `TailItems`

#### Properties



* `scriptName` string

  * The name of the producer script.

* `event` object

  * Contains information about the Worker’s triggering event.
    * For fetch events: a [`FetchEventInfo` object](/workers/runtime-apis/handlers/tail/#fetcheventinfo)
    * For other event types: `null`, currently.

* `eventTimestamp` number

  * Measured in epoch time.

* `logs` array

  * An array of [TailLogs](/workers/runtime-apis/handlers/tail/#taillog).

* `exceptions` array

  * An array of [`TailExceptions`](/workers/runtime-apis/handlers/tail/#tailexception). A single Worker invocation might result in multiple unhandled exceptions, since a Worker can register multiple asynchronous tasks.

* `outcome` string

  * The outcome of the Worker invocation, one of:
    * `unknown`: outcome status was not set.
    * `ok`: The worker invocation succeeded.
    * `exception`: An unhandled exception was thrown.  This can happen for many reasons, including:
      * An uncaught JavaScript exception.
      * A fetch handler that does not result in a Response.
      * An internal error.
    * `exceededCpu`: The Worker invocation exceeded either its CPU limits.
    * `exceededMemory`: The Worker invocation exceeded memory limits.
    * `scriptNotFound`: An internal error from difficulty retrieving the Worker script.
    * `canceled`: The worker invocation was canceled before it completed. Commonly because the client disconnected before a response could be sent.
    * `responseStreamDisconnected`: The response stream was disconnected during deferred proxying. Happens when either the client or server hangs up early.



:::note[Outcome is not the same as HTTP status.]

Outcome is equivalent to the exit status of a script and an indicator of whether it has fully run to completion. A Worker outcome may differ from a response code if, for example:

* a script successfully processes a request but is logically designed to return a `4xx`/`5xx` response.
* a script sends a successful `200` response but an asynchronous task registered via `waitUntil()` later exceeds CPU or memory limits.
  :::

### `FetchEventInfo`

#### Properties



* `request` object

  * A [`TailRequest` object](/workers/runtime-apis/handlers/tail/#tailrequest).

* `response` object

  * A [`TailResponse` object](/workers/runtime-apis/handlers/tail/#tailresponse).


### `TailRequest`

#### Properties



* `cf` object

  * Contains the data from [`IncomingRequestCfProperties`](/workers/runtime-apis/request/#incomingrequestcfproperties).

* `headers` object

  * Header name/value entries (redacted by default). Header names are lowercased, and the values associated with duplicate header names are concatenated, with the string `", "` (comma space) interleaved, similar to [the Fetch standard](https://fetch.spec.whatwg.org/#concept-header-list-get).

* `method` string

  * The HTTP request method.

* `url` string

  * The HTTP request URL (redacted by default).



#### Methods



* `getUnredacted()` object

  * Returns a TailRequest object with unredacted properties



Some of the properties of `TailRequest` are redacted by default to make it harder to accidentally record sensitive information, like user credentials or API tokens. The redactions use heuristic rules, so they are subject to false positives and negatives. Clients can call `getUnredacted()` to bypass redaction, but they should always be careful about what information is retained, whether using the redaction or not.

* Header redaction: The header value will be the string `“REDACTED”` when the (case-insensitive) header name is `cookie`/`set-cookie` or contains a substring `"auth”`, `“key”`, `“secret”`, `“token”`, or `"jwt"`.
* URL redaction: For each greedily matched substring of ID characters (a-z, A-Z, 0-9, '+', '-', '\_') in the URL, if it meets the following criteria for a hex or base-64 ID, the substring will be replaced with the string `“REDACTED”`.
* Hex ID: Contains 32 or more hex digits, and contains only hex digits and separators ('+', '-', '\_')
* Base-64 ID: Contains 21 or more characters, and contains at least two uppercase, two lowercase, and two digits.

### `TailResponse`

#### Properties



* `status` number

  * The HTTP status code.



### `TailLog`

Records information sent to console functions.

#### Properties



* `timestamp` number

  * Measured in epoch time.

* `level` string

  * A string indicating the console function that was called. One of: `debug`, `info`, `log`, `warn`, `error`.

* `message` object

  * The array of parameters passed to the console function.


### `TailException`

Records an unhandled exception that occurred during the Worker invocation.

#### Properties



* `timestamp` number

  * Measured in epoch time.

* `name` string

  * The error type (For example,`Error`, `TypeError`, etc.).

* `message` object

  * The error description (For example, `"x" is not a function`).



## Related resources

* [Tail Workers](/workers/observability/logs/tail-workers/) - Configure a Tail Worker to receive information about the execution of other Workers.

---

# EventEmitter

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/eventemitter/

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

An `EventEmitter` is an object that emits named events that cause listeners to be called.

```js
import { EventEmitter } from 'node:events';

const emitter = new EventEmitter();
emitter.on('hello', (...args) => {
  console.log(...args);
});

emitter.emit('hello', 1, 2, 3);
```

The implementation in the Workers runtime fully supports the entire Node.js `EventEmitter` API. This includes the `captureRejections` option that allows improved handling of async functions as event handlers:

```js
const emitter = new EventEmitter({ captureRejections: true });
emitter.on('hello', async (...args) => {
  throw new Error('boom');
});
emitter.on('error', (err) => {
  // the async promise rejection is emitted here!
});
```

Refer to the [Node.js documentation for `EventEmitter`](https://nodejs.org/api/events.html#class-eventemitter) for more information.

---

# assert

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/assert/

import { Render } from "~/components";

<Render file="nodejs-compat-howto" />

The `assert` module in Node.js provides a number of useful assertions that are useful when building tests.

```js
import { strictEqual, deepStrictEqual, ok, doesNotReject } from "node:assert";

strictEqual(1, 1); // ok!
strictEqual(1, "1"); // fails! throws AssertionError

deepStrictEqual({ a: { b: 1 } }, { a: { b: 1 } }); // ok!
deepStrictEqual({ a: { b: 1 } }, { a: { b: 2 } }); // fails! throws AssertionError

ok(true); // ok!
ok(false); // fails! throws AssertionError

await doesNotReject(async () => {}); // ok!
await doesNotReject(async () => {
	throw new Error("boom");
}); // fails! throws AssertionError
```

:::note

In the Workers implementation of `assert`, all assertions run in, what Node.js calls, the strict assertion mode. In strict assertion mode, non-strict methods behave like their corresponding strict methods. For example, `deepEqual()` will behave like `deepStrictEqual()`.
:::

Refer to the [Node.js documentation for `assert`](https://nodejs.org/dist/latest-v19.x/docs/api/assert.html) for more information.

---

# AsyncLocalStorage

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/asynclocalstorage/

import { Render } from "~/components"

## Background

<Render file="nodejs-compat-howto" />

Cloudflare Workers provides an implementation of a subset of the Node.js [`AsyncLocalStorage`](https://nodejs.org/dist/latest-v18.x/docs/api/async_context.html#class-asynclocalstorage) API for creating in-memory stores that remain coherent through asynchronous operations.

## Constructor

```js
import { AsyncLocalStorage } from 'node:async_hooks';

const asyncLocalStorage = new AsyncLocalStorage();
```



* <code>new AsyncLocalStorage()</code> : AsyncLocalStorage

  * Returns a new `AsyncLocalStorage` instance.



## Methods



* `getStore()` : any

  * Returns the current store. If called outside of an asynchronous context initialized by calling `asyncLocalStorage.run()`, it returns `undefined`.

* <code>run(storeany, callbackfunction, ...argsarguments)</code> : any

  * Runs a function synchronously within a context and returns its return value. The store is not accessible outside of the callback function. The store is accessible to any asynchronous operations created within the callback. The optional `args` are passed to the callback function. If the callback function throws an error, the error is thrown by `run()` also.

* <code>exit(callbackfunction, ...argsarguments)</code> : any

  * Runs a function synchronously outside of a context and returns its return value. This method is equivalent to calling `run()` with the `store` value set to `undefined`.



## Static Methods



* `AsyncLocalStorage.bind(fn)` : function

  * Captures the asynchronous context that is current when `bind()` is called and returns a function that enters that context before calling the passed in function.

* `AsyncLocalStorage.snapshot()` : function

  * Captures the asynchronous context that is current when `snapshot()` is called and returns a function that enters that context before calling a given function.



## Examples

### Fetch Listener

```js
import { AsyncLocalStorage } from 'node:async_hooks';

const asyncLocalStorage = new AsyncLocalStorage();
let idSeq = 0;

export default {
  async fetch(req) {
    return asyncLocalStorage.run(idSeq++, () => {
      // Simulate some async activity...
      await scheduler.wait(1000);
      return new Response(asyncLocalStorage.getStore());
    });
  }
};
```

### Multiple stores

The API supports multiple `AsyncLocalStorage` instances to be used concurrently.

```js
import { AsyncLocalStorage } from 'node:async_hooks';

const als1 = new AsyncLocalStorage();
const als2 = new AsyncLocalStorage();

export default {
  async fetch(req) {
    return als1.run(123, () => {
      return als2.run(321, () => {
        // Simulate some async activity...
        await scheduler.wait(1000);
        return new Response(`${als1.getStore()}-${als2.getStore()}`);
      });
    });
  }
};
```

### Unhandled Rejections

When a `Promise` rejects and the rejection is unhandled, the async context propagates to the `'unhandledrejection'` event handler:

```js
import { AsyncLocalStorage } from 'node:async_hooks';

const asyncLocalStorage = new AsyncLocalStorage();
let idSeq = 0;

addEventListener('unhandledrejection', (event) => {
  console.log(asyncLocalStorage.getStore(), 'unhandled rejection!');
});

export default {
  async fetch(req) {
    return asyncLocalStorage.run(idSeq++, () => {
      // Cause an unhandled rejection!
      throw new Error('boom');
    });
  }
};
```

### `AsyncLocalStorage.bind()` and `AsyncLocalStorage.snapshot()`

```js
import { AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage();

function foo() { console.log(als.getStore()); }
function bar() { console.log(als.getStore()); }

const oneFoo = als.run(123, () => AsyncLocalStorage.bind(foo));
oneFoo(); // prints 123

const snapshot = als.run('abc', () => AsyncLocalStorage.snapshot());
snapshot(foo); // prints 'abc'
snapshot(bar); // prints 'abc'
```

```js
import { AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage();

class MyResource {
  #runInAsyncScope = AsyncLocalStorage.snapshot();

  doSomething() {
    this.#runInAsyncScope(() => {
      return als.getStore();
    });
  }
};

const myResource = als.run(123, () => new MyResource());
console.log(myResource.doSomething()); // prints 123
```

## `AsyncResource`

The [`AsyncResource`](https://nodejs.org/dist/latest-v18.x/docs/api/async_context.html#class-asyncresource) class is a component of Node.js' async context tracking API that allows users to create their own async contexts. Objects that extend from `AsyncResource` are capable of propagating the async context in much the same way as promises.

Note that `AsyncLocalStorage.snapshot()` and `AsyncLocalStorage.bind()` provide a better approach. `AsyncResource` is provided solely for backwards compatibility with Node.js.

### Constructor

```js
import { AsyncResource, AsyncLocalStorage } from 'node:async_hooks';

const als = new AsyncLocalStorage();

class MyResource extends AsyncResource {
  constructor() {
    // The type string is required by Node.js but unused in Workers.
    super('MyResource');
  }

  doSomething() {
    this.runInAsyncScope(() => {
      return als.getStore();
    });
  }
};

const myResource = als.run(123, () => new MyResource());
console.log(myResource.doSomething()); // prints 123
```



* <code>new AsyncResource(typestring, optionsAsyncResourceOptions)</code> : AsyncResource

  * Returns a new `AsyncResource`. Importantly, while the constructor arguments are required in Node.js' implementation of `AsyncResource`, they are not used in Workers.

* <code>AsyncResource.bind(fnfunction, typestring, thisArgany)</code>

  * Binds the given function to the current async context.



### Methods



* <code>asyncResource.bind(fnfunction, thisArgany)</code>

  * Binds the given function to the async context associated with this `AsyncResource`.

* <code>asyncResource.runInAsyncScope(fnfunction, thisArgany, ...argsarguments)</code>

  * Call the provided function with the given arguments in the async context associated with this `AsyncResource`.



## Caveats

* The `AsyncLocalStorage` implementation provided by Workers intentionally omits support for the [`asyncLocalStorage.enterWith()`](https://nodejs.org/dist/latest-v18.x/docs/api/async_context.html#asynclocalstorageenterwithstore) and [`asyncLocalStorage.disable()`](https://nodejs.org/dist/latest-v18.x/docs/api/async_context.html#asynclocalstoragedisable) methods.

* Workers does not implement the full [`async_hooks`](https://nodejs.org/dist/latest-v18.x/docs/api/async_hooks.html) API upon which Node.js' implementation of `AsyncLocalStorage` is built.

* Workers does not implement the ability to create an `AsyncResource` with an explicitly identified trigger context as allowed by Node.js. This means that a new `AsyncResource` will always be bound to the async context in which it was created.

* Thenables (non-Promise objects that expose a `then()` method) are not fully supported when using `AsyncLocalStorage`. When working with thenables, instead use [`AsyncLocalStorage.snapshot()`](https://nodejs.org/api/async_context.html#static-method-asynclocalstoragesnapshot) to capture a snapshot of the current context.

---

# Buffer

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/buffer/

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

The `Buffer` API in Node.js is one of the most commonly used Node.js APIs for manipulating binary data. Every `Buffer` instance extends from the standard [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) class, but adds a range of unique capabilities such as built-in base64 and hex encoding/decoding, byte-order manipulation, and encoding-aware substring searching.

```js
import { Buffer } from 'node:buffer';

const buf = Buffer.from('hello world', 'utf8');

console.log(buf.toString('hex'));
// Prints: 68656c6c6f20776f726c64
console.log(buf.toString('base64'));
// Prints: aGVsbG8gd29ybGQ=
```

A Buffer extends from `Uint8Array`. Therefore, it can be used in any Workers API that currently accepts `Uint8Array`, such as creating a new Response:

```js
const response = new Response(Buffer.from("hello world"));
```

You can also use the `Buffer` API when interacting with streams:

```js
const writable = getWritableStreamSomehow();
const writer = writable.getWriter();
writer.write(Buffer.from("hello world"));
```

Refer to the [Node.js documentation for `Buffer`](https://nodejs.org/dist/latest-v19.x/docs/api/buffer.html) for more information.

---

# crypto

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/crypto/

import { Render } from "~/components";

<Render file="nodejs-compat-howto" />

The `node:crypto` module provides cryptographic functionality that includes a set of wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify functions.

All `node:crypto` APIs are fully supported in Workers with the following exceptions:

- The functions [generateKeyPair](https://nodejs.org/api/crypto.html#cryptogeneratekeypairtype-options-callback) and [generateKeyPairSync](https://nodejs.org/api/crypto.html#cryptogeneratekeypairsynctype-options)
  do not support DSA or DH key pairs.
- `ed448` and `x448` curves are not supported.

The full `node:crypto` API is documented in the [Node.js documentation for `node:crypto`](https://nodejs.org/api/crypto.html).

The [WebCrypto API](/workers/runtime-apis/web-crypto/) is also available within Cloudflare Workers. This does not
require the `nodejs_compat` compatibility flag.

---

# Diagnostics Channel

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/diagnostics-channel/

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

The [`diagnostics_channel`](https://nodejs.org/dist/latest-v20.x/docs/api/diagnostics_channel.html) module provides an API to create named channels to report arbitrary message data for diagnostics purposes. The API is essentially a simple event pub/sub model that is specifically designed to support low-overhead diagnostics reporting.

```js
import {
  channel,
  hasSubscribers,
  subscribe,
  unsubscribe,
  tracingChannel,
} from 'node:diagnostics_channel';

// For publishing messages to a channel, acquire a channel object:
const myChannel = channel('my-channel');

// Any JS value can be published to a channel.
myChannel.publish({ foo: 'bar' });

// For receiving messages on a channel, use subscribe:

subscribe('my-channel', (message) => {
  console.log(message);
});
```

All `Channel` instances are singletons per each Isolate/context (for example, the same entry point). Subscribers are always invoked synchronously and in the order they were registered, much like an `EventTarget` or Node.js `EventEmitter` class.

## Integration with Tail Workers

When using [Tail Workers](/workers/observability/logs/tail-workers/), all messages published to any channel will be forwarded also to the [Tail Worker](/workers/observability/logs/tail-workers/). Within the Tail Worker, the diagnostic channel messages can be accessed via the `diagnosticsChannelEvents` property:

```js
export default {
  async tail(events) {
    for (const event of events) {
      for (const messageData of event.diagnosticsChannelEvents) {
        console.log(messageData.timestamp, messageData.channel, messageData.message);
      }
    }
  }
}
```

Note that message published to the tail worker is passed through the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) (same mechanism as the [`structuredClone()`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone) API) so only values that can be successfully cloned are supported.

## `TracingChannel`

Per the Node.js documentation, "[`TracingChannel`](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel) is a collection of \[Channels] which together express a single traceable action. `TracingChannel` is used to formalize and simplify the process of producing events for tracing application flow."

```js
import { tracingChannel } from 'node:diagnostics_channel';
import { AsyncLocalStorage } from 'node:async_hooks'

const channels = tracingChannel('my-channel');
const requestId = new AsyncLocalStorage();
channels.start.bindStore(requestId);

channels.subscribe({
  start(message) {
    console.log(requestId.getStore());  // { requestId: '123' }
    // Handle start message
  },
  end(message) {
    console.log(requestId.getStore());  // { requestId: '123' }
    // Handle end message
  },
  asyncStart(message) {
    console.log(requestId.getStore());  // { requestId: '123' }
    // Handle asyncStart message
  },
  asyncEnd(message) {
    console.log(requestId.getStore());  // { requestId: '123' }
    // Handle asyncEnd message
  },
  error(message) {
    console.log(requestId.getStore());  // { requestId: '123' }
    // Handle error message
  },
});

// The subscriber handlers will be invoked while tracing the execution of the async
// function passed into `channel.tracePromise`...
channel.tracePromise(async () => {
  // Perform some asynchronous work...
}, { requestId: '123' });
```

Refer to the [Node.js documentation for `diagnostics_channel`](https://nodejs.org/dist/latest-v20.x/docs/api/diagnostics_channel.html) for more information.

---

# dns

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/dns/

import { Render, TypeScriptExample } from "~/components";

<Render file="nodejs-compat-howto" />

You can use [`node:dns`](https://nodejs.org/api/dns.html) for name resolution via [DNS over HTTPS](/1.1.1.1/encryption/dns-over-https/) using
[Cloudflare DNS](https://www.cloudflare.com/application-services/products/dns/) at 1.1.1.1.

<TypeScriptExample filename="index.ts">
```ts
import dns from 'node:dns';

let responese = await dns.promises.resolve4('cloudflare.com', 'NS');
```
</TypeScriptExample>

All `node:dns` functions are available, except `lookup`, `lookupService`, and `resolve` which throw "Not implemented" errors when called.

:::note

DNS requests will execute a subrequest, counts for your [Worker's subrequest limit](/workers/platform/limits/#subrequests).

:::

The full `node:dns` API is documented in the [Node.js documentation for `node:dns`](https://nodejs.org/api/dns.html).

---

# Node.js compatibility

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/

import { DirectoryListing, WranglerConfig } from "~/components";

When you write a Worker, you may need to import packages from [npm](https://www.npmjs.com/). Many npm packages rely on APIs from the [Node.js runtime](https://nodejs.org/en/about), and will not work unless these Node.js APIs are available.

Cloudflare Workers provides a subset of Node.js APIs in two forms:

1. As built-in APIs provided by the Workers Runtime
2. As polyfill shim implementations that [Wrangler](/workers/wrangler/) adds to your Worker's code, allowing it to import the module, but calling API methods will throw errors.

## Get Started

To enable built-in Node.js APIs and add polyfills, add the `nodejs_compat` compatibility flag to your [wrangler configuration file](/workers/wrangler/configuration/), and ensure that your Worker's [compatibility date](/workers/configuration/compatibility-dates/) is 2024-09-23 or later. [Learn more about the Node.js compatibility flag and v2](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag).

<WranglerConfig>

```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_compat" ]
compatibility_date = "2024-09-23"
```

</WranglerConfig>

## Supported Node.js APIs

The runtime APIs from Node.js listed below as "🟢 supported" are currently natively supported in the Workers Runtime.

[Deprecated or experimental APIs from Node.js](https://nodejs.org/docs/latest/api/documentation.html#stability-index), and APIs that do not fit in a serverless context, are not included as part of the list below:

| API Name                                                                             | Natively supported by the Workers Runtime |
|--------------------------------------------------------------------------------------|-------------------------------------------|
| [Assertion testing](/workers/runtime-apis/nodejs/assert/)                            | 🟢 supported                              |
| [Asynchronous context tracking](/workers/runtime-apis/nodejs/asynclocalstorage/)     | 🟢 supported                              |
| [Buffer](/workers/runtime-apis/nodejs/buffer/)                                       | 🟢 supported                              |
| Console                                                                              | 🟢 supported                              |
| [Crypto](/workers/runtime-apis/nodejs/crypto/)                                       | 🟢 supported                              |
| [Debugger](/workers/observability/dev-tools/)                                        | 🟢 supported via [Chrome Dev Tools integration](/workers/observability/dev-tools/) |
| [Diagnostics Channel](/workers/runtime-apis/nodejs/diagnostics-channel/)             | 🟢 supported                              |
| [DNS](/workers/runtime-apis/nodejs/dns/)                                             | 🟢 supported                              |
| Errors                                                                               | 🟢 supported                              |
| Events                                                                               | 🟢 supported                              |
| File system                                                                          | ⚪ coming soon                            |
| Globals                                                                              | 🟢 supported                              |
| HTTP                                                                                 | ⚪ not yet supported                      |
| HTTP/2                                                                               | ⚪ not yet supported                      |
| HTTPS                                                                                | ⚪ not yet supported                      |
| Inspector                                                                            | 🟢 supported via [Chrome Dev Tools integration](/workers/observability/dev-tools/) |
| [Net](/workers/runtime-apis/nodejs/net/)                                             | 🟢 supported                              |
| OS                                                                                   | ⚪ not yet supported                      |
| [Path](/workers/runtime-apis/nodejs/path/)                                           | 🟢 supported                              |
| Performance hooks                                                                    | 🟡 partially supported                    |
| Process                                                                              | 🟢 supported                              |
| Query strings                                                                        | 🟢 supported                              |
| Stream                                                                               | 🟢 supported                              |
| [String decoder](/workers/runtime-apis/nodejs/string-decoder/)                       | 🟢 supported                              |
| [Timers](/workers/runtime-apis/nodejs/timers/)                                       | 🟢 supported                              |
| TLS/SSL                                                                              | 🟡 partially supported                    |
| UDP/datagram                                                                         | ⚪ not yet supported                      |
| [URL](/workers/runtime-apis/nodejs/url/)                                             | 🟢 supported                              |
| [Utilities](/workers/runtime-apis/nodejs/util/)                                      | 🟢 supported                              |
| Web Crypto API                                                                       | 🟢 supported                              |
| Web Streams API                                                                      | 🟢 supported                              |
| [Zlib](/workers/runtime-apis/nodejs/zlib/)                                           | 🟢 supported                              |

Unless otherwise specified, native implementations of Node.js APIs in Workers are intended to match the implementation in the [Current release of Node.js](https://github.com/nodejs/release#release-schedule).

If an API you wish to use is missing and you want to suggest that Workers support it, please add a post or comment in the
[Node.js APIs discussions category](https://github.com/cloudflare/workerd/discussions/categories/node-js-apis) on GitHub.

### Node.js API Polyfills

Node.js APIs that are not yet supported in the Workers runtime are polyfilled via [Wrangler](/workers/wrangler/), which uses [unenv](https://github.com/unjs/unenv). If the `nodejs_compat` [compatibility flag](/workers/configuration/compatibility-flags/) is enabled, and your Worker's [compatibility date](/workers/configuration/compatibility-dates/) is 2024-09-23 or later, Wrangler will automatically inject polyfills into your Worker's code.

Adding polyfills maximizes compatibility with existing npm packages by providing modules with mocked methods. Calling these mocked methods will either noop or will throw an error with a message like:

```
[unenv] <method name> is not implemented yet!
```

This allows you to import packages that use these Node.js modules, even if certain methods are not supported.

## Enable only AsyncLocalStorage

If you need to enable only the Node.js `AsyncLocalStorage` API, you can enable the `nodejs_als` compatibility flag:

<WranglerConfig>

```toml
compatibility_flags = [ "nodejs_als" ]
```

</WranglerConfig>

---

# net

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/net/

import { Render, TypeScriptExample } from "~/components";

<Render file="nodejs-compat-howto" />

You can use [`node:net`](https://nodejs.org/api/net.html) to create a direct connection to servers via a TCP sockets
with [`net.Socket`](https://nodejs.org/api/net.html#class-netsocket).

These functions use [`connect`](/workers/runtime-apis/tcp-sockets/#connect) functionality from the built-in `cloudflare:sockets` module.

<TypeScriptExample filename="index.ts">
```ts
import net from "node:net";

const exampleIP = "127.0.0.1";

export default {
  async fetch(req): Promise<Response> {
    const socket = new net.Socket();
    socket.connect(4000, exampleIP, function () {
      console.log("Connected");
    });

    socket.write("Hello, Server!");
    socket.end();

    return new Response("Wrote to server", { status: 200 });
  },
} satisfies ExportedHandler;

```
</TypeScriptExample>

Additionally, other APIs such as [`net.BlockList`](https://nodejs.org/api/net.html#class-netblocklist)
and [`net.SocketAddress`](https://nodejs.org/api/net.html#class-netsocketaddress) are available.

Note that the [`net.Server`](https://nodejs.org/api/net.html#class-netserver) class is not supported by Workers.

The full `node:net` API is documented in the [Node.js documentation for `node:net`](https://nodejs.org/api/net.html).

---

# path

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/path/

import { Render } from "~/components";

<Render file="nodejs-compat-howto" />

The [`node:path`](https://nodejs.org/api/path.html) module provides utilities for working with file and directory paths. The `node:path` module can be accessed using:

```js
import path from "node:path";
path.join("/foo", "bar", "baz/asdf", "quux", "..");
// Returns: '/foo/bar/baz/asdf'
```

Refer to the [Node.js documentation for `path`](https://nodejs.org/api/path.html) for more information.

---

# process

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/process/

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

The [`process`](https://nodejs.org/dist/latest-v19.x/docs/api/process.html) module in Node.js provides a number of useful APIs related to the current process. Within a serverless environment like Workers, most of these APIs are not relevant or meaningful, but some are useful for cross-runtime compatibility. Within Workers, the following APIs are available:

```js
import {
  env,
  nextTick,
} from 'node:process';

env['FOO'] = 'bar';
console.log(env['FOO']); // Prints: bar

nextTick(() => {
  console.log('next tick');
});
```

## `process.env`

In the Node.js implementation of `process.env`, the `env` object is a copy of the environment variables at the time the process was started. In the Workers implementation, there is no process-level environment, so by default `env` is an empty object. You can still set and get values from `env`, and those will be globally persistent for all Workers running in the same isolate and context (for example, the same Workers entry point).

When [Node.js compatability](/workers/runtime-apis/nodejs/) is turned on and the [`nodejs_compat_populate_process_env`](/workers/configuration/compatibility-flags/#enable-auto-populating-processenv) compatability flag is set, `process.env` will contain any [environment variables](/workers/configuration/environment-variables/),
[secrets](/workers/configuration/secrets/), or [version metadata](/workers/runtime-apis/bindings/version-metadata/) metadata that has been configured on your Worker.

### Relationship to per-request `env` argument in `fetch()` handlers

Workers do have a concept of [environment variables](/workers/configuration/environment-variables/) that are applied on a per-Worker and per-request basis. These are not accessible automatically via the `process.env` API. It is possible to manually copy these values into `process.env` if you need to. Be aware, however, that setting any value on `process.env` will coerce that value into a string.

```js
import * as process from 'node:process';

export default {
  fetch(req, env) {
    // Set process.env.FOO to the value of env.FOO if process.env.FOO is not already set
    // and env.FOO is a string.
    process.env.FOO ??= (() => {
      if (typeof env.FOO === 'string') {
        return env.FOO;
      }
    })();
  }
};
```

It is strongly recommended that you *do not* replace the entire `process.env` object with the request `env` object. Doing so will cause you to lose any environment variables that were set previously and will cause unexpected behavior for other Workers running in the same isolate. Specifically, it would cause inconsistency with the `process.env` object when accessed via named imports.

```js
import * as process from 'node:process';
import { env } from 'node:process';

process.env === env; // true! they are the same object
process.env = {}; // replace the object! Do not do this!
process.env === env; // false! they are no longer the same object

// From this point forward, any changes to process.env will not be reflected in env,
// and vice versa!
```

## `process.nextTick()`

The Workers implementation of `process.nextTick()` is a wrapper for the standard Web Platform API [`queueMicrotask()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/queueMicrotask).

Refer to the [Node.js documentation for `process`](https://nodejs.org/dist/latest-v19.x/docs/api/process.html) for more information.

---

# Streams

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/streams/

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

The [Node.js streams API](https://nodejs.org/api/stream.html) is the original API for working with streaming data in JavaScript, predating the [WHATWG ReadableStream standard](https://streams.spec.whatwg.org/). A stream is an abstract interface for working with streaming data in Node.js. Streams can be readable, writable, or both. All streams are instances of [EventEmitter](/workers/runtime-apis/nodejs/eventemitter/).

Where possible, you should use the [WHATWG standard "Web Streams" API](https://streams.spec.whatwg.org/), which is [supported in Workers](https://streams.spec.whatwg.org/).

```js
import {
  Readable,
  Transform,
} from 'node:stream';

import {
  text,
} from 'node:stream/consumers';

import {
  pipeline,
} from 'node:stream/promises';

// A Node.js-style Transform that converts data to uppercase
// and appends a newline to the end of the output.
class MyTransform extends Transform {
  constructor() {
    super({ encoding: 'utf8' });
  }
  _transform(chunk, _, cb) {
    this.push(chunk.toString().toUpperCase());
    cb();
  }
  _flush(cb) {
    this.push('\n');
    cb();
  }
}

export default {
  async fetch() {
    const chunks = [
      "hello ",
      "from ",
      "the ",
      "wonderful ",
      "world ",
      "of ",
      "node.js ",
      "streams!"
    ];

    function nextChunk(readable) {
      readable.push(chunks.shift());
      if (chunks.length === 0) readable.push(null);
      else queueMicrotask(() => nextChunk(readable));
    }

    // A Node.js-style Readable that emits chunks from the
    // array...
    const readable = new Readable({
      encoding: 'utf8',
      read() { nextChunk(readable); }
    });

    const transform = new MyTransform();
    await pipeline(readable, transform);
    return new Response(await text(transform));
  }
};
```

Refer to the [Node.js documentation for `stream`](https://nodejs.org/api/stream.html) for more information.

---

# StringDecoder

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/string-decoder/

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

The [`node:string_decoder`](https://nodejs.org/api/string_decoder.html) is a legacy utility module that predates the WHATWG standard [TextEncoder](/workers/runtime-apis/encoding/#textencoder) and [TextDecoder](/workers/runtime-apis/encoding/#textdecoder) API. In most cases, you should use `TextEncoder` and `TextDecoder` instead. `StringDecoder` is available in the Workers runtime primarily for compatibility with existing npm packages that rely on it. `StringDecoder` can be accessed using:

```js
const { StringDecoder } = require('node:string_decoder');
const decoder = new StringDecoder('utf8');

const cent = Buffer.from([0xC2, 0xA2]);
console.log(decoder.write(cent));

const euro = Buffer.from([0xE2, 0x82, 0xAC]);
console.log(decoder.write(euro));
```

Refer to the [Node.js documentation for `string_decoder`](https://nodejs.org/dist/latest-v20.x/docs/api/string_decoder.html) for more information.

---

# timers

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/timers/

import { Render, TypeScriptExample } from "~/components";

<Render file="nodejs-compat-howto" />

Use [`node:timers`](https://nodejs.org/api/timers.html) APIs to schedule functions to be executed later.

This includes [`setTimeout`](https://nodejs.org/api/timers.html#settimeoutcallback-delay-args) for calling a function after a delay,
[`setInterval`](https://nodejs.org/api/timers.html#clearintervaltimeout) for calling a function repeatedly,
and [`setImmediate`](https://nodejs.org/api/timers.html#setimmediatecallback-args) for calling a function in the next iteration of the event loop.

<TypeScriptExample filename="index.ts">
```ts
import timers from "node:timers";

console.log("first");
timers.setTimeout(() => {
  console.log("last");
}, 10);

timers.setTimeout(() => {
  console.log("next");
});
```
</TypeScriptExample>

:::note
Due to [security-based restrictions on timers](/workers/reference/security-model/#step-1-disallow-timers-and-multi-threading) in Workers,
timers are limited to returning the time of the last I/O. This means that while setTimeout, setInterval, and setImmediate will defer your function execution
until after other events have run, they will not delay them for the full time specified.
:::

:::note
When called from a global level (on [`globalThis`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis)),
functions such as `clearTimeout` and `setTimeout` will respect web standards rather than Node.js-specific functionality. For complete Node.js
compatibility, you must call functions from the `node:timers` module.
:::

The full `node:timers` API is documented in the [Node.js documentation for `node:timers`](https://nodejs.org/api/timers.html).

---

# test

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/test/

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

## `MockTracker`

The `MockTracker` API in Node.js provides a means of tracking and managing mock objects in a test
environment.

```js
import { mock } from 'node:test';

const fn = mock.fn();
fn(1,2,3);  // does nothing... but

console.log(fn.mock.callCount());  // Records how many times it was called
console.log(fn.mock.calls[0].arguments));  // Recoreds the arguments that were passed each call
```

The full `MockTracker` API is documented in the [Node.js documentation for `MockTracker`](https://nodejs.org/docs/latest/api/test.html#class-mocktracker).

The Workers implementation of `MockTracker` currently does not include an implementation of the [Node.js mock timers API](https://nodejs.org/docs/latest/api/test.html#class-mocktimers).

---

# tls

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/tls/

import { Render, TypeScriptExample } from "~/components";

<Render file="nodejs-compat-howto" />

You can use [`node:tls`](https://nodejs.org/api/tls.html) to create secure connections to
external services using [TLS](https://developer.mozilla.org/en-US/docs/Web/Security/Transport_Layer_Security) (Transport Layer Security).

```js
import { connect } from "node:tls";

// ... in a request handler ...
const connectionOptions = { key: env.KEY, cert: env.CERT };
const socket = connect(url, connectionOptions, () => {
	if (socket.authorized) {
		console.log("Connection authorized");
	}
});

socket.on("data", (data) => {
	console.log(data);
});

socket.on("end", () => {
	console.log("server ends connection");
});
```

The following APIs are available:

- [`connect`](https://nodejs.org/api/tls.html#tlsconnectoptions-callback)
- [`TLSSocket`](https://nodejs.org/api/tls.html#class-tlstlssocket)
- [`checkServerIdentity`](https://nodejs.org/api/tls.html#tlscheckserveridentityhostname-cert)
- [`createSecureContext`](https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions)

All other APIs, including [`tls.Server`](https://nodejs.org/api/tls.html#class-tlsserver) and [`tls.createServer`](https://nodejs.org/api/tls.html#tlscreateserveroptions-secureconnectionlistener),
are not supported and will throw a `Not implemented` error when called.

The full `node:tls` API is documented in the [Node.js documentation for `node:tls`](https://nodejs.org/api/tls.html).

---

# url

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/url/

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

## domainToASCII

Returns the Punycode ASCII serialization of the domain. If domain is an invalid domain, the empty string is returned.

```js
import { domainToASCII } from 'node:url';

console.log(domainToASCII('español.com'));
// Prints xn--espaol-zwa.com
console.log(domainToASCII('中文.com'));
// Prints xn--fiq228c.com
console.log(domainToASCII('xn--iñvalid.com'));
// Prints an empty string
```

## domainToUnicode

Returns the Unicode serialization of the domain. If domain is an invalid domain, the empty string is returned.

It performs the inverse operation to `domainToASCII()`.

```js
import { domainToUnicode } from 'node:url';

console.log(domainToUnicode('xn--espaol-zwa.com'));
// Prints español.com
console.log(domainToUnicode('xn--fiq228c.com'));
// Prints 中文.com
console.log(domainToUnicode('xn--iñvalid.com'));
// Prints an empty string
```

---

# util

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/util/

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

## promisify/callbackify

The `promisify` and `callbackify` APIs in Node.js provide a means of bridging between a Promise-based programming model and a callback-based model.

The `promisify` method allows taking a Node.js-style callback function and converting it into a Promise-returning async function:

```js
import { promisify } from 'node:util';

function foo(args, callback) {
  try {
    callback(null, 1);
  } catch (err) {
    // Errors are emitted to the callback via the first argument.
    callback(err);
  }
}

const promisifiedFoo = promisify(foo);
await promisifiedFoo(args);
```

Similarly to `promisify`, `callbackify` converts a Promise-returning async function into a Node.js-style callback function:

```js
import { callbackify } from 'node:util';

async function foo(args) {
  throw new Error('boom');
}

const callbackifiedFoo = callbackify(foo);

callbackifiedFoo(args, (err, value) => {
  If (err) throw err;
});
```

`callbackify` and `promisify` make it easy to handle all of the challenges that come with bridging between callbacks and promises.

Refer to the [Node.js documentation for `callbackify`](https://nodejs.org/dist/latest-v19.x/docs/api/util.html#utilcallbackifyoriginal) and [Node.js documentation for `promisify`](https://nodejs.org/dist/latest-v19.x/docs/api/util.html#utilpromisifyoriginal) for more information.

## util.types

The `util.types` API provides a reliable and efficient way of checking that values are instances of various built-in types.

```js
import { types } from 'node:util';

types.isAnyArrayBuffer(new ArrayBuffer());  // Returns true
types.isAnyArrayBuffer(new SharedArrayBuffer());  // Returns true
types.isArrayBufferView(new Int8Array());  // true
types.isArrayBufferView(Buffer.from('hello world')); // true
types.isArrayBufferView(new DataView(new ArrayBuffer(16)));  // true
types.isArrayBufferView(new ArrayBuffer());  // false
function foo() {
  types.isArgumentsObject(arguments);  // Returns true
}
types.isAsyncFunction(function foo() {});  // Returns false
types.isAsyncFunction(async function foo() {});  // Returns true
// .. and so on
```

:::caution

The Workers implementation currently does not provide implementations of the `util.types.isExternal()`, `util.types.isProxy()`, `util.types.isKeyObject()`, or `util.type.isWebAssemblyCompiledModule()` APIs.
:::

For more about `util.types`, refer to the [Node.js documentation for `util.types`](https://nodejs.org/dist/latest-v19.x/docs/api/util.html#utiltypes).

## util.MIMEType

`util.MIMEType` provides convenience methods that allow you to more easily work with and manipulate [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types). For example:

```js
import { MIMEType } from 'node:util';

const myMIME = new MIMEType('text/javascript;key=value');

console.log(myMIME.type);
// Prints: text

console.log(myMIME.essence);
// Prints: text/javascript

console.log(myMIME.subtype);
// Prints: javascript

console.log(String(myMIME));
// Prints: application/javascript;key=value
```

For more about `util.MIMEType`, refer to the [Node.js documentation for `util.MIMEType`](https://nodejs.org/api/util.html#class-utilmimetype).

---

# zlib

URL: https://developers.cloudflare.com/workers/runtime-apis/nodejs/zlib/

import { Render } from "~/components"

<Render file="nodejs-compat-howto" />

The node:zlib module provides compression functionality implemented using Gzip, Deflate/Inflate, and Brotli.
To access it:

```js
import zlib from 'node:zlib';
```

The full `node:zlib` API is documented in the [Node.js documentation for `node:zlib`](https://nodejs.org/api/zlib.html).

---

# Error handling

URL: https://developers.cloudflare.com/workers/runtime-apis/rpc/error-handling/

## Exceptions

An exception thrown by an RPC method implementation will propagate to the caller. If it is one of the standard JavaScript Error types, the `message` and prototype's `name` will be retained, though the stack trace is not.

### Unsupported error types

* If an [`AggregateError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AggregateError) is thrown by an RPC method, it is not propagated back to the caller.
* The [`SuppressedError`](https://github.com/tc39/proposal-explicit-resource-management?tab=readme-ov-file#the-suppressederror-error) type from the Explicit Resource Management proposal is not currently implemented or supported in Workers.
* Own properties of error objects, such as the [`cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) property, are not propagated back to the caller

## Additional properties

For some remote exceptions, the runtime may set properties on the propagated exception to provide more information about the error; see [Durable Object error handling](/durable-objects/best-practices/error-handling) for more details.

---

# Remote-procedure call (RPC)

URL: https://developers.cloudflare.com/workers/runtime-apis/rpc/

import {
	DirectoryListing,
	Render,
	Stream,
	WranglerConfig,
	TypeScriptExample,
} from "~/components";

:::note
To use RPC, [define a compatibility date](/workers/configuration/compatibility-dates) of `2024-04-03` or higher, or include `rpc` in your [compatibility flags](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag).
:::

Workers provide a built-in, JavaScript-native [RPC (Remote Procedure Call)](https://en.wikipedia.org/wiki/Remote_procedure_call) system, allowing you to:

- Define public methods on your Worker that can be called by other Workers on the same Cloudflare account, via [Service Bindings](/workers/runtime-apis/bindings/service-bindings/rpc)
- Define public methods on [Durable Objects](/durable-objects) that can be called by other workers on the same Cloudflare account that declare a binding to it.

The RPC system is designed to feel as similar as possible to calling a JavaScript function in the same Worker. In most cases, you should be able to write code in the same way you would if everything was in a single Worker.

## Example

<Render file="service-binding-rpc-example" product="workers" />

The client, in this case Worker A, calls Worker B and tells it to execute a specific procedure using specific arguments that the client provides. This is accomplished with standard JavaScript classes.

## All calls are asynchronous

Whether or not the method you are calling was declared asynchronous on the server side, it will behave as such on the client side. You must `await` the result.

Note that RPC calls do not actually return `Promise`s, but they return a type that behaves like a `Promise`. The type is a "custom thenable", in that it implements the method `then()`. JavaScript supports awaiting any "thenable" type, so, for the most part, you can treat the return value like a Promise.

(We'll see why the type is not actually a Promise a bit later.)

## Structured clonable types, and more

Nearly all types that are [Structured Cloneable](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#supported_types) can be used as a parameter or return value of an RPC method. This includes, most basic "value" types in JavaScript, including objects, arrays, strings and numbers.

As an exception to Structured Clone, application-defined classes (or objects with custom prototypes) cannot be passed over RPC, except as described below.

The RPC system also supports a number of types that are not Structured Cloneable, including:

- Functions, which are replaced by stubs that call back to the sender.
- Application-defined classes that extend `RpcTarget`, which are similarly replaced by stubs.
- [ReadableStream](/workers/runtime-apis/streams/readablestream/) and [WriteableStream](/workers/runtime-apis/streams/writablestream/), with automatic streaming flow control.
- [Request](/workers/runtime-apis/request/) and [Response](/workers/runtime-apis/response/), for conveniently representing HTTP messages.
- RPC stubs themselves, even if the stub was received from a third Worker.

## Functions

You can send a function over RPC. When you do so, the function is replaced by a "stub". The recipient can call the stub like a function, but doing so makes a new RPC back to the place where the function originated.

### Return functions from RPC methods

<Render file="service-binding-rpc-functions-example" product="workers" />

### Send functions as parameters of RPC methods

You can also send a function in the parameters of an RPC. This enables the "server" to call back to the "client", reversing the direction of the relationship.

Because of this, the words "client" and "server" can be ambiguous when talking about RPC. The "server" is a Durable Object or WorkerEntrypoint, and the "client" is the Worker that invoked the server via a binding. But, RPCs can flow both ways between the two. When talking about an individual RPC, we recommend instead using the words "caller" and "callee".

## Class Instances

To use an instance of a class that you define as a parameter or return value of an RPC method, you must extend the built-in `RpcTarget` class.

Consider the following example:

<WranglerConfig>

```toml
name = "counter"
main = "./src/counter.js"
```

</WranglerConfig>

<TypeScriptExample>

```ts
import { WorkerEntrypoint, RpcTarget } from "cloudflare:workers";

class Counter extends RpcTarget {
	#value = 0;

	increment(amount: number) {
		this.#value += amount;
		return this.#value;
	}

	get value() {
		return this.#value;
	}
}

export class CounterService extends WorkerEntrypoint {
	async newCounter() {
		return new Counter();
	}
}

export default {
	fetch() {
		return new Response("ok");
	},
};
```

</TypeScriptExample>

The method `increment` can be called directly by the client, as can the public property `value`:

<WranglerConfig>

```toml
name = "client-worker"
main = "./src/clientWorker.js"
services = [
  { binding = "COUNTER_SERVICE", service = "counter", entrypoint = "CounterService" }
]
```

</WranglerConfig>

<TypeScriptExample>

```ts
export default {
	async fetch(request: Request, env: Env) {
		using counter = await env.COUNTER_SERVICE.newCounter();

		await counter.increment(2); // returns 2
		await counter.increment(1); // returns 3
		await counter.increment(-5); // returns -2

		const count = await counter.value; // returns -2

		return new Response(count);
	},
};
```

</TypeScriptExample>

:::note

Refer to [Explicit Resource Management](/workers/runtime-apis/rpc/lifecycle) to learn more about the `using` declaration shown in the example above.
:::

Classes that extend `RpcTarget` work a lot like functions: the object itself is not serialized, but is instead replaced by a stub. In this case, the stub itself is not callable, but its methods are. Calling any method on the stub actually makes an RPC back to the original object, where it was created.

As shown above, you can also access properties of classes. Properties behave like RPC methods that don't take any arguments — you await the property to asynchronously fetch its current value. Note that the act of awaiting the property (which, behind the scenes, calls `.then()` on it) is what causes the property to be fetched. If you do not use `await` when accessing the property, it will not be fetched.

:::note

While it's possible to define a similar interface to the caller using an object that contains many functions, this is less efficient. If you return an object that contains five functions, then you are creating five stubs. If you return a class instance, where the class declares five methods, you are only returning a single stub. Returning a single stub is often more efficient and easier to reason about. Moreover, when returning a plain object (not a class), non-function properties of the object will be transmitted at the time the object itself is transmitted; they cannot be fetched asynchronously on-demand.
:::

:::note

Classes which do not inherit `RpcTarget` cannot be sent over RPC at all. This differs from Structured Clone, which defines application-defined classes as clonable. Why the difference? By default, the Structured Clone algorithm simply ignores an object's class entirely. So, the recipient receives a plain object, containing the original object's instance properties but entirely missing its original type. This behavior is rarely useful in practice, and could be confusing if the developer had intended the class to be treated as an `RpcTarget`. So, Workers RPC has chosen to disallow classes that are not `RpcTarget`s, to avoid any confusion.
:::

### Promise pipelining

When you call an RPC method and get back an object, it's common to immediately call a method on the object:

<TypeScriptExample>

```ts
// Two round trips.
using counter = await env.COUNTER_SERVICE.getCounter();
await counter.increment();
```

</TypeScriptExample>

But consider the case where the Worker service that you are calling may be far away across the network, as in the case of [Smart Placement](/workers/runtime-apis/bindings/service-bindings/#smart-placement) or [Durable Objects](/durable-objects). The code above makes two round trips, once when calling `getCounter()`, and again when calling `.increment()`. We'd like to avoid this.

With most RPC systems, the only way to avoid the problem would be to combine the two calls into a single "batch" call, perhaps called `getCounterAndIncrement()`. However, this makes the interface worse. You wouldn't design a local interface this way.

Workers RPC allows a different approach: You can simply omit the first `await`:

<TypeScriptExample>

```ts
// Only one round trip! Note the missing `await`.
using promiseForCounter = env.COUNTER_SERVICE.getCounter();
await promiseForCounter.increment();
```

</TypeScriptExample>

In this code, `getCounter()` returns a promise for a counter. Normally, the only thing you would do with a promise is `await` it. However, Workers RPC promises are special: they also allow you to initiate speculative calls on the future result of the promise. These calls are sent to the server immediately, without waiting for the initial call to complete. Thus, multiple chained calls can be completed in a single round trip.

How does this work? The promise returned by an RPC is not a real JavaScript `Promise`. Instead, it is a custom ["Thenable"](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables). It has a `.then()` method like `Promise`, which allows it to be used in all the places where you'd use a normal `Promise`. For instance, you can `await` it. But, in addition to that, an RPC promise also acts like a stub. Calling any method name on the promise forms a speculative call on the promise's eventual result. This is known as "promise pipelining".

This works when calling properties of objects returned by RPC methods as well. For example:

<TypeScriptExample>

```ts
import { WorkerEntrypoint } from "cloudflare:workers";

export class MyService extends WorkerEntrypoint {
	async foo() {
		return {
			bar: {
				baz: () => "qux",
			},
		};
	}
}
```

</TypeScriptExample>

<TypeScriptExample>

```ts
export default {
	async fetch(request, env) {
		using foo = env.MY_SERVICE.foo();
		let baz = await foo.bar.baz();
		return new Response(baz);
	},
};
```

</TypeScriptExample>

If the initial RPC ends up throwing an exception, then any pipelined calls will also fail with the same exception

## ReadableStream, WriteableStream, Request and Response

You can send and receive [`ReadableStream`](/workers/runtime-apis/streams/readablestream/), [`WriteableStream`](/workers/runtime-apis/streams/writablestream/), [`Request`](/workers/runtime-apis/request/), and [`Response`](/workers/runtime-apis/response/) using RPC methods. When doing so, bytes in the body are automatically streamed with appropriate flow control. This allows you to send messages over RPC which are larger than [the typical 32 MiB limit](#limitations).

Only [byte-oriented streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API/Using_readable_byte_streams) (streams with an underlying byte source of `type: "bytes"`) are supported.

In all cases, ownership of the stream is transferred to the recipient. The sender can no longer read/write the stream after sending it. If the sender wishes to keep its own copy, it can use the [`tee()` method of `ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/tee) or the [`clone()` method of `Request` or `Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone). Keep in mind that doing this may force the system to buffer bytes and lose the benefits of flow control.

## Forwarding RPC stubs

A stub received over RPC from one Worker can be forwarded over RPC to another Worker.

<TypeScriptExample>

```ts
using counter = env.COUNTER_SERVICE.getCounter();
await env.ANOTHER_SERVICE.useCounter(counter);
```

</TypeScriptExample>

Here, three different workers are involved:

1. The calling Worker (we'll call this the "introducer")
2. `COUNTER_SERVICE`
3. `ANOTHER_SERVICE`

When `ANOTHER_SERVICE` calls a method on the `counter` that is passed to it, this call will automatically be proxied through the introducer and on to the [`RpcTarget`](/workers/runtime-apis/rpc/) class implemented by `COUNTER_SERVICE`.

In this way, the introducer Worker can connect two Workers that did not otherwise have any ability to form direct connections to each other.

Currently, this proxying only lasts until the end of the Workers' execution contexts. A proxy connection cannot be persisted for later use.

## Video Tutorial

In this video, we explore how Cloudflare Workers support Remote Procedure Calls (RPC) to simplify communication between Workers. Learn how to implement RPC in your JavaScript applications and build serverless solutions with ease. Whether you're managing microservices or optimizing web architecture, this tutorial will show you how to quickly set up and use Cloudflare Workers for RPC calls. By the end of this video, you'll understand how to call functions between Workers, pass functions as arguments, and implement user authentication with Cloudflare Workers.

<Stream
	id="d506935b6767fd07626adbec46d41e6d"
	title="Introduction to Workers RPC"
	thumbnail="2.5s"
/>

## More Details

<DirectoryListing />

## Limitations

- [Smart Placement](/workers/configuration/smart-placement/) is currently ignored when making RPC calls. If Smart Placement is enabled for Worker A, and Worker B declares a [Service Binding](/workers/runtime-apis/bindings) to it, when Worker B calls Worker A via RPC, Worker A will run locally, on the same machine.

- The maximum serialized RPC limit is 32 MiB. Consider using [`ReadableStream`](/workers/runtime-apis/streams/readablestream/) when returning more data.

  <TypeScriptExample>

  ```ts
  export class MyService extends WorkerEntrypoint {
  	async foo() {
  		// Although this works, it puts a lot of memory pressure on the isolate.
  		// If possible, streaming the data from its original source is much preferred and would yield better performance.
  		// If you must buffer the data into memory, consider chunking it into smaller pieces if possible.

  		const sizeInBytes = 33 * 1024 * 1024; // 33 MiB
  		const arr = new Uint8Array(sizeInBytes);

  		return new ReadableStream({
  			start(controller) {
  				controller.enqueue(arr);
  				controller.close();
  			},
  		});
  	}
  }
  ```

  </TypeScriptExample>

---

# Reserved Methods

URL: https://developers.cloudflare.com/workers/runtime-apis/rpc/reserved-methods/

Some method names are reserved or have special semantics.

## Special Methods

For backwards compatibility, when extending `WorkerEntrypoint` or `DurableObject`, the following method names have special semantics. Note that this does *not* apply to `RpcTarget`. On `RpcTarget`, these methods work like any other RPC method.

### `fetch()`

The `fetch()` method is treated specially — it can only be used to handle an HTTP request — equivalent to the [fetch handler](/workers/runtime-apis/handlers/fetch/).

You may implement a `fetch()` method in your class that extends `WorkerEntrypoint` — but it must accept only one parameter of type [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request), and must return an instance of [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response), or a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) of one.

On the client side, `fetch()` called on a service binding or Durable Object stub works like the standard global `fetch()`. That is, the caller may pass one or two parameters to `fetch()`. If the caller does not simply pass a single `Request` object, then a new `Request` is implicitly constructed, passing the parameters to its constructor, and that request is what is actually sent to the server.

Some properties of `Request` control the behavior of `fetch()` on the client side and are not actually sent to the server. For example, the property `redirect: "auto"` (which is the default) instructs `fetch()` that if the server returns a redirect response, it should automatically be followed, resulting in an HTTP request to the public internet. Again, this behavior is according to the Fetch API standard. In short, `fetch()` doesn't have RPC semantics, it has Fetch API semantics.

### `connect()`

The `connect()` method of the `WorkerEntrypoint` class is reserved for opening a socket-like connection to your Worker. This is currently not implemented or supported — though you can [open a TCP socket from a Worker](/workers/runtime-apis/tcp-sockets/) or connect directly to databases over a TCP socket with [Hyperdrive](/hyperdrive/get-started/).

## Disallowed Method Names

The following method (or property) names may not be used as RPC methods on any RPC type (including `WorkerEntrypoint`, `DurableObject`, and `RpcTarget`):

* `dup`: This is reserved for duplicating a stub. Refer to the [RPC Lifecycle](/workers/runtime-apis/rpc/lifecycle) docs to learn more about `dup()`.
* `constructor`: This name has special meaning for JavaScript classes. It is not intended to be called as a method, so it is not allowed over RPC.

The following methods are disallowed only on `WorkerEntrypoint` and `DurableObject`, but allowed on `RpcTarget`. These methods have historically had special meaning to Durable Objects, where they are used to handle certain system-generated events.

* `alarm`
* `webSocketMessage`
* `webSocketClose`
* `webSocketError`

---

# Lifecycle

URL: https://developers.cloudflare.com/workers/runtime-apis/rpc/lifecycle/

## Lifetimes, Memory and Resource Management

When you call another Worker over RPC using a Service binding, you are using memory in the Worker you are calling. Consider the following example:

```js
let user = await env.USER_SERVICE.findUser(id);
```

Assume that `findUser()` on the server side returns an object extending `RpcTarget`, thus `user` on the client side ends up being a stub pointing to that remote object.

As long as the stub still exists on the client, the corresponding object on the server cannot be garbage collected. But, each isolate has its own garbage collector which cannot see into other isolates. So, in order for the server's isolate to know that the object can be collected, the calling isolate must send it an explicit signal saying so, called "disposing" the stub.

In many cases (described below), the system will automatically realize when a stub is no longer needed, and will dispose it automatically. However, for best performance, your code should dispose stubs explicitly when it is done with them.

## Explicit Resource Management

To ensure resources are properly disposed of, you should use [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management), a new JavaScript language feature that allows you to explicitly signal when resources can be disposed of. Explicit Resource Management is a Stage 3 TC39 proposal — it is [coming to V8 soon](https://bugs.chromium.org/p/v8/issues/detail?id=13559).

Explicit Resource Management adds the following language features:

- The [`using` declaration](https://github.com/tc39/proposal-explicit-resource-management?tab=readme-ov-file#using-declarations)
- [`Symbol.dispose` and `Symbol.asyncDispose`](https://github.com/tc39/proposal-explicit-resource-management?tab=readme-ov-file#additions-to-symbol)

If a variable is declared with `using`, when the variable is no longer in scope, the variable's disposer will be invoked. For example:

```js
function sendEmail(id, message) {
  using user = await env.USER_SERVICE.findUser(id);
  await user.sendEmail(message);

  // user[Symbol.dispose]() is implicitly called at the end of the scope.
}
```

`using` declarations are useful to make sure you can't forget to dispose stubs — even if your code is interrupted by an exception.

### How to use the `using` declaration in your Worker

[Wrangler](/workers/wrangler/) v4+ supports the `using` keyword natively. If you are using an earlier version of Wrangler, you will need to manually dispose of resources instead.

The following code:

```js
{
	using counter = await env.COUNTER_SERVICE.newCounter();
	await counter.increment(2);
	await counter.increment(4);
}
```

...is equivalent to:

```js
{
	const counter = await env.COUNTER_SERVICE.newCounter();
	try {
		await counter.increment(2);
		await counter.increment(4);
	} finally {
		counter[Symbol.dispose]();
	}
}
```

## Automatic disposal and execution contexts

The RPC system automatically disposes of stubs in the following cases:

### End of event handler / execution context

When an event handler is "done", any stubs created as part of the event are automatically disposed.

For example, consider a [`fetch()` handler](/workers/runtime-apis/handlers/fetch) which handles incoming HTTP events. The handler may make outgoing RPCs as part of handling the event, and those may return stubs. When the final HTTP response is sent, the handler is "done", and all stubs are immediately disposed.

More precisely, the event has an "execution context", which begins when the handler is first invoked, and ends when the HTTP response is sent. The execution context may also end early if the client disconnects before receiving a response, or it can be extended past its normal end point by calling [`ctx.waitUntil()`](/workers/runtime-apis/context).

For example, the Worker below does not make use of the `using` declaration, but stubs will be disposed of once the `fetch()` handler returns a response:

```js
export default {
	async fetch(request, env, ctx) {
		let authResult = await env.AUTH_SERVICE.checkCookie(
			req.headers.get("Cookie"),
		);
		if (!authResult.authorized) {
			return new Response("Not authorized", { status: 403 });
		}
		let profile = await authResult.user.getProfile();

		return new Response(`Hello, ${profile.name}!`);
	},
};
```

A Worker invoked via RPC also has an execution context. The context begins when an RPC method on a `WorkerEntrypoint` is invoked. If no stubs are passed in the parameters or results of this RPC, the context ends (the event is "done") when the RPC returns. However, if any stubs are passed, then the execution context is implicitly extended until all such stubs are disposed (and all calls made through them have returned). As with HTTP, if the client disconnects, the server's execution context is canceled immediately, regardless of whether stubs still exist. A client that is itself another Worker is considered to have disconnected when its own execution context ends. Again, the context can be extended with [`ctx.waitUntil()`](/workers/runtime-apis/context).

### Stubs received as parameters in an RPC call

When stubs are received in the parameters of an RPC, those stubs are automatically disposed when the call returns. If you wish to keep the stubs longer than that, you must call the `dup()` method on them.

### Disposing RPC objects disposes stubs that are part of that object

When an RPC returns any kind of object, that object will have a disposer added by the system. Disposing it will dispose all stubs returned by the call. For instance, if an RPC returns an array of four stubs, the array itself will have a disposer that disposes all four stubs. The only time the value returned by an RPC does not have a disposer is when it is a primitive value, such as a number or string. These types cannot have disposers added to them, but because these types cannot themselves contain stubs, there is no need for a disposer in this case.

This means you should almost always store the result of an RPC into a `using` declaration:

```js
using result = stub.foo();
```

This way, if the result contains any stubs, they will be disposed of. Even if you don't expect the RPC to return stubs, if it returns any kind of an object, it is a good idea to store it into a `using` declaration. This way, if the RPC is extended in the future to return stubs, your code is ready.

If you decide you want to keep a returned stub beyond the scope of the `using` declaration, you can call `dup()` on the stub before the end of the scope. (Remember to explicitly dispose the duplicate later.)

## Disposers and `RpcTarget` classes

A class that extends [`RpcTarget`](/workers/runtime-apis/rpc/) can optionally implement a disposer:

```js
class Foo extends RpcTarget {
	[Symbol.dispose]() {
		// ...
	}
}
```

The RpcTarget's disposer runs after the last stub is disposed. Note that the client-side call to the stub's disposer does not wait for the server-side disposer to be called; the server's disposer is called later on. Because of this, any exceptions thrown by the disposer do not propagate to the client; instead, they are reported as uncaught exceptions. Note that an `RpcTarget`'s disposer must be declared as `Symbol.dispose`. `Symbol.asyncDispose` is not supported.

## The `dup()` method

Sometimes, you need to pass a stub to a function which will dispose the stub when it is done, but you also want to keep the stub for later use. To solve this problem, you can "dup" the stub:

```js
let stub = await env.SOME_SERVICE.getThing();

// Create a duplicate.
let stub2 = stub.dup();

// Call some function that will dispose the stub.
await func(stub);

// stub2 is still valid
```

You can think of `dup()` like the [Unix system call of the same name](https://man7.org/linux/man-pages/man2/dup.2.html): it creates a new handle pointing at the same target, which must be independently closed (disposed).

If the instance of the [`RpcTarget` class](/workers/runtime-apis/rpc/) that the stubs point to has a disposer, the disposer will only be invoked when all duplicates have been disposed. However, this only applies to duplicates that originate from the same stub. If the same instance of `RpcTarget` is passed over RPC multiple times, a new stub is created each time, and these are not considered duplicates of each other. Thus, the disposer will be invoked once for each time the `RpcTarget` was sent.

In order to avoid this situation, you can manually create a stub locally, and then pass the stub across RPC multiple times. When passing a stub over RPC, ownership of the stub transfers to the recipient, so you must make a `dup()` for each time you send it:

```js
import { RpcTarget, RpcStub } from "cloudflare:workers";

class Foo extends RpcTarget {
	// ...
}

let obj = new Foo();
let stub = new RpcStub(obj);
await rpc1(stub.dup()); // sends a dup of `stub`
await rpc2(stub.dup()); // sends another dup of `stub`
stub[Symbol.dispose](); // disposes the original stub

// obj's disposer will be called when the other two stubs
// are disposed remotely.
```

---

# TypeScript

URL: https://developers.cloudflare.com/workers/runtime-apis/rpc/typescript/

import { PackageManagers } from "~/components";

Running [`wrangler types`](/workers/languages/typescript/#generate-types) generates runtime types including the `Service` and `DurableObjectNamespace` types, each of which accepts a single type parameter for the [`WorkerEntrypoint`](/workers/runtime-apis/bindings/service-bindings/rpc) or [`DurableObject`](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#call-rpc-methods) types.

Using higher-order types, we automatically generate client-side stub types (e.g., forcing all methods to be async).

[`wrangler types`](/workers/languages/typescript/#generate-types) also generates types for the `env` object. You can pass in the path to the config files of the Worker or Durable Object being called so that the generated types include the type parameters for the `Service` and `DurableObjectNamespace` types.

For example, if your client Worker had bindings to a Worker in `../sum-worker/` and a Durable Object in `../counter/`, you should generate types for the client Worker's `env` by running:

<PackageManagers
	type="exec"
	pkg="wrangler"
	args={
		"types -c ./client/wrangler.jsonc -c ../sum-worker/wrangler.jsonc -c ../counter/wrangler.jsonc"
	}
/>

:::note
If your service binding targets a `WorkerEntrypoint` that is a default export, make sure you set `entrypoint: "default"` in your Wrangler config when you configure your service binding.
:::

This will produce a `worker-configuration.d.ts` file that includes:

```ts title="worker-configuration.d.ts"
interface Env {
	SUM_SERVICE: Service<import("../sum-worker/src/index").SumService>;
	COUNTER_OBJECT: DurableObjectNamespace<
		import("../counter/src/index").Counter
	>;
}
```

Now types for RPC method like the `env.SUM_SERVICE.sum` method will be exposed to the client Worker.

```ts title="src/index.ts"
export default {
	async fetch(req, env, ctx): Promise<Response> {
		const result = await env.SUM_SERVICE.sum(1, 2);
		return new Response(result.toString());
	},
} satisfies ExportedHandler<Env>;
```

---

# Visibility and Security Model

URL: https://developers.cloudflare.com/workers/runtime-apis/rpc/visibility/

## Security Model

The Workers RPC system is intended to allow safe communications between Workers that do not trust each other. The system does not allow either side of an RPC session to access arbitrary objects on the other side, much less invoke arbitrary code. Instead, each side can only invoke the objects and functions for which they have explicitly received stubs via previous calls.

This security model is commonly known as Object Capabilities, or Capability-Based Security. Workers RPC is built on [Cap'n Proto RPC](https://capnproto.org/rpc.html), which in turn is based on CapTP, the object transport protocol used by the [distributed programming language E](https://www.crockford.com/ec/etut.html).

## Visibility of Methods and Properties

### Private properties

[Private properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_properties) of classes are not directly exposed over RPC.

### Class instance properties

When you send an instance of an application-defined class, the recipient can only access methods and properties declared on the class, not properties of the instance. For example:

```js
class Foo extends RpcTarget {
  constructor() {
    super();

    // i CANNOT be accessed over RPC
    this.i = 0;

    // funcProp CANNOT be called over RPC
    this.funcProp = () => {}
  }

  // value CAN be accessed over RPC
  get value() {
    return this.i;
  }

  // method CAN be called over RPC
  method() {}
}
```

This behavior is intentional — it is intended to protect you from accidentally exposing private class internals. Generally, instance properties should be declared private, [by prefixing them with `#`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_properties). However, private properties are a relatively new feature of JavaScript, and are not yet widely used in the ecosystem.

Since the RPC interface between two of your Workers may be a security boundary, we need to be extra-careful, so instance properties are always private when communicating between Workers using RPC, whether or not they have the `#` prefix. You can always declare an explicit getter at the class level if you wish to expose the property, as shown above.

These visibility rules apply only to objects that extend `RpcTarget`, `WorkerEntrypoint`, or `DurableObject`, and do not apply to plain objects. Plain objects are passed "by value", sending all of their "own" properties.

### "Own" properties of functions

When you pass a function over RPC, the caller can access the "own" properties of the function object itself.

```js
someRpcMethod() {
  let func = () => {};
  func.prop = 123;  // `prop` is visible over RPC
  return func;
}
```

Such properties on a function are accessed asynchronously, like class properties of an RpcTarget. But, unlike the `RpcTarget` example above, the function's instance properties that are accessible to the caller. In practice, properties are rarely added to functions.

---

# Streams

URL: https://developers.cloudflare.com/workers/runtime-apis/streams/

import { DirectoryListing, TabItem, Tabs } from "~/components";

The [Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) is a web standard API that allows JavaScript to programmatically access and process streams of data.

<DirectoryListing />

Workers do not need to prepare an entire response body before returning a `Response`. You can use a [`ReadableStream`](/workers/runtime-apis/streams/readablestream/) to stream a response body after sending the front matter (that is, HTTP status line and headers). This allows you to minimize:

- The visitor's time-to-first-byte.
- The buffering done in the Worker.

Minimizing buffering is especially important for processing or transforming response bodies larger than the Worker's memory limit. For these cases, streaming is the only implementation strategy.

:::note

By default, Cloudflare Workers is capable of streaming responses using the [Streams APIs](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API). To maintain the streaming behavior, you should only modify the response body using the methods in the Streams APIs. If your Worker only forwards subrequest responses to the client verbatim without reading their body text, then its body handling is already optimal and you do not have to use these APIs.

:::

The worker can create a `Response` object using a `ReadableStream` as the body. Any data provided through the
`ReadableStream` will be streamed to the client as it becomes available.

<Tabs> <TabItem label="Module Worker" icon="seti:javascript">

```js
export default {
	async fetch(request, env, ctx) {
		// Fetch from origin server.
		const response = await fetch(request);

		// ... and deliver our Response while that’s running.
		return new Response(response.body, response);
	},
};
```

</TabItem> <TabItem label="Service Worker" icon="seti:javascript">

:::caution[Service Workers are deprecated]

Service Workers are deprecated, but still supported. We recommend using [Module Workers](/workers/reference/migrate-to-module-workers/) instead. New features may not be supported for Service Workers.

:::

```js
addEventListener("fetch", (event) => {
	event.respondWith(fetchAndStream(event.request));
});

async function fetchAndStream(request) {
	// Fetch from origin server.
	const response = await fetch(request);

	// ... and deliver our Response while that’s running.
	return new Response(readable.body, response);
}
```

</TabItem> </Tabs>

A [`TransformStream`](/workers/runtime-apis/streams/transformstream/) and the [`ReadableStream.pipeTo()`](/workers/runtime-apis/streams/readablestream/#methods) method can be used to modify the response body as it is being streamed:

<Tabs> <TabItem label="Module Worker" icon="seti:javascript">

```js
export default {
	async fetch(request, env, ctx) {
		// Fetch from origin server.
		const response = await fetch(request);

		const { readable, writable } = new TransformStream({
			transform(chunk, controller) {
				controller.enqueue(modifyChunkSomehow(chunk));
			},
		});

		// Start pumping the body. NOTE: No await!
		response.body.pipeTo(writable);

		// ... and deliver our Response while that’s running.
		return new Response(readable, response);
	},
};
```

</TabItem> <TabItem label="Service Worker" icon="seti:javascript">

:::caution[Service Workers are deprecated]

Service Workers are deprecated, but still supported. We recommend using [Module Workers](/workers/reference/migrate-to-module-workers/) instead. New features may not be supported for Service Workers.

:::

```js
addEventListener("fetch", (event) => {
	event.respondWith(fetchAndStream(event.request));
});

async function fetchAndStream(request) {
	// Fetch from origin server.
	const response = await fetch(request);

	const { readable, writable } = new TransformStream({
		transform(chunk, controller) {
			controller.enqueue(modifyChunkSomehow(chunk));
		},
	});

	// Start pumping the body. NOTE: No await!
	response.body.pipeTo(writable);

	// ... and deliver our Response while that’s running.
	return new Response(readable, response);
}
```

</TabItem> </Tabs>

This example calls `response.body.pipeTo(writable)` but does not `await` it. This is so it does not block the forward progress of the remainder of the `fetchAndStream()` function. It continues to run asynchronously until the response is complete or the client disconnects.

The runtime can continue running a function (`response.body.pipeTo(writable)`) after a response is returned to the client. This example pumps the subrequest response body to the final response body. However, you can use more complicated logic, such as adding a prefix or a suffix to the body or to process it somehow.

---

## Common issues

:::caution[Warning]

The Streams API is only available inside of the [Request context](/workers/runtime-apis/request/), inside the `fetch` event listener callback.

:::

---

## Related resources

- [MDN's Streams API documentation](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API)
- [Streams API spec](https://streams.spec.whatwg.org/)
- Write your Worker code in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.

---

# ReadableStream

URL: https://developers.cloudflare.com/workers/runtime-apis/streams/readablestream/

## Background

A `ReadableStream` is returned by the `readable` property inside [`TransformStream`](/workers/runtime-apis/streams/transformstream/).

## Properties



* `locked` boolean
  * A Boolean value that indicates if the readable stream is locked to a reader.



## Methods



* <code>pipeTo(destinationWritableStream, optionsPipeToOptions)</code> : Promise\<void>

  * Pipes the readable stream to a given writable stream `destination` and returns a promise that is fulfilled when the `write` operation succeeds or rejects it if the operation fails.

* <code>getReader(optionsObject)</code> : ReadableStreamDefaultReader

  * Gets an instance of `ReadableStreamDefaultReader` and locks the `ReadableStream` to that reader instance. This method accepts an object argument indicating options. The only supported option is `mode`, which can be set to `byob` to create a [`ReadableStreamBYOBReader`](/workers/runtime-apis/streams/readablestreambyobreader/), as shown here:

```js
let reader = readable.getReader({ mode: 'byob' });
```



### `PipeToOptions`



* `preventClose` bool

  * When `true`, closure of the source `ReadableStream` will not cause the destination `WritableStream` to be closed.

* `preventAbort` bool

  * When `true`, errors in the source `ReadableStream` will no longer abort the destination `WritableStream`. `pipeTo` will return a rejected promise with the error from the source or any error that occurred while aborting the destination.



***

## Related resources

* [Streams](/workers/runtime-apis/streams/)
* [Readable streams in the WHATWG Streams API specification](https://streams.spec.whatwg.org/#rs-model)
* [MDN’s `ReadableStream` documentation](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)

---

# ReadableStream BYOBReader

URL: https://developers.cloudflare.com/workers/runtime-apis/streams/readablestreambyobreader/

{/* <!-- The space in the title was introduced to create a pleasing line-break in the title in the sidebar. --> */}

{/* <!-- TODO: See EW-2105. Should we document this if it isn’t effectively using buffer space? --> */}

## Background

`BYOB` is an abbreviation of bring your own buffer. A `ReadableStreamBYOBReader` allows reading into a developer-supplied buffer, thus minimizing copies.

An instance of `ReadableStreamBYOBReader` is functionally identical to [`ReadableStreamDefaultReader`](/workers/runtime-apis/streams/readablestreamdefaultreader/) with the exception of the `read` method.

A `ReadableStreamBYOBReader` is not instantiated via its constructor. Rather, it is retrieved from a [`ReadableStream`](/workers/runtime-apis/streams/readablestream/):

```js
const { readable, writable } = new TransformStream();
const reader = readable.getReader({ mode: 'byob' });
```

***

## Methods



* <code>read(bufferArrayBufferView)</code> : Promise\<ReadableStreamBYOBReadResult>

  * Returns a promise with the next available chunk of data read into a passed-in buffer.

* <code>readAtLeast(minBytes, bufferArrayBufferView)</code> : Promise\<ReadableStreamBYOBReadResult>

  * Returns a promise with the next available chunk of data read into a passed-in buffer. The promise will not resolve until at least `minBytes` have been read.



***

## Common issues

:::caution[Warning]


`read` provides no control over the minimum number of bytes that should be read into the buffer. Even if you allocate a 1 MiB buffer, the kernel is perfectly within its rights to fulfill this read with a single byte, whether or not an EOF immediately follows.

In practice, the Workers team has found that `read` typically fills only 1% of the provided buffer.

`readAtLeast` is a non-standard extension to the Streams API which allows users to specify that at least `minBytes` bytes must be read into the buffer before resolving the read.


:::

***

## Related resources

* [Streams](/workers/runtime-apis/streams/)
* [Background about BYOB readers in the Streams API WHATWG specification](https://streams.spec.whatwg.org/#byob-readers)

---

# ReadableStream DefaultReader

URL: https://developers.cloudflare.com/workers/runtime-apis/streams/readablestreamdefaultreader/

{/* <!-- The space in the title was introduced to create a pleasing line-break in the title in the sidebar. --> */}

## Background

A reader is used when you want to read from a [`ReadableStream`](/workers/runtime-apis/streams/readablestream/), rather than piping its output to a [`WritableStream`](/workers/runtime-apis/streams/writablestream/).

A `ReadableStreamDefaultReader` is not instantiated via its constructor. Rather, it is retrieved from a [`ReadableStream`](/workers/runtime-apis/streams/readablestream/):

```js
const { readable, writable } = new TransformStream();
const reader = readable.getReader();
```

***

## Properties



* `reader.closed` : Promise

  * A promise indicating if the reader is closed. The promise is fulfilled when the reader stream closes and is rejected if there is an error in the stream.



## Methods



* `read()` : Promise

  * A promise that returns the next available chunk of data being passed through the reader queue.

* <code>cancel(reasonstringoptional)</code> : void

  * Cancels the stream. `reason` is an optional human-readable string indicating the reason for cancellation. `reason` will be passed to the underlying source’s cancel algorithm -- if this readable stream is one side of a [`TransformStream`](/workers/runtime-apis/streams/transformstream/), then its cancel algorithm causes the transform’s writable side to become errored with `reason`.

  :::caution[Warning]

  Any data not yet read is lost.
  :::

* `releaseLock()` : void

  * Releases the lock on the readable stream. A lock cannot be released if the reader has pending read operations. A `TypeError` is thrown and the reader remains locked.



***

## Related resources

* [Streams](/workers/runtime-apis/streams/)
* [Readable streams in the WHATWG Streams API specification](https://streams.spec.whatwg.org/#rs-model)

---

# TransformStream

URL: https://developers.cloudflare.com/workers/runtime-apis/streams/transformstream/

## Background

A transform stream consists of a pair of streams: a writable stream, known as its writable side, and a readable stream, known as its readable side. Writes to the writable side result in new data being made available for reading from the readable side.

Workers currently only implements an identity transform stream, a type of transform stream which forwards all chunks written to its writable side to its readable side, without any changes.

***

## Constructor

```js
let { readable, writable } = new TransformStream();
```



* `TransformStream()` TransformStream

  * Returns a new identity transform stream.



## Properties



* `readable` ReadableStream
  * An instance of a `ReadableStream`.
* `writable` WritableStream
  * An instance of a `WritableStream`.



***

## `IdentityTransformStream`

The current implementation of `TransformStream` in the Workers platform is not current compliant with the [Streams Standard](https://streams.spec.whatwg.org/#transform-stream) and we will soon be making changes to the implementation to make it conform with the specification. In preparation for doing so, we have introduced the `IdentityTransformStream` class that implements behavior identical to the current `TransformStream` class. This type of stream forwards all chunks of byte data (in the form of `TypedArray`s) written to its writable side to its readable side, without any changes.

The `IdentityTransformStream` readable side supports [bring your own buffer (BYOB) reads](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader).

### Constructor

```js
let { readable, writable } = new IdentityTransformStream();
```



* `IdentityTransformStream()` IdentityTransformStream

  * Returns a new identity transform stream.



### Properties



* `readable` ReadableStream
  * An instance of a `ReadableStream`.
* `writable` WritableStream
  * An instance of a `WritableStream`.



***

## `FixedLengthStream`

The `FixedLengthStream` is a specialization of `IdentityTransformStream` that limits the total number of bytes that the stream will passthrough. It is useful primarily because, when using `FixedLengthStream` to produce either a `Response` or `Request`, the fixed length of the stream will be used as the `Content-Length` header value as opposed to use chunked encoding when using any other type of stream. An error will occur if too many, or too few bytes are written through the stream.

### Constructor

```js
let { readable, writable } = new FixedLengthStream(1000);
```



* `FixedLengthStream(length)` FixedLengthStream

  * Returns a new identity transform stream.
  * `length` maybe a `number` or `bigint` with a maximum value of `2^53 - 1`.



### Properties



* `readable` ReadableStream
  * An instance of a `ReadableStream`.
* `writable` WritableStream
  * An instance of a `WritableStream`.



***

## Related resources

* [Streams](/workers/runtime-apis/streams/)
* [Transform Streams in the WHATWG Streams API specification](https://streams.spec.whatwg.org/#transform-stream)

---

# WritableStream

URL: https://developers.cloudflare.com/workers/runtime-apis/streams/writablestream/

## Background

A `WritableStream` is the `writable` property of a [`TransformStream`](/workers/runtime-apis/streams/transformstream/). On the Workers platform, `WritableStream` cannot be directly created using the `WritableStream` constructor.

A typical way to write to a `WritableStream` is to pipe a [`ReadableStream`](/workers/runtime-apis/streams/readablestream/) to it.

```js
readableStream
  .pipeTo(writableStream)
  .then(() => console.log('All data successfully written!'))
  .catch(e => console.error('Something went wrong!', e));
```

To write to a `WritableStream` directly, you must use its writer.

```js
const writer = writableStream.getWriter();
writer.write(data);
```

Refer to the [WritableStreamDefaultWriter](/workers/runtime-apis/streams/writablestreamdefaultwriter/) documentation for further detail.

## Properties



* `locked` boolean

  * A Boolean value to indicate if the writable stream is locked to a writer.



## Methods



* <code>abort(reasonstringoptional)</code> : Promise\<void>

  * Aborts the stream. This method returns a promise that fulfills with a response `undefined`. `reason` is an optional human-readable string indicating the reason for cancellation. `reason` will be passed to the underlying sink’s abort algorithm. If this writable stream is one side of a [TransformStream](/workers/runtime-apis/streams/transformstream/), then its abort algorithm causes the transform’s readable side to become errored with `reason`.

  :::caution[Warning]

  Any data not yet written is lost upon abort.
  :::

* `getWriter()` : WritableStreamDefaultWriter

  * Gets an instance of `WritableStreamDefaultWriter` and locks the `WritableStream` to that writer instance.



***

## Related resources

* [Streams](/workers/runtime-apis/streams/)
* [Writable streams in the WHATWG Streams API specification](https://streams.spec.whatwg.org/#ws-model)

---

# WritableStream DefaultWriter

URL: https://developers.cloudflare.com/workers/runtime-apis/streams/writablestreamdefaultwriter/

{/* <!-- The space in the title was introduced to create a pleasing line-break in the title in the sidebar. --> */}

## Background

A writer is used when you want to write directly to a [`WritableStream`](/workers/runtime-apis/streams/writablestream/), rather than piping data to it from a [`ReadableStream`](/workers/runtime-apis/streams/readablestream/). For example:

```js
function writeArrayToStream(array, writableStream) {
  const writer = writableStream.getWriter();
  array.forEach(chunk => writer.write(chunk).catch(() => {}));

  return writer.close();
}

writeArrayToStream([1, 2, 3, 4, 5], writableStream)
  .then(() => console.log('All done!'))
  .catch(e => console.error('Error with the stream: ' + e));
```

## Properties



* `writer.desiredSize` int

  * The size needed to fill the stream’s internal queue, as an integer. Always returns 1, 0 (if the stream is closed), or `null` (if the stream has errors).

* `writer.closed` Promise\<void>

  * A promise that indicates if the writer is closed. The promise is fulfilled when the writer stream is closed and rejected if there is an error in the stream.



## Methods



* <code>abort(reasonstringoptional)</code> : Promise\<void>

  * Aborts the stream. This method returns a promise that fulfills with a response `undefined`. `reason` is an optional human-readable string indicating the reason for cancellation. `reason` will be passed to the underlying sink’s abort algorithm. If this writable stream is one side of a [TransformStream](/workers/runtime-apis/streams/transformstream/), then its abort algorithm causes the transform’s readable side to become errored with `reason`.

  :::caution[Warning]

  Any data not yet written is lost upon abort.
  :::

* `close()` : Promise\<void>

  * Attempts to close the writer. Remaining writes finish processing before the writer is closed. This method returns a promise fulfilled with `undefined` if the writer successfully closes and processes the remaining writes, or rejected on any error.

* `releaseLock()` : void

  * Releases the writer’s lock on the stream. Once released, the writer is no longer active. You can call this method before all pending `write(chunk)` calls are resolved. This allows you to queue a `write` operation, release the lock, and begin piping into the writable stream from another source, as shown in the example below.

```js
let writer = writable.getWriter();
// Write a preamble.
writer.write(new TextEncoder().encode('foo bar'));
// While that’s still writing, pipe the rest of the body from somewhere else.
writer.releaseLock();
await someResponse.body.pipeTo(writable);
```

* <code>write(chunkany)</code> : Promise\<void>

  * Writes a chunk of data to the writer and returns a promise that resolves if the operation succeeds.
  * The underlying stream may accept fewer kinds of type than `any`, it will throw an exception when encountering an unexpected type.



***

## Related resources

* [Streams](/workers/runtime-apis/streams/)
* [Writable streams in the WHATWG Streams API specification](https://streams.spec.whatwg.org/#ws-model)

---

# WebAssembly (Wasm)

URL: https://developers.cloudflare.com/workers/runtime-apis/webassembly/

import { DirectoryListing } from "~/components"

[WebAssembly](https://webassembly.org/) (abbreviated Wasm) allows you to compile languages like [Rust](/workers/languages/rust/), Go, or C to a binary format that can run in a wide variety of environments, including [web browsers](https://developer.mozilla.org/en-US/docs/WebAssembly#browser_compatibility), Cloudflare Workers, and other WebAssembly runtimes.

On Workers and in [Cloudflare Pages Functions](https://blog.cloudflare.com/pages-functions-with-webassembly/), you can use WebAssembly to:

* Execute code written in a language other than JavaScript, via `WebAssembly.instantiate()`.
* Write an entire Cloudflare Worker in Rust, using bindings that make Workers' JavaScript APIs available directly from your Rust code.

Most programming languages can be compiled to Wasm, although support varies across languages and compilers. Guides are available for the following languages:

<DirectoryListing />

## Supported proposals

WebAssembly is a rapidly evolving set of standards, with [many proposed APIs](https://webassembly.org/roadmap/) which are in various stages of development. In general, Workers supports the same set of features that are available in Google Chrome.

### SIMD

SIMD is supported on Workers. For more information on using SIMD in WebAssembly, refer to [Fast, parallel applications with WebAssembly SIMD](https://v8.dev/features/simd).

### Threading

Threading is not possible in Workers. Each Worker runs in a single thread, and the [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) API is not supported.

## Binary size

Compiling to WebAssembly often requires including additional runtime dependencies. As a result, Workers that use WebAssembly are typically larger than an equivalent Worker written in JavaScript. The larger your Worker is, the longer it may take your Worker to start. Refer to [Worker startup time](https://developers.cloudflare.com/workers/platform/limits/#worker-startup-time) for more information. We recommend using tools like [`wasm-opt`](https://github.com/brson/wasm-opt-rs) to optimize the size of your Wasm binary.

## WebAssembly System Interface (WASI)

The [WebAssembly System Interface](https://wasi.dev/) (abbreviated WASI) is a modular system interface for WebAssembly that standardizes a set of underlying system calls for networking, file system access, and more. Applications can depend on the WebAssembly System Interface to behave identically across host environments and operating systems.

WASI is an earlier and more rapidly evolving set of standards than Wasm. WASI support is experimental on Cloudflare Workers, with only some syscalls implemented. Refer to our [open source implementation of WASI](https://github.com/cloudflare/workers-wasi), and [blog post about WASI on Workers](https://blog.cloudflare.com/announcing-wasi-on-workers/) demonstrating its use.

### Resources on WebAssembly

* [Serverless Rust with Cloudflare Workers](https://blog.cloudflare.com/cloudflare-workers-as-a-serverless-rust-platform/)
* [WebAssembly on Cloudflare Workers](https://blog.cloudflare.com/webassembly-on-cloudflare-workers/)

---

# Wasm in JavaScript

URL: https://developers.cloudflare.com/workers/runtime-apis/webassembly/javascript/

Wasm can be used from within a Worker written in JavaScript or TypeScript by importing a Wasm module,
and instantiating an instance of this module using [`WebAssembly.instantiate()`](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/instantiate). This can be used to accelerate computationally intensive operations which do not involve significant I/O.

This guide demonstrates the basics of Wasm and JavaScript interoperability.

## Simple Wasm Module

In this guide, you will use the WebAssembly Text Format to create a simple Wasm module to understand how imports and exports work. In practice, you would not write code in this format. You would instead use the programming language of your choice and compile directly to WebAssembly Binary Format (`.wasm`).

Review the following example module (`;;` denotes a comment):

```txt
;; src/simple.wat
(module
  ;; Import a function from JavaScript named `imported_func`
  ;; which takes a single i32 argument and assign to
  ;; variable $i
  (func $i (import "imports" "imported_func") (param i32))
  ;; Export a function named `exported_func` which takes a
  ;; single i32 argument and returns an i32
  (func (export "exported_func") (param $input i32) (result i32)
    ;; Invoke `imported_func` with $input as argument
    local.get $input
    call $i
    ;; Return $input
    local.get $input
    return
  )
)
```

Using [`wat2wasm`](https://github.com/WebAssembly/wabt), convert the WAT format to WebAssembly Binary Format:

```sh
wat2wasm src/simple.wat -o src/simple.wasm
```

## Bundling

Wrangler will bundle any Wasm module that ends in `.wasm` or `.wasm?module`, so that it is available at runtime within your Worker. This is done using a default bundling rule which can be customized in the [Wrangler configuration file](/workers/wrangler/configuration/). Refer to [Wrangler Bundling](/workers/wrangler/bundling/) for more information.

## Use from JavaScript

After you have converted the WAT format to WebAssembly Binary Format, import and use the Wasm module in your existing JavaScript or TypeScript Worker:

```typescript
import mod from "./simple.wasm";

// Define imports available to Wasm instance.
const importObject = {
	imports: {
		imported_func: (arg: number) => {
			console.log(`Hello from JavaScript: ${arg}`);
		},
	},
};

// Create instance of WebAssembly Module `mod`, supplying
// the expected imports in `importObject`. This should be
// done at the top level of the script to avoid instantiation on every request.
const instance = await WebAssembly.instantiate(mod, importObject);

export default {
	async fetch() {
		// Invoke the `exported_func` from our Wasm Instance with
		// an argument.
		const retval = instance.exports.exported_func(42);
		// Return the return value!
		return new Response(`Success: ${retval}`);
	},
};
```

When invoked, this Worker should log `Hello from JavaScript: 42` and return `Success: 42`, demonstrating the ability to invoke Wasm methods with arguments from JavaScript and vice versa.

## Next steps

In practice, you will likely compile a language of your choice (such as Rust) to WebAssembly binaries. Many languages provide a `bindgen` to simplify the interaction between JavaScript and Wasm. These tools may integrate with your JavaScript bundler, and provide an API other than the WebAssembly API for initializing and invoking your Wasm module. As an example, refer to the [Rust `wasm-bindgen` documentation](https://rustwasm.github.io/wasm-bindgen/examples/without-a-bundler.html).

Alternatively, to write your entire Worker in Rust, Workers provides many of the same [Runtime APIs](/workers/runtime-apis) and [bindings](/workers/runtime-apis/bindings/) when using the `workers-rs` crate. For more information, refer to the [Workers Rust guide](/workers/languages/rust/).

---

# Get Started

URL: https://developers.cloudflare.com/workers/testing/miniflare/get-started/

import { PackageManagers } from "~/components";

The Miniflare API allows you to dispatch events to workers without making actual HTTP requests, simulate connections between Workers, and interact with local emulations of storage products like [KV](/workers/testing/miniflare/storage/kv), [R2](/workers/testing/miniflare/storage/r2), and [Durable Objects](/workers/testing/miniflare/storage/durable-objects). This makes it great for writing tests, or other advanced use cases where you need finer-grained control.

## Installation

Miniflare is installed using `npm` as a dev dependency:

<PackageManagers pkg="miniflare" dev />

## Usage

In all future examples, we'll assume Node.js is running in ES module mode. You
can do this by setting the `type` field in your `package.json`:

```json title=package.json
{
	...
	"type": "module"
	...
}
```

To initialise Miniflare, import the `Miniflare` class from `miniflare`:

```js
import { Miniflare } from "miniflare";

const mf = new Miniflare({
	modules: true,
	script: `
  export default {
    async fetch(request, env, ctx) {
      return new Response("Hello Miniflare!");
    }
  }
  `,
});

const res = await mf.dispatchFetch("http://localhost:8787/");
console.log(await res.text()); // Hello Miniflare!
await mf.dispose();
```

The [rest of these docs](/workers/testing/miniflare/core/fetch) go into more detail on configuring
specific features.

### String and File Scripts

Note in the above example we're specifying `script` as a string. We could've
equally put the script in a file such as `worker.js`, then used the `scriptPath`
property instead:

```js
const mf = new Miniflare({
	scriptPath: "worker.js",
});
```

### Watching, Reloading and Disposing

Miniflare's API is primarily intended for testing use cases, where file watching isn't usually required. If you need to watch files, consider using a separate file watcher like [fs.watch()](https://nodejs.org/api/fs.html#fswatchfilename-options-listener) or [chokidar](https://github.com/paulmillr/chokidar), and calling setOptions() with your original configuration on change.

To cleanup and stop listening for requests, you should `dispose()` your instances:

```js
await mf.dispose();
```

You can also manually reload scripts (main and Durable Objects') and options by calling `setOptions()` with the original configuration object.

### Updating Options and the Global Scope

You can use the `setOptions` method to update the options of an existing
`Miniflare` instance. This accepts the same options object as the
`new Miniflare` constructor, applies those options, then reloads the worker.

```js
const mf = new Miniflare({
	script: "...",
	kvNamespaces: ["TEST_NAMESPACE"],
	bindings: { KEY: "value1" },
});

await mf.setOptions({
	script: "...",
	kvNamespaces: ["TEST_NAMESPACE"],
	bindings: { KEY: "value2" },
});
```

### Dispatching Events

`getWorker` dispatches `fetch`, `queues`, and `scheduled` events
to workers respectively:

```js
import { Miniflare } from "miniflare";

const mf = new Miniflare({
	modules: true,
	script: `
	let lastScheduledController;
	let lastQueueBatch;
	export default {
		async fetch(request, env, ctx) {
			const { pathname } = new URL(request.url);
			if (pathname === "/scheduled") {
				return Response.json({
					scheduledTime: lastScheduledController?.scheduledTime,
					cron: lastScheduledController?.cron,
				});
			} else if (pathname === "/queue") {
				return Response.json({
					queue: lastQueueBatch.queue,
					messages: lastQueueBatch.messages.map((message) => ({
					id: message.id,
					timestamp: message.timestamp.getTime(),
					body: message.body,
					bodyType: message.body.constructor.name,
					})),
				});
			} else if (pathname === "/get-url") {
				return new Response(request.url);
			} else {
				return new Response(null, { status: 404 });
			}
		},
		async scheduled(controller, env, ctx) {
			lastScheduledController = controller;
			if (controller.cron === "* * * * *") controller.noRetry();
		},
		async queue(batch, env, ctx) {
			lastQueueBatch = batch;
			if (batch.queue === "needy") batch.retryAll();
			for (const message of batch.messages) {
				if (message.id === "perfect") message.ack();
			}
		}
	}`,
});

const res = await mf.dispatchFetch("http://localhost:8787/", {
	headers: { "X-Message": "Hello Miniflare!" },
});
console.log(await res.text()); // Hello Miniflare!

const worker = await mf.getWorker();

const scheduledResult = await worker.scheduled({
	cron: "* * * * *",
});
console.log(scheduledResult); // { outcome: "ok", noRetry: true });

const queueResult = await worker.queue("needy", [
	{ id: "a", timestamp: new Date(1000), body: "a", attempts: 1 },
	{ id: "b", timestamp: new Date(2000), body: { b: 1 }, attempts: 1 },
]);
console.log(queueResult); // { outcome: "ok", retryAll: true, ackAll: false, explicitRetries: [], explicitAcks: []}
```

See [📨 Fetch Events](/workers/testing/miniflare/core/fetch) and [⏰ Scheduled Events](/workers/testing/miniflare/core/scheduled)
for more details.

### HTTP Server

Miniflare starts an HTTP server automatically. To wait for it to be ready, `await` the `ready` property:

```js {11}
import { Miniflare } from "miniflare";

const mf = new Miniflare({
	modules: true,
	script: `
  export default {
    async fetch(request, env, ctx) {
      return new Response("Hello Miniflare!");
    })
  }
  `,
	port: 5000,
});
await mf.ready;
console.log("Listening on :5000");
```

#### `Request#cf` Object

By default, Miniflare will fetch the `Request#cf` object from a trusted
Cloudflare endpoint. You can disable this behaviour, using the `cf` option:

```js
const mf = new Miniflare({
	cf: false,
});
```

You can also provide a custom cf object via a filepath:

```js
const mf = new Miniflare({
	cf: "cf.json",
});
```

### HTTPS Server

To start an HTTPS server instead, set the `https` option. To use the [default shared self-signed certificate](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare/src/http/cert.ts), set `https` to `true`:

```js
const mf = new Miniflare({
	https: true,
});
```

To load an existing certificate from the file system:

```js
const mf = new Miniflare({
	// These are all optional, you don't need to include them all
	httpsKeyPath: "./key.pem",
	httpsCertPath: "./cert.pem",
});
```

To load an existing certificate from strings instead:

```js
const mf = new Miniflare({
	// These are all optional, you don't need to include them all
	httpsKey: "-----BEGIN RSA PRIVATE KEY-----...",
	httpsCert: "-----BEGIN CERTIFICATE-----...",
});
```

If both a string and path are specified for an option (e.g. `httpsKey` and
`httpsKeyPath`), the string will be preferred.

### Logging

By default, `[mf:*]` logs are disabled when using the API. To
enable these, set the `log` property to an instance of the `Log` class. Its only
parameter is a log level indicating which messages should be logged:

```js {5}
import { Miniflare, Log, LogLevel } from "miniflare";

const mf = new Miniflare({
	scriptPath: "worker.js",
	log: new Log(LogLevel.DEBUG), // Enable debug messages
});
```

## Reference

```js
import { Miniflare, Log, LogLevel } from "miniflare";

const mf = new Miniflare({
  // All options are optional, but one of script or scriptPath is required

  log: new Log(LogLevel.INFO), // Logger Miniflare uses for debugging

  script: `
    export default {
      async fetch(request, env, ctx) {
        return new Response("Hello Miniflare!");
      }
    }
  `,
  scriptPath: "./index.js",

  modules: true, // Enable modules
  modulesRules: [
    // Modules import rule
    { type: "ESModule", include: ["**/*.js"], fallthrough: true },
    { type: "Text", include: ["**/*.text"] },
  ],
  compatibilityDate: "2021-11-23", // Opt into backwards-incompatible changes from
  compatibilityFlags: ["formdata_parser_supports_files"], // Control specific backwards-incompatible changes
  upstream: "https://miniflare.dev", // URL of upstream origin
  workers: [{
    // reference additional named workers
    name: "worker2",
    kvNamespaces: { COUNTS: "counts" },
    serviceBindings: {
      INCREMENTER: "incrementer",
      // Service bindings can also be defined as custom functions, with access
      // to anything defined outside Miniflare.
      async CUSTOM(request) {
        // `request` is the incoming `Request` object.
        return new Response(message);
      },
    },
    modules: true,
    script: `export default {
        async fetch(request, env, ctx) {
          // Get the message defined outside
          const response = await env.CUSTOM.fetch("http://host/");
          const message = await response.text();

          // Increment the count 3 times
          await env.INCREMENTER.fetch("http://host/");
          await env.INCREMENTER.fetch("http://host/");
          await env.INCREMENTER.fetch("http://host/");
          const count = await env.COUNTS.get("count");

          return new Response(message + count);
        }
      }`,
    },
  }],
  name: "worker", // Name of service
  routes: ["*site.mf/worker"],


  host: "127.0.0.1", // Host for HTTP(S) server to listen on
  port: 8787, // Port for HTTP(S) server to listen on
  https: true, // Enable self-signed HTTPS (with optional cert path)
  httpsKey: "-----BEGIN RSA PRIVATE KEY-----...",
  httpsKeyPath: "./key.pem", // Path to PEM SSL key
  httpsCert: "-----BEGIN CERTIFICATE-----...",
  httpsCertPath: "./cert.pem", // Path to PEM SSL cert chain
  cf: "./node_modules/.mf/cf.json", // Path for cached Request cf object from Cloudflare
  liveReload: true, // Reload HTML pages whenever worker is reloaded



  kvNamespaces: ["TEST_NAMESPACE"], // KV namespace to bind
  kvPersist: "./kv-data", // Persist KV data (to optional path)

  r2Buckets: ["BUCKET"], // R2 bucket to bind
  r2Persist: "./r2-data", // Persist R2 data (to optional path)

  durableObjects: {
    // Durable Object to bind
    TEST_OBJECT: "TestObject", // className
    API_OBJECT: { className: "ApiObject", scriptName: "api" },
  },
  durableObjectsPersist: "./durable-objects-data", // Persist Durable Object data (to optional path)

  cache: false, // Enable default/named caches (enabled by default)
  cachePersist: "./cache-data", // Persist cached data (to optional path)
  cacheWarnUsage: true, // Warn on cache usage, for workers.dev subdomains

  sitePath: "./site", // Path to serve Workers Site files from
  siteInclude: ["**/*.html", "**/*.css", "**/*.js"], // Glob pattern of site files to serve
  siteExclude: ["node_modules"], // Glob pattern of site files not to serve


  bindings: { SECRET: "sssh" }, // Binds variable/secret to environment
  wasmBindings: { ADD_MODULE: "./add.wasm" }, // WASM module to bind
  textBlobBindings: { TEXT: "./text.txt" }, // Text blob to bind
  dataBlobBindings: { DATA: "./data.bin" }, // Data blob to bind
});

await mf.setOptions({ kvNamespaces: ["TEST_NAMESPACE2"] }); // Apply options and reload

const bindings = await mf.getBindings(); // Get bindings (KV/Durable Object namespaces, variables, etc)

// Dispatch "fetch" event to worker
const res = await mf.dispatchFetch("http://localhost:8787/", {
  headers: { Authorization: "Bearer ..." },
});
const text = await res.text();

const worker = await mf.getWorker();

// Dispatch "scheduled" event to worker
const scheduledResult = await worker.scheduled({ cron: "30 * * * *" })

const TEST_NAMESPACE = await mf.getKVNamespace("TEST_NAMESPACE");

const BUCKET = await mf.getR2Bucket("BUCKET");

const caches = await mf.getCaches(); // Get global `CacheStorage` instance
const defaultCache = caches.default;
const namedCache = await caches.open("name");

// Get Durable Object namespace and storage for ID
const TEST_OBJECT = await mf.getDurableObjectNamespace("TEST_OBJECT");
const id = TEST_OBJECT.newUniqueId();
const storage = await mf.getDurableObjectStorage(id);

// Get Queue Producer
const producer = await mf.getQueueProducer("QUEUE_BINDING");

// Get D1 Database
const db = await mf.getD1Database("D1_BINDING")

await mf.dispose(); // Cleanup storage database connections and watcher
```

---

# Miniflare

URL: https://developers.cloudflare.com/workers/testing/miniflare/

import { DirectoryListing, LinkButton } from "~/components";

:::caution
This documentation describes the Miniflare API, which is only relevant for advanced use cases. Instead, most users should use [Wrangler](/workers/wrangler) to build, run & deploy their Workers locally
:::

**Miniflare** is a simulator for developing and testing
[**Cloudflare Workers**](https://workers.cloudflare.com/). It's written in
TypeScript, and runs your code in a sandbox implementing Workers' runtime APIs.

- 🎉 **Fun:** develop Workers easily with detailed logging, file watching and
  pretty error pages supporting source maps.
- 🔋 **Full-featured:** supports most Workers features, including KV, Durable
  Objects, WebSockets, modules and more.
- ⚡ **Fully-local:** test and develop Workers without an Internet connection.
  Reload code on change quickly.

<LinkButton href="/workers/testing/miniflare/get-started">
	Get Started
</LinkButton>
<LinkButton
	variant="secondary"
	href="https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare"
>
	GitHub
</LinkButton>
<LinkButton variant="secondary" href="https://npmjs.com/package/miniflare">
	NPM
</LinkButton>

---

These docs primarily cover Miniflare specific things. For more information on
runtime APIs, refer to the
[Cloudflare Workers docs](/workers).

If you find something that doesn't behave as it does in the production Workers
environment (and this difference isn't documented), or something's wrong in
these docs, please
[open a GitHub issue](https://github.com/cloudflare/workers-sdk/issues/new/choose).

<DirectoryListing descriptions />

---

# Writing tests

URL: https://developers.cloudflare.com/workers/testing/miniflare/writing-tests/

import { TabItem, Tabs, Details, PackageManagers } from "~/components";

import { FileTree } from "@astrojs/starlight/components";

:::note
For most users, Cloudflare recommends using the Workers Vitest integration. If you have been using test environments from Miniflare, refer to the [Migrate from Miniflare 2 guide](/workers/testing/vitest-integration/migration-guides/migrate-from-miniflare-2/).
:::

This guide will show you how to set up [Miniflare](/workers/testing/miniflare) to test your Workers. Miniflare is a low-level API that allows you to fully control how your Workers are run and tested.

To use Miniflare, make sure you've installed the latest version of Miniflare v3:

<PackageManagers pkg="miniflare@latest" dev />

The rest of this guide demonstrates concepts with the [`node:test`](https://nodejs.org/api/test.html) testing framework, but any testing framework can be used.

Miniflare is a low-level API that exposes a large variety of configuration options for running your Worker. In most cases, your tests will only need a subset of the available options, but you can refer to the [full API reference](/workers/testing/miniflare/get-started/#reference) to explore what is possible with Miniflare.

Before writing a test, you will need to create a Worker. Since Miniflare is a low-level API that emulates the Cloudflare platform primitives, your Worker will need to be written in JavaScript or you'll need to [integrate your own build pipeline](#custom-builds) into your testing setup. Here's an example JavaScript-only Worker:

```js title="src/index.js"
export default {
	async fetch(request) {
		return new Response(`Hello World`);
	},
};
```

Next, you will need to create an initial test file:

```js {12,13,14,15,16,17,18,19} title="src/index.test.js"
import assert from "node:assert";
import test, { after, before, describe } from "node:test";
import { Miniflare } from "miniflare";

describe("worker", () => {
	/**
	 * @type {Miniflare}
	 */
	let worker;

	before(async () => {
		worker = new Miniflare({
			modules: [
				{
					type: "ESModule",
					path: "src/index.js",
				},
			],
		});
		await worker.ready;
	});

	test("hello world", async () => {
		assert.strictEqual(
			await (await worker.dispatchFetch("http://example.com")).text(),
			"Hello World",
		);
	});

	after(async () => {
		await worker.dispose();
	});
});
```

You should be able to run the above test via `node --test`

The highlighted lines of the test file above demonstrate how to set up Miniflare to run a JavaScript Worker. Once Miniflare has been set up, your individual tests can send requests to the running Worker and assert against the responses. This is the main limitation of using Miniflare for testing your Worker as compared to the [Vitest integration](/workers/testing/vitest-integration/) — all access to your Worker must be through the `dispatchFetch()` Miniflare API, and you cannot unit test individual functions from your Worker.

<Details header="What runtime are tests running in?">
	When using the [Vitest integration](/workers/testing/vitest-integration/),
	your entire test suite runs in
	[`workerd`](https://github.com/cloudflare/workerd), which is why it is
	possible to unit test individual functions. By contrast, when using a
	different testing framework to run tests via Miniflare, only your Worker
	itself is running in [`workerd`](https://github.com/cloudflare/workerd) — your
	test files run in Node.js. This means that importing functions from your
	Worker into your test files might exhibit different behaviour than you'd see
	at runtime if the functions rely on `workerd`-specific behaviour.
</Details>

## Interacting with Bindings

:::caution

Miniflare does not read [Wrangler's config file](/workers/wrangler/configuration). All bindings that your Worker uses need to be specified in the Miniflare API options.

:::

The `dispatchFetch()` API from Miniflare allows you to send requests to your Worker and assert that the correct response is returned, but sometimes you need to interact directly with bindings in tests. For use cases like that, Miniflare provides the [`getBindings()`](/workers/testing/miniflare/get-started/#reference) API. For instance, to access an environment variable in your tests, adapt the test file `src/index.test.js` as follows:

```diff lang="js" title="src/index.test.js"
...
describe("worker", () => {
	...
	before(async () => {
		worker = new Miniflare({
			...
+			bindings: {
+				FOO: "Hello Bindings",
+			},
		});
		...
	});

	test("text binding", async () => {
		const bindings = await worker.getBindings();
		assert.strictEqual(bindings.FOO, "Hello Bindings");
	});
	...
});
```

You can also interact with local resources such as KV and R2 using the same API as you would from a Worker. For example, here's how you would interact with a KV namespace:

```diff lang="js" title="src/index.test.js"
...
describe("worker", () => {
	...
	before(async () => {
		worker = new Miniflare({
			...
+			kvNamespaces: ["KV"],
		});
		...
	});

	test("kv binding", async () => {
		const bindings = await worker.getBindings();
		await bindings.KV.put("key", "value");
		assert.strictEqual(await bindings.KV.get("key"), "value");
	});
	...
});
```

## More complex Workers

The example given above shows how to test a simple Worker consisting of a single JavaScript file. However, most real-world Workers are more complex than that. Miniflare supports providing all constituent files of your Worker directly using the API:

```js
new Miniflare({
	modules: [
		{
			type: "ESModule",
			path: "src/index.js",
		},
		{
			type: "ESModule",
			path: "src/imported.js",
		},
	],
});
```

This can be a bit cumbersome as your Worker grows. To help with this, Miniflare can also crawl your module graph to automatically figure out which modules to include:

```js
new Miniflare({
	scriptPath: "src/index-with-imports.js",
	modules: true,
	modulesRules: [{ type: "ESModule", include: ["**/*.js"] }],
});
```

## Custom builds

In many real-world cases, Workers are not written in plain JavaScript but instead consist of multiple TypeScript files that import from npm packages and other dependencies, which are then bundled by a build tool. When testing your Worker via Miniflare directly you need to run this build tool before your tests. Exactly how this build is run will depend on the specific test framework you use, but for `node:test` it would likely be in a `setup()` hook. For example, if you use [Wrangler](/workers/wrangler/) to build and deploy your Worker, you could spawn a `wrangler build` command like this:

```js
before(() => {
	spawnSync("npx wrangler build -c wrangler-build.json", {
		shell: true,
		stdio: "pipe",
	});
});
```

---

# Configuration

URL: https://developers.cloudflare.com/workers/testing/vitest-integration/configuration/

import { Details } from "~/components";

The Workers Vitest integration provides additional configuration on top of Vitest's usual options using the [`defineWorkersConfig()`](/workers/testing/vitest-integration/configuration/#defineworkersconfigoptions) API.

An example configuration would be:

```ts
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
	test: {
		poolOptions: {
			workers: {
				wrangler: {
					configPath: "./wrangler.toml",
				},
			},
		},
	},
});
```

:::caution

Custom Vitest `environment`s or `runner`s are not supported when using the Workers Vitest integration.

:::

## APIs

The following APIs are exported from the `@cloudflare/vitest-pool-workers/config` module.

### `defineWorkersConfig(options)`

Ensures Vitest is configured to use the Workers integration with the correct module resolution settings, and provides type checking for [WorkersPoolOptions](#workerspooloptions). This should be used in place of the [`defineConfig()`](https://vitest.dev/config/file.html) function from Vitest.

It also accepts a `Promise` of `options`, or an optionally-`async` function returning `options`.

```ts
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
	test: {
		poolOptions: {
			workers: {
				// Refer to type of WorkersPoolOptions...
			},
		},
	},
});
```

### `defineWorkersProject(options)`

Use [`defineWorkersProject`](#defineworkersprojectoptions) with [Vitest Workspaces](https://vitest.dev/guide/workspace) to specify a different configuration for certain tests. It should be used in place of the [`defineProject()`](https://vitest.dev/guide/workspace) function from Vitest.

Similar to [`defineWorkersConfig()`](#defineworkersconfigoptions), this ensures Vitest is configured to use the Workers integration with the correct module resolution settings, and provides type checking for [WorkersPoolOptions](#workerspooloptions).

It also accepts a `Promise` of `options`, or an optionally-`async` function returning `options`.

```ts
import { defineWorkspace, defineProject } from "vitest/config";
import { defineWorkersProject } from "@cloudflare/vitest-pool-workers/config";

const workspace = defineWorkspace([
	defineWorkersProject({
		test: {
			name: "Workers",
			include: ["**/*.worker.test.ts"],
			poolOptions: {
				workers: {
					// Refer to type of WorkersPoolOptions...
				},
			},
		},
	}),

	// ...
]);

export default workspace;
```

### `buildPagesASSETSBinding(assetsPath)`

Creates a Pages ASSETS binding that serves files insides the `assetsPath`. This is required if you uses `createPagesEventContext()` or `SELF` to test your **Pages Functions**. Refer to the [Pages recipe](/workers/testing/vitest-integration/recipes) for a full example.

```ts
import path from "node:path";
import {
	buildPagesASSETSBinding,
	defineWorkersProject,
} from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersProject(async () => {
	const assetsPath = path.join(__dirname, "public");

	return {
		test: {
			poolOptions: {
				workers: {
					miniflare: {
						serviceBindings: {
							ASSETS: await buildPagesASSETSBinding(assetsPath),
						},
					},
				},
			},
		},
	};
});
```

### `readD1Migrations(migrationsPath)`

Reads all [D1 migrations](/d1/reference/migrations/) stored at `migrationsPath` and returns them ordered by migration number. Each migration will have its contents split into an array of individual SQL queries. Call the [`applyD1Migrations()`](/workers/testing/vitest-integration/test-apis/#d1) function inside a test or [setup file](https://vitest.dev/config/#setupfiles) to apply migrations. Refer to the [D1 recipe](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/d1) for an example project using migrations.

```ts
import path from "node:path";
import {
	defineWorkersProject,
	readD1Migrations,
} from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersProject(async () => {
	// Read all migrations in the `migrations` directory
	const migrationsPath = path.join(__dirname, "migrations");
	const migrations = await readD1Migrations(migrationsPath);

	return {
		test: {
			setupFiles: ["./test/apply-migrations.ts"],
			poolOptions: {
				workers: {
					miniflare: {
						// Add a test-only binding for migrations, so we can apply them in a setup file
						bindings: { TEST_MIGRATIONS: migrations },
					},
				},
			},
		},
	};
});
```

## `WorkersPoolOptions`

- `main`: string optional

  - Entry point to Worker run in the same isolate/context as tests. This option is required to use `import { SELF } from "cloudflare:test"` for integration tests, or Durable Objects without an explicit `scriptName` if classes are defined in the same Worker. This file goes through Vite transforms and can be TypeScript. Note that `import module from "<path-to-main>"` inside tests gives exactly the same `module` instance as is used internally for the `SELF` and Durable Object bindings. If `wrangler.configPath` is defined and this option is not, it will be read from the `main` field in that configuration file.

- `isolatedStorage`: boolean optional

  - Enables per-test isolated storage. If enabled, any writes to storage performed in a test will be undone at the end of the test. The test's storage environment is copied from the containing suite, meaning `beforeAll()` hooks can be used to seed data. If this option is disabled, all tests will share the same storage. `.concurrent` tests are not supported when isolated storage is enabled. Refer to [Isolation and concurrency](/workers/testing/vitest-integration/isolation-and-concurrency/) for more information on the isolation model.

  - Defaults to `true`.

    <Details header="Illustrative example">

    ```ts
    import { env } from "cloudflare:test";
    import { beforeAll, beforeEach, describe, test, expect } from "vitest";

    // Get the current list stored in a KV namespace
    async function get(): Promise<string[]> {
    	return (await env.NAMESPACE.get("list", "json")) ?? [];
    }
    // Add an item to the end of the list
    async function append(item: string) {
    	const value = await get();
    	value.push(item);
    	await env.NAMESPACE.put("list", JSON.stringify(value));
    }

    beforeAll(() => append("all"));
    beforeEach(() => append("each"));

    test("one", async () => {
    	// Each test gets its own storage environment copied from the parent
    	await append("one");
    	expect(await get()).toStrictEqual(["all", "each", "one"]);
    });
    // `append("each")` and `append("one")` undone
    test("two", async () => {
    	await append("two");
    	expect(await get()).toStrictEqual(["all", "each", "two"]);
    });
    // `append("each")` and `append("two")` undone

    describe("describe", async () => {
    	beforeAll(() => append("describe all"));
    	beforeEach(() => append("describe each"));

    	test("three", async () => {
    		await append("three");
    		expect(await get()).toStrictEqual([
    			// All `beforeAll()`s run before `beforeEach()`s
    			"all",
    			"describe all",
    			"each",
    			"describe each",
    			"three",
    		]);
    	});
    	// `append("each")`, `append("describe each")` and `append("three")` undone
    	test("four", async () => {
    		await append("four");
    		expect(await get()).toStrictEqual([
    			"all",
    			"describe all",
    			"each",
    			"describe each",
    			"four",
    		]);
    	});
    	// `append("each")`, `append("describe each")` and `append("four")` undone
    });
    ```

    </Details>

- `singleWorker`: boolean optional

  - Runs all tests in this project serially in the same Worker, using the same module cache. This can significantly speed up execution if you have lots of small test files. Refer to the [Isolation and concurrency](/workers/testing/vitest-integration/isolation-and-concurrency/) page for more information on the isolation model.

  - Defaults to `false`.

- `miniflare`: `SourcelessWorkerOptions & { workers?: WorkerOptions\[]; }` optional

  - Use this to provide configuration information that is typically stored within the [Wrangler configuration file](/workers/wrangler/configuration/), such as [bindings](/workers/runtime-apis/bindings/), [compatibility dates](/workers/configuration/compatibility-dates/), and [compatibility flags](/workers/configuration/compatibility-flags/). The `WorkerOptions` interface is defined [here](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare#interface-workeroptions). Use the `main` option above to configure the entry point, instead of the Miniflare `script`, `scriptPath`, or `modules` options.

  - If your project makes use of multiple Workers, you can configure auxiliary Workers that run in the same `workerd` process as your tests and can be bound to. Auxiliary Workers are configured using the `workers` array, containing regular Miniflare [`WorkerOptions`](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare#interface-workeroptions) objects. Note that unlike the `main` Worker, auxiliary Workers:
    - Cannot have TypeScript entrypoints. You must compile auxiliary Workers to JavaScript first. You can use the [`wrangler deploy --dry-run --outdir dist`](/workers/wrangler/commands/#deploy) command for this.
    - Use regular Workers module resolution semantics. Refer to the [Isolation and concurrency](/workers/testing/vitest-integration/isolation-and-concurrency/#modules) page for more information.
    - Cannot access the [`cloudflare:test`](/workers/testing/vitest-integration/test-apis/) module.
    - Do not require specific compatibility dates or flags.
    - Can be written with the [Service Worker syntax](/workers/reference/migrate-to-module-workers/#service-worker-syntax).
    - Are not affected by global mocks defined in your tests.

- `wrangler`: `{ configPath?: string; environment?: string; }` optional

  - Path to [Wrangler configuration file](/workers/wrangler/configuration/) to load `main`, [compatibility settings](/workers/configuration/compatibility-dates/) and [bindings](/workers/runtime-apis/bindings/) from. These options will be merged with the `miniflare` option above, with `miniflare` values taking precedence. For example, if your Wrangler configuration defined a [service binding](/workers/runtime-apis/bindings/service-bindings/) named `SERVICE` to a Worker named `service`, but you included `serviceBindings: { SERVICE(request) { return new Response("body"); } }` in the `miniflare` option, all requests to `SERVICE` in tests would return `body`. Note `configPath` accepts both `.toml` and `.json` files.

  - The environment option can be used to specify the [Wrangler environment](/workers/wrangler/environments/) to pick up bindings and variables from.

## `WorkersPoolOptionsContext`

- `inject`: typeof import("vitest").inject

  - The same `inject()` function usually imported from the `vitest` module inside tests. This allows you to define `miniflare` configuration based on injected values from [`globalSetup`](https://vitest.dev/config/#globalsetup) scripts. Use this if you have a value in your configuration that is dynamically generated and only known at runtime of your tests. For example, a global setup script might start an upstream server on a random port. This port could be `provide()`d and then `inject()`ed in the configuration for an external service binding or [Hyperdrive](/hyperdrive/). Refer to the [Hyperdrive recipe](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/hyperdrive) for an example project using this provide/inject approach.

    <Details header="Illustrative example">

    ```ts
    // env.d.ts
    declare module "vitest" {
    	interface ProvidedContext {
    		port: number;
    	}
    }

    // global-setup.ts
    import type { GlobalSetupContext } from "vitest/node";
    export default function ({ provide }: GlobalSetupContext) {
    	// Runs inside Node.js, could start server here...
    	provide("port", 1337);
    	return () => {
    		/* ...then teardown here */
    	};
    }

    // vitest.config.ts
    import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
    export default defineWorkersConfig({
    	test: {
    		globalSetup: ["./global-setup.ts"],
    		pool: "@cloudflare/vitest-pool-workers",
    		poolOptions: {
    			workers: ({ inject }) => ({
    				miniflare: {
    					hyperdrives: {
    						DATABASE: `postgres://user:pass@example.com:${inject("port")}/db`,
    					},
    				},
    			}),
    		},
    	},
    });
    ```

    </Details>

## `SourcelessWorkerOptions`

Sourceless `WorkerOptions` type without `script`, `scriptPath`, or `modules` properties. Refer to the Miniflare [`WorkerOptions`](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare#interface-workeroptions) type for more details.

```ts
type SourcelessWorkerOptions = Omit<
	WorkerOptions,
	"script" | "scriptPath" | "modules" | "modulesRoot"
>;
```

---

# Debugging

URL: https://developers.cloudflare.com/workers/testing/vitest-integration/debugging/

This guide shows you how to debug your Workers tests with Vitest. This is available with `@cloudflare/vitest-pool-workers` v0.7.5 or later.

## Open inspector with Vitest

To start debugging, run Vitest with the following command and attach a debugger to port `9229`:

```sh
vitest --inspect --no-file-parallelism
```

## Customize the inspector port

By default, the inspector will be opened on port `9229`. If you need to use a different port (for example, `3456`), you can run the following command:

```sh
vitest --inspect=3456 --no-file-parallelism
```

Alternatively, you can define it in your Vitest configuration file:

```ts
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
  test: {
    inspector: {
        port: 3456,
    },
    poolOptions: {
      workers: {
        // ...
      },
    },
  },
});
```

## Setup VS Code to use breakpoints

To setup VS Code for breakpoint debugging in your Worker tests, create a `.vscode/launch.json` file that contains the following configuration:

```json
{
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Open inspector with Vitest",
            "program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
            "console": "integratedTerminal",
            "args": ["--inspect=9229", "--no-file-parallelism"]
        },
        {
            "name": "Attach to Workers Runtime",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "cwd": "/",
            "resolveSourceMapLocations": null,
            "attachExistingChildren": false,
            "autoAttachChildProcesses": false,
        }
    ],
    "compounds": [
        {
            "name": "Debug Workers tests",
            "configurations": ["Open inspector with Vitest", "Attach to Workers Runtime"],
            "stopAll": true
        }
    ]
}
```

Select **Debug Workers tests** at the top of the **Run & Debug** panel to open an inspector with Vitest and attach a debugger to the Workers runtime. Then you can add breakpoints to your test files and start debugging.

---

# Vitest integration

URL: https://developers.cloudflare.com/workers/testing/vitest-integration/

import { DirectoryListing, Render, LinkButton } from "~/components";

For most users, Cloudflare recommends using the Workers Vitest integration for testing Workers and [Pages Functions](/pages/functions/) projects. [Vitest](https://vitest.dev/) is a popular JavaScript testing framework featuring a very fast watch mode, Jest compatibility, and out-of-the-box support for TypeScript. In this integration, Cloudflare provides a custom pool that allows your Vitest tests to run _inside_ the Workers runtime.

The Workers Vitest integration:

- Supports both **unit tests** and **integration tests**.
- Provides direct access to Workers runtime APIs and bindings.
- Implements isolated per-test storage.
- Runs tests fully-locally using [Miniflare](https://miniflare.dev/).
- Leverages Vitest's hot-module reloading for near instant reruns.
- Provides a declarative interface for mocking outbound requests.
- Supports projects with multiple Workers.

<LinkButton href="/workers/testing/vitest-integration/write-your-first-test/">
	Write your first test
</LinkButton>

---

# Isolation and concurrency

URL: https://developers.cloudflare.com/workers/testing/vitest-integration/isolation-and-concurrency/

Review how the Workers Vitest integration runs your tests, how it isolates tests from each other, and how it imports modules.

## Run tests

When you run your tests with the Workers Vitest integration, Vitest will:

1. Read and evaluate your configuration file using Node.js.
2. Run any [`globalSetup`](https://vitest.dev/config/#globalsetup) files using Node.js.
3. Collect and sequence test files.
4. For each Vitest project, depending on its configured isolation and concurrency, start one or more [`workerd`](https://github.com/cloudflare/workerd) processes, each running one or more Workers.
5. Run [`setupFiles`](https://vitest.dev/config/#setupfiles) and test files in `workerd` using the appropriate Workers.
6. Watch for changes and re-run test files using the same Workers if the configuration has not changed.

## Isolation and concurrency models

The [`isolatedStorage` and `singleWorker`](/workers/testing/vitest-integration/configuration/#workerspooloptions) configuration options both control isolation and concurrency. The Workers Vitest integration tries to minimise the number of `workerd` processes it starts, reusing Workers and their module caches between test runs where possible. The current implementation of isolated storage requires each `workerd` process to run one test file at a time, and does not support `.concurrent` tests. A copy of all auxiliary `workers` exists in each `workerd` process.

By default, the `isolatedStorage` option is enabled. We recommend you enable the `singleWorker: true` option if you have lots of small test files.

### `isolatedStorage: true, singleWorker: false` (Default)

In this model, a `workerd` process is started for each test file. Test files are executed concurrently but `.concurrent` tests are not supported. Each test will read/write from an isolated storage environment, and bind to its own set of auxiliary `workers`.

![Isolation Model: Isolated Storage & No Single Worker](~/assets/images/workers/testing/vitest/isolation-model-3-isolated-storage-no-single-worker.svg)

### `isolatedStorage: true, singleWorker: true`

In this model, a single `workerd` process is started with a single Worker for all test files. Test files are executed in serial and `.concurrent` tests are not supported. Each test will read/write from an isolated storage environment, and bind to the same auxiliary `workers`.

![Isolation Model: Isolated Storage & Single Worker](~/assets/images/workers/testing/vitest/isolation-model-4-isolated-storage-single-worker.svg)

### `isolatedStorage: false, singleWorker: false`

In this model, a single `workerd` process is started with a Worker for each test file. Tests files are executed concurrently and `.concurrent` tests are supported. Every test will read/write from the same shared storage, and bind to the same auxiliary `workers`.

![Isolation Model: No Isolated Storage & No Single Worker](~/assets/images/workers/testing/vitest/isolation-model-1-no-isolated-storage-no-single-worker.svg)

### `isolatedStorage: false, singleWorker: true`

In this model, a single `workerd` process is started with a single Worker for all test files. Test files are executed in serial but `.concurrent` tests are supported. Every test will read/write from the same shared storage, and bind to the same auxiliary `workers`.

![Isolation Model: No Isolated Storage & Single Worker](~/assets/images/workers/testing/vitest/isolation-model-2-no-isolated-storage-single-worker.svg)

## Modules

Each Worker has its own module cache. As Workers are reused between test runs, their module caches are also reused. Vitest invalidates parts of the module cache at the start of each test run based on changed files.

The Workers Vitest pool works by running code inside a Cloudflare Worker that Vitest would usually run inside a [Node.js Worker thread](https://nodejs.org/api/worker_threads.html). To make this possible, the pool **automatically injects** the [`nodejs_compat`](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag), [`no_nodejs_compat_v2`] and [`export_commonjs_default`](/workers/configuration/compatibility-flags/#commonjs-modules-do-not-export-a-module-namespace) compatibility flags. This is the minimal compatibility setup that still allows Vitest to run correctly, but without pulling in polyfills and globals that aren't required. If you already have a Node.js compatibility flag defined in your configuration, Vitest Pool Workers will not try to add those flags.

:::caution


Using Vitest Pool Workers may cause your Worker to behave differently when deployed than during testing as the `nodejs_compat` flag is enabled by default. This means that Node.js-specific APIs and modules are available when running your tests. However, Cloudflare Workers do not support these Node.js APIs in the production environment unless you specify this flag in your Worker configuration.

If you do not have a `nodejs_compat` or `nodejs_compat_v2` flag in your configuration and you import a Node.js module in your Worker code, your tests may pass, but you will find that you will not be able to deploy this Worker, as the upload call (either via the REST API or via Wrangler) will throw an error.

However, if you use Node.js globals that are not supported by the runtime, your Worker upload will be successful, but you may see errors in production code. Let's create a contrived example to illustrate the issue.

The `wrangler.toml` does not specify either `nodejs_compat` or `nodejs_compat_v2`:

```toml
name = "test"
main = "src/index.ts"
compatibility_date = "2024-12-16"
# no nodejs_compat flags here
```

In our `src/index.ts` file, we use the `process` object, which is a Node.js global, unavailable in the Workerd runtime:

```typescript
export default {
	async fetch(request, env, ctx): Promise<Response> {
		process.env.TEST = 'test';
		return new Response(process.env.TEST);
	},
} satisfies ExportedHandler<Env>;
```

The test is a simple assertion that the Worker managed to use `process`.

```typescript
it('responds with "test"', async () => {
	const response = await SELF.fetch('https://example.com/');
	expect(await response.text()).toMatchInlineSnapshot(`"test"`);
});
```

Now, if we run `npm run test`, we see that the tests will _pass_:

```
 ✓ test/index.spec.ts (1)
   ✓ responds with "test"

 Test Files  1 passed (1)
      Tests  1 passed (1)
```

And we can run `wrangler dev` and `wrangler deploy` without issues. It _looks like_ our code is fine. However, this code will fail in production as `process` is not available in the Workerd runtime.

To fix the issue, we either need to avoid using Node.js APIs, or add the `nodejs_compat` flag to our Wrangler configuration.

:::

---

# Known issues

URL: https://developers.cloudflare.com/workers/testing/vitest-integration/known-issues/

The Workers Vitest pool is currently in open beta. The following are issues Cloudflare is aware of and fixing:

### Coverage

Native code coverage via [V8](https://v8.dev/blog/javascript-code-coverage) is not supported. You must use instrumented code coverage via [Istanbul](https://istanbul.js.org/) instead. Refer to the [Vitest Coverage documentation](https://vitest.dev/guide/coverage) for setup instructions.

### Fake timers

Vitest's [fake timers](https://vitest.dev/guide/mocking.html#timers) do not apply to KV, R2 and cache simulators. For example, you cannot expire a KV key by advancing fake time.

### Dynamic `import()` statements with `SELF` and Durable Objects

Dynamic `import()` statements do not work inside `export default { ... }` handlers when writing integration tests with `SELF`, or inside Durable Object event handlers. You must import and call your handlers directly, or use static `import` statements in the global scope.

### Durable Object alarms

Durable Object alarms are not reset between test runs and do not respect isolated storage. Ensure you delete or run all alarms with [`runDurableObjectAlarm()`](/workers/testing/vitest-integration/test-apis/#durable-objects) scheduled in each test before finishing the test.

### WebSockets

Using WebSockets with Durable Objects with the [`isolatedStorage`](/workers/testing/vitest-integration/isolation-and-concurrency) flag turned on is not supported. You must set `isolatedStorage: false` in your `vitest.config.ts` file.

### Isolated storage

When the `isolatedStorage` flag is enabled (the default), the test runner will undo any writes to the storage at the end of the test as detailed in the [isolation and concurrency documentation](/workers/testing/vitest-integration/isolation-and-concurrency/). However, Cloudflare recommends that you consider the following actions to avoid any common issues:

#### Await all storage operations

Always `await` all `Promise`s that read or write to storage services.

```ts
// Example: Seed data
beforeAll(async () => {
	await env.KV.put('message', 'test message');
	await env.R2.put('file', 'hello-world');
});
```

#### Explicitly signal resource disposal

When calling RPC methods of a Service Worker or Durable Object that return non-primitive values (such as objects or classes extending `RpcTarget`), use the `using` keyword to explicitly signal when resources can be disposed of. See [this example test](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/rpc/test/unit.test.ts#L155) and refer to [explicit-resource-management](/workers/runtime-apis/rpc/lifecycle#explicit-resource-management) for more details.

```ts
using result = await stub.getCounter();
```

#### Consume response bodies

When making requests via `fetch` or `R2.get()`, consume the entire response body, even if you are not asserting its content. For example:

```ts
test('check if file exists', async () => {
	await env.R2.put('file', 'hello-world');
	const response = await env.R2.get('file');

	expect(response).not.toBe(null);
	// Consume the response body even if you are not asserting it
	await response.text()
});
```

### Module resolution

If you encounter module resolution issues such as: `Error: Cannot use require() to import an ES Module` or `Error: No such module`, you can bundle these dependencies using the [deps.optimizer](https://vitest.dev/config/#deps-optimizer) option:

```tsx
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
	test: {
		deps: {
			optimizer: {
				ssr: {
					enabled: true,
					include: ["your-package-name"],
				},
			},
		},
		poolOptions: {
			workers: {
				// ...
			},
		},
	},
});
```

You can find an example in the [Recipes](/workers/testing/vitest-integration/recipes) page.

### Importing modules from global setup file

Although Vitest is set up to resolve packages for the `workerd` runtime, it runs your global setup file in the Node.js environment. This can cause issues when importing packages like [Postgres.js](https://github.com/cloudflare/workers-sdk/issues/6465), which exports a non-Node version for `workerd`.
To work around this, you can create a wrapper that uses Vite's SSR module loader to import the global setup file under the correct conditions. Then, adjust your Vitest configuration to point to this wrapper. For example:

```ts
// File: global-setup-wrapper.ts
import { createServer } from "vite"

// Import the actual global setup file with the correct setup
const mod = await viteImport("./global-setup.ts")

export default mod.default;

// Helper to import the file with default node setup
async function viteImport(file: string) {
  const server = await createServer({
    root: import.meta.dirname,
    configFile: false,
    server: { middlewareMode: true, hmr: false, watch: null, ws: false },
    optimizeDeps: { noDiscovery: true },
    clearScreen: false,
  });
  const mod = await server.ssrLoadModule(file);
  await server.close();
  return mod;
}
```

```ts
// File: vitest.config.ts
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
	test: {
		// Replace the globalSetup with the wrapper file
		globalSetup: ["./global-setup-wrapper.ts"],
		poolOptions: {
			workers: {
				// ...
			},
		},
	},
});
```

---

# Recipes and examples

URL: https://developers.cloudflare.com/workers/testing/vitest-integration/recipes/

Recipes are examples that help demonstrate how to write unit tests and integration tests for Workers projects using the [`@cloudflare/vitest-pool-workers`](https://www.npmjs.com/package/@cloudflare/vitest-pool-workers) package.

- [Basic unit and integration tests for Workers using `SELF`](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/basics-unit-integration-self)
- [Basic unit and integration tests for Pages Functions using `SELF`](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/pages-functions-unit-integration-self)
- [Basic integration tests using an auxiliary Worker](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/basics-integration-auxiliary)
- [Basic integration test for Workers with static assets](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/workers-assets)
- [Isolated tests using KV, R2 and the Cache API](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/kv-r2-caches)
- [Isolated tests using D1 with migrations](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/d1)
- [Isolated tests using Durable Objects with direct access](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/durable-objects)
- [Tests using Queue producers and consumers](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/queues)
- [Tests using Hyperdrive with a Vitest managed TCP server](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/hyperdrive)
- [Tests using declarative/imperative outbound request mocks](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/request-mocking)
- [Tests using multiple auxiliary Workers and request mocks](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/multiple-workers)
- [Tests importing WebAssembly modules](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/web-assembly)
- [Tests using JSRPC with entrypoints and Durable Objects](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/rpc)
- [Integration test with static assets and Puppeteer](https://github.com/GregBrimble/puppeteer-vitest-workers-assets)
- [Resolving modules with Vite Dependency Pre-Bundling](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/module-resolution)
- [Mocking Workers AI and Vectorize bindings in unit tests](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/ai-vectorize)

---

# Test APIs

URL: https://developers.cloudflare.com/workers/testing/vitest-integration/test-apis/

The Workers Vitest integration provides runtime helpers for writing tests in the `cloudflare:test` module. The `cloudflare:test` module is provided by the `@cloudflare/vitest-pool-workers` package, but can only be imported from test files that execute in the Workers runtime.

## `cloudflare:test` module definition



* <code>env</code>: import("cloudflare:test").ProvidedEnv

  * Exposes the [`env` object](/workers/runtime-apis/handlers/fetch/#parameters) for use as the second argument passed to ES modules format exported handlers. This provides access to [bindings](/workers/runtime-apis/bindings/) that you have defined in your [Vitest configuration file](/workers/testing/vitest-integration/configuration/).

    <br/>

    ```js
    import { env } from "cloudflare:test";

    it("uses binding", async () => {
      await env.KV_NAMESPACE.put("key", "value");
      expect(await env.KV_NAMESPACE.get("key")).toBe("value");
    });
    ```

    To configure the type of this value, use an ambient module type:

    ```ts
    declare module "cloudflare:test" {
      interface ProvidedEnv {
        KV_NAMESPACE: KVNamespace;
      }
      // ...or if you have an existing `Env` type...
      interface ProvidedEnv extends Env {}
    }
    ```

* <code>SELF</code>: Fetcher

  * [Service binding](/workers/runtime-apis/bindings/service-bindings/) to the default export defined in the `main` Worker. Use this to write integration tests against your Worker. The `main` Worker runs in the same isolate/context as tests so any global mocks will apply to it too.

    <br/>

    ```js
    import { SELF } from "cloudflare:test";

    it("dispatches fetch event", async () => {
      const response = await SELF.fetch("https://example.com");
      expect(await response.text()).toMatchInlineSnapshot(...);
    });
    ```

* <code>fetchMock</code>: import("undici").MockAgent

  * Declarative interface for mocking outbound `fetch()` requests. Deactivated by default and reset before running each test file. Refer to [`undici`'s `MockAgent` documentation](https://undici.nodejs.org/#/docs/api/MockAgent) for more information. Note this only mocks `fetch()` requests for the current test runner Worker. Auxiliary Workers should mock `fetch()`es using the Miniflare `fetchMock`/`outboundService` options. Refer to [Configuration](/workers/testing/vitest-integration/configuration/#workerspooloptions) for more information.

    <br/>

    ```js
    import { fetchMock } from "cloudflare:test";
    import { beforeAll, afterEach, it, expect } from "vitest";

    beforeAll(() => {
      // Enable outbound request mocking...
      fetchMock.activate();
      // ...and throw errors if an outbound request isn't mocked
      fetchMock.disableNetConnect();
    });
    // Ensure we matched every mock we defined
    afterEach(() => fetchMock.assertNoPendingInterceptors());

    it("mocks requests", async () => {
      // Mock the first request to `https://example.com`
      fetchMock
        .get("https://example.com")
        .intercept({ path: "/" })
        .reply(200, "body");

      const response = await fetch("https://example.com/");
      expect(await response.text()).toBe("body");
    });
    ```



### Events



* <code>createExecutionContext()</code>: ExecutionContext

  * Creates an instance of the [`context` object](/workers/runtime-apis/handlers/fetch/#parameters) for use as the third argument to ES modules format exported handlers.

* <code>waitOnExecutionContext(ctx:ExecutionContext)</code>: Promise\<void>

  * Use this to wait for all Promises passed to `ctx.waitUntil()` to settle, before running test assertions on any side effects. Only accepts instances of `ExecutionContext` returned by `createExecutionContext()`.

    <br/>

    ```ts
    import { env, createExecutionContext, waitOnExecutionContext } from "cloudflare:test";
    import { it, expect } from "vitest";
    import worker from "./index.mjs";

    it("calls fetch handler", async () => {
      const request = new Request("https://example.com");
      const ctx = createExecutionContext();
      const response = await worker.fetch(request, env, ctx);
      await waitOnExecutionContext(ctx);
      expect(await response.text()).toMatchInlineSnapshot(...);
    });
    ```

* <code>createScheduledController(options?:FetcherScheduledOptions)</code>: ScheduledController

  * Creates an instance of `ScheduledController` for use as the first argument to modules-format [`scheduled()`](/workers/runtime-apis/handlers/scheduled/) exported handlers.

    <br/>

    ```ts
    import { env, createScheduledController, createExecutionContext, waitOnExecutionContext } from "cloudflare:test";
    import { it, expect } from "vitest";
    import worker from "./index.mjs";

    it("calls scheduled handler", async () => {
      const ctrl = createScheduledController({
        scheduledTime: new Date(1000),
        cron: "30 * * * *"
      });
      const ctx = createExecutionContext();
      await worker.scheduled(ctrl, env, ctx);
      await waitOnExecutionContext(ctx);
    });
    ```

* <code>createMessageBatch(queueName:string, messages:ServiceBindingQueueMessage\[])</code>: MessageBatch

  * Creates an instance of `MessageBatch` for use as the first argument to modules-format [`queue()`](/queues/configuration/javascript-apis/#consumer) exported handlers.

* <code>getQueueResult(batch:MessageBatch, ctx:ExecutionContext)</code>: Promise\<FetcherQueueResult>

  * Gets the acknowledged/retry state of messages in the `MessageBatch`, and waits for all `ExecutionContext#waitUntil()`ed `Promise`s to settle. Only accepts instances of `MessageBatch` returned by `createMessageBatch()`, and instances of `ExecutionContext` returned by `createExecutionContext()`.

    <br/>

    ```ts
    import { env, createMessageBatch, createExecutionContext, getQueueResult } from "cloudflare:test";
    import { it, expect } from "vitest";
    import worker from "./index.mjs";

    it("calls queue handler", async () => {
      const batch = createMessageBatch("my-queue", [
        {
          id: "message-1",
          timestamp: new Date(1000),
          body: "body-1"
        }
      ]);
      const ctx = createExecutionContext();
      await worker.queue(batch, env, ctx);
      const result = await getQueueResult(batch, ctx);
      expect(result.ackAll).toBe(false);
      expect(result.retryBatch).toMatchObject({ retry: false });
      expect(result.explicitAcks).toStrictEqual(["message-1"]);
      expect(result.retryMessages).toStrictEqual([]);
    });
    ```



### Durable Objects



* <code>runInDurableObject\<O extends DurableObject, R>(stub:DurableObjectStub, callback:(instance: O, state: DurableObjectState) => R | Promise\<R>)</code>: Promise\<R>

  * Runs the provided `callback` inside the Durable Object that corresponds to the provided `stub`.

    <br/>

    This temporarily replaces your Durable Object's `fetch()` handler with `callback`, then sends a request to it, returning the result. This can be used to call/spy-on Durable Object methods or seed/get persisted data. Note this can only be used with `stub`s pointing to Durable Objects defined in the `main` Worker.

    <br/>

    ```ts
    export class Counter {
      constructor(readonly state: DurableObjectState) {}

      async fetch(request: Request): Promise<Response> {
        let count = (await this.state.storage.get<number>("count")) ?? 0;
        void this.state.storage.put("count", ++count);
        return new Response(count.toString());
    	}
    }
    ```

    ```ts
    import { env, runInDurableObject } from "cloudflare:test";
    import { it, expect } from "vitest";
    import { Counter } from "./index.ts";

    it("increments count", async () => {
      const id = env.COUNTER.newUniqueId();
      const stub = env.COUNTER.get(id);
      let response = await stub.fetch("https://example.com");
      expect(await response.text()).toBe("1");

      response = await runInDurableObject(stub, async (instance: Counter, state) => {
        expect(instance).toBeInstanceOf(Counter);
        expect(await state.storage.get<number>("count")).toBe(1);

        const request = new Request("https://example.com");
        return instance.fetch(request);
      });
      expect(await response.text()).toBe("2");
    });
    ```

* <code>runDurableObjectAlarm(stub:DurableObjectStub)</code>: Promise\<boolean>

  * Immediately runs and removes the Durable Object pointed to by `stub`'s alarm if one is scheduled. Returns `true` if an alarm ran, and `false` otherwise. Note this can only be used with `stub`s pointing to Durable Objects defined in the `main` Worker.

* <code>listDurableObjectIds(namespace:DurableObjectNamespace)</code>: Promise\<DurableObjectId\[]>

  * Gets the IDs of all objects that have been created in the `namespace`. Respects `isolatedStorage` if enabled, meaning objects created in a different test will not be returned.

    <br/>

    ```ts
    import { env, listDurableObjectIds } from "cloudflare:test";
    import { it, expect } from "vitest";

    it("increments count", async () => {
      const id = env.COUNTER.newUniqueId();
      const stub = env.COUNTER.get(id);
      const response = await stub.fetch("https://example.com");
      expect(await response.text()).toBe("1");

      const ids = await listDurableObjectIds(env.COUNTER);
      expect(ids.length).toBe(1);
      expect(ids[0].equals(id)).toBe(true);
    });
    ```



### D1



* <code>applyD1Migrations(db:D1Database, migrations:D1Migration\[], migrationTableName?:string)</code>: Promise\<void>

  * Applies all un-applied [D1 migrations](/d1/reference/migrations/) stored in the `migrations` array to database `db`, recording migrations state in the `migrationsTableName` table. `migrationsTableName` defaults to `d1_migrations`. Call the [`readD1Migrations()`](/workers/testing/vitest-integration/configuration/#readd1migrationsmigrationspath) function from the `@cloudflare/vitest-pool-workers/config` package inside Node.js to get the `migrations` array. Refer to the [D1 recipe](https://github.com/cloudflare/workers-sdk/tree/main/fixtures/vitest-pool-workers-examples/d1) for an example project using migrations.

---

# Migration Guides

URL: https://developers.cloudflare.com/workers/static-assets/migration-guides/

import { Description, DirectoryListing } from "~/components";

<Description>
	Migrate your existing applications to Cloudflare Workers.
</Description>

Take advantage of Cloudflare's global network and migrate your existing applications to Workers.

<DirectoryListing />

---

# Write your first test

URL: https://developers.cloudflare.com/workers/testing/vitest-integration/write-your-first-test/

import {
	TabItem,
	Tabs,
	TypeScriptExample,
	PackageManagers,
	Details,
} from "~/components";

This guide will instruct you through getting started with the `@cloudflare/vitest-pool-workers` package. For more complex examples of testing using `@cloudflare/vitest-pool-workers`, refer to [Recipes](/workers/testing/vitest-integration/recipes/).

## Prerequisites

First, make sure that:

- Your [compatibility date](/workers/configuration/compatibility-dates/) is set to `2022-10-31` or later.
- Your Worker using the ES modules format (if not, refer to the [migrate to the ES modules format](/workers/reference/migrate-to-module-workers/) guide).
- Vitest and `@cloudflare/vitest-pool-workers` are installed in your project as dev dependencies

  <PackageManagers
  	pkg="vitest@~3.2.0 @cloudflare/vitest-pool-workers"
  	dev="true"
  />

  :::note

  Currently, the `@cloudflare/vitest-pool-workers` package _only_ works with Vitest 2.0.x - 3.2.x.

  :::

## Define Vitest configuration

In your `vitest.config.ts` file, use `defineWorkersConfig` to configure the Workers Vitest integration.

You can use your Worker configuration from your [Wrangler config file](/workers/wrangler/configuration/) by specifying it with `wrangler.configPath`.

```ts title = vitest.config.ts
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
	test: {
		poolOptions: {
			workers: {
				wrangler: { configPath: "./wrangler.jsonc" },
			},
		},
	},
});
```

You can also override or define additional configuration using the `miniflare` key. This takes precedence over values set in via your Wrangler config.

For example, this configuration would add a KV namespace `TEST_NAMESPACE` that was only accessed and modified in tests.

        ```js null {6-8}
        export default defineWorkersConfig({
        	test: {
        		poolOptions: {
        			workers: {
        				wrangler: { configPath: "./wrangler.jsonc" },
        				miniflare: {
        					kvNamespaces: ["TEST_NAMESPACE"],
        				},
        			},
        		},
        	},
        });
        ```

    For a full list of available Miniflare options, refer to the [Miniflare `WorkersOptions` API documentation](https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare#interface-workeroptions).

For a full list of available configuration options, refer to [Configuration](/workers/testing/vitest-integration/configuration/).

## Define types

If you are not using Typescript, you can skip this section.

First make sure you have run [`wrangler types`](/workers/wrangler/commands/), which generates [types for the Cloudflare Workers runtime](/workers/languages/typescript/) and an `Env` type based on your Worker's bindings.

Then add a `tsconfig.json` in your tests folder and add `"@cloudflare/vitest-pool-workers"` to your types array to define types for `cloudflare:test`.
You should also add the output of `wrangler types` to the `include` array so that the types for the Cloudflare Workers runtime are available.

<Details header="Example test/tsconfig.json">
	```jsonc title="test/tsconfig.json"
	{
		"extends": "../tsconfig.json",
		"compilerOptions": {
			"moduleResolution": "bundler",
			"types": [
				"@cloudflare/vitest-pool-workers", // provides `cloudflare:test` types
			],
		},
		"include": [
			"./**/*.ts",
			"../src/worker-configuration.d.ts", // output of `wrangler types`
		],
	}
	```
</Details>

You also need to define the type of the `env` object that is provided to your tests. Create an `env.d.ts` file in your tests folder, and declare the `ProvidedEnv` interface by extending the `Env` interface that is generated by `wrangler types`.

```ts title="test/env.d.ts"
declare module "cloudflare:test" {
	// ProvidedEnv controls the type of `import("cloudflare:test").env`
	interface ProvidedEnv extends Env {}
}
```

If your test bindings differ from the bindings in your Wrangler config, you should type them here in `ProvidedEnv`.

## Writing tests

We will use this simple Worker as an example. It returns a 404 response for the `/404` path and `"Hello World!"` for all other paths.

<TypeScriptExample filename="src/index.ts">
```ts
export default {
	async fetch(request, env, ctx): Promise<Response> {
		if (pathname === "/404") {
			return new Response("Not found", { status: 404 });
		}
		return new Response("Hello World!");
	},
} satisfies ExportedHandler<Env>;
```

</TypeScriptExample>

### Unit tests

By importing the Worker we can write a unit test for its `fetch` handler.

<TypeScriptExample filename="test/unit.spec.ts">
	```ts
	import {
		env,
		createExecutionContext,
		waitOnExecutionContext,
	} from "cloudflare:test";
	import { describe, it, expect } from "vitest";
	// Import your worker so you can unit test it
	import worker from "../src";

    // For now, you'll need to do something like this to get a correctly-typed
    // `Request` to pass to `worker.fetch()`.
    const IncomingRequest = Request<unknown, IncomingRequestCfProperties>;

    describe("Hello World worker", () => {
    	it("responds with Hello World!", async () => {
    		const request = new IncomingRequest("http://example.com/404");
    		// Create an empty context to pass to `worker.fetch()`
    		const ctx = createExecutionContext();
    		const response = await worker.fetch(request, env, ctx);
    		// Wait for all `Promise`s passed to `ctx.waitUntil()` to settle before running test assertions
    		await waitOnExecutionContext(ctx);
    		expect(await response.status).toBe(404);
    		expect(await response.text()).toBe("Not found");
    	});
    });

    ```

</TypeScriptExample>

### Integration tests

You can use the SELF fetcher provided by the `cloudflare:test` to write an integration test. This is a service binding to the default export defined in the main Worker.

<TypeScriptExample filename="test/integration.spec.ts">
	```ts
	import { SELF } from "cloudflare:test";
	import { describe, it, expect } from "vitest";

    describe("Hello World worker", () => {
    	it("responds with not found and proper status for /404", async () => {
    		const response = await SELF.fetch("http://example.com/404");
    		expect(await response.status).toBe(404);
    		expect(await response.text()).toBe("Not found");
    	});
    });

    ```

</TypeScriptExample>

When using `SELF` for integration tests, your Worker code runs in the same context as the test runner. This means you can use global mocks to control your Worker, but also means your Worker uses the subtly different module resolution behavior provided by Vite.
Usually this is not a problem, but to run your Worker in a fresh environment that is as close to production as possible, you can use an auxiliary Worker. Refer to [this example](https://github.com/cloudflare/workers-sdk/blob/main/fixtures/vitest-pool-workers-examples/basics-integration-auxiliary/vitest.config.ts) for how to set up integration tests using auxiliary Workers. However, using auxiliary Workers comes with [limitations](/workers/testing/vitest-integration/configuration/#workerspooloptions) that you should be aware of.

## Related resources

- For more complex examples of testing using `@cloudflare/vitest-pool-workers`, refer to [Recipes](/workers/testing/vitest-integration/recipes/).
- [Configuration API reference](/workers/testing/vitest-integration/configuration/)
- [Test APIs reference](/workers/testing/vitest-integration/test-apis/)

---

# Migrate from Pages to Workers

URL: https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/

import {
	Badge,
	Description,
	FileTree,
	InlineBadge,
	Render,
	TabItem,
	Tabs,
	WranglerConfig,
	TypeScriptExample,
	PackageManagers,
} from "~/components";

You can deploy full-stack applications, including front-end static assets and back-end APIs, as well as server-side rendered pages (SSR), with [Cloudflare Workers](/workers/static-assets/).

Like Pages, requests for static assets on Workers are free, and Pages Functions invocations are charged at the same rate as Workers, so you can expect [a similar cost structure](/workers/platform/pricing/#workers).

Unlike Pages, Workers has a distinctly broader set of features available to it, (including Durable Objects, Cron Triggers, and more comprehensive Observability). A complete list can be found at [the bottom of this page](#compatibility-matrix). Workers will receive the focus of Cloudflare's development efforts going forwards, so we therefore [are recommending using Cloudflare Workers over Cloudflare Pages for any new projects](http://blog.cloudflare.com/full-stack-development-on-cloudflare-workers).

## Migration 

Migrating from Cloudflare Pages to Cloudflare Workers is often a straightforward process. The following are some of the most common steps you will need to take to migrate your project.

### Frameworks

If your Pages project uses [a popular framework](/workers/framework-guides/), most frameworks already have adaptors available for Cloudflare Workers. Switch out any Pages-specific adaptors for the Workers equivalent and follow any guidance that they provide.

### Project configuration

If your project doesn't already have one, create a [Wrangler configuration file](/workers/wrangler/configuration/) (either `wrangler.jsonc`, `wrangler.json` or `wrangler.toml`) in the root of your project. The two mandatory fields are:

- [`name`](/workers/wrangler/configuration/#inheritable-keys)

  Set this to the name of the Worker you wish to deploy to. This can be the same as your existing Pages project name, so long as it conforms to Workers' name restrictions (e.g. max length).

- [`compatibility_date`](/workers/configuration/compatibility-dates/).

  If you were already using [Pages Functions](/pages/functions/wrangler-configuration/#inheritable-keys), set this to the same date configured there. Otherwise, set it to the current date.

#### Build output directory

Where you previously would configure a "build output directory" for Pages (in either a [Wrangler configuration file](/pages/functions/wrangler-configuration/#inheritable-keys) or in [the Cloudflare dashboard](/pages/configuration/build-configuration/#build-commands-and-directories)), you must now set the [`assets.directory`](/workers/static-assets/binding/#directory) value for a Worker project.

Before, with **Cloudflare Pages**:

<WranglerConfig>

```json
{
	"name": "my-pages-project",
	"pages_build_output_dir": "./dist/client/"
}
```

</WranglerConfig>

Now, with **Cloudflare Workers**:

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "2025-04-01",
	"assets": {
		"directory": "./dist/client/"
	}
}
```

</WranglerConfig>

#### Serving behavior

Pages would automatically attempt to determine the type of project you deployed. It would look for `404.html` and `index.html` files as signals for whether the project was likely a [Single Page Application (SPA)](/pages/configuration/serving-pages/#single-page-application-spa-rendering) or if it should [serve custom 404 pages](/pages/configuration/serving-pages/#not-found-behavior).

In Workers, to prevent accidental misconfiguration, this behavior is explicit and [must be set up manually](/workers/static-assets/routing/).

For a Single Page Application (SPA):

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "2025-04-01",
	"assets": {
		"directory": "./dist/client/",
		"not_found_handling": "single-page-application"
	}
}
```

</WranglerConfig>

For custom 404 pages:

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "2025-04-01",
	"assets": {
		"directory": "./dist/client/",
		"not_found_handling": "404-page"
	}
}
```

</WranglerConfig>

##### Ignoring assets

Pages would automatically exclude some files and folders from being uploaded as static assets such as `node_modules`, `.DS_Store`, and `.git`. If you wish to also avoid uploading these files to Workers, you can create an [`.assetsignore` file](/workers/static-assets/binding/#ignoring-assets) in your project's static asset directory.

```txt title="dist/client/.assetsignore"
**/node_modules
**/.DS_Store
**/.git
```

#### Pages Functions

##### Full-stack framework

If you use a full-stack framework powered by Pages Functions, ensure you have [updated your framework](#frameworks) to target Workers instead of Pages.

##### Pages Functions with an "advanced mode" `_worker.js` file

If you use Pages Functions with an ["advanced mode" `_worker.js` file](/pages/functions/advanced-mode/), you must first ensure this script doesn't get uploaded as a static asset. Either move `_worker.js` out of the static asset directory (recommended), or create [an `.assetsignore` file](/workers/static-assets/binding/#ignoring-assets) in the static asset directory and include `_worker.js` within it.

```txt title="dist/client/.assetsignore"
_worker.js
```

Then, update your configuration file's `main` field to point to the location of this Worker script:

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "2025-04-01",
	"main": "./dist/client/_worker.js", // or some other location if you moved the script out of the static asset directory
	"assets": {
		"directory": "./dist/client/"
	}
}
```

</WranglerConfig>

##### Pages Functions with a `functions/` folder

If you use **Pages Functions with a [folder of `functions/`](/pages/functions/)**, you must first compile these functions into a single Worker script with the [`wrangler pages functions build`](/workers/wrangler/commands/#functions-build) command.

<PackageManagers
	type="exec"
	pkg="wrangler"
	args={"pages functions build --outdir=./dist/worker/"}
/>

Although this command will remain available to you to run at any time, we do recommend considering using another framework if you wish to continue to use file-based routing. [HonoX](https://github.com/honojs/honox) is one popular option.

Once the Worker script has been compiled, you can update your configuration file's `main` field to point to the location it was built to:

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "2025-04-01",
	"main": "./dist/worker/index.js",
	"assets": {
		"directory": "./dist/client/"
	}
}
```

</WranglerConfig>

##### `_routes.json` and Pages Functions middleware

If you authored [a `_routes.json` file](/pages/functions/routing/#create-a-_routesjson-file) in your Pages project, or used [middleware](/pages/functions/middleware/) in Pages Functions, you must pay close attention to the configuration of your Worker script. Pages would default to serving your Pages Functions ahead of static assets and `_routes.json` and Pages Functions middleware allowed you to customize this behavior.

Workers, on the other hand, will default to serving static assets ahead of your Worker script, unless you have configured [`assets.run_worker_first`](/workers/static-assets/routing/worker-script/#run-your-worker-script-first). This option is required if you are, for example, performing any authentication checks or logging requests before serving static assets.

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "2025-04-01",
	"main": "./dist/worker/index.js",
	"assets": {
		"directory": "./dist/client/",
		"run_worker_first": true
	}
}
```

</WranglerConfig>

##### Starting from scratch

If you wish to, you can start a new Worker script from scratch and take advantage of all of Wrangler's and the latest runtime features (e.g. [`WorkerEntrypoint`s](/workers/runtime-apis/bindings/service-bindings/rpc/), [TypeScript support](/workers/languages/typescript/), [bundling](/workers/wrangler/bundling), etc.):

<TypeScriptExample filename="./worker/index.ts">

```ts
import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint {
	async fetch(request: Request) {
		return new Response("Hello, world!");
	}
}
```

</TypeScriptExample>

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "2025-04-01",
	"main": "./worker/index.ts",
	"assets": {
		"directory": "./dist/client/"
	}
}
```

</WranglerConfig>

#### Assets binding

Pages automatically provided [an `ASSETS` binding](/pages/functions/api-reference/#envassetsfetch) to access static assets from Pages Functions. In Workers, the name of this binding is customizable and it must be manually configured:

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "2025-04-01",
	"main": "./worker/index.ts",
	"assets": {
		"directory": "./dist/client/",
		"binding": "ASSETS"
	}
}
```

</WranglerConfig>

#### Runtime

If you had customized [placement](/workers/configuration/smart-placement/), or set a [compatibility date](/workers/configuration/compatibility-dates/) or any [compatibility flags](/workers/configuration/compatibility-flags/) in your Pages project, you can define the same in your Wrangler configuration file:

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "2025-04-01",
	"compatibility_flags": ["nodejs_compat"],
	"main": "./worker/index.ts",
	"placement": {
		"mode": "smart"
	},
	"assets": {
		"directory": "./dist/client/",
		"binding": "ASSETS"
	}
}
```

</WranglerConfig>

### Variables, secrets and bindings

[Variables](/workers/configuration/environment-variables/) and [bindings](/workers/runtime-apis/bindings/) can be set in your [Wrangler configuration file](/workers/wrangler/configuration/) and are made available in your Worker's environment (`env`). [Secrets](/workers/configuration/secrets/) can uploaded with Wrangler or defined in the Cloudflare dashboard for [production](/workers/configuration/secrets/#adding-secrets-to-your-project) and [`.dev.vars` for local development](/workers/configuration/secrets/#local-development-with-secrets).

If you are [using Workers Builds](#builds), ensure you also [configure any variables relevant to the build environment there](/workers/ci-cd/builds/configuration/). Unlike Pages, Workers does not share the same set of runtime and build-time variables.

### Wrangler commands

Where previously you used [`wrangler pages dev`](/workers/wrangler/commands/#dev-1) and [`wrangler pages deploy`](/workers/wrangler/commands/#deploy-1), now instead use [`wrangler dev`](/workers/wrangler/commands/#dev) and [`wrangler deploy`](/workers/wrangler/commands/#deploy). Additionally, if you are using a Vite-powered framework, [our new Vite plugin](/workers/vite-plugin/) may be able offer you an even simpler development experience.

### Builds

If you are using Pages' built-in CI/CD system, you can swap this for Workers Builds by first [connecting your repository to Workers Builds](/workers/ci-cd/builds/#get-started) and then [disabling automatic deployments on your Pages project](/pages/configuration/git-integration/#disable-automatic-deployments).

### Preview environment

Pages automatically creates a preview environment for each project, and can be indepenedently configured.

To get a similar experience in Workers, you must:

1. Ensure [preview URLs](/workers/configuration/previews/) are enabled (they are on by default).

   <WranglerConfig>

   ```json
   {
   	"name": "my-worker",
   	"compatibility_date": "2025-04-01",
   	"main": "./worker/index.ts",
   	"assets": {
   		"directory": "./dist/client/"
   	},
   	"preview_urls": true
   }
   ```

   </WranglerConfig>

1. [Enable non-production branch builds](/workers/ci-cd/builds/build-branches/#configure-non-production-branch-builds) in Workers Builds.

Optionally, you can also [protect these preview URLs with Cloudflare Access](/workers/configuration/previews/#manage-access-to-preview-urls).

:::note

Unlike Pages, Workers does not natively support defining different bindings in production vs. non-production builds. This is something we are actively exploring, but in the meantime, you may wish to consider using [Wrangler Environments](/workers/wrangler/environments/) and an [appropriate Workers Build configuration](/workers/ci-cd/builds/advanced-setups/#wrangler-environments) to achieve this.

:::

### Headers and redirects

[`_headers`](/workers/static-assets/headers/) and [`_redirects`](/workers/static-assets/redirects/) files are supported natively in Workers with static assets. Ensure that, just like for Pages, these files are included in the static asset directory of your project.

### pages.dev

Where previously you were offered a `pages.dev` subdomain for your Pages project, you can now configure a personalized `workers.dev` subdomain for all of your Worker projects. You can [configure this subdomain in the Cloudflare dashboard](/workers/configuration/routing/workers-dev/#configure-workersdev), and opt-in to using it with the [`workers_dev` option](/workers/configuration/routing/workers-dev/#disabling-workersdev-in-the-wrangler-configuration-file) in your configuration file.

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "2025-04-01",
	"main": "./worker/index.ts",
	"workers_dev": true
}
```

</WranglerConfig>

### Custom domains

If your domain's nameservers are managed by Cloudflare, you can, like Pages, configure a [custom domain](/workers/configuration/routing/custom-domains/) for your Worker. Additionally, you can also configure a [route](/workers/configuration/routing/routes/) if you only wish to some subset of paths to be served by your Worker.

:::note

Unlike Pages, Workers does not support any domain whose nameservers are not managed by Cloudflare.

:::

### Rollout

Once you have validated the behavior of Worker, and are satisfied with the development workflows, and have migrated all of your production traffic, you can delete your Pages project in the Cloudflare dashboard or with Wrangler:

<PackageManagers type="exec" pkg="wrangler" args={"pages project delete"} />

## Migrate your project using an AI coding assistant

You can add the following [experimental prompt](https://developers.cloudflare.com/workers/prompts/pages-to-workers.txt) in your preferred coding assistant (e.g. Claude Code, Cursor) to make your project compatible with Workers: 

```
https://developers.cloudflare.com/workers/prompts/pages-to-workers.txt
```

You can also use the Cloudflare Documentation [MCP server](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize) in your coding assistant to provide better context to your LLM when building with Workers, which includes this prompt when you ask to migrate from Pages to Workers.

## Compatibility matrix

This compatibility matrix compares the features of Workers and Pages. Unless otherwise stated below, what works in Pages works in Workers, and what works in Workers works in Pages. Think something is missing from this list? [Open a pull request](https://github.com/cloudflare/cloudflare-docs/edit/production/src/content/docs/workers/static-assets/compatibility-matrix.mdx) or [create a GitHub issue](https://github.com/cloudflare/cloudflare-docs/issues/new).

**Legend** <br />
✅: Supported <br />
⏳: Coming soon <br />
🟡: Unsupported, workaround available <br />
❌: Unsupported

|                                                                                                             | Workers | Pages   |
| ----------------------------------------------------------------------------------------------------------- | ------- | ------- |
| **Writing, Testing, and Deploying Code**                                                                    |         |         |
| [Cloudflare Vite plugin](/workers/vite-plugin/)                                                             | ✅      | ❌      |
| [Rollbacks](/workers/configuration/versions-and-deployments/rollbacks/)                                     | ✅      | ✅      |
| [Gradual Deployments](/workers/configuration/versions-and-deployments/)                                     | ✅      | ❌      |
| [Preview URLs](/workers/configuration/previews)                                                             | ✅      | ✅      |
| [Testing tools](/workers/testing)                                                                           | ✅      | ✅      |
| [Local Development](/workers/development-testing/)                                                            | ✅      | ✅      |
| [Remote Development (`--remote`)](/workers/wrangler/commands/)                                              | ✅      | ❌      |
| [Quick Editor in Dashboard](https://blog.cloudflare.com/improved-quick-edit)                                | ✅      | ❌      |
| **Static Assets**                                                                                           |         |         |
| [Early Hints](/pages/configuration/early-hints/)                                                            | ❌      | ✅      |
| [Custom HTTP headers for static assets](/workers/static-assets/headers/)                                    | ✅      | ✅      |
| [Middleware](/workers/static-assets/binding/#run_worker_first)                                              | ✅ [^1] | ✅      |
| [Redirects](/workers/static-assets/redirects/)                                                              | ✅      | ✅      |
| [Smart Placement](/workers/configuration/smart-placement/)                                                  | ✅      | ✅      |
| [Serve assets on a path](/workers/static-assets/routing/advanced/serving-a-subdirectory/)                   | ✅      | ❌      |
| **Observability**                                                                                           |         |         |
| [Workers Logs](/workers/observability/)                                                                     | ✅      | ❌      |
| [Logpush](/workers/observability/logs/logpush/)                                                             | ✅      | ❌      |
| [Tail Workers](/workers/observability/logs/tail-workers/)                                                   | ✅      | ❌      |
| [Real-time logs](/workers/observability/logs/real-time-logs/)                                               | ✅      | ✅      |
| [Source Maps](/workers/observability/source-maps/)                                                          | ✅      | ❌      |
| **Runtime APIs & Compute Models**                                                                           |         |         |
| [Node.js Compatibility Mode](/workers/runtime-apis/nodejs/)                                                 | ✅      | ✅      |
| [Durable Objects](/durable-objects/api/)                                                                    | ✅      | 🟡 [^2] |
| [Cron Triggers](/workers/configuration/cron-triggers/)                                                      | ✅      | ❌      |
| **Bindings**                                                                                                |         |         |
| [AI](/workers-ai/get-started/workers-wrangler/#2-connect-your-worker-to-workers-ai)                         | ✅      | ✅      |
| [Analytics Engine](/analytics/analytics-engine)                                                             | ✅      | ✅      |
| [Assets](/workers/static-assets/binding/)                                                                   | ✅      | ✅      |
| [Browser Rendering](/browser-rendering)                                                                     | ✅      | ✅      |
| [D1](/d1/worker-api/)                                                                                       | ✅      | ✅      |
| [Email Workers](/email-routing/email-workers/send-email-workers/)                                           | ✅      | ❌      |
| [Environment Variables](/workers/configuration/environment-variables/)                                      | ✅      | ✅      |
| [Hyperdrive](/hyperdrive/)                                                                                  | ✅      | ✅      |
| [Image Resizing](/images/transform-images/bindings/)                                                        | ✅      | ❌      |
| [KV](/kv/)                                                                                                  | ✅      | ✅      |
| [mTLS](/workers/runtime-apis/bindings/mtls/)                                                                | ✅      | ✅      |
| [Queue Producers](/queues/configuration/configure-queues/#producer-worker-configuration)                    | ✅      | ✅      |
| [Queue Consumers](/queues/configuration/configure-queues/#consumer-worker-configuration)                    | ✅      | ❌      |
| [R2](/r2/)                                                                                                  | ✅      | ✅      |
| [Rate Limiting](/workers/runtime-apis/bindings/rate-limit/)                                                 | ✅      | ❌      |
| [Secrets](/workers/configuration/secrets/)                                                                  | ✅      | ✅      |
| [Service bindings](/workers/runtime-apis/bindings/service-bindings/)                                        | ✅      | ✅      |
| [Vectorize](/vectorize/get-started/intro/#3-bind-your-worker-to-your-index)                                 | ✅      | ✅      |
| **Builds (CI/CD)**                                                                                          |         |         |
| [Monorepos](/workers/ci-cd/builds/advanced-setups/)                                                         | ✅      | ✅      |
| [Build Watch Paths](/workers/ci-cd/builds/build-watch-paths/)                                               | ✅      | ✅      |
| [Build Caching](/workers/ci-cd/builds/build-caching/)                                                       | ✅      | ✅      |
| [Deploy Hooks](/pages/configuration/deploy-hooks/)                                                          | ⏳      | ✅      |
| [Branch Deploy Controls](/pages/configuration/branch-build-controls/)                                       | 🟡 [^3] | ✅      |
| [Custom Branch Aliases](/pages/how-to/custom-branch-aliases/)                                               | ⏳      | ✅      |
| **Pages Functions**                                                                                         |         |         |
| [File-based Routing](/pages/functions/routing/)                                                             | 🟡 [^4] | ✅      |
| [Pages Plugins](/pages/functions/plugins/)                                                                  | 🟡 [^5] | ✅      |
| **Domain Configuration**                                                                                    |         |         |
| [Custom domains](/workers/configuration/routing/custom-domains/#add-a-custom-domain)                        | ✅      | ✅      |
| [Custom subdomains](/workers/configuration/routing/custom-domains/#set-up-a-custom-domain-in-the-dashboard) | ✅      | ✅      |
| [Custom domains outside Cloudflare zones](/pages/configuration/custom-domains/#add-a-custom-cname-record)   | ❌      | ✅      |
| [Non-root routes](/workers/configuration/routing/routes/)                                                   | ✅      | ❌      |

[^1]: Middleware can be configured via the [`run_worker_first`](/workers/static-assets/binding/#run_worker_first) option, but is charged as a normal Worker invocation. We plan to explore additional related options in the future.

[^2]: To [use Durable Objects with your Cloudflare Pages project](/pages/functions/bindings/#durable-objects), you must create a separate Worker with a Durable Object and then declare a binding to it in both your Production and Preview environments. Using Durable Objects with Workers is simpler and recommended.

[^3]: Workers Builds supports enabling [non-production branch builds](/workers/ci-cd/builds/build-branches/#configure-non-production-branch-builds), though does not yet have the same level of configurability as Pages does.

[^4]: Workers [supports popular frameworks](/workers/framework-guides/), many of which implement file-based routing. Additionally, you can use Wrangler to [compile your folder of `functions/`](#folder-of-functions) into a Worker to help ease the migration from Pages to Workers.

[^5]: As in <sup>4</sup>, Wrangler can [compile your Pages Functions into a Worker](#folder-of-functions). Or if you are starting from scratch, everything that is possible with Pages Functions can also be achieved by adding code to your Worker or by using framework-specific plugins for relevant third party tools.

---

# Migrate from Netlify to Workers

URL: https://developers.cloudflare.com/workers/static-assets/migration-guides/netlify-to-workers/

import { WranglerConfig } from "~/components";

In this tutorial, you will learn how to migrate your Netlify application to Cloudflare Workers.

You should already have an existing project deployed on Netlify that you would like to host on Cloudflare Workers. Netlify specific features are not supported by Cloudflare Workers. Review the [Workers compatibility matrix](/workers/static-assets/migration-guides/migrate-from-pages/#compatibility-matrix) for more information on what is supported.

## Frameworks

Some frameworks like Next.js, Astro with on demand rendering, and others have specific guides for migrating to Cloudflare Workers. Refer to our [framework guides](/workers/framework-guides/) for more information. If your framework has a **Deploy an existing project on Workers** guide, follow that guide for specific instructions. Otherwise, continue with the steps below.

## Find your build command and build directory

To move your application to Cloudflare Workers, you will need to know your build command and build directory. Cloudflare Workers will use this information to build and deploy your application. We will cover how to find these values in the Netlify Dashboard below.

In your Netlify Dashboard, find the project you want to migrate to Workers. Go to the **Project configuration** menu for your specific project, then go into the **Build & deploy** menu item. You will find a **Build settings** card that includes the **Build command** and **Publish directory** fields. Save these for deploying to Cloudflare Workers. In the below image, the **Build Command** is `npm run build`, and the **Output Directory** is `.next`.

![Finding the Build Command and publish Directory fields](~/assets/images/workers/migrations/netlify-build-command.png)

## Create a wrangler file

In the root of your project, create a `wrangler.jsonc` or `wrangler.toml` file (`wrangler.jsonc` is recommended). What goes in the file depends on what type of application you are deploying: an application powered by [Static Site Generation (SSG)](/workers/static-assets/routing/static-site-generation/), or a [Single Page Application (SPA)](/workers/static-assets/routing/single-page-application/).

For each case, be sure to update the `<your-project-name>` value with the name of your project and `<your-build-directory>` value with the build directory from Netlify.

For a **static site**, you will need to add the following to your wrangler file.

<WranglerConfig>

```jsonc
{
  "name": "<your-project-name>",
  "compatibility_date": "$today",
  "assets": {
    "directory": "<your-build-directory>",
  }
}
```

</WranglerConfig>

For a **Single Page Application**, you will need to add the following to your Wrangler configuration file, which includes the `not_found_handling` field.

<WranglerConfig>

```jsonc
{
  "name": "<your-project-name>",
  "compatibility_date": "2025-04-23",
  "assets": {
    "directory": "<your-build-directory>",
		"not_found_handling": "single-page-application"
  }
}
```

</WranglerConfig>

Some frameworks provide specific guides for migrating to Cloudflare Workers. Please refer to our [framework guides](/workers/framework-guides/) for more information. If your framework includes a “Deploy an existing project on Workers” guide, follow it for detailed instructions.

## Create a new Workers project

Your application has the proper configuration to be built and deployed to Cloudflare Workers.

The [Connect a new Worker](/workers/ci-cd/builds/#connect-a-new-worker) guide will instruct you how to connect your GitHub project to Cloudflare Workers. In the configuration step, ensure your build command is the same as the command you found on Netlify. Also, the deploy command should be the default `npx wrangler deploy`.

## Add a custom domain

Workers Custom Domains only supports domains that are configured as zones on your account. A zone refers to a domain (such as example.com) that Cloudflare manages for you, including its DNS and traffic.

Follow these instructions for [adding a custom domain to your Workers project](/workers/configuration/routing/custom-domains/#add-a-custom-domain). You will also find additional information on creating a zone for your domain.

## Delete your Netlify app

Once your custom domain is set up and sending requests to Cloudflare Workers, you can safely delete your Netlify application.

## Troubleshooting

For additional migration instructions, review the [Cloudflare Pages to Workers migration guide](/workers/static-assets/migration-guides/migrate-from-pages/). While not Netlify specific, it does cover some additional steps that may be helpful.

---

# Migrate from Vercel to Workers

URL: https://developers.cloudflare.com/workers/static-assets/migration-guides/vercel-to-workers/

import { WranglerConfig } from "~/components";

In this tutorial, you will learn how to migrate your Vercel application to Cloudflare Workers.

You should already have an existing project deployed on Vercel that you would like to host on Cloudflare Workers. Vercel specific features are not supported by Cloudflare Workers. Review the [Workers compatibility matrix](/workers/static-assets/migration-guides/migrate-from-pages/#compatibility-matrix) for more information on what is supported.

## Frameworks

Some frameworks like Next.js, Astro with on demand rendering, and others have specific guides for migrating to Cloudflare Workers. Refer to our [framework guides](/workers/framework-guides/) for more information. If your framework has a **Deploy an existing project on Workers** guide, follow that guide for specific instructions. Otherwise, continue with the steps below.

## Find your build command and build directory

To move your application to Cloudflare Workers, you will need to know your build command and build directory. Cloudflare Workers will use this information to build and deploy your application. We'll cover how to find these values in the Vercel Dashboard below.

In your Vercel Dashboard, find the project you want to migrate to Workers. Go to the **Settings** tab for your specific project and find the **Build & Development settings** panel. You will find the **Build Command** and **Output Directory** fields there. If you are using a framework, these values may not be filled in but will show the defaults used by the framework. Save these for deploying to Cloudflare Workers. In the below image, the **Build Command** is `npm run build`, and the **Output Directory** is `dist`.

![Finding the Build Command and Output Directory fields](~/assets/images/workers/migrations/vercel-deploy-1.png)

## Create a wrangler file

In the root of your project, create a `wrangler.jsonc` or `wrangler.toml` file (`wrangler.jsonc` is recommended). What goes in the file depends on what type of application you are deploying: static or single-page application.

For each case, be sure to update the `<your-project-name>` value with the name of your project and `<your-build-directory>` value with the build directory from Vercel. Be sure to set the right pathing, for example `./dist` if the build directory is `dist` or `./build` if your build directory is `build`.

For a **static site**, you will need to add the following to your wrangler file.

<WranglerConfig>

```jsonc
{
  "name": "<your-project-name>",
  "compatibility_date": "2025-04-23",
  "assets": {
    "directory": "<your-build-directory>",
  }
}
```

</WranglerConfig>

For a **single page application**, you will need to add the following to your wrangler file, which includes the `not_found_handling` field.

<WranglerConfig>

```jsonc
{
  "name": "<your-project-name>",
  "compatibility_date": "2025-04-23",
  "assets": {
    "directory": "<your-build-directory>",
		"not_found_handling": "single-page-application"
  }
}
```

</WranglerConfig>

Some frameworks provide specific guides for migrating to Cloudflare Workers. Please refer to our [framework guides](/workers/framework-guides/) for more information. If your framework includes a “Deploy an existing project on Workers” guide, follow it for detailed instructions.

## Create a new Workers project

Your application has the proper configuration to be built and deployed to Cloudflare Workers.

The [Connect a new Worker](/workers/ci-cd/builds/#connect-a-new-worker) guide will instruct you how to connect your GitHub project to Cloudflare Workers. In the configuration step, ensure your build command is the same as the command you found on Vercel. Also, the deploy command should be the default `npx wrangler deploy`.

## Add a custom domain

Workers Custom Domains only supports domains that are configured as zones on your account. A zone refers to a domain (such as example.com) that Cloudflare manages for you, including its DNS and traffic.

Follow these instructions for [adding a custom domain to your Workers project](/workers/configuration/routing/custom-domains/#add-a-custom-domain). You will also find additional information on creating a zone for your domain.

## Delete your Vercel app

Once your custom domain is set up and sending requests to Cloudflare Workers, you can safely delete your Vercel application.

## Troubleshooting

For additional migration instructions, review the [Cloudflare Pages to Workers migration guide](/workers/static-assets/migration-guides/migrate-from-pages/). While not Vercel specific, it does cover some additional steps that may be helpful.

---

# Full-stack application

URL: https://developers.cloudflare.com/workers/static-assets/routing/full-stack-application/

import { WranglerConfig, Render, DirectoryListing } from "~/components";

Full-stack applications are web applications which are span both the client and server. The build process of these applications will produce a HTML files, accompanying client-side resources (e.g. JavaScript bundles, CSS stylesheets, images, fonts, etc.) and a Worker script. Data is typically fetched the Worker script at request-time and the initial page response is usually server-side rendered (SSR). From there, the client is then hydrated and a SPA-like experience ensues.

The following full-stack frameworks are natively supported by Workers:

<DirectoryListing
	folder="workers/framework-guides/web-apps"
	tag="full-stack"
/>
<DirectoryListing
	folder="workers/framework-guides/web-apps/more-web-frameworks"
	tag="full-stack"
/>

---

# Routing

URL: https://developers.cloudflare.com/workers/static-assets/routing/

import { Badge, DirectoryListing } from "~/components";

Learn how to configure different archtectures for the static assets of your Worker.

<DirectoryListing />

---

# Single Page Application (SPA)

URL: https://developers.cloudflare.com/workers/static-assets/routing/single-page-application/

import { WranglerConfig, Aside, TypeScriptExample, Render } from "~/components";

Single Page Applications (SPAs) are web applications which are client-side rendered (CSR). They are often built with a framework such as [React](/workers/framework-guides/web-apps/react/), [Vue](/workers/framework-guides/web-apps/vue/) or [Svelte](/workers/framework-guides/web-apps/svelte/). The build process of these frameworks will produce a single `/index.html` file and accompanying client-side resources (e.g. JavaScript bundles, CSS stylesheets, images, fonts, etc.). Typically, data is fetched by the client from an API with client-side requests.

When you configure `single-page-application` mode, Cloudflare provides default routing behavior that automatically serves your `/index.html` file for navigation requests (those with `Sec-Fetch-Mode: navigate` headers) which don't match any other asset. For more control over which paths invoke your Worker script, you can use [advanced routing control](#advanced-routing-control).

## Configuration

In order to deploy a Single Page Application to Workers, you must configure the `assets.directory` and `assets.not_found_handling` options in your [Wrangler configuration file](/workers/wrangler/configuration/#assets):

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "$today",
	"assets": {
		"directory": "./dist/",
		"not_found_handling": "single-page-application"
	}
}
```

</WranglerConfig>

Configuring `assets.not_found_handling` to `single-page-application` overrides the default serving behavior of Workers for static assets. When an incoming request does not match a file in the `assets.directory`, Workers will serve the contents of the `/index.html` file with a `200 OK` status.

<Render file="navigation_requests" />

## Advanced routing control

For more explicit control over SPA routing behavior, you can use `run_worker_first` with an array of route patterns. This approach disables the automatic `Sec-Fetch-Mode: navigate` detection and gives you explicit control over which requests should be handled by your Worker script vs served as static assets.

<Aside type="note">
	Advanced routing control is supported in:
    - [Wrangler](/workers/wrangler/install-and-update/) v4.20.0 and above
    - [Cloudflare Vite plugin](/workers/vite-plugin/get-started/) v1.7.0 and above

</Aside>

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "$today",
	"main": "./src/index.ts",
	"assets": {
		"directory": "./dist/",
		"not_found_handling": "single-page-application",
		"binding": "ASSETS",
		"run_worker_first": ["/api/*", "!/api/docs/*"]
	}
}
```

</WranglerConfig>

This configuration provides explicit routing control without relying on browser navigation headers, making it ideal for complex SPAs that need fine-grained routing behavior. Your Worker script can then handle the matched routes and (optionally using [the assets binding](/workers/static-assets/binding/#binding)) and serve dynamic content.

**For example:**

<TypeScriptExample filename="./src/index.ts">

```ts
export default {
	async fetch(request, env): Promise<Response> {
		const url = new URL(request.url);

		if (url.pathname === "/api/name") {
			return new Response(JSON.stringify({ name: "Cloudflare" }), {
				headers: { "Content-Type": "application/json" },
			});
		}

		return new Response(null, { status: 404 });
	},
} satisfies ExportedHandler;
```
</TypeScriptExample>

## Local Development

If you are using a Vite-powered SPA framework, you might be interested in using our [Vite plugin](/workers/vite-plugin/) which offers a Vite-native developer experience.

<Render
	file="static_asset_routing_reference"
	params={{ not_found_handling: "single-page-application" }}
/>

---

# Static Site Generation (SSG) and custom 404 pages

URL: https://developers.cloudflare.com/workers/static-assets/routing/static-site-generation/

import { WranglerConfig, Render } from "~/components";

Static Site Generation (SSG) applications are web applications which are predominantely built or "prerendered" ahead-of-time. They are often built with a framework such as [Gatsby](/workers/framework-guides/web-apps/more-web-frameworks/gatsby/) or [Docusaurus](/workers/framework-guides/web-apps/more-web-frameworks/docusaurus/). The build process of these frameworks will produce many HTML files and accompanying client-side resources (e.g. JavaScript bundles, CSS stylesheets, images, fonts, etc.). Data is either static, fetched and compiled into the HTML at build-time, or fetched by the client from an API with client-side requests.

Often, an SSG framework will allow you to create a custom 404 page.

## Configuration

In order to deploy a Static Site Generation application to Workers, you must configure the `assets.directory`, and optionally, the `assets.not_found_handling` and `assets.html_handling` options in your [Wrangler configuration file](/workers/wrangler/configuration/#assets):

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "$today",
	"assets": {
		"directory": "./dist/",
		"not_found_handling": "404-page",
		"html_handling": "auto-trailing-slash"
	}
}
```

</WranglerConfig>

`assets.html_handling` defaults to `auto-trailing-slash` and this will usually give you the desired behavior automatically: individual files (e.g. `foo.html`) will be served _without_ a trailing slash and folder index files (e.g. `foo/index.html`) will be served _with_ a trailing slash. Alternatively, you can force trailing slashes (`force-trailing-slash`) or drop trailing slashes (`drop-trailing-slash`) on requests for HTML pages.

### Custom 404 pages

Configuring `assets.not_found_handling` to `404-page` overrides the default serving behavior of Workers for static assets. When an incoming request does not match a file in the `assets.directory`, Workers will serve the contents of the nearest `404.html` file with a `404 Not Found` status.

<Render file="navigation_requests" />

## Local Development

If you are using a Vite-powered SPA framework, you might be interested in using our [Vite plugin](/workers/vite-plugin/) which offers a Vite-native developer experience.

<Render
	file="static_asset_routing_reference"
	params={{ not_found_handling: "404-page" }}
/>

---

# Worker script

URL: https://developers.cloudflare.com/workers/static-assets/routing/worker-script/

import { WranglerConfig, TypeScriptExample, Aside } from "~/components";

If you have both static assets and a Worker script configured, Cloudflare will first attempt to serve static assets if one matches the incoming request. You can read more about how we match assets in the [HTML handling docs](/workers/static-assets/routing/advanced/html-handling/).

If an appropriate static asset if not found, Cloudflare will invoke your Worker script.

This allows you to easily combine together these two features to create powerful applications (e.g. a [full-stack application](/workers/static-assets/routing/full-stack-application/), or a [Single Page Application (SPA)](/workers/static-assets/routing/single-page-application/) or [Static Site Generation (SSG) application](/workers/static-assets/routing/static-site-generation/) with an API).

## Run your Worker script first

You can configure the [`assets.run_worker_first` setting](/workers/static-assets/binding/#run_worker_first) to control when your Worker script runs relative to static asset serving. This gives you more control over exactly how and when those assets are served and can be used to implement "middleware" for requests.

<Aside type="caution">
	If you are using [Smart Placement](/workers/configuration/smart-placement/) in
	combination with `assets.run_worker_first`, you may find that placement
	decisions are not optimized correctly as, currently, the entire Worker script
	is placed as a single unit. This may not accurately reflect the desired
	"split" in behavior of edge-first vs. smart-placed compute for your
	application. This is a limitation that we are currently working to resolve.
</Aside>

### Run Worker before each request

If you need to always run your Worker script before serving static assets (for example, you wish to log requests, perform some authentication checks, use [HTMLRewriter](/workers/runtime-apis/html-rewriter/), or otherwise transform assets before serving), set `run_worker_first` to `true`:

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "$today",
	"main": "./worker/index.ts",
	"assets": {
		"directory": "./dist/",
		"binding": "ASSETS",
		"run_worker_first": true
	}
}
```

</WranglerConfig>

<TypeScriptExample filename="./worker/index.ts">

```ts
import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint<Env> {
	async fetch(request: Request) {
		// You can perform checks before fetching assets
		const user = await checkIfRequestIsAuthenticated(request);

		if (!user) {
			return new Response("Unauthorized", { status: 401 });
		}

		// You can then just fetch the assets as normal, or you could pass in a custom Request object here if you wanted to fetch some other specific asset
		const assetResponse = await this.env.ASSETS.fetch(request);

		// You can return static asset response as-is, or you can transform them with something like HTMLRewriter
		return new HTMLRewriter()
			.on("#user", {
				element(element) {
					element.setInnerContent(JSON.stringify({ name: user.name }));
				},
			})
			.transform(assetResponse);
	}
}
```
</TypeScriptExample>

### Run Worker first for selective paths

You can also configure selective Worker-first routing using an array of route patterns, often paired with the [`single-page-application` setting](/workers/static-assets/routing/single-page-application/#advanced-routing-control). This allows you to run the Worker first only for specific routes while letting other requests follow the default asset-first behavior:

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "$today",
	"main": "./worker/index.ts",
	"assets": {
		"directory": "./dist/",
		"not_found_handling": "single-page-application",
		"binding": "ASSETS",
		"run_worker_first": ["/oauth/callback"]
	}
}
```

</WranglerConfig>

<TypeScriptExample filename="./worker/index.ts">

```ts
import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint<Env> {
	async fetch(request: Request) {
		// The only thing this Worker script does is handle an OAuth callback.
		// All other requests either serve an asset that matches or serve the index.html fallback, without ever hitting this code.
		const url = new URL(request.url);
		const code = url.searchParams.get("code");
		const state = url.searchParams.get("state");

		const accessToken = await exchangeCodeForToken(code, state);
		const sessionIdentifier = await storeTokenAndGenerateSession(accessToken);

		// Redirect back to the index, but set a cookie that the front-end will use.
		return new Response(null, {
			headers: {
				"Location": "/",
				"Set-Cookie": `session_token=${sessionIdentifier}; HttpOnly; Secure; SameSite=Lax; Path=/`
			}
		});
	}
}
```
</TypeScriptExample>

---

# API

URL: https://developers.cloudflare.com/workers/vite-plugin/reference/api/

import { Type, MetaInfo } from "~/components";

## `cloudflare()`

The `cloudflare` plugin should be included in the Vite `plugins` array:

```ts {2, 5} title="vite.config.ts"
import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [cloudflare()],
});
```

It accepts an optional `PluginConfig` parameter.

## `interface PluginConfig`

- `configPath` <Type text='string' /> <MetaInfo text='optional' />

  An optional path to your Worker config file.
  By default, a `wrangler.jsonc`, `wrangler.json`, or `wrangler.toml` file in the root of your application will be used as the Worker config.

  For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/).

- `viteEnvironment` <Type text='{ name?: string }' /> <MetaInfo text='optional' />

  Optional Vite environment options.
  By default, the environment name is the Worker name with `-` characters replaced with `_`.
  Setting the name here will override this.
  A typical use case is setting `viteEnvironment: { name: "ssr" }` to apply the Worker to the SSR environment.

  See [Vite Environments](/workers/vite-plugin/reference/vite-environments/) for more information.

- `persistState` <Type text='boolean | { path: string }' /> <MetaInfo text='optional' />

  An optional override for state persistence.
  By default, state is persisted to `.wrangler/state`.
  A custom `path` can be provided or, alternatively, persistence can be disabled by setting the value to `false`.

- `inspectorPort` <Type text='number | false' /> <MetaInfo text='optional' />

  An optional override for debugging your Workers.
  By default, the debugging inspector is enabled and listens on port `9229`.
  A custom port can be provided or, alternatively, setting this to `false` will disable the debugging inspector.

  See [Debugging](/workers/vite-plugin/reference/debugging/) for more information.

- `auxiliaryWorkers` <Type text='Array<AuxiliaryWorkerConfig>' /> <MetaInfo text='optional' />

  An optional array of auxiliary Workers.
  Auxiliary Workers are additional Workers that are used as part of your application.
  You can use [service bindings](/workers/runtime-apis/bindings/service-bindings/) to call auxiliary Workers from your main (entry) Worker.
  All requests are routed through your entry Worker.
  During the build, each Worker is output to a separate subdirectory of `dist`.

  :::note
  Auxiliary Workers are not currently supported when using [React Router](https://reactrouter.com/) as a framework.
  :::

  :::note
  When running `wrangler deploy`, only your main (entry) Worker will be deployed.
  If using multiple Workers, each auxiliary Worker must be deployed individually.
  You can inspect the `dist` directory and then run `wrangler deploy -c dist/<auxiliary-worker>/wrangler.json` for each.
  :::

## `interface AuxiliaryWorkerConfig`

- `configPath` <Type text='string' />

  A required path to your Worker config file.

  For more information about the Worker configuration, see [Configuration](/workers/wrangler/configuration/).

- `viteEnvironment` <Type text='{ name?: string }' /> <MetaInfo text='optional' />

  Optional Vite environment options.
  By default, the environment name is the Worker name with `-` characters replaced with `_`.
  Setting the name here will override this.

  See [Vite Environments](/workers/vite-plugin/reference/vite-environments/) for more information.

---

# Cloudflare Environments

URL: https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/

import { PackageManagers, WranglerConfig } from "~/components";

A Worker config file may contain configuration for multiple [Cloudflare environments](/workers/wrangler/environments/).
With the Cloudflare Vite plugin, you select a Cloudflare environment at dev or build time by providing the `CLOUDFLARE_ENV` environment variable.
Consider the following example Worker config file:

<WranglerConfig>

```toml
name = "my-worker"
compatibility_date = "2025-04-03"
main = "./src/index.ts"

vars = { MY_VAR = "Top-level var" }

[env.staging]
vars = { MY_VAR = "Staging var" }

[env.production]
vars = { MY_VAR = "Production var" }
```

</WranglerConfig>

If you run `CLOUDFLARE_ENV=production vite build` then the output `wrangler.json` file generated by the build will be a flattened configuration for the 'production' Cloudflare environment, as shown in the following example:

```json title=wrangler.json
{
	"name": "my-worker",
	"compatibility_date": "2025-04-03",
	"main": "index.js",
	"vars": { "MY_VAR": "Production var" }
}
```

Notice that the value of `MY_VAR` is `Production var`.
This flattened configuration combines [top-level only](/workers/wrangler/configuration/#top-level-only-keys), [inheritable](/workers/wrangler/configuration/#inheritable-keys), and [non-inheritable](/workers/wrangler/configuration/#non-inheritable-keys) keys.

:::note
The default Vite environment name for a Worker is always the top-level Worker name.
This enables you to reference the Worker consistently in your Vite config when using multiple Cloudflare environments.
See [Vite Environments](/workers/vite-plugin/reference/vite-environments/) for more information.
:::

Cloudflare environments can also be used in development.
For example, you could run `CLOUDFLARE_ENV=development vite dev`.
It is common to use the default top-level environment as the development environment and then add additional environments as necessary.

:::note
Running `vite dev` or `vite build` without providing `CLOUDFLARE_ENV` will use the default top-level Cloudflare environment.
As Cloudflare environments are applied at dev and build time, specifying `CLOUDFLARE_ENV` when running `vite preview` or `wrangler deploy` will have no effect.
:::

## Combining Cloudflare environments and Vite modes

You may wish to combine the concepts of [Cloudflare environments](/workers/wrangler/environments/) and [Vite modes](https://vite.dev/guide/env-and-mode.html#modes).
With this approach, the Vite mode can be used to select the Cloudflare environment and a single method can be used to determine environment specific configuration and code.
Consider again the previous example:

<WranglerConfig>

```toml
# wrangler.toml

name = "my-worker"
compatibility_date = "2025-04-03"
main = "./src/index.ts"

vars = { MY_VAR = "Top-level var" }

[env.staging]
vars = { MY_VAR = "Staging var" }

[env.production]
vars = { MY_VAR = "Production var" }
```

</WranglerConfig>

Next, provide `.env.staging` and `.env.production` files:

```sh title=".env.staging"
CLOUDFLARE_ENV=staging
```

```sh title=".env.production"
CLOUDFLARE_ENV=production
```

By default, `vite build` uses the 'production' Vite mode.
Vite will therefore load the `.env.production` file to get the environment variables that are used in the build.
Since the `.env.production` file contains `CLOUDFLARE_ENV=production`, the Cloudflare Vite plugin will select the 'production' Cloudflare environment.
The value of `MY_VAR` will therefore be `'Production var'`.
If you run `vite build --mode staging` then the 'staging' Vite mode will be used and the 'staging' Cloudflare environment will be selected.
The value of `MY_VAR` will therefore be `'Staging var'`.

For more information about using `.env` files with Vite, see the [relevant documentation](https://vite.dev/guide/env-and-mode#env-files).

---

# Debugging

URL: https://developers.cloudflare.com/workers/vite-plugin/reference/debugging/

The Cloudflare Vite plugin has debugging enabled by default and listens on port `9229`.
You may choose a custom port or disable debugging by setting the `inspectorPort` option in the [plugin config](/workers/vite-plugin/reference/api#interface-pluginconfig).
There are two recommended methods for debugging your Workers during local development:

## DevTools

When running `vite dev` or `vite preview`, a `/__debug` route is added that provides access to [Cloudflare's implementation](https://github.com/cloudflare/workers-sdk/tree/main/packages/chrome-devtools-patches) of [Chrome's DevTools](https://developer.chrome.com/docs/devtools/overview).
Navigating to this route will open a DevTools tab for each of the Workers in your application.

Once the tab(s) are open, you can make a request to your application and start debugging your Worker code.

:::note
When debugging multiple Workers, you may need to allow your browser to open pop-ups.
:::

## VS Code

To set up [VS Code](https://code.visualstudio.com/) to support breakpoint debugging in your application, you should create a `.vscode/launch.json` file that contains the following configuration:

```json title=".vscode/launch.json"
{
	"configurations": [
		{
			"name": "<NAME_OF_WORKER>",
			"type": "node",
			"request": "attach",
			"websocketAddress": "ws://localhost:9229/<NAME_OF_WORKER>",
			"resolveSourceMapLocations": null,
			"attachExistingChildren": false,
			"autoAttachChildProcesses": false,
			"sourceMaps": true
		}
	],
	"compounds": [
		{
			"name": "Debug Workers",
			"configurations": ["<NAME_OF_WORKER>"],
			"stopAll": true
		}
	]
}
```

Here, `<NAME_OF_WORKER>` indicates the name of the Worker as specified in your Worker config file.
If you have used the `inspectorPort` option to set a custom port then this should be the value provided in the `websocketaddress` field.

:::note
If you have more than one Worker in your application, you should add a configuration in the `configurations` field for each and include the configuration name in the `compounds` `configurations` array.
:::

With this set up, you can run `vite dev` or `vite preview` and then select **Debug Workers** at the top of the **Run & Debug** panel to start debugging.

---

# Reference

URL: https://developers.cloudflare.com/workers/vite-plugin/reference/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Secrets

URL: https://developers.cloudflare.com/workers/vite-plugin/reference/secrets/

import { PackageManagers, WranglerConfig } from "~/components";

[Secrets](/workers/configuration/secrets/) are typically used for storing sensitive information such as API keys and auth tokens.
For deployed Workers, they are set via the dashboard or Wrangler CLI.

In local development, secrets can be provided to your Worker by using a [`.dev.vars`](/workers/configuration/secrets/#local-development-with-secrets) file.
If you are using [Cloudflare Environments](/workers/vite-plugin/reference/cloudflare-environments/) then the relevant `.dev.vars` file will be selected.
For example, `CLOUDFLARE_ENV=staging vite dev` will load `.dev.vars.staging` if it exists and fall back to `.dev.vars`.

:::note
The `vite build` command copies the relevant `.dev.vars` file to the output directory.
This is only used when running `vite preview` and is not deployed with your Worker.
:::

---

# Migrating from wrangler dev

URL: https://developers.cloudflare.com/workers/vite-plugin/reference/migrating-from-wrangler-dev/

In most cases, migrating from [`wrangler dev`](/workers/wrangler/commands/#dev) is straightforward and you can follow the instructions in [Get started](/workers/vite-plugin/get-started/).
There are a few key differences to highlight:

## Input and output Worker config files

With the Cloudflare Vite plugin, your [Worker config file](/workers/wrangler/configuration/) (for example, `wrangler.jsonc`) is the input configuration and a separate output configuration is created as part of the build.
This output file is a snapshot of your configuration at the time of the build and is modified to reference your build artifacts.
It is the configuration that is used for preview and deployment.
Once you have run `vite build`, running `wrangler deploy` or `vite preview` will automatically locate this output configuration file.

## Cloudflare Environments

With the Cloudflare Vite plugin, [Cloudflare Environments](/workers/vite-plugin/reference/cloudflare-environments/) are applied at dev and build time.
Running `wrangler deploy --env some-env` is therefore not applicable and the environment to deploy should instead be set by running `CLOUDFLARE_ENV=some-env vite build`.

## Redundant fields in the Wrangler config file

There are various options in the [Worker config file](/workers/wrangler/configuration/) that are ignored when using Vite, as they are either no longer applicable or are replaced by Vite equivalents.
If these options are provided, then warnings will be printed to the console with suggestions for how to proceed.
Examples where the Vite configuration should be used instead include `alias` and `define`.
See [Vite Environments](/workers/vite-plugin/reference/vite-environments/) for more information about configuring your Worker environments in Vite.

## No remote mode

The Vite plugin does not support [remote mode](/workers/development-testing/#remote-bindings).
We will be adding support for accessing remote resources in local development in a future update.

---

# Static Assets

URL: https://developers.cloudflare.com/workers/vite-plugin/reference/static-assets/

import { WranglerConfig } from "~/components";

The Vite plugin does not require that you provide the `assets` field in order to enable assets and instead determines whether assets should be included based on whether the `client` environment has been built.
By default, the `client` environment is built if there is an `index.html` file in the root of your project or if `build.rollupOptions.input` is specified in the Vite config.

:::note
When using the Cloudflare Vite plugin, the `client` environment is deployed as your static assets.
This typically includes files such as static HTML, front-end JavaScript, CSS, images and fonts.
For more information about using static assets in Vite, refer to [Static Asset Handling](https://vite.dev/guide/assets).
:::

On running `vite build`, an output `wrangler.json` configuration file is generated as part of the build output.
The `assets.directory` field in this file is automatically populated with the path to your `client` build output.
It is therefore not necessary to provide the `assets.directory` field in your input Worker configuration.

The `assets` configuration should be used, however, if you wish to set [routing configuration](/workers/static-assets/routing/) or enable the [assets binding](/workers/static-assets/binding/#binding).
The following example configures the `not_found_handling` for a single-page application so that the fallback will always be the root `index.html` file.

<WranglerConfig>

```toml
assets = { not_found_handling = "single-page-application" }
```

</WranglerConfig>

## Headers and redirects

Custom [headers](/workers/static-assets/headers/) and [redirects](/workers/static-assets/redirects/) are supported at build, preview and deploy time by adding `_headers` and `_redirects` files to your [`public` directory](https://vite.dev/guide/assets#the-public-directory).
The paths in these files should reflect the structure of your client build output.
For example, generated assets are typically located in an [assets subdirectory](https://vite.dev/config/build-options#build-assetsdir).

<br />

---

# Vite Environments

URL: https://developers.cloudflare.com/workers/vite-plugin/reference/vite-environments/

import { WranglerConfig } from "~/components";

The [Vite Environment API](https://vite.dev/guide/api-environment), released in Vite 6, is the key feature that enables the Cloudflare Vite plugin to integrate Vite directly with the Workers runtime.
It is not necessary to understand all the intricacies of the Environment API as an end user, but it is useful to have a high-level understanding.

## Default behavior

Vite creates two environments by default: `client` and `ssr`.
A front-end only application uses the `client` environment, whereas a full-stack application created with a framework typically uses the `client` environment for front-end code and the `ssr` environment for server-side rendering.

By default, when you add a Worker using the Cloudflare Vite plugin, an additional environment is created.
Its name is derived from the Worker name, with any dashes replaced with underscores.
This name can be used to reference the environment in your Vite config in order to apply environment specific configuration.

:::note
The default Vite environment name for a Worker is always the top-level Worker name.
This enables you to reference the Worker consistently in your Vite config when using multiple [Cloudflare Environments](/workers/vite-plugin/reference/cloudflare-environments/).
:::

## Environment configuration

In the following example we have a Worker named `my-worker` that is associated with a Vite environment named `my_worker`.
We use the Vite config to set global constant replacements for this environment:

<WranglerConfig>

```toml
name = "my-worker"
compatibility_date = "2025-04-03"
main = "./src/index.ts"
```

</WranglerConfig>

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	environments: {
		my_worker: {
			define: {
				__APP_VERSION__: JSON.stringify("v1.0.0"),
			},
		},
	},
	plugins: [cloudflare()],
});
```

For more information about Vite's configuration options, see [Configuring Vite](https://vite.dev/config/).

The default behavior of using the Worker name as the environment name is appropriate when you have a standalone Worker, such as an API that is accessed from your front-end application, or an [auxiliary Worker](/workers/vite-plugin/reference/api/#interface-pluginconfig) that is accessed via service bindings.

## React Router v7

If you are using the Cloudflare Vite plugin with [React Router v7](https://reactrouter.com/), then your Worker is used for server-side rendering and tightly integrated with the framework.
To support this, you should assign it to the `ssr` environment by setting `viteEnvironment.name` in the plugin config.

```ts title="vite.config.ts"
import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";
import { reactRouter } from "@react-router/dev/vite";

export default defineConfig({
	plugins: [cloudflare({ viteEnvironment: { name: "ssr" } }), reactRouter()],
});
```

This merges the Worker's environment configuration with the framework's SSR configuration and ensures that the Worker is included as part of the framework's build output.

---

# Automate analytics reporting with Cloudflare Workers and email routing

URL: https://developers.cloudflare.com/workers/tutorials/automated-analytics-reporting/

import {
	Render,
	PackageManagers,
	TabItem,
	Tabs,
	WranglerConfig,
} from "~/components";

In this tutorial, you will create a [Cloudflare Worker](https://workers.cloudflare.com/) that fetches analytics data about your account from Cloudflare's [GraphQL Analytics API](https://developers.cloudflare.com/analytics/graphql-api/). You will be able to view the account analytics data in your browser and receive a scheduled email report.

You will learn:

1. How to create a Worker using the `c3` CLI.
2. How to fetch analytics data from Cloudflare's GraphQL Analytics API.
3. How to send an email with a Worker.
4. How to schedule the Worker to run at a specific time.
5. How to store secrets and environment variables in your Worker.
6. How to test the Worker locally.
7. How to deploy the Worker to Cloudflare's edge network.

## Prerequisites

Before you start, make sure you:

<Render file="prereqs" product="workers" />

3. [Add a domain](/fundamentals/manage-domains/add-site/) to your Cloudflare account.
4. [Enable Email Routing](/email-routing/get-started/enable-email-routing/) for your domain.
5. Create Cloudflare's [Analytics API token](/analytics/graphql-api/getting-started/authentication/api-token-auth/).

## 1. Create a Worker

While you can create a Worker using the Cloudflare dashboard, creating a Worker using the `c3` CLI is recommended as it provides a more streamlined development experience and allows you to test your Worker locally.

First, use the `c3` CLI to create a new Cloudflare Workers project.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"account-analytics"}
/>

In this tutorial, name your Worker as `account-analytics`.

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Now, the Worker is set up. Move into your project directory:

```sh
cd account-analytics
```

To continue with this tutorial, install the [`mimetext`](https://www.npmjs.com/package/mimetext) package:

<PackageManagers pkg="mimetext@latest" />

## 2. Update Wrangler configuration file

[`wrangler.jsonc`](/workers/wrangler/configuration/) contains the configuration for your Worker. It was created when you ran `c3` CLI. Open `wrangler.jsonc` in your code editor and update it with the following configuration:

<WranglerConfig>

```toml
name = "account-analytics"
main = "src/index.js"

compatibility_date = "2024-11-01"
compatibility_flags = ["nodejs_compat"]

# Set destination_address to the email address where you want to receive the report
send_email = [
  { name = "ANALYTICS_EMAIL", destination_address = "<>" }
]

# Schedule the Worker to run every day at 10:00 AM
[triggers]
crons = ["0 10 * * *"]

# Enable observability to view Worker logs
[observability]
enabled = true

[vars]
# This value shows the name of the sender in the email
SENDER_NAME = "Cloudflare Analytics Worker"

# This email address will be used as the sender of the email
SENDER_EMAIL = "<>"

# This email address will be used as the recipient of the email
RECIPIENT_EMAIL = "<>"

# This value will be used as the subject of the email
EMAIL_SUBJECT = "Cloudflare Analytics Report"
```

</WranglerConfig>

Before you continue, update the following:

1. `destination_address`: Enter the email address where you want to receive the analytics report.
2. `[VARS]`: Enter the environment variable values you want to use in your Worker.

:::note[IMPORTANT]
`destination_address` and `RECIPIENT_EMAIL` **must** contain [Email Routing verified email](/email-routing/get-started/enable-email-routing/) address.

`SENDER_EMAIL` **must** be an email address on a domain that is added to your Cloudflare domain and has Email Routing enabled.

:::

## 3. Update the Worker code

You will now add the code step by step to the `src/index.js` file. This tutorial will explain each part of the code.

### Add the required modules and Handlers

While you are in your project directory, open `src/index.js` in your code editor and update it with the following code:

```js
// Import required modules for email handling
import { EmailMessage } from "cloudflare:email";
import { createMimeMessage } from "mimetext";

export default {
	// HTTP request handler - This Handler is invoked when the Worker is accessed via HTTP
	async fetch(request, env, ctx) {
		try {
			const analyticsData = await fetchAnalytics(env);
			const formattedContent = formatContent(
				analyticsData.data,
				analyticsData.formattedDate,
			);
			return new Response(formattedContent, {
				headers: { "Content-Type": "text/plain" },
			});
		} catch (error) {
			console.error("Error:", error);
			return new Response(`Error: ${error.message}`, {
				status: 500,
				headers: { "Content-Type": "text/plain" },
			});
		}
	},

	// Scheduled task handler - This Handler is invoked via a Cron Trigger
	async scheduled(event, env, ctx) {
		try {
			const analyticsData = await fetchAnalytics(env);
			const formattedContent = formatContent(
				analyticsData.data,
				analyticsData.formattedDate,
			);
			await sendEmail(env, formattedContent);
			console.log("Analytics email sent successfully");
		} catch (error) {
			console.error("Failed to send analytics email:", error);
		}
	},
};
```

The code above defines two [Worker Handlers](/workers/runtime-apis/handlers/):

- `fetch`: This Handler executes when the Worker is accessed via HTTP. It fetches the analytics data, formats it and returns it as a response.
- `scheduled`: This Handler executes at the scheduled time. It fetches the analytics data, formats it and sends an email with the analytics data.

### Add the analytics fetching function

Add the following function to the `src/index.js` file, below the Handlers:

```js
async function fetchAnalytics(env) {
	// Calculate yesterday's date for the report and format it for display
	const yesterday = new Date();
	yesterday.setDate(yesterday.getDate() - 1);
	const dateString = yesterday.toISOString().split("T")[0];
	const formattedDate = yesterday.toLocaleDateString("en-US", {
		weekday: "long",
		year: "numeric",
		month: "long",
		day: "numeric",
	});

	// Fetch analytics data from Cloudflare's GraphQL Analytics API
	const response = await fetch(`https://api.cloudflare.com/client/v4/graphql`, {
		method: "POST",
		headers: {
			Authorization: `Bearer ${env.CF_API_TOKEN}`,
			"Content-Type": "application/json",
		},
		body: JSON.stringify({
			query: `
                query GetAnalytics($accountTag: String!, $date: String!) {
                    viewer {
                        accounts(filter: { accountTag: $accountTag }) {
                            httpRequests1dGroups(limit: 1, filter: { date: $date }) {
                                sum {
                                    requests
                                    pageViews
                                    bytes
                                    encryptedRequests
                                    encryptedBytes
                                    cachedRequests
                                    cachedBytes
                                    threats
                                    browserMap {
                                        pageViews
                                        uaBrowserFamily
                                    }
                                    responseStatusMap {
                                        requests
                                        edgeResponseStatus
                                    }
                                    clientHTTPVersionMap {
                                        requests
                                        clientHTTPProtocol
                                    }
                                }
                            }
                        }
                    }
                }
            `,
			variables: {
				accountTag: env.CF_ACCOUNT_ID,
				date: dateString,
			},
		}),
	});

	const data = await response.json();
	if (data.errors) {
		throw new Error(`GraphQL Error: ${JSON.stringify(data.errors)}`);
	}

	return { data, formattedDate };
}
```

In the code above, the `fetchAnalytics` function fetches analytics data from Cloudflare's GraphQL Analytics API. The `fetchAnalytics` function calculates yesterday's date, formats the date for display, and sends a GraphQL query to the Analytics API to fetch the analytics data.

:::note
`env.CF_API_TOKEN` and `env.CF_ACCOUNT_ID` are [Worker Secrets](/workers/configuration/secrets/). These variables are used to authenticate the request and fetch the analytics data for the specified account. You will add these secrets to your Worker after the code is complete.
:::

This function returns the **raw** data for the previous day, including:

- Traffic overview data (Total requests, Page views and Blocked threats)
- Bandwidth data (Total bandwidth, Encrypted bandwidth and Cached bandwidth)
- Caching and Encryption data (Encrypted requests, Cached requests, Encryption rate and Cache rate)
- Browser data (Page views by browser)
- HTTP status code data (Requests by status code)
- HTTP version data (Requests by HTTP version)

This data will be used to generate the analytics report. In the following step, you will add the function that formats this data.

### Add the data formatting function

Add the following function to the `src/index.js` file, below the `fetchAnalytics` function:

```js
function formatContent(analyticsData, formattedDate) {
	const stats =
		analyticsData.data.viewer.accounts[0].httpRequests1dGroups[0].sum;

	// Helper function to format bytes into human-readable format
	const formatBytes = (bytes) => {
		if (bytes === 0) return "0 Bytes";
		const k = 1024;
		const sizes = ["Bytes", "KB", "MB", "GB", "TB"];
		const i = Math.floor(Math.log(bytes) / Math.log(k));
		return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
	};

	// Format browser statistics
	const browserData = stats.browserMap
		.sort((a, b) => b.pageViews - a.pageViews)
		.map((b) => `    ${b.uaBrowserFamily}: ${b.pageViews} views`)
		.join("\n");

	// Format HTTP status code statistics
	const statusData = stats.responseStatusMap
		.sort((a, b) => b.requests - a.requests)
		.map((s) => `    ${s.edgeResponseStatus}: ${s.requests} requests`)
		.join("\n");

	// Format HTTP version statistics
	const httpVersionData = stats.clientHTTPVersionMap
		.sort((a, b) => b.requests - a.requests)
		.map((h) => `    ${h.clientHTTPProtocol}: ${h.requests} requests`)
		.join("\n");

	// Return formatted report
	return `
CLOUDFLARE ANALYTICS REPORT
==========================
Generated for: ${formattedDate}

TRAFFIC OVERVIEW
---------------
    Total Requests: ${stats.requests.toLocaleString()}
    Page Views: ${stats.pageViews.toLocaleString()}
    Security Threats Blocked: ${stats.threats.toLocaleString()}

BANDWIDTH
---------
    Total Bandwidth: ${formatBytes(stats.bytes)}
    Encrypted Bandwidth: ${formatBytes(stats.encryptedBytes)}
    Cached Bandwidth: ${formatBytes(stats.cachedBytes)}

CACHING & ENCRYPTION
-------------------
    Total Requests: ${stats.requests.toLocaleString()}
    Encrypted Requests: ${stats.encryptedRequests.toLocaleString()}
    Cached Requests: ${stats.cachedRequests.toLocaleString()}
    Encryption Rate: ${((stats.encryptedRequests / stats.requests) * 100).toFixed(1)}%
    Cache Rate: ${((stats.cachedRequests / stats.requests) * 100).toFixed(1)}%

BROWSERS
--------
${browserData}

HTTP STATUS CODES
---------------
${statusData}

HTTP VERSIONS
------------
${httpVersionData}
`;
}
```

At this point, you have defined the `fetchAnalytics` function that fetches raw analytics data from Cloudflare's GraphQL Analytics API and the `formatContent` function that formats the analytics data into a human-readable report.

### Add the email sending function

Add the following function to the `src/index.js` file, below the `formatContent` function:

```js
async function sendEmail(env, content) {
	// Create and configure email message
	const msg = createMimeMessage();

	msg.setSender({
		name: env.SENDER_NAME,
		addr: env.SENDER_EMAIL,
	});

	msg.setRecipient(env.RECIPIENT_EMAIL);
	msg.setSubject(env.EMAIL_SUBJECT);

	msg.addMessage({
		contentType: "text/plain",
		data: content,
	});

	// Send email using Cloudflare Email Routing service
	const message = new EmailMessage(
		env.SENDER_EMAIL,
		env.RECIPIENT_EMAIL,
		msg.asRaw(),
	);

	try {
		await env.ANALYTICS_EMAIL.send(message);
	} catch (error) {
		throw new Error(`Failed to send email: ${error.message}`);
	}
}
```

This function sends an email with the formatted analytics data to the specified recipient email address using Cloudflare's Email Routing service.

:::note
`sendEmail` function uses multiple environment variables that are set in the Wrangler file.
:::

## 4. Test the Worker

Now that you have updated the Worker code, you can test it locally using the `wrangler dev` command. This command starts a local server that runs your Worker code.

Before you run the Worker, you need to add two Worker secrets:

- `CF_API_TOKEN`: Cloudflare GraphQL Analytics API token you created earlier.
- `CF_ACCOUNT_ID`: Your Cloudflare account ID. You can find your account ID in the Cloudflare dashboard under the **Workers & Pages** Overview tab.

Create a `.dev.vars` file in the root of your project directory and add the following:

```sh
CF_API_TOKEN=YOUR_CLOUDFLARE_API_TOKEN
CF_ACCOUNT_ID=YOUR_CLOUDFLARE_ACCOUNT_ID
```

Now, run the Worker locally:

```sh
npx wrangler dev --remote
```

Open the `http://localhost:8787` URL on your browser. The browser will display analytics data.

## 5. Deploy the Worker and Worker secrets

Once you have tested the Worker locally, you can deploy your Worker to Cloudflare's edge network:

```sh
npx wrangler deploy
```

CLI command will output the URL where your Worker is deployed. Before you can use this URL in your browser to view the analytics data, you need to add two Worker secrets you already have locally to your deployed Worker:

```sh
npx wrangler secret put <secret>
```

Replace `<secret>` with the name of the secret you want to add. Repeat this command for `CF_API_TOKEN` and `CF_ACCOUNT_ID` secrets.

Once you put the secrets, preview your analytics data at `account-analytics.<YOUR_SUBDOMAIN>.workers.dev`. You will also receive an email report to the specified recipient email address every day at 10:00 AM.

If you want to disable a public URL for your Worker, you can do so by following these steps:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com).

2. In Account Home, select **Workers & Pages**, then select `account-analytics` Worker.

3. Go to **Settings** > **Domains & Routes**.

4. Select **Disable** to disable the public `account-analytics.<YOUR_SUBDOMAIN>.workers.dev` URL.

You have successfully created, tested and deployed a Worker that fetches analytics data from Cloudflare's GraphQL Analytics API and sends an email report via Email Routing.

## Related resources

To build more with Workers, refer to [Tutorials](/workers/tutorials/).

If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on [Discord](https://discord.cloudflare.com) to connect with other developers and the Cloudflare team.

---

# Build a todo list Jamstack application

URL: https://developers.cloudflare.com/workers/tutorials/build-a-jamstack-app/

import { Render, PackageManagers, WranglerConfig } from "~/components";

In this tutorial, you will build a todo list application using HTML, CSS, and JavaScript. The application data will be stored in [Workers KV](/kv/api/).

![Preview of a finished todo list. Continue reading for instructions on how to set up a todo list.](~/assets/images/workers/tutorials/jamstack/finished.png)

Before starting this project, you should have some experience with HTML, CSS, and JavaScript. You will learn:

1. How building with Workers makes allows you to focus on writing code and ship finished products.
2. How the addition of Workers KV makes this tutorial a great introduction to building full, data-driven applications.

If you would like to see the finished code for this project, find the [project on GitHub](https://github.com/lauragift21/cloudflare-workers-todos) and refer to the [live demo](https://todos.examples.workers.dev/) to review what you will be building.

<Render file="tutorials-before-you-start" />

## 1. Create a new Workers project

First, use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI tool to create a new Cloudflare Workers project named `todos`. In this tutorial, you will use the default `Hello World` template to create a Workers project.

<PackageManagers type="create" pkg="cloudflare@latest" args={"todos"} />

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Move into your newly created directory:

```sh
cd todos
```

Inside of your new `todos` Worker project directory, `index.js` represents the entry point to your Cloudflare Workers application.

All incoming HTTP requests to a Worker are passed to the [`fetch()` handler](/workers/runtime-apis/handlers/fetch/) as a [request](/workers/runtime-apis/request/) object. After a request is received by the Worker, the response your application constructs will be returned to the user. This tutorial will guide you through understanding how the request/response pattern works and how you can use it to build fully featured applications.

```js
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello World!");
	},
};
```

In your default `index.js` file, you can see that request/response pattern in action. The `fetch` constructs a new `Response` with the body text `'Hello World!'`.

When a Worker receives a `request`, the Worker returns the newly constructed response to the client. Your Worker will serve new responses directly from [Cloudflare's global network](https://www.cloudflare.com/network) instead of continuing to your origin server. A standard server would accept requests and return responses. Cloudflare Workers allows you to respond by constructing responses directly on the Cloudflare global network.

## 2. Review project details

Any project you deploy to Cloudflare Workers can make use of modern JavaScript tooling like [ES modules](/workers/reference/migrate-to-module-workers/), `npm` packages, and [`async`/`await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) functions to build your application. In addition to writing Workers, you can use Workers to [build full applications](/workers/tutorials/build-a-slackbot/) using the same tooling and process as in this tutorial.

In this tutorial, you will build a todo list application running on Workers that allows reading data from a [KV](/kv/) store and using the data to populate an HTML response to send to the client.

The work needed to create this application is split into three tasks:

1. Write data to KV.
2. Rendering data from KV.
3. Adding todos from the application UI.

For the remainder of this tutorial you will complete each task, iterating on your application, and then publish it to your own domain.

## 3. Write data to KV

To begin, you need to understand how to populate your todo list with actual data. To do this, use [Cloudflare Workers KV](/kv/) — a key-value store that you can access inside of your Worker to read and write data.

To get started with KV, set up a namespace. All of your cached data will be stored inside that namespace and, with configuration, you can access that namespace inside the Worker with a predefined variable. Use Wrangler to create a new namespace called `TODOS` with the [`kv namespace create` command](/workers/wrangler/commands/#kv-namespace-create) and get the associated namespace ID by running the following command in your terminal:

```sh title="Create a new KV namespace"
npx wrangler kv namespace create "TODOS" --preview
```

The associated namespace can be combined with a `--preview` flag to interact with a preview namespace instead of a production namespace. Namespaces can be added to your application by defining them inside your Wrangler configuration. Copy your newly created namespace ID, and in your [Wrangler configuration file](/workers/wrangler/configuration/), define a `kv_namespaces` key to set up your namespace:

<WranglerConfig>

```toml
kv_namespaces = [
  {binding = "TODOS", id = "<YOUR_ID>", preview_id = "<YOUR_PREVIEW_ID>"}
]
```

</WranglerConfig>

The defined namespace, `TODOS`, will now be available inside of your codebase. With that, it is time to understand the [KV API](/kv/api/). A KV namespace has three primary methods you can use to interface with your cache: `get`, `put`, and `delete`.

Start storing data by defining an initial set of data, which you will put inside of the cache using the `put` method. The following example defines a `defaultData` object instead of an array of todo items. You may want to store metadata and other information inside of this cache object later on. Given that data object, use `JSON.stringify` to add a string into the cache:

```js
export default {
	async fetch(request, env, ctx) {
		const defaultData = {
			todos: [
				{
					id: 1,
					name: "Finish the Cloudflare Workers blog post",
					completed: false,
				},
			],
		};
		await env.TODOS.put("data", JSON.stringify(defaultData));
		return new Response("Hello World!");
	},
};
```

Workers KV is an eventually consistent, global datastore. Any writes within a region are immediately reflected within that same region but will not be immediately available in other regions. However, those writes will eventually be available everywhere and, at that point, Workers KV guarantees that data within each region will be consistent.

Given the presence of data in the cache and the assumption that your cache is eventually consistent, this code needs a slight adjustment: the application should check the cache and use its value, if the key exists. If it does not, you will use `defaultData` as the data source for now (it should be set in the future) and write it to the cache for future use. After breaking out the code into a few functions for simplicity, the result looks like this:

```js
export default {
	async fetch(request, env, ctx) {
		const defaultData = {
			todos: [
				{
					id: 1,
					name: "Finish the Cloudflare Workers blog post",
					completed: false,
				},
			],
		};
		const setCache = (data) => env.TODOS.put("data", data);
		const getCache = () => env.TODOS.get("data");

		let data;

		const cache = await getCache();
		if (!cache) {
			await setCache(JSON.stringify(defaultData));
			data = defaultData;
		} else {
			data = JSON.parse(cache);
		}

		return new Response(JSON.stringify(data));
	},
};
```

## Render data from KV

Given the presence of data in your code, which is the cached data object for your application, you should take this data and render it in a user interface.

To do this, make a new `html` variable in your Workers script and use it to build up a static HTML template that you can serve to the client. In `fetch`, construct a new `Response` with a `Content-Type: text/html` header and serve it to the client:

```js
const html = `<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>Todos</title>
  </head>
  <body>
    <h1>Todos</h1>
  </body>
</html>
`;

async fetch (request, env, ctx) {
  // previous code
  return new Response(html, {
      headers: {
        'Content-Type': 'text/html'
      }
    });
}
```

You have a static HTML site being rendered and you can begin populating it with data. In the body, add a `div` tag with an `id` of `todos`:

```js null {10}
const html = `<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>Todos</title>
  </head>
  <body>
    <h1>Todos</h1>
    <div id="todos"></div>
  </body>
</html>
`;
```

Add a `<script>` element at the end of the body content that takes a `todos` array. For each `todo` in the array, create a `div` element and appends it to the `todos` HTML element:

```js null {12,13,14,15,16,17,18,19,20}
const html = `<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>Todos</title>
  </head>
  <body>
    <h1>Todos</h1>
    <div id="todos"></div>
  </body>
  <script>
    window.todos = []
    var todoContainer = document.querySelector("#todos")
    window.todos.forEach(todo => {
      var el = document.createElement("div")
      el.textContent = todo.name
      todoContainer.appendChild(el)
    })
  </script>
</html>
`;
```

Your static page can take in `window.todos` and render HTML based on it, but you have not actually passed in any data from KV. To do this, you will need to make a few changes.

First, your `html` variable will change to a function. The function will take in a `todos` argument, which will populate the `window.todos` variable in the above code sample:

```js null {1,6}
const html = (todos) => `
<!doctype html>
<html>
  <!-- existing content -->
  <script>
    window.todos = ${todos}
    var todoContainer = document.querySelector("#todos")
    // ...
  <script>
</html>
`;
```

In `fetch`, use the retrieved KV data to call the `html` function and generate a `Response` based on it:

```js null {2}
async fetch (request, env, ctx) {
  const body = html(JSON.stringify(data.todos).replace(/</g, '\\u003c'));
  return new Response(body, {
    headers: { 'Content-Type': 'text/html' },
  });
}
```

## 4. Add todos from the user interface (UI)

At this point, you have built a Cloudflare Worker that takes data from Cloudflare KV and renders a static page based on that Worker. That static page reads data and generates a todo list based on that data. The remaining task is creating todos from inside the application UI. You can add todos using the KV API — update the cache by running `env.TODOS.put(newData)`.

To update a todo item, you will add a second handler in your Workers script, designed to watch for `PUT` requests to `/`. When a request body is received at that URL, the Worker will send the new todo data to your KV store.

Add this new functionality in `fetch`: if the request method is a PUT, it will take the request body and update the cache.

```js null {5,6,7,8,9,10,11,12,13,14}
export default {
	async fetch(request, env, ctx) {
		const setCache = (data) => env.TODOS.put("data", data);

		if (request.method === "PUT") {
			const body = await request.text();
			try {
				JSON.parse(body);
				await setCache(body);
				return new Response(body, { status: 200 });
			} catch (err) {
				return new Response(err, { status: 500 });
			}
		}
		// previous code
	},
};
```

Check that the request is a `PUT` and wrap the remainder of the code in a `try/catch` block. First, parse the body of the request coming in, ensuring that it is JSON, before you update the cache with the new data and return it to the user. If anything goes wrong, return a `500` status code. If the route is hit with an HTTP method other than `PUT` — for example, `POST` or `DELETE` — return a `404` error.

With this script, you can now add some dynamic functionality to your HTML page to actually hit this route. First, create an input for your todo name and a button for submitting the todo.

```js null {5,6,7,8}
const html = (todos) => `
<!doctype html>
<html>
  <!-- existing content -->
  <div>
    <input type="text" name="name" placeholder="A new todo"></input>
    <button id="create">Create</button>
  </div>
  <!-- existing script -->
</html>
`;
```

Given that input and button, add a corresponding JavaScript function to watch for clicks on the button — once the button is clicked, the browser will `PUT` to `/` and submit the todo.

```js null {8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23}
const html = (todos) => `
<!doctype html>
<html>
  <!-- existing content -->
  <script>
    // Existing JavaScript code

    var createTodo = function() {
      var input = document.querySelector("input[name=name]")
      if (input.value.length) {
        todos = [].concat(todos, {
          id: todos.length + 1,
          name: input.value,
          completed: false,
        })
        fetch("/", {
          method: "PUT",
          body: JSON.stringify({ todos: todos }),
        })
      }
    }

    document.querySelector("#create").addEventListener("click", createTodo)
  </script>
</html>
`;
```

This code updates the cache. Remember that the KV cache is eventually consistent — even if you were to update your Worker to read from the cache and return it, you have no guarantees it will actually be up to date. Instead, update the list of todos locally, by taking your original code for rendering the todo list, making it a reusable function called `populateTodos`, and calling it when the page loads and when the cache request has finished:

```js null {6,7,8,9,10,11,12,13,14,15,16}
const html = (todos) => `
<!doctype html>
<html>
  <!-- existing content -->
  <script>
    var populateTodos = function() {
      var todoContainer = document.querySelector("#todos")
      todoContainer.innerHTML = null
      window.todos.forEach(todo => {
        var el = document.createElement("div")
        el.textContent = todo.name
        todoContainer.appendChild(el)
      })
    }

    populateTodos()

    var createTodo = function() {
      var input = document.querySelector("input[name=name]")
      if (input.value.length) {
        todos = [].concat(todos, {
          id: todos.length + 1,
          name: input.value,
          completed: false,
        })
        fetch("/", {
          method: "PUT",
          body: JSON.stringify({ todos: todos }),
        })
        populateTodos()
        input.value = ""
      }
    }

    document.querySelector("#create").addEventListener("click", createTodo)
  </script>
`;
```

With the client-side code in place, deploying the new version of the function should put all these pieces together. The result is an actual dynamic todo list.

## 5. Update todos from the application UI

For the final piece of your todo list, you need to be able to update todos — specifically, marking them as completed.

Luckily, a great deal of the infrastructure for this work is already in place. You can update the todo list data in the cache, as evidenced by your `createTodo` function. Performing updates on a todo is more of a client-side task than a Worker-side one.

To start, the `populateTodos` function can be updated to generate a `div` for each todo. In addition, move the name of the todo into a child element of that `div`:

```js null {11,12,13}
const html = (todos) => `
<!doctype html>
<html>
  <!-- existing content -->
  <script>
    var populateTodos = function() {
      var todoContainer = document.querySelector("#todos")
      todoContainer.innerHTML = null
      window.todos.forEach(todo => {
        var el = document.createElement("div")
        var name = document.createElement("span")
        name.textContent = todo.name
        el.appendChild(name)
        todoContainer.appendChild(el)
      })
    }
  </script>
`;
```

You have designed the client-side part of this code to handle an array of todos and render a list of HTML elements. There is a number of things that you have been doing that you have not quite had a use for yet – specifically, the inclusion of IDs and updating the todo's completed state. These things work well together to actually support updating todos in the application UI.

To start, it would be useful to attach the ID of each todo in the HTML. By doing this, you can then refer to the element later in order to correspond it to the todo in the JavaScript part of your code. Data attributes and the corresponding `dataset` method in JavaScript are a perfect way to implement this. When you generate your `div` element for each todo, you can attach a data attribute called todo to each `div`:

```js null {11}
const html = (todos) => `
<!doctype html>
<html>
  <!-- existing content -->
  <script>
    var populateTodos = function() {
      var todoContainer = document.querySelector("#todos")
      todoContainer.innerHTML = null
      window.todos.forEach(todo => {
        var el = document.createElement("div")
        el.dataset.todo = todo.id

        var name = document.createElement("span")
        name.textContent = todo.name

        el.appendChild(name)
        todoContainer.appendChild(el)
      })
    }
  </script>
`;
```

Inside your HTML, each `div` for a todo now has an attached data attribute, which looks like:

```html
<div data-todo="1"></div>
<div data-todo="2"></div>
```

You can now generate a checkbox for each todo element. This checkbox will default to unchecked for new todos but you can mark it as checked as the element is rendered in the window:

```js null {13,14,15,17}
const html = (todos) => `
<!doctype html>
<html>
  <!-- existing content -->
  <script>
    window.todos.forEach(todo => {
      var el = document.createElement("div")
      el.dataset.todo = todo.id

      var name = document.createElement("span")
      name.textContent = todo.name

      var checkbox = document.createElement("input")
      checkbox.type = "checkbox"
      checkbox.checked = todo.completed ? 1 : 0

      el.appendChild(checkbox)
      el.appendChild(name)
      todoContainer.appendChild(el)
    })
  </script>
`;
```

The checkbox is set up to correctly reflect the value of completed on each todo but it does not yet update when you actually check the box. To do this, attach the `completeTodo` function as an event listener on the `click` event. Inside the function, inspect the checkbox element, find its parent (the todo `div`), and use its `todo` data attribute to find the corresponding todo in the data array. You can toggle the completed status, update its properties, and rerender the UI:

```js null {9,13,14,15,16,17,18,19,20,21,22}
const html = (todos) => `
<!doctype html>
<html>
  <!-- existing content -->
  <script>
    var populateTodos = function() {
      window.todos.forEach(todo => {
        // Existing todo element set up code
        checkbox.addEventListener("click", completeTodo)
      })
    }

    var completeTodo = function(evt) {
      var checkbox = evt.target
      var todoElement = checkbox.parentNode

      var newTodoSet = [].concat(window.todos)
      var todo = newTodoSet.find(t => t.id == todoElement.dataset.todo)
      todo.completed = !todo.completed
      todos = newTodoSet
      updateTodos()
    }
  </script>
`;
```

The final result of your code is a system that checks the `todos` variable, updates your Cloudflare KV cache with that value, and then does a re-render of the UI based on the data it has locally.

## 6. Conclusion and next steps

By completing this tutorial, you have built a static HTML, CSS, and JavaScript application that is transparently powered by Workers and Workers KV, which take full advantage of Cloudflare's global network.

If you would like to keep improving on your project, you can implement a better design (you can refer to a live version available at [todos.signalnerve.workers.dev](https://todos.signalnerve.workers.dev/)), or make additional improvements to security and speed.

You may also want to add user-specific caching. Right now, the cache key is always `data` – this means that any visitor to the site will share the same todo list with other visitors. Within your Worker, you could use values from the client request to create and maintain user-specific lists. For example, you may generate a cache key based on the requesting IP:

```js null {15,16,22,33}
export default {
	async fetch(request, env, ctx) {
		const defaultData = {
			todos: [
				{
					id: 1,
					name: "Finish the Cloudflare Workers blog post",
					completed: false,
				},
			],
		};
		const setCache = (key, data) => env.TODOS.put(key, data);
		const getCache = (key) => env.TODOS.get(key);

		const ip = request.headers.get("CF-Connecting-IP");
		const myKey = `data-${ip}`;

		if (request.method === "PUT") {
			const body = await request.text();
			try {
				JSON.parse(body);
				await setCache(myKey, body);
				return new Response(body, { status: 200 });
			} catch (err) {
				return new Response(err, { status: 500 });
			}
		}

		let data;

		const cache = await getCache();
		if (!cache) {
			await setCache(myKey, JSON.stringify(defaultData));
			data = defaultData;
		} else {
			data = JSON.parse(cache);
		}

		const body = html(JSON.stringify(data.todos).replace(/</g, "\\u003c"));

		return new Response(body, {
			headers: {
				"Content-Type": "text/html",
			},
		});
	},
};
```

After making these changes and deploying the Worker one more time, your todo list application now includes per-user functionality while still taking full advantage of Cloudflare's global network.

The final version of your Worker script should look like this:

```js
const html = (todos) => `
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>Todos</title>
    <link href="https://cdn.jsdelivr.net/npm/tailwindcss/dist/tailwind.min.css" rel="stylesheet"></link>
  </head>

  <body class="bg-blue-100">
    <div class="w-full h-full flex content-center justify-center mt-8">
      <div class="bg-white shadow-md rounded px-8 pt-6 py-8 mb-4">
        <h1 class="block text-grey-800 text-md font-bold mb-2">Todos</h1>
        <div class="flex">
          <input class="shadow appearance-none border rounded w-full py-2 px-3 text-grey-800 leading-tight focus:outline-none focus:shadow-outline" type="text" name="name" placeholder="A new todo"></input>
          <button class="bg-blue-500 hover:bg-blue-800 text-white font-bold ml-2 py-2 px-4 rounded focus:outline-none focus:shadow-outline" id="create" type="submit">Create</button>
        </div>
        <div class="mt-4" id="todos"></div>
      </div>
    </div>
  </body>

  <script>
    window.todos = ${todos}

    var updateTodos = function() {
      fetch("/", { method: "PUT", body: JSON.stringify({ todos: window.todos }) })
      populateTodos()
    }

    var completeTodo = function(evt) {
      var checkbox = evt.target
      var todoElement = checkbox.parentNode
      var newTodoSet = [].concat(window.todos)
      var todo = newTodoSet.find(t => t.id == todoElement.dataset.todo)
      todo.completed = !todo.completed
      window.todos = newTodoSet
      updateTodos()
    }

    var populateTodos = function() {
      var todoContainer = document.querySelector("#todos")
      todoContainer.innerHTML = null

      window.todos.forEach(todo => {
        var el = document.createElement("div")
        el.className = "border-t py-4"
        el.dataset.todo = todo.id

        var name = document.createElement("span")
        name.className = todo.completed ? "line-through" : ""
        name.textContent = todo.name

        var checkbox = document.createElement("input")
        checkbox.className = "mx-4"
        checkbox.type = "checkbox"
        checkbox.checked = todo.completed ? 1 : 0
        checkbox.addEventListener("click", completeTodo)

        el.appendChild(checkbox)
        el.appendChild(name)
        todoContainer.appendChild(el)
      })
    }

    populateTodos()

    var createTodo = function() {
      var input = document.querySelector("input[name=name]")
      if (input.value.length) {
        window.todos = [].concat(todos, { id: window.todos.length + 1, name: input.value, completed: false })
        input.value = ""
        updateTodos()
      }
    }

    document.querySelector("#create").addEventListener("click", createTodo)
  </script>
</html>
`;

export default {
	async fetch(request, env, ctx) {
		const defaultData = {
			todos: [
				{
					id: 1,
					name: "Finish the Cloudflare Workers blog post",
					completed: false,
				},
			],
		};
		const setCache = (key, data) => env.TODOS.put(key, data);
		const getCache = (key) => env.TODOS.get(key);

		const ip = request.headers.get("CF-Connecting-IP");
		const myKey = `data-${ip}`;

		if (request.method === "PUT") {
			const body = await request.text();
			try {
				JSON.parse(body);
				await setCache(myKey, body);
				return new Response(body, { status: 200 });
			} catch (err) {
				return new Response(err, { status: 500 });
			}
		}

		let data;

		const cache = await getCache();
		if (!cache) {
			await setCache(myKey, JSON.stringify(defaultData));
			data = defaultData;
		} else {
			data = JSON.parse(cache);
		}

		const body = html(JSON.stringify(data.todos).replace(/</g, "\\u003c"));

		return new Response(body, {
			headers: {
				"Content-Type": "text/html",
			},
		});
	},
};
```

You can find the source code for this project, as well as a README with deployment instructions, [on GitHub](https://github.com/lauragift21/cloudflare-workers-todos).

---

# Build a QR code generator

URL: https://developers.cloudflare.com/workers/tutorials/build-a-qr-code-generator/

import { Render, PackageManagers } from "~/components";

In this tutorial, you will build and publish a Worker application that generates QR codes.

If you would like to review the code for this tutorial, the final version of the codebase is [available on GitHub](https://github.com/kristianfreeman/workers-qr-code-generator). You can take the code provided in the example repository, customize it, and deploy it for use in your own projects.

<Render file="tutorials-before-you-start" />

## 1. Create a new Workers project

First, use the [`create-cloudflare` CLI](/pages/get-started/c3) to create a new Cloudflare Workers project. To do this, open a terminal window and run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"qr-code-generator"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Then, move into your newly created directory:

```sh
cd qr-code-generator
```

Inside of your new `qr-code-generator` Worker project directory, `index.js` represents the entry point to your Cloudflare Workers application.

All Cloudflare Workers applications start by listening for `fetch` events, which are triggered when a client makes a request to a Workers route. After a request is received by the Worker, the response your application constructs will be returned to the user. This tutorial will guide you through understanding how the request/response pattern works and how you can use it to build fully featured applications.

```js
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello Worker!");
	},
};
```

In your default `index.js` file, you can see that request/response pattern in action. The `fetch` constructs a new `Response` with the body text `'Hello Worker!'`.

When a Worker receives a `fetch` event, the Worker returns the newly constructed response to the client. Your Worker will serve new responses directly from [Cloudflare's global network](https://www.cloudflare.com/network) instead of continuing to your origin server. A standard server would accept requests and return responses. Cloudflare Workers allows you to respond quickly by constructing responses directly on the Cloudflare global network.

## 2. Handle Incoming Request

Any project you publish to Cloudflare Workers can make use of modern JavaScript tooling like ES modules, `npm` packages, and [`async`/`await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) functions to build your application. In addition to writing Workers, you can use Workers to [build full applications](/workers/tutorials/build-a-slackbot/) using the same tooling and process as in this tutorial.

The QR code generator you will build in this tutorial will be a Worker that runs on a single route and receives requests. Each request will contain a text message (a URL, for example), which the function will encode into a QR code. The function will then respond with the QR code in PNG image format.

At this point in the tutorial, your Worker function can receive requests and return a simple response with the text `"Hello Worker!"`. To handle data coming into your Worker, check if the incoming request is a `POST` request:

```js null {2,3,4}
export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
			return new Response("Hello Worker!");
		}
	},
};
```

Currently, if an incoming request is not a `POST`, the function will return `undefined`. However, a Worker always needs to return a `Response`. Since the function should only accept incoming `POST` requests, return a new `Response` with a [`405` status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/405) if the incoming request is not a `POST`:

```js null {7,8}
export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
			return new Response("Hello Worker!");
		}

		return new Response("Expected POST request", {
			status: 405,
		});
	},
};
```

You have established the basic flow of the request. You will now set up a response to incoming valid requests. If a `POST` request comes in, the function should generate a QR code. To start, move the `"Hello Worker!"` response into a new function, `generateQRCode`, which will ultimately contain the bulk of your function’s logic:

```js null {7,8,9,10}
export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
		}
	},
};

async function generateQRCode(request) {
	// TODO: Include QR code generation
	return new Response("Hello worker!");
}
```

With the `generateQRCode` function filled out, call it within `fetch` function and return its result directly to the client:

```js null {4}
export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
			return generateQRCode(request);
		}
	},
};
```

## 3. Build a QR code generator

All projects deployed to Cloudflare Workers support npm packages. This support makes it easy to rapidly build out functionality in your Workers. The ['qrcode-svg'](https://github.com/papnkukn/qrcode-svg) package is a great way to take text and encode it into a QR code. In the command line, install and save 'qrcode-svg' to your project’s 'package.json':

<PackageManagers pkg="qrcode-svg" />

In `index.js`, import the `qrcode-svg` package as the variable `QRCode`. In the `generateQRCode` function, parse the incoming request as JSON using `request.json`, and generate a new QR code using the `qrcode-svg` package. The QR code is generated as an SVG. Construct a new instance of `Response`, passing in the SVG data as the body, and a `Content-Type` header of `image/svg+xml`. This will allow browsers to properly parse the data coming back from your Worker as an image:

```js null {1,2,3,4,5,6}
import QRCode from "qrcode-svg";

async function generateQRCode(request) {
	const { text } = await request.json();
	const qr = new QRCode({ content: text || "https://workers.dev" });
	return new Response(qr.svg(), {
		headers: { "Content-Type": "image/svg+xml" },
	});
}
```

## 4. Test in an application UI

The Worker will execute when a user sends a `POST` request to a route, but it is best practice to also provide a proper interface for testing the function. At this point in the tutorial, if any request is received by your function that is not a `POST`, a `405` response is returned. The new version of `fetch` should return a new `Response` with a static HTML document instead of the `405` error:

```js null {23-54}
export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
			return generateQRCode(request);
		}

		return new Response(landing, {
			headers: {
				"Content-Type": "text/html",
			},
		});
	},
};

async function generateQRCode(request) {
	const { text } = await request.json();
	const qr = new QRCode({ content: text || "https://workers.dev" });
	return new Response(qr.svg(), {
		headers: { "Content-Type": "image/svg+xml" },
	});
}

const landing = `
<h1>QR Generator</h1>
<p>Click the below button to generate a new QR code. This will make a request to your Worker.</p>
<input type="text" id="text" value="https://workers.dev"></input>
<button onclick="generate()">Generate QR Code</button>
<p>Generated QR Code Image</p>
<img id="qr" src="#" />
<script>
	function generate() {
		fetch(window.location.pathname, {
			method: "POST",
			headers: { "Content-Type": "application/json" },
			body: JSON.stringify({ text: document.querySelector("#text").value })
		})
		.then(response => response.blob())
		.then(blob => {
			const reader = new FileReader();
			reader.onloadend = function () {
				document.querySelector("#qr").src = reader.result; // Update the image source with the newly generated QR code
			}
			reader.readAsDataURL(blob);
		})
	}
</script>
`;
```

The `landing` variable, which is a static HTML string, sets up an `input` tag and a corresponding `button`, which calls the `generateQRCode` function. This function will make an HTTP `POST` request back to your Worker, allowing you to see the corresponding QR code image returned on the page.

With the above steps complete, your Worker is ready. The full version of the code looks like this:

```js
const QRCode = require("qrcode-svg");

export default {
	async fetch(request, env, ctx) {
		if (request.method === "POST") {
			return generateQRCode(request);
		}

		return new Response(landing, {
			headers: {
				"Content-Type": "text/html",
			},
		});
	},
};

async function generateQRCode(request) {
	const { text } = await request.json();
	const qr = new QRCode({ content: text || "https://workers.dev" });
	return new Response(qr.svg(), {
		headers: { "Content-Type": "image/svg+xml" },
	});
}

const landing = `
<h1>QR Generator</h1>
<p>Click the below button to generate a new QR code. This will make a request to your Worker.</p>
<input type="text" id="text" value="https://workers.dev"></input>
<button onclick="generate()">Generate QR Code</button>
<p>Generated QR Code Image</p>
<img id="qr" src="#" />
<script>
	function generate() {
		fetch(window.location.pathname, {
			method: "POST",
			headers: { "Content-Type": "application/json" },
			body: JSON.stringify({ text: document.querySelector("#text").value })
		})
		.then(response => response.blob())
		.then(blob => {
			const reader = new FileReader();
			reader.onloadend = function () {
				document.querySelector("#qr").src = reader.result; // Update the image source with the newly generated QR code
			}
			reader.readAsDataURL(blob);
		})
	}
</script>
`;
```

## 5. Deploy your Worker

With all the above steps complete, you have written the code for a QR code generator on Cloudflare Workers.

Wrangler has built-in support for bundling, uploading, and releasing your Cloudflare Workers application. To do this, run `npx wrangler deploy`, which will build and deploy your code.

```sh title="Deploy your Worker project"
npx wrangler deploy
```

## Related resources

In this tutorial, you built and deployed a Worker application for generating QR codes. If you would like to see the full source code for this application, you can find it [on GitHub](https://github.com/kristianfreeman/workers-qr-code-generator).

If you want to get started building your own projects, review the existing list of [Quickstart templates](/workers/get-started/quickstarts/).

---

# Build a Slackbot

URL: https://developers.cloudflare.com/workers/tutorials/build-a-slackbot/

import { Render, TabItem, Tabs, PackageManagers } from "~/components";

In this tutorial, you will build a [Slack](https://slack.com) bot using [Cloudflare Workers](/workers/). Your bot will make use of GitHub webhooks to send messages to a Slack channel when issues are updated or created, and allow users to write a command to look up GitHub issues from inside Slack.

![After following this tutorial, you will be able to create a Slackbot like the one in this example. Continue reading to build your Slackbot.](~/assets/images/workers/tutorials/slackbot/issue-command.png)

This tutorial is recommended for people who are familiar with writing web applications. You will use TypeScript as the programming language and [Hono](https://hono.dev/) as the web framework. If you have built an application with tools like [Node](https://nodejs.org) and [Express](https://expressjs.com), this project will feel very familiar to you. If you are new to writing web applications or have wanted to build something like a Slack bot in the past, but were intimidated by deployment or configuration, Workers will be a way for you to focus on writing code and shipping projects.

If you would like to review the code or how the bot works in an actual Slack channel before proceeding with this tutorial, you can access the final version of the codebase [on GitHub](https://github.com/yusukebe/workers-slack-bot). From GitHub, you can add your own Slack API keys and deploy it to your own Slack channels for testing.

---

<Render file="tutorials-before-you-start" />

## Set up Slack

This tutorial assumes that you already have a Slack account, and the ability to create and manage Slack applications.

### Configure a Slack application

To post messages from your Cloudflare Worker into a Slack channel, you will need to create an application in Slack’s UI. To do this, go to Slack’s API section, at [api.slack.com/apps](https://api.slack.com/apps), and select **Create New App**.

![To create a Slackbot, first create a Slack App](~/assets/images/workers/tutorials/slackbot/create-a-slack-app.png)

Slack applications have many features. You will make use of two of them, Incoming Webhooks and Slash Commands, to build your Worker-powered Slack bot.

#### Incoming Webhook

Incoming Webhooks are URLs that you can use to send messages to your Slack channels. Your incoming webhook will be paired with GitHub’s webhook support to send messages to a Slack channel whenever there are updates to issues in a given repository. You will see the code in more detail as you build your application. First, create a Slack webhook:

1. On the sidebar of Slack's UI, select **Incoming Webhooks**.
2. In **Webhook URLs for your Workspace**, select **Add New Webhook to Workspace**.
3. On the following screen, select the channel that you want your webhook to send messages to (you can select a room, like #general or #code, or be messaged directly by your Slack bot when the webhook is called.)
4. Authorize the new webhook URL.

After authorizing your webhook URL, you will be returned to the **Incoming Webhooks** page and can view your new webhook URL. You will add this into your Workers code later. Next, you will add the second component to your Slack bot: a Slash Command.

![Select Add New Webhook to Workspace to add a new Webhook URL in Slack's dashboard](~/assets/images/workers/tutorials/slackbot/slack-incoming-webhook.png)

#### Slash Command

A Slash Command in Slack is a custom-configured command that can be attached to a URL request. For example, if you configured `/weather <zip>`, Slack would make an HTTP POST request to a configured URL, passing the text `<zip>` to get the weather for a specified zip code. In your application, you will use the `/issue` command to look up GitHub issues using the [GitHub API](https://developer.github.com). Typing `/issue cloudflare/wrangler#1` will send the text `cloudflare/wrangler#1` in a HTTP POST request to your application, which the application will use to find the [relevant GitHub issue](https://github.com/cloudflare/wrangler-legacy/issues/1).

1. On the Slack sidebar, select **Slash Commands**.
2. Create your first slash command.

For this tutorial, you will use the command `/issue`. The request URL should be the `/lookup` path on your application URL: for example, if your application will be hosted at `https://myworkerurl.com`, the Request URL should be `https://myworkerurl.com/lookup`.

![You must create a Slash Command in Slack's dashboard and attach it to a Request URL](~/assets/images/workers/tutorials/slackbot/create-slack-command.png)

### Configure your GitHub Webhooks

Your Cloudflare Workers application will be able to handle incoming requests from Slack. It should also be able to receive events directly from GitHub. If a GitHub issue is created or updated, you can make use of GitHub webhooks to send that event to your Workers application and post a corresponding message in Slack.

To configure a webhook:

1. Go to your GitHub repository's **Settings** > **Webhooks** > **Add webhook**.

If you have a repository like `https://github.com/user/repo`, you can access the **Webhooks** page directly at `https://github.com/user/repo/settings/hooks`.

2. Set the Payload URL to the `/webhook` path on your Worker URL.

For example, if your Worker will be hosted at `https://myworkerurl.com`, the Payload URL should be `https://myworkerurl.com/webhook`.

3. In the **Content type** dropdown, select **application/json**.

The **Content type** for your payload can either be a URL-encoded payload (`application/x-www-form-urlencoded`) or JSON (`application/json`). For the purpose of this tutorial and to make parsing the payload sent to your application, select JSON.

4. In **Which events would you like to trigger this webhook?**, select **Let me select individual events**.

GitHub webhooks allow you to specify which events you would like to have sent to your webhook. By default, the webhook will send `push` events from your repository. For the purpose of this tutorial, you will choose **Let me select individual events**.

5. Select the **Issues** event type.

There are many different event types that can be enabled for your webhook. Selecting **Issues** will send every issue-related event to your webhook, including when issues are opened, edited, deleted, and more. If you would like to expand your Slack bot application in the future, you can select more of these events after the tutorial.

6. Select **Add webhook**.

![Create a GitHub Webhook in the GitHub dashboard](~/assets/images/workers/tutorials/slackbot/new-github-webhook.png)

When your webhook is created, it will attempt to send a test payload to your application. Since your application is not actually deployed yet, leave the configuration as it is. You will later return to your repository to create, edit, and close some issues to ensure that the webhook is working once your application is deployed.

## Init

To initiate the project, use the command line interface [C3 (create-cloudflare-cli)](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare).

<PackageManagers type="create" pkg="cloudflare@latest" args={"slack-bot"} />

Follow these steps to create a Hono project.

- For _What would you like to start with_?, select `Framework Starter`.
- For _Which development framework do you want to use?_, select `Hono`.
- For, _Do you want to deploy your application?_, select `No`.

Go to the `slack-bot` directory:

```sh
cd slack-bot
```

Open `src/index.ts` in an editor to find the following code.

```ts
import { Hono } from "hono";

type Bindings = {
	[key in keyof CloudflareBindings]: CloudflareBindings[key];
};

const app = new Hono<{ Bindings: Bindings }>();

app.get("/", (c) => {
	return c.text("Hello Hono!");
});

export default app;
```

This is a minimal application using Hono. If a GET access comes in on the path `/`, it will return a response with the text `Hello Hono!`. It also returns a message `404 Not Found` with status code 404 if any other path or method is accessed.

To run the application on your local machine, execute the following command.

<PackageManagers exec="run" args="dev" />

Access to `http://localhost:8787` in your browser after the server has been started, and you can see the message.

Hono helps you to create your Workers application easily and quickly.

## Build

Now, let's create a Slack bot on Cloudflare Workers.

### Separating files

You can create your application in several files instead of writing all endpoints and functions in one file. With Hono, it is able to add routing of child applications to the parent application using the function `app.route()`.

For example, imagine the following Web API application.

```ts
import { Hono } from "hono";

const app = new Hono();

app.get("/posts", (c) => c.text("Posts!"));
app.post("/posts", (c) => c.text("Created!", 201));

export default app;
```

You can add the routes under `/api/v1`.

```ts null {2,6}
import { Hono } from "hono";
import api from "./api";

const app = new Hono();

app.route("/api/v1", api);

export default app;
```

It will return `Posts!` when accessing `GET /api/v1/posts`.

The Slack bot will have two child applications called "route" each.

1. `lookup` route will take requests from Slack (sent when a user uses the `/issue` command), and look up the corresponding issue using the GitHub API. This application will be added to `/lookup` in the main application.

2. `webhook` route will be called when an issue changes on GitHub, via a configured webhook. This application will be add to `/webhook` in the main application.

Create the route files in a directory named `routes`.

```sh title="Create new folders and files"
mkdir -p src/routes
touch src/routes/lookup.ts
touch src/routes/webhook.ts
```

Then update the main application.

```ts null {2,3,7,8}
import { Hono } from "hono";
import lookup from "./routes/lookup";
import webhook from "./routes/webhook";

const app = new Hono();

app.route("/lookup", lookup);
app.route("/webhook", webhook);

export default app;
```

### Defining TypeScript types

Before implementing the actual functions, you need to define the TypeScript types you will use in this project. Create a new file in the application at `src/types.ts` and write the code. `Bindings` is a type that describes the Cloudflare Workers environment variables. `Issue` is a type for a GitHub issue and `User` is a type for a GitHub user. You will need these later.

```ts
export type Bindings = {
	SLACK_WEBHOOK_URL: string;
};

export type Issue = {
	html_url: string;
	title: string;
	body: string;
	state: string;
	created_at: string;
	number: number;
	user: User;
};

type User = {
	html_url: string;
	login: string;
	avatar_url: string;
};
```

### Creating the lookup route

Start creating the lookup route in `src/routes/lookup.ts`.

```ts
import { Hono } from "hono";

const app = new Hono();

export default app;
```

To understand how you should design this function, you need to understand how Slack slash commands send data to URLs.

According to the [documentation for Slack slash commands](https://api.slack.com/interactivity/slash-commands), Slack sends an HTTP POST request to your specified URL, with a `application/x-www-form-urlencoded` content type. For example, if someone were to type `/issue cloudflare/wrangler#1`, you could expect a data payload in the format:

```txt
token=gIkuvaNzQIHg97ATvDxqgjtO
&team_id=T0001
&team_domain=example
&enterprise_id=E0001
&enterprise_name=Globular%20Construct%20Inc
&channel_id=C2147483705
&channel_name=test
&user_id=U2147483697
&user_name=Steve
&command=/issue
&text=cloudflare/wrangler#1
&response_url=https://hooks.slack.com/commands/1234/5678
&trigger_id=13345224609.738474920.8088930838d88f008e0
```

Given this payload body, you need to parse it, and get the value of the `text` key. With that `text`, for example, `cloudflare/wrangler#1`, you can parse that string into known piece of data (`owner`, `repo`, and `issue_number`), and use it to make a request to GitHub’s API, to retrieve the issue data.

With Slack slash commands, you can respond to a slash command by returning structured data as the response to the incoming slash command. In this case, you should use the response from GitHub’s API to present a formatted version of the GitHub issue, including pieces of data like the title of the issue, who created it, and the date it was created. Slack’s new [Block Kit](https://api.slack.com/block-kit) framework will allow you to return a detailed message response, by constructing text and image blocks with the data from GitHub’s API.

#### Parsing slash commands

To begin, the `lookup` route should parse the messages coming from Slack. As previously mentioned, the Slack API sends an HTTP POST in URL Encoded format. You can get the variable `text` by parsing it with `c.req.json()`.

```ts null {5,6,7,8,9,10}
import { Hono } from "hono";

const app = new Hono();

app.post("/", async (c) => {
	const { text } = await c.req.parseBody();
	if (typeof text !== "string") {
		return c.notFound();
	}
});

export default app;
```

Given a `text` variable, that contains text like `cloudflare/wrangler#1`, you should parse that text, and get the individual parts from it for use with GitHub’s API: `owner`, `repo`, and `issue_number`.

To do this, create a new file in your application, at `src/utils/github.ts`. This file will contain a number of “utility” functions for working with GitHub’s API. The first of these will be a string parser, called `parseGhIssueString`:

```ts
const ghIssueRegex =
	/(?<owner>[\w.-]*)\/(?<repo>[\w.-]*)\#(?<issue_number>\d*)/;

export const parseGhIssueString = (text: string) => {
	const match = text.match(ghIssueRegex);
	return match ? (match.groups ?? {}) : {};
};
```

`parseGhIssueString` takes in a `text` input, matches it against `ghIssueRegex`, and if a match is found, returns the `groups` object from that match, making use of the `owner`, `repo`, and `issue_number` capture groups defined in the regex. By exporting this function from `src/utils/github.ts`, you can make use of it back in `src/handlers/lookup.ts`:

```ts null {2,12}
import { Hono } from "hono";
import { parseGhIssueString } from "../utils/github";

const app = new Hono();

app.post("/", async (c) => {
	const { text } = await c.req.parseBody();
	if (typeof text !== "string") {
		return c.notFound();
	}

	const { owner, repo, issue_number } = parseGhIssueString(text);
});

export default app;
```

#### Making requests to GitHub’s API

With this data, you can make your first API lookup to GitHub. Again, make a new function in `src/utils/github.ts`, to make a `fetch` request to the GitHub API for the issue data:

```ts null {8,9,10,11,12}
const ghIssueRegex =
	/(?<owner>[\w.-]*)\/(?<repo>[\w.-]*)\#(?<issue_number>\d*)/;

export const parseGhIssueString = (text: string) => {
	const match = text.match(ghIssueRegex);
	return match ? (match.groups ?? {}) : {};
};

export const fetchGithubIssue = (
	owner: string,
	repo: string,
	issue_number: string,
) => {
	const url = `https://api.github.com/repos/${owner}/${repo}/issues/${issue_number}`;
	const headers = { "User-Agent": "simple-worker-slack-bot" };
	return fetch(url, { headers });
};
```

Back in `src/handlers/lookup.ts`, use `fetchGitHubIssue` to make a request to GitHub’s API, and parse the response:

```ts null {2,3,14,15}
import { Hono } from "hono";
import { fetchGithubIssue, parseGhIssueString } from "../utils/github";
import { Issue } from "../types";

const app = new Hono();

app.post("/", async (c) => {
	const { text } = await c.req.parseBody();
	if (typeof text !== "string") {
		return c.notFound();
	}

	const { owner, repo, issue_number } = parseGhIssueString(text);
	const response = await fetchGithubIssue(owner, repo, issue_number);
	const issue = await response.json<Issue>();
});

export default app;
```

#### Constructing a Slack message

After you have received a response back from GitHub’s API, the final step is to construct a Slack message with the issue data, and return it to the user. The final result will look something like this:

![A successful Slack Message will have the components listed below](~/assets/images/workers/tutorials/slackbot/issue-slack-message.png)

You can see four different pieces in the above screenshot:

1. The first line (bolded) links to the issue, and shows the issue title
2. The following lines (including code snippets) are the issue body
3. The last line of text shows the issue status, the issue creator (with a link to the user’s GitHub profile), and the creation date for the issue
4. The profile picture of the issue creator, on the right-hand side

The previously mentioned [Block Kit](https://api.slack.com/block-kit) framework will help take the issue data (in the structure lined out in [GitHub’s REST API documentation](https://developer.github.com/v3/issues/)) and format it into something like the above screenshot.

Create another file, `src/utils/slack.ts`, to contain the function `constructGhIssueSlackMessage`, a function for taking issue data, and turning it into a collection of blocks. Blocks are JavaScript objects that Slack will use to format the message:

```ts
import { Issue } from "../types";

export const constructGhIssueSlackMessage = (
	issue: Issue,
	issue_string: string,
	prefix_text?: string,
) => {
	const issue_link = `<${issue.html_url}|${issue_string}>`;
	const user_link = `<${issue.user.html_url}|${issue.user.login}>`;
	const date = new Date(Date.parse(issue.created_at)).toLocaleDateString();

	const text_lines = [
		prefix_text,
		`*${issue.title} - ${issue_link}*`,
		issue.body,
		`*${issue.state}* - Created by ${user_link} on ${date}`,
	];
};
```

Slack messages accept a variant of Markdown, which supports bold text via asterisks (`*bolded text*`), and links in the format `<https://yoururl.com|Display Text>`.

Given that format, construct `issue_link`, which takes the `html_url` property from the GitHub API `issue` data (in format `https://github.com/cloudflare/wrangler-legacy/issues/1`), and the `issue_string` sent from the Slack slash command, and combines them into a clickable link in the Slack message.

`user_link` is similar, using `issue.user.html_url` (in the format `https://github.com/signalnerve`, a GitHub user) and the user’s GitHub username (`issue.user.login`), to construct a clickable link to the GitHub user.

Finally, parse `issue.created_at`, an ISO 8601 string, convert it into an instance of a JavaScript `Date`, and turn it into a formatted string, in the format `MM/DD/YY`.

With those variables in place, `text_lines` is an array of each line of text for the Slack message. The first line is the **issue title** and the **issue link**, the second is the **issue body**, and the final line is the **issue state** (for example, open or closed), the **user link**, and the **creation date**.

With the text constructed, you can finally construct your Slack message, returning an array of blocks for Slack’s [Block Kit](https://api.slack.com/block-kit). In this case, there is only have one block: a [section](https://api.slack.com/reference/messaging/blocks#section) block with Markdown text, and an accessory image of the user who created the issue. Return that single block inside of an array, to complete the `constructGhIssueSlackMessage` function:

```ts null {15,16,17,18,19,20,21,22,23,24,25,26,27,28}
import { Issue } from "../types";

export const constructGhIssueSlackMessage = (
	issue: Issue,
	issue_string: string,
	prefix_text?: string,
) => {
	const issue_link = `<${issue.html_url}|${issue_string}>`;
	const user_link = `<${issue.user.html_url}|${issue.user.login}>`;
	const date = new Date(Date.parse(issue.created_at)).toLocaleDateString();

	const text_lines = [
		prefix_text,
		`*${issue.title} - ${issue_link}*`,
		issue.body,
		`*${issue.state}* - Created by ${user_link} on ${date}`,
	];

	return [
		{
			type: "section",
			text: {
				type: "mrkdwn",
				text: text_lines.join("\n"),
			},
			accessory: {
				type: "image",
				image_url: issue.user.avatar_url,
				alt_text: issue.user.login,
			},
		},
	];
};
```

#### Finishing the lookup route

In `src/handlers/lookup.ts`, use `constructGhIssueSlackMessage` to construct `blocks`, and return them as a new response with `c.json()` when the slash command is called:

```ts null {3,17,18,19,20,21,22}
import { Hono } from "hono";
import { fetchGithubIssue, parseGhIssueString } from "../utils/github";
import { constructGhIssueSlackMessage } from "../utils/slack";
import { Issue } from "../types";

const app = new Hono();

app.post("/", async (c) => {
	const { text } = await c.req.parseBody();
	if (typeof text !== "string") {
		return c.notFound();
	}

	const { owner, repo, issue_number } = parseGhIssueString(text);
	const response = await fetchGithubIssue(owner, repo, issue_number);
	const issue = await response.json<Issue>();
	const blocks = constructGhIssueSlackMessage(issue, text);

	return c.json({
		blocks,
		response_type: "in_channel",
	});
});

export default app;
```

One additional parameter passed into the response is `response_type`. By default, responses to slash commands are ephemeral, meaning that they are only seen by the user who writes the slash command. Passing a `response_type` of `in_channel`, as seen above, will cause the response to appear for all users in the channel.

If you would like the messages to remain private, remove the `response_type` line. This will cause `response_type` to default to `ephemeral`.

#### Handling errors

The `lookup` route is almost complete, but there are a number of errors that can occur in the route, such as parsing the body from Slack, getting the issue from GitHub, or constructing the Slack message itself. Although Hono applications can handle errors without having to do anything, you can customize the response returned in the following way.

```ts null {25,26,27,28,29,30}
import { Hono } from "hono";
import { fetchGithubIssue, parseGhIssueString } from "../utils/github";
import { constructGhIssueSlackMessage } from "../utils/slack";
import { Issue } from "../types";

const app = new Hono();

app.post("/", async (c) => {
	const { text } = await c.req.parseBody();
	if (typeof text !== "string") {
		return c.notFound();
	}

	const { owner, repo, issue_number } = parseGhIssueString(text);
	const response = await fetchGithubIssue(owner, repo, issue_number);
	const issue = await response.json<Issue>();
	const blocks = constructGhIssueSlackMessage(issue, text);

	return c.json({
		blocks,
		response_type: "in_channel",
	});
});

app.onError((_e, c) => {
	return c.text(
		"Uh-oh! We couldn't find the issue you provided. " +
			"We can only find public issues in the following format: `owner/repo#issue_number`.",
	);
});

export default app;
```

### Creating the webhook route

You are now halfway through implementing the routes for your Workers application. In implementing the next route, `src/routes/webhook.ts`, you will re-use a lot of the code that you have already written for the lookup route.

At the beginning of this tutorial, you configured a GitHub webhook to track any events related to issues in your repository. When an issue is opened, for example, the function corresponding to the path `/webhook` on your Workers application should take the data sent to it from GitHub, and post a new message in the configured Slack channel.

In `src/routes/webhook.ts`, define a blank Hono application. The difference from the `lookup` route is that the `Bindings` is passed as a generics for the `new Hono()`. This is necessary to give the appropriate TypeScript type to `SLACK_WEBHOOK_URL` which will be used later.

```ts
import { Hono } from "hono";
import { Bindings } from "../types";

const app = new Hono<{ Bindings: Bindings }>();

export default app;
```

Much like with the `lookup` route, you will need to parse the incoming payload inside of `request`, get the relevant issue data from it (refer to [the GitHub API documentation on `IssueEvent`](https://developer.github.com/v3/activity/events/types/#issuesevent) for the full payload schema), and send a formatted message to Slack to indicate what has changed. The final version will look something like this:

![A successful Webhook Message example](~/assets/images/workers/tutorials/slackbot/webhook_example.png)

Compare this message format to the format returned when a user uses the `/issue` slash command. You will see that there is only one actual difference between the two: the addition of an action text on the first line, in the format `An issue was $action:`. This action, which is sent as part of the `IssueEvent` from GitHub, will be used as you construct a very familiar looking collection of blocks using Slack’s Block Kit.

#### Parsing event data

To start filling out the route, parse the request body formatted JSON into an object and construct some helper variables:

```ts null {2,6,7,8,9,10}
import { Hono } from "hono";
import { constructGhIssueSlackMessage } from "../utils/slack";

const app = new Hono();

app.post("/", async (c) => {
	const { action, issue, repository } = await c.req.json();
	const prefix_text = `An issue was ${action}:`;
	const issue_string = `${repository.owner.login}/${repository.name}#${issue.number}`;
});

export default app;
```

An `IssueEvent`, the payload sent from GitHub as part of your webhook configuration, includes an `action` (what happened to the issue: for example, it was opened, closed, locked, etc.), the `issue` itself, and the `repository`, among other things.

Use `c.req.json()` to convert the payload body of the request from JSON into a plain JS object. Use ES6 destructuring to set `action`, `issue` and `repository` as variables you can use in your code. `prefix_text` is a string indicating what happened to the issue, and `issue_string` is the familiar string `owner/repo#issue_number` that you have seen before: while the `lookup` route directly used the text sent from Slack to fill in `issue_string`, you will construct it directly based on the data passed in the JSON payload.

#### Constructing and sending a Slack message

The messages your Slack bot sends back to your Slack channel from the `lookup` and `webhook` routes are incredibly similar. Because of this, you can re-use the existing `constructGhIssueSlackMessage` to continue populating `src/handlers/webhook.ts`. Import the function from `src/utils/slack.ts`, and pass the issue data into it:

```ts null {10}
import { Hono } from "hono";
import { constructGhIssueSlackMessage } from "../utils/slack";

const app = new Hono();

app.post("/", async (c) => {
	const { action, issue, repository } = await c.req.json();
	const prefix_text = `An issue was ${action}:`;
	const issue_string = `${repository.owner.login}/${repository.name}#${issue.number}`;
	const blocks = constructGhIssueSlackMessage(issue, issue_string, prefix_text);
});

export default app;
```

Importantly, the usage of `constructGhIssueSlackMessage` in this handler adds one additional argument to the function, `prefix_text`. Update the corresponding function inside of `src/utils/slack.ts`, adding `prefix_text` to the collection of `text_lines` in the message block, if it has been passed in to the function.

Add a utility function, `compact`, which takes an array, and filters out any `null` or `undefined` values from it. This function will be used to remove `prefix_text` from `text_lines` if it has not actually been passed in to the function, such as when called from `src/handlers/lookup.ts`. The full (and final) version of the `src/utils/slack.ts` looks like this:

```ts null {3,26}
import { Issue } from "../types";

const compact = (array: unknown[]) => array.filter((el) => el);

export const constructGhIssueSlackMessage = (
	issue: Issue,
	issue_string: string,
	prefix_text?: string,
) => {
	const issue_link = `<${issue.html_url}|${issue_string}>`;
	const user_link = `<${issue.user.html_url}|${issue.user.login}>`;
	const date = new Date(Date.parse(issue.created_at)).toLocaleDateString();

	const text_lines = [
		prefix_text,
		`*${issue.title} - ${issue_link}*`,
		issue.body,
		`*${issue.state}* - Created by ${user_link} on ${date}`,
	];

	return [
		{
			type: "section",
			text: {
				type: "mrkdwn",
				text: compact(text_lines).join("\n"),
			},
			accessory: {
				type: "image",
				image_url: issue.user.avatar_url,
				alt_text: issue.user.login,
			},
		},
	];
};
```

Back in `src/handlers/webhook.ts`, the `blocks` that are returned from `constructGhIssueSlackMessage` become the body in a new `fetch` request, an HTTP POST request to a Slack webhook URL. Once that request completes, return a response with status code `200`, and the body text `"OK"`:

```ts null {13,14,15,16,17,18,19}
import { Hono } from "hono";
import { constructGhIssueSlackMessage } from "../utils/slack";
import { Bindings } from "../types";

const app = new Hono<{ Bindings: Bindings }>();

app.post("/", async (c) => {
	const { action, issue, repository } = await c.req.json();
	const prefix_text = `An issue was ${action}:`;
	const issue_string = `${repository.owner.login}/${repository.name}#${issue.number}`;
	const blocks = constructGhIssueSlackMessage(issue, issue_string, prefix_text);

	const fetchResponse = await fetch(c.env.SLACK_WEBHOOK_URL, {
		body: JSON.stringify({ blocks }),
		method: "POST",
		headers: { "Content-Type": "application/json" },
	});

	return c.text("OK");
});

export default app;
```

The constant `SLACK_WEBHOOK_URL` represents the Slack Webhook URL that you created all the way back in the [Incoming Webhook](/workers/tutorials/build-a-slackbot/#incoming-webhook) section of this tutorial.

:::caution

Since this webhook allows developers to post directly to your Slack channel, keep it secret.

:::

To use this constant inside of your codebase, use the [`wrangler secret`](/workers/wrangler/commands/#secret) command:

```sh title="Set the SLACK_WEBHOOK_URL secret"
npx wrangler secret put SLACK_WEBHOOK_URL
```

```sh output
Enter a secret value: https://hooks.slack.com/services/abc123
```

#### Handling errors

Similarly to the `lookup` route, the `webhook` route should include some basic error handling. Unlike `lookup`, which sends responses directly back into Slack, if something goes wrong with your webhook, it may be useful to actually generate an erroneous response, and return it to GitHub.

To do this, write the custom error handler with `app.onError()` and return a new response with a status code of `500`. The final version of `src/routes/webhook.ts` looks like this:

```ts null {24,25,26,27,28,29,30,31}
import { Hono } from "hono";
import { constructGhIssueSlackMessage } from "../utils/slack";
import { Bindings } from "../types";

const app = new Hono<{ Bindings: Bindings }>();

app.post("/", async (c) => {
	const { action, issue, repository } = await c.req.json();
	const prefix_text = `An issue was ${action}:`;
	const issue_string = `${repository.owner.login}/${repository.name}#${issue.number}`;
	const blocks = constructGhIssueSlackMessage(issue, issue_string, prefix_text);

	const fetchResponse = await fetch(c.env.SLACK_WEBHOOK_URL, {
		body: JSON.stringify({ blocks }),
		method: "POST",
		headers: { "Content-Type": "application/json" },
	});

	if (!fetchResponse.ok) throw new Error();

	return c.text("OK");
});

app.onError((_e, c) => {
	return c.json(
		{
			message: "Unable to handle webhook",
		},
		500,
	);
});

export default app;
```

## Deploy

By completing the preceding steps, you have finished writing the code for your Slack bot. You can now deploy your application.

Wrangler has built-in support for bundling, uploading, and releasing your Cloudflare Workers application. To do this, run the following command which will build and deploy your code.

<PackageManagers exec="run" args="deploy" />

Deploying your Workers application should now cause issue updates to start appearing in your Slack channel, as the GitHub webhook can now successfully reach your Workers webhook route:

![When you create new issue, a Slackbot will now appear in your Slack channel](/images/workers/tutorials/slackbot/create-new-issue.gif)

## Related resources

In this tutorial, you built and deployed a Cloudflare Workers application that can respond to GitHub webhook events, and allow GitHub API lookups within Slack. If you would like to review the full source code for this application, you can find the repository [on GitHub](https://github.com/yusukebe/workers-slack-bot).

If you want to get started building your own projects, review the existing list of [Quickstart templates](/workers/get-started/quickstarts/).

---

# Connect to and query your Turso database using Workers

URL: https://developers.cloudflare.com/workers/tutorials/connect-to-turso-using-workers/

import { Render, PackageManagers, WranglerConfig } from "~/components";

This tutorial will guide you on how to build globally distributed applications with Cloudflare Workers, and [Turso](https://chiselstrike.com/), an edge-hosted distributed database based on libSQL. By using Workers and Turso, you can create applications that are close to your end users without having to maintain or operate infrastructure in tens or hundreds of regions.

:::note

For a more seamless experience, refer to the [Turso Database Integration guide](/workers/databases/third-party-integrations/turso/). The Turso Database Integration will guide you through connecting your Worker to a Turso database by securely configuring your database credentials as [secrets](/workers/configuration/secrets/) in your Worker.

:::

## Prerequisites

Before continuing with this tutorial, you should have:

- Successfully [created up your first Cloudflare Worker](/workers/get-started/guide/) and/or have deployed a Cloudflare Worker before.
- Installed [Wrangler](/workers/wrangler/install-and-update/), a command-line tool for building Cloudflare Workers.
- A [GitHub account](https://github.com/), required for authenticating to Turso.
- A basic familiarity with installing and using command-line interface (CLI) applications.

## Install the Turso CLI

You will need the Turso CLI to create and populate a database. Run either of the following two commands in your terminal to install the Turso CLI:

```sh
# On macOS or Linux with Homebrew
brew install chiselstrike/tap/turso

# Manual scripted installation
curl -sSfL <https://get.tur.so/install.sh> | bash
```

After you have installed the Turso CLI, verify that the CLI is in your shell path:

```sh
turso --version
```

```sh output
# This should output your current Turso CLI version (your installed version may be higher):
turso version v0.51.0
```

## Create and populate a database

Before you create your first Turso database, you need to log in to the CLI using your GitHub account by running:

```sh
turso auth login
```

```sh output

Waiting for authentication...
✔  Success! Logged in as <your GitHub username>
```

`turso auth login` will open a browser window and ask you to sign into your GitHub account, if you are not already logged in. The first time you do this, you will need to give the Turso application permission to use your account. Select **Approve** to grant Turso the permissions needed.

After you have authenticated, you can create a database by running `turso db create <DATABASE_NAME>`. Turso will automatically choose a location closest to you.

```sh
turso db create my-db
```

```sh output
# Example:
[===>                ]
Creating database my-db in Los Angeles, California (US) (lax)
# Once succeeded:
Created database my-db in Los Angeles, California (US) (lax) in 34 seconds.
```

With your first database created, you can now connect to it directly and execute SQL against it:

```sh
turso db shell my-db
```

To get started with your database, create and define a schema for your first table. In this example, you will create a `example_users` table with one column: `email` (of type `text`) and then populate it with one email address.

In the shell you just opened, paste in the following SQL:

```sql
create table example_users (email text);
insert into example_users values ("foo@bar.com");
```

If the SQL statements succeeded, there will be no output. Note that the trailing semi-colons (`;`) are necessary to terminate each SQL statement.

Type `.quit` to exit the shell.

## Use Wrangler to create a Workers project

The Workers command-line interface, [Wrangler](/workers/wrangler/install-and-update/), allows you to create, locally develop, and deploy your Workers projects.

To create a new Workers project (named `worker-turso-ts`), run the following:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"worker-turso-ts"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

To start developing your Worker, `cd` into your new project directory:

```sh
cd worker-turso-ts
```

In your project directory, you now have the following files:

- `wrangler.json` / `wrangler.toml`: [Wrangler configuration file](/workers/wrangler/configuration/)
- `src/index.ts`: A minimal Hello World Worker written in TypeScript
- `package.json`: A minimal Node dependencies configuration file.
- `tsconfig.json`: TypeScript configuration that includes Workers types. Only generated if indicated.

For this tutorial, only the [Wrangler configuration file](/workers/wrangler/configuration/) and `src/index.ts` file are relevant. You will not need to edit the other files, and they should be left as is.

## Configure your Worker for your Turso database

The Turso client library requires two pieces of information to make a connection:

1. `LIBSQL_DB_URL` - The connection string for your Turso database.
2. `LIBSQL_DB_AUTH_TOKEN` - The authentication token for your Turso database. This should be kept a secret, and not committed to source code.

To get the URL for your database, run the following Turso CLI command, and copy the result:

```sh
turso db show my-db --url
```

```sh output
libsql://my-db-<your-github-username>.turso.io
```

Open the [Wrangler configuration file](/workers/wrangler/configuration/) in your editor and at the bottom of the file, create a new `[vars]` section representing the [environment variables](/workers/configuration/environment-variables/) for your project:

<WranglerConfig>

```toml
[vars]
LIBSQL_DB_URL = "paste-your-url-here"
```

</WranglerConfig>

Save the changes to the [Wrangler configuration file](/workers/wrangler/configuration/).

Next, create a long-lived authentication token for your Worker to use when connecting to your database. Run the following Turso CLI command, and copy the output to your clipboard:

```sh
turso db tokens create my-db -e none
# Will output a long text string (an encoded JSON Web Token)
```

To keep this token secret:

1. You will create a `.dev.vars` file for local development. Do not commit this file to source control. You should add `.dev.vars to your `.gitignore\` file if you are using Git.

- You will also create a [secret](/workers/configuration/secrets/) to keep your authentication token confidential.

First, create a new file called `.dev.vars` with the following structure. Paste your authentication token in the quotation marks:

```
LIBSQL_DB_AUTH_TOKEN="<YOUR_AUTH_TOKEN>"
```

Save your changes to `.dev.vars`. Next, store the authentication token as a secret for your production Worker to reference. Run the following `wrangler secret` command to create a Secret with your token:

```sh
# Ensure you specify the secret name exactly: your Worker will need to reference it later.
npx wrangler secret put LIBSQL_DB_AUTH_TOKEN
```

```sh output
? Enter a secret value: › <paste your token here>
```

Select `<Enter>` on your keyboard to save the token as a secret. Both `LIBSQL_DB_URL` and `LIBSQL_DB_AUTH_TOKEN` will be available in your Worker's environment at runtime.

## Install extra libraries

Install the Turso client library and a router:

<PackageManagers pkg="@libsql/client itty-router" />

The `@libsql/client` library allows you to query a Turso database. The `itty-router` library is a lightweight router you will use to help handle incoming requests to the worker.

## Write your Worker

You will now write a Worker that will:

1. Handle an HTTP request.
2. Route it to a specific handler to either list all users in our database or add a new user.
3. Return the results and/or success.

Open `src/index.ts` and delete the existing template. Copy the below code exactly as is and paste it into the file:

```ts
import { Client as LibsqlClient, createClient } from "@libsql/client/web";
import { Router, RouterType } from "itty-router";

export interface Env {
	// The environment variable containing your the URL for your Turso database.
	LIBSQL_DB_URL?: string;
	// The Secret that contains the authentication token for your Turso database.
	LIBSQL_DB_AUTH_TOKEN?: string;

	// These objects are created before first use, then stashed here
	// for future use
	router?: RouterType;
}

export default {
	async fetch(request, env): Promise<Response> {
		if (env.router === undefined) {
			env.router = buildRouter(env);
		}

		return env.router.fetch(request);
	},
} satisfies ExportedHandler<Env>;

function buildLibsqlClient(env: Env): LibsqlClient {
	const url = env.LIBSQL_DB_URL?.trim();
	if (url === undefined) {
		throw new Error("LIBSQL_DB_URL env var is not defined");
	}

	const authToken = env.LIBSQL_DB_AUTH_TOKEN?.trim();
	if (authToken === undefined) {
		throw new Error("LIBSQL_DB_AUTH_TOKEN env var is not defined");
	}

	return createClient({ url, authToken });
}

function buildRouter(env: Env): RouterType {
	const router = Router();

	router.get("/users", async () => {
		const client = buildLibsqlClient(env);
		const rs = await client.execute("select * from example_users");
		return Response.json(rs);
	});

	router.get("/add-user", async (request) => {
		const client = buildLibsqlClient(env);
		const email = request.query.email;
		if (email === undefined) {
			return new Response("Missing email", { status: 400 });
		}
		if (typeof email !== "string") {
			return new Response("email must be a single string", { status: 400 });
		}
		if (email.length === 0) {
			return new Response("email length must be > 0", { status: 400 });
		}

		try {
			await client.execute({
				sql: "insert into example_users values (?)",
				args: [email],
			});
		} catch (e) {
			console.error(e);
			return new Response("database insert failed");
		}

		return new Response("Added");
	});

	router.all("*", () => new Response("Not Found.", { status: 404 }));

	return router;
}
```

Save your `src/index.ts` file with your changes.

Note:

- The libSQL client library import '@libsql/client/web' must be imported exactly as shown when working with Cloudflare workers. The non-web import will not work in the Workers environment.
- The `Env` interface contains the environment variable and secret you defined earlier.
- The `Env` interface also caches the libSQL client object and router, which are created on the first request to the Worker.
- The `/users` route fetches all rows from the `example_users` table you created in the Turso shell. It simply serializes the `ResultSet` object as JSON directly to the caller.
- The `/add-user` route inserts a new row using a value provided in the query string.

With your environment configured and your code ready, you will now test your Worker locally before you deploy.

## Run the Worker locally with Wrangler

To run a local instance of our Worker (entirely on your machine), run the following command:

```sh
npx wrangler dev
```

You should be able to review output similar to the following:

```txt
Your worker has access to the following bindings:
- Vars:
  - LIBSQL_DB_URL: "your-url"
⎔ Starting a local server...
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ [b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit                                                                  	│
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Debugger listening on ws://127.0.0.1:61918/1064babd-bc9d-4bed-b171-b35dab3b7680
For help, see: https://nodejs.org/en/docs/inspector
Debugger attached.
[mf:inf] Worker reloaded! (40.25KiB)
[mf:inf] Listening on 0.0.0.0:8787
[mf:inf] - http://127.0.0.1:8787
[mf:inf] - http://192.168.1.136:8787
[mf:inf] Updated `Request.cf` object cache!
```

The localhost address — the one with `127.0.0.1` in it — is a web-server running locally on your machine.

Connect to it and validate your Worker returns the email address you inserted when you created your `example_users` table by visiting the `/users` route in your browser: [http://127.0.0.1:8787/users](http://127.0.0.1:8787/users).

You should see JSON similar to the following containing the data from the `example_users` table:

```json
{
	"columns": ["email"],
	"rows": [{ "email": "foo@bar.com" }],
	"rowsAffected": 0
}
```

:::caution

If you see an error instead of a list of users, double check that:

- You have entered the correct value for your `LIBSQL_DB_URL` in the [Wrangler configuration file](/workers/wrangler/configuration/).
- You have set a secret called `LIBSQL_DB_AUTH_TOKEN` with your database authentication token.

Both of these need to be present and match the variable names in your Worker's code.
:::

Test the `/add-users` route and pass it an email address to insert: [http://127.0.0.1:8787/add-user?email=test@test.com](http://127.0.0.1:8787/add-user?email=test@test.com.)

You should see the text `“Added”`. If you load the first URL with the `/users` route again ([http://127.0.0.1:8787/users](http://127.0.0.1:8787/users)), it will show the newly added row. You can repeat this as many times as you like. Note that due to its design, your application will not stop you from adding duplicate email addresses.

Quit Wrangler by typing `q` into the shell where it was started.

## Deploy to Cloudflare

After you have validated that your Worker can connect to your Turso database, deploy your Worker. Run the following Wrangler command to deploy your Worker to the Cloudflare global network:

```sh
npx wrangler deploy
```

The first time you run this command, it will launch a browser, ask you to sign in with your Cloudflare account, and grant permissions to Wrangler.

The `deploy` command will output the following:

```txt
Your worker has access to the following bindings:
- Vars:
  - LIBSQL_DB_URL: "your-url"
...
Published worker-turso-ts (0.19 sec)
  https://worker-turso-ts.<your-Workers-subdomain>.workers.dev
Current Deployment ID: f9e6b48f-5aac-40bd-8f44-8a40be2212ff
```

You have now deployed a Worker that can connect to your Turso database, query it, and insert new data.

## Optional: Clean up

To clean up the resources you created as part of this tutorial:

- If you do not want to keep this Worker, run `npx wrangler delete worker-turso-ts` to delete the deployed Worker.
- You can also delete your Turso database via `turso db destroy my-db`.

## Related resources

- Find the [complete project source code on GitHub](https://github.com/cloudflare/workers-sdk/tree/main/templates/worker-turso-ts/).
- Understand how to [debug your Cloudflare Worker](/workers/observability/).
- Join the [Cloudflare Developer Discord](https://discord.cloudflare.com).
- Join the [ChiselStrike (Turso) Discord](https://discord.com/invite/4B5D7hYwub).

---

# Create a fine-tuned OpenAI model with R2

URL: https://developers.cloudflare.com/workers/tutorials/create-finetuned-chatgpt-ai-models-with-r2/

import { Render, PackageManagers, WranglerConfig } from "~/components";

In this tutorial, you will use the [OpenAI](https://openai.com) API and [Cloudflare R2](/r2) to create a [fine-tuned model](https://platform.openai.com/docs/guides/fine-tuning).

This feature in OpenAI's API allows you to derive a custom model from OpenAI's various large language models based on a set of custom instructions and example answers. These instructions and example answers are written in a document, known as a fine-tune document. This document will be stored in R2 and dynamically provided to OpenAI's APIs when creating a new fine-tune model.

In order to use this feature, you will do the following tasks:

1. Upload a fine-tune document to R2.
2. Read the R2 file and upload it to OpenAI.
3. Create a new fine-tuned model based on the document.

![Demo](~/assets/images/workers/tutorials/finetune/finetune-example.png)

To review the completed code for this application, refer to the [GitHub repository for this tutorial](https://github.com/kristianfreeman/openai-finetune-r2-example).

## Prerequisites

Before you start, make sure you have:

- A Cloudflare account with access to R2. If you do not have a Cloudflare account, [sign up](https://dash.cloudflare.com/sign-up/workers-and-pages) before continuing. Then purchase R2 from your Cloudflare dashboard.
- An OpenAI API key.
- A fine-tune document, structured as [JSON Lines](https://jsonlines.org/). Use the [example document](https://github.com/kristianfreeman/openai-finetune-r2-example/blob/16ca53ca9c8589834abe317487eeedb8a24c7643/example_data.jsonl) in the source code.

## 1. Create a Worker application

First, use the `c3` CLI to create a new Cloudflare Workers project.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"finetune-chatgpt-model"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

The above options will create the "Hello World" TypeScript project.

Move into your newly created directory:

```sh
cd finetune-chatgpt-model
```

## 2. Upload a fine-tune document to R2

Next, upload the fine-tune document to R2. R2 is a key-value store that allows you to store and retrieve files from within your Workers application. You will use [Wrangler](/workers/wrangler) to create a new R2 bucket.

To create a new R2 bucket use the [`wrangler r2 bucket create`](/workers/wrangler/commands/#r2-bucket-create) command. Note that you are logged in with your Cloudflare account. If not logged in via Wrangler, use the [`wrangler login`](/workers/wrangler/commands/#login) command.

```sh
npx wrangler r2 bucket create <BUCKET_NAME>
```

Replace `<BUCKET_NAME>` with your desired bucket name. Note that bucket names must be lowercase and can only contain dashes.

Next, upload a file using the [`wrangler r2 object put`](/workers/wrangler/commands/#r2-object-put) command.

```sh
npx wrangler r2 object put <PATH> -f <FILE_NAME>
```

`<PATH>` is the combined bucket and file path of the file you want to upload -- for example, `fine-tune-ai/finetune.jsonl`, where `fine-tune-ai` is the bucket name. Replace `<FILE_NAME>` with the local filename of your fine-tune document.

## 3. Bind your bucket to the Worker

A binding is how your Worker interacts with external resources such as the R2 bucket.

To bind the R2 bucket to your Worker, add the following to your Wrangler file. Update the binding property to a valid JavaScript variable identifier. Replace `<YOUR_BUCKET_NAME>` with the name of the bucket you created in [step 2](#2-upload-a-fine-tune-document-to-r2):

<WranglerConfig>

```toml
[[r2_buckets]]
binding = 'MY_BUCKET' # <~ valid JavaScript variable name
bucket_name = '<YOUR_BUCKET_NAME>'
```

</WranglerConfig>

## 4. Initialize your Worker application

You will use [Hono](https://hono.dev/), a lightweight framework for building Cloudflare Workers applications. Hono provides an interface for defining routes and middleware functions. Inside your project directory, run the following command to install Hono:

<PackageManagers pkg="hono" />

You also need to install the [OpenAI Node API library](https://www.npmjs.com/package/openai). This library provides convenient access to the OpenAI REST API in a Node.js project. To install the library, execute the following command:

<PackageManagers pkg="openai" />

Next, open the `src/index.ts` file and replace the default code with the below code. Replace `<MY_BUCKET>` with the binding name you set in Wrangler file.

```typescript
import { Context, Hono } from "hono";
import OpenAI from "openai";

type Bindings = {
	<MY_BUCKET>: R2Bucket
	OPENAI_API_KEY: string
}

type Variables = {
	openai: OpenAI
}

const app = new Hono<{ Bindings: Bindings, Variables: Variables }>()

app.use('*', async (c, next) => {
	const openai = new OpenAI({
		apiKey: c.env.OPENAI_API_KEY,
	})
	c.set("openai", openai)
	await next()
})

app.onError((err, c) => {
	return c.text(err.message, 500)
})

export default app;
```

In the above code, you first import the required packages and define the types. Then, you initialize `app` as a new Hono instance. Using the `use` middleware function, you add the OpenAI API client to the context of all routes. This middleware function allows you to access the client from within any route handler. `onError()` defines an error handler to return any errors as a JSON response.

## 5. Read R2 files and upload them to OpenAI

In this section, you will define the route and function responsible for handling file uploads.

In `createFile`, your Worker reads the file from R2 and converts it to a `File` object. Your Worker then uses the OpenAI API to upload the file and return the response.

The `GET /files` route listens for `GET` requests with a query parameter `file`, representing a filename of an uploaded fine-tune document in R2. The function uses the `createFile` function to manage the file upload process.

Replace `<MY_BUCKET>` with the binding name you set in Wrangler file.

```typescript
// New import added at beginning of file
import { toFile } from 'openai/uploads'

const createFile = async (c: Context, r2Object: R2ObjectBody) => {
	const openai: OpenAI = c.get("openai")

	const blob = await r2Object.blob()
	const file = await toFile(blob, r2Object.key)

	const uploadedFile = await openai.files.create({
		file,
		purpose: "fine-tune",
	})

	return uploadedFile
}

app.get('/files', async c => {
	const fileQueryParam = c.req.query("file")
	if (!fileQueryParam) return c.text("Missing file query param", 400)

	const file = await c.env.<MY_BUCKET>.get(fileQueryParam)
	if (!file) return c.text("Couldn't find file", 400)

	const uploadedFile = await createFile(c, file)
	return c.json(uploadedFile)
})
```

## 6. Create fine-tuned models

This section includes the `GET /models` route and the `createModel` function. The function `createModel` takes care of specifying the details and initiating the fine-tuning process with OpenAI. The route handles incoming requests for creating a new fine-tuned model.

```typescript
const createModel = async (c: Context, fileId: string) => {
	const openai: OpenAI = c.get("openai");

	const body = {
		training_file: fileId,
		model: "gpt-4o-mini",
	};

	return openai.fineTuning.jobs.create(body);
};

app.get("/models", async (c) => {
	const fileId = c.req.query("file_id");
	if (!fileId) return c.text("Missing file ID query param", 400);

	const model = await createModel(c, fileId);
	return c.json(model);
});
```

## 7. List all fine-tune jobs

This section describes the `GET /jobs` route and the corresponding `getJobs` function. The function interacts with OpenAI's API to fetch a list of all fine-tuning jobs. The route provides an interface for retrieving this information.

```typescript
const getJobs = async (c: Context) => {
	const openai: OpenAI = c.get("openai");
	const resp = await openai.fineTuning.jobs.list();
	return resp.data;
};

app.get("/jobs", async (c) => {
	const jobs = await getJobs(c);
	return c.json(jobs);
});
```

## 8. Deploy your application

After you have created your Worker application and added the required functions, deploy the application.

Before you deploy, you must set the `OPENAI_API_KEY` [secret](/workers/configuration/secrets/) for your application. Do this by running the [`wrangler secret put`](/workers/wrangler/commands/#put) command:

```sh
npx wrangler secret put OPENAI_API_KEY
```

To deploy your Worker application to the Cloudflare global network:

1. Make sure you are in your Worker project's directory, then run the [`wrangler deploy`](/workers/wrangler/commands/#deploy) command:

```sh
npx wrangler deploy
```

2. Wrangler will package and upload your code.

3. After your application is deployed, Wrangler will provide you with your Worker's URL.

## 9. View the fine-tune job status and use the model

To use your application, create a new fine-tune job by making a request to the `/files` with a `file` query param matching the filename you uploaded earlier:

```sh
curl https://your-worker-url.com/files?file=finetune.jsonl
```

When the file is uploaded, issue another request to `/models`, passing the `file_id` query parameter. This should match the `id` returned as JSON from the `/files` route:

```sh
curl https://your-worker-url.com/models?file_id=file-abc123
```

Finally, visit `/jobs` to see the status of your fine-tune jobs in OpenAI. Once the fine-tune job has completed, you can see the `fine_tuned_model` value, indicating a fine-tuned model has been created.

![Jobs](~/assets/images/workers/tutorials/finetune/finetune-jobs.png)

Visit the [OpenAI Playground](https://platform.openai.com/playground) in order to use your fine-tune model. Select your fine-tune model from the top-left dropdown of the interface.

![Demo](~/assets/images/workers/tutorials/finetune/finetune-example.png)

Use it in any API requests you make to OpenAI's chat completions endpoints. For instance, in the below code example:

```javascript
openai.chat.completions.create({
	messages: [{ role: "system", content: "You are a helpful assistant." }],
	model: "ft:gpt-4o-mini:my-org:custom_suffix:id",
});
```

## Next steps

To build more with Workers, refer to [Tutorials](/workers/tutorials).

If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on [Discord](https://discord.cloudflare.com) to connect with other developers and the Cloudflare team.

---

# Deploy a real-time chat application

URL: https://developers.cloudflare.com/workers/tutorials/deploy-a-realtime-chat-app/

import { Render, WranglerConfig } from "~/components";

In this tutorial, you will deploy a serverless, real-time chat application that runs using [Durable Objects](/durable-objects/).

This chat application uses a Durable Object to control each chat room. Users connect to the Object using WebSockets. Messages from one user are broadcast to all the other users. The chat history is also stored in durable storage. Real-time messages are relayed directly from one user to others without going through the storage layer.

<Render file="tutorials-before-you-start" />

## Clone the chat application repository

Open your terminal and clone the [workers-chat-demo](https://github.com/cloudflare/workers-chat-demo) repository:

```sh
git clone https://github.com/cloudflare/workers-chat-demo.git
```

## Authenticate Wrangler

After you have cloned the repository, authenticate Wrangler by running:

```sh
npx wrangler login
```

## Deploy your project

When you are ready to deploy your application, run:

```sh
npx wrangler deploy
```

Your application will be deployed to your `*.workers.dev` subdomain.

To deploy your application to a custom domain within the Cloudflare dashboard, go to your Worker > **Triggers** > **Add Custom Domain**.

To deploy your application to a custom domain using Wrangler, open your project's [Wrangler configuration file](/workers/wrangler/configuration/).

To configure a route in your Wrangler configuration file, add the following to your environment:

<WranglerConfig>

```toml
routes = [
    { pattern = "example.com/about", zone_id = "<YOUR_ZONE_ID>" }
]
```

</WranglerConfig>

If you have specified your zone ID in the environment of your Wrangler configuration file, you will not need to write it again in object form.

To configure a subdomain in your Wrangler configuration file, add the following to your environment:

<WranglerConfig>

```toml
routes = [
	{ pattern = "subdomain.example.com", custom_domain = true }
]
```

</WranglerConfig>

To test your live application:

1. Open your `edge-chat-demo.<SUBDOMAIN>.workers.dev` subdomain. Your subdomain can be found in the [Cloudflare dashboard](https://dash.cloudflare.com) > **Workers & Pages** > your Worker > **Triggers** > **Routes** > select the `edge-chat-demo.<SUBDOMAIN>.workers.dev` route.
2. Enter a name in the **your name** field.
3. Choose whether to enter a public room or create a private room.
4. Send the link to other participants. You will be able to view room participants on the right side of the screen.

## Uninstall your application

To uninstall your chat application, modify your Wrangler file to remove the `durable_objects` bindings and add a `deleted_classes` migration:



<WranglerConfig>

```toml
[durable_objects]
bindings = [
]

# Indicate that you want the ChatRoom and RateLimiter classes to be callable as Durable Objects.
[[migrations]]
tag = "v1" # Should be unique for each entry
new_sqlite_classes = ["ChatRoom", "RateLimiter"]

[[migrations]]
tag = "v2"
deleted_classes = ["ChatRoom", "RateLimiter"]
```

</WranglerConfig>

Then run `npx wrangler deploy`.

To delete your Worker:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. In Account Home, select **Workers & Pages**.
3. In **Overview**, select your Worker.
4. Select **Manage Service** > **Delete**. For complete instructions on set up and deletion, refer to the `README.md` in your cloned repository.

By completing this tutorial, you have deployed a real-time chat application with Durable Objects and Cloudflare Workers.

## Related resources

Continue building with other Cloudflare Workers tutorials below.

- [Build a Slackbot](/workers/tutorials/build-a-slackbot/)
- [Create SMS notifications for your GitHub repository using Twilio](/workers/tutorials/github-sms-notifications-using-twilio/)
- [Build a QR code generator](/workers/tutorials/build-a-qr-code-generator/)

---

# GitHub SMS notifications using Twilio

URL: https://developers.cloudflare.com/workers/tutorials/github-sms-notifications-using-twilio/

import { Render, PackageManagers, WranglerConfig } from "~/components";

In this tutorial, you will learn to build an SMS notification system on Workers to receive updates on a GitHub repository. Your Worker will send you a text update using Twilio when there is new activity on your repository.

You will learn how to:

- Build webhooks using Workers.
- Integrate Workers with GitHub and Twilio.
- Use Worker secrets with Wrangler.

![Animated gif of receiving a text message on your phone after pushing changes to a repository](/images/workers/tutorials/github-sms/video-of-receiving-a-text-after-pushing-to-a-repo.gif)

---

<Render file="tutorials-before-you-start" />

## Create a Worker project

Start by using `npm create cloudflare@latest` to create a Worker project in the command line:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"github-twilio-notifications"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Make note of the URL that your application was deployed to. You will be using it when you configure your GitHub webhook.

```sh
cd github-twilio-notifications
```

Inside of your new `github-sms-notifications` directory, `src/index.js` represents the entry point to your Cloudflare Workers application. You will configure this file for most of the tutorial.

You will also need a GitHub account and a repository for this tutorial. If you do not have either setup, [create a new GitHub account](https://github.com/join) and [create a new repository](https://docs.github.com/en/get-started/quickstart/create-a-repo) to continue with this tutorial.

First, create a webhook for your repository to post updates to your Worker. Inside of your Worker, you will then parse the updates. Finally, you will send a `POST` request to Twilio to send a text message to you.

You can reference the finished code at this [GitHub repository](https://github.com/rickyrobinett/workers-sdk/tree/main/templates/examples/github-sms-notifications-using-twilio).

---

## Configure GitHub

To start, configure a GitHub webhook to post to your Worker when there is an update to the repository:

1. Go to your GitHub repository's **Settings** > **Webhooks** > **Add webhook**.

2. Set the Payload URL to the `/webhook` path on the Worker URL that you made note of when your application was first deployed.

3. In the **Content type** dropdown, select _application/json_.

4. In the **Secret** field, input a secret key of your choice.

5. In **Which events would you like to trigger this webhook?**, select **Let me select individual events**. Select the events you want to get notifications for (such as **Pull requests**, **Pushes**, and **Branch or tag creation**).

6. Select **Add webhook** to finish configuration.

![Following instructions to set up your webhook in the GitHub webhooks settings dashboard](~/assets/images/workers/tutorials/github-sms/github-config-screenshot.png)

---

## Parsing the response

With your local environment set up, parse the repository update with your Worker.

Initially, your generated `index.js` should look like this:

```js
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello World!");
	},
};
```

Use the `request.method` property of [`Request`](/workers/runtime-apis/request/) to check if the request coming to your application is a `POST` request, and send an error response if the request is not a `POST` request.

```js
export default {
	async fetch(request, env, ctx) {
		if (request.method !== "POST") {
			return new Response("Please send a POST request!");
		}
	},
};
```

Next, validate that the request is sent with the right secret key. GitHub attaches a hash signature for [each payload using the secret key](https://docs.github.com/en/developers/webhooks-and-events/webhooks/securing-your-webhooks). Use a helper function called `checkSignature` on the request to ensure the hash is correct. Then, you can access data from the webhook by parsing the request as JSON.

```js
async fetch(request, env, ctx) {
  if(request.method !== 'POST') {
    return new Response('Please send a POST request!');
  }
  try {
    const rawBody = await request.text();

    if (!checkSignature(rawBody, request.headers, env.GITHUB_SECRET_TOKEN)) {
      return new Response("Wrong password, try again", {status: 403});
    }
  } catch (e) {
    return new Response(`Error:  ${e}`);
  }
},
```

The `checkSignature` function will use the Node.js crypto library to hash the received payload with your known secret key to ensure it matches the request hash. GitHub uses an HMAC hexdigest to compute the hash in the SHA-256 format. You will place this function at the top of your `index.js` file, before your export.

```js
import { createHmac, timingSafeEqual } from "node:crypto";
import { Buffer } from "node:buffer";

function checkSignature(text, headers, githubSecretToken) {
	const hmac = createHmac("sha256", githubSecretToken);
	hmac.update(text);
	const expectedSignature = hmac.digest("hex");
	const actualSignature = headers.get("x-hub-signature-256");

	const trusted = Buffer.from(`sha256=${expectedSignature}`, "ascii");
	const untrusted = Buffer.from(actualSignature, "ascii");

	return (
		trusted.byteLength == untrusted.byteLength &&
		timingSafeEqual(trusted, untrusted)
	);
}
```

To make this work, you need to use [`wrangler secret put`](/workers/wrangler/commands/#put) to set your `GITHUB_SECRET_TOKEN`. This token is the secret you picked earlier when configuring you GitHub webhook:

```sh
npx wrangler secret put GITHUB_SECRET_TOKEN
```

Add the nodejs_compat flag to your Wrangler file:

<WranglerConfig>

```toml
compatibility_flags = ["nodejs_compat"]
```

</WranglerConfig>

---

## Sending a text with Twilio

You will send a text message to you about your repository activity using Twilio. You need a Twilio account and a phone number that can receive text messages. [Refer to the Twilio guide to get set up](https://www.twilio.com/messaging/sms). (If you are new to Twilio, they have [an interactive game](https://www.twilio.com/quest) where you can learn how to use their platform and get some free credits for beginners to the service.)

You can then create a helper function to send text messages by sending a `POST` request to the Twilio API endpoint. [Refer to the Twilio reference](https://www.twilio.com/docs/sms/api/message-resource#create-a-message-resource) to learn more about this endpoint.

Create a new function called `sendText()` that will handle making the request to Twilio:

```js
async function sendText(accountSid, authToken, message) {
	const endpoint = `https://api.twilio.com/2010-04-01/Accounts/${accountSid}/Messages.json`;

	const encoded = new URLSearchParams({
		To: "%YOUR_PHONE_NUMBER%",
		From: "%YOUR_TWILIO_NUMBER%",
		Body: message,
	});

	const token = btoa(`${accountSid}:${authToken}`);

	const request = {
		body: encoded,
		method: "POST",
		headers: {
			Authorization: `Basic ${token}`,
			"Content-Type": "application/x-www-form-urlencoded",
		},
	};

	const response = await fetch(endpoint, request);
	const result = await response.json();

	return Response.json(result);
}
```

To make this work, you need to set some secrets to hide your `ACCOUNT_SID` and `AUTH_TOKEN` from the source code. You can set secrets with [`wrangler secret put`](/workers/wrangler/commands/#put) in your command line.

```sh
npx wrangler secret put TWILIO_ACCOUNT_SID
npx wrangler secret put TWILIO_AUTH_TOKEN
```

Modify your `githubWebhookHandler` to send a text message using the `sendText` function you just made.

```js
async fetch(request, env, ctx) {
  if(request.method !== 'POST') {
    return new Response('Please send a POST request!');
  }
  try {
    const rawBody = await request.text();
    if (!checkSignature(rawBody, request.headers, env.GITHUB_SECRET_TOKEN)) {
      return new Response('Wrong password, try again', {status: 403});
    }

    const action = request.headers.get('X-GitHub-Event');
    const json = JSON.parse(rawBody);
    const repoName = json.repository.full_name;
    const senderName = json.sender.login;

    return await sendText(
      env.TWILIO_ACCOUNT_SID,
      env.TWILIO_AUTH_TOKEN,
      `${senderName} completed ${action} onto your repo ${repoName}`
    );
  } catch (e) {
    return new Response(`Error:  ${e}`);
  }
};
```

Run the `npx wrangler deploy` command to redeploy your Worker project:

```sh
npx wrangler deploy
```

![Video of receiving a text after pushing to a repo](/images/workers/tutorials/github-sms/video-of-receiving-a-text-after-pushing-to-a-repo.gif)

Now when you make an update (that you configured in the GitHub **Webhook** settings) to your repository, you will get a text soon after. If you have never used Git before, refer to the [GIT Push and Pull Tutorial](https://www.datacamp.com/tutorial/git-push-pull) for pushing to your repository.

Reference the finished code [on GitHub](https://github.com/rickyrobinett/workers-sdk/tree/main/templates/examples/github-sms-notifications-using-twilio).

By completing this tutorial, you have learned how to build webhooks using Workers, integrate Workers with GitHub and Twilio, and use Worker secrets with Wrangler.

## Related resources

{/* <!-- - [Authorize users with Auth0](/workers/tutorials/authorize-users-with-auth0/) --> */}

- [Build a JAMStack app](/workers/tutorials/build-a-jamstack-app/)
- [Build a QR code generator](/workers/tutorials/build-a-qr-code-generator/)

---

# Generate YouTube thumbnails with Workers and Cloudflare Image Resizing

URL: https://developers.cloudflare.com/workers/tutorials/generate-youtube-thumbnails-with-workers-and-images/

import { Render, PackageManagers, WranglerConfig } from "~/components";

In this tutorial, you will learn how to programmatically generate a custom YouTube thumbnail using Cloudflare Workers and Cloudflare Image Resizing. You may want to generate a custom YouTube thumbnail to customize the thumbnail's design, call-to-actions and images used to encourage more viewers to watch your video.

This tutorial will help you understand how to work with [Images](/images/),[Image Resizing](/images/transform-images/) and [Cloudflare Workers](/workers/).

<Render file="tutorials-before-you-start" />

To follow this tutorial, make sure you have Node, Cargo, and [Wrangler](/workers/wrangler/install-and-update/) installed on your machine.

## Learning goals

In this tutorial, you will learn how to:

- Upload Images to Cloudflare with the Cloudflare dashboard or API.
- Set up a Worker project with Wrangler.
- Manipulate images with image transformations in your Worker.

## Upload your image

To generate a custom thumbnail image, you first need to upload a background image to Cloudflare Images. This will serve as the image you use for transformations to generate the thumbnails.

Cloudflare Images allows you to store, resize, optimize and deliver images in a fast and secure manner. To get started, upload your images to the Cloudflare dashboard or use the Upload API.

### Upload with the dashboard

To upload an image using the Cloudflare dashboard:

1. Log in to the [Cloudflare Dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Images**.
3. Use **Quick Upload** to either drag and drop an image or click to browse and choose a file from your local files.
4. After the image is uploaded, view it using the generated URL.

### Upload with the API

To upload your image with the [Upload via URL](/images/upload-images/upload-url/) API, refer to the example below:

```sh
curl --request POST \
 --url https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/images/v1 \
 --header 'Authorization: Bearer <API_TOKEN>' \
 --form 'url=<PATH_TO_IMAGE>' \
 --form 'metadata={"key":"value"}' \
 --form 'requireSignedURLs=false'

```

- `ACCOUNT_ID`: The current user's account id which can be found in your account settings.
- `API_TOKEN`: Needs to be generated to scoping Images permission.
- `PATH_TO_IMAGE`: Indicates the URL for the image you want to upload.

You will then receive a response similar to this:

```json
{
	"result": {
		"id": "2cdc28f0-017a-49c4-9ed7-87056c83901",
		"filename": "image.jpeg",
		"metadata": {
			"key": "value"
		},
		"uploaded": "2022-01-31T16:39:28.458Z",
		"requireSignedURLs": false,
		"variants": [
			"https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/public",
			"https://imagedelivery.net/Vi7wi5KSItxGFsWRG2Us6Q/2cdc28f0-017a-49c4-9ed7-87056c83901/thumbnail"
		]
	},
	"success": true,
	"errors": [],
	"messages": []
}
```

Now that you have uploaded your image, you will use it as the background image for your video's thumbnail.

## Create a Worker to transform text to image

After uploading your image, create a Worker that will enable you to transform text to image. This image can be used as an overlay on the background image you uploaded. Use the [rustwasm-worker-template](https://github.com/cloudflare/workers-sdk/tree/main/templates/worker-rust).

You will need the following before you begin:

- A recent version of [Rust](https://rustup.rs/).
- Access to the `cargo-generate` subcommand:

  ```sh
  cargo install cargo-generate
  ```

Create a new Worker project using the `worker-rust` template:

```sh
cargo generate https://github.com/cloudflare/rustwasm-worker-template
```

You will now make a few changes to the files in your project directory.

1. In the `lib.rs` file, add the following code block:

```rs
use worker::*;
mod utils;

#[event(fetch)]
pub async fn main(req: Request, env: Env, _ctx: worker::Context) -> Result<Response> {
   // Optionally, get more helpful error messages written to the console in the case of a panic.
   utils::set_panic_hook();

   let router = Router::new();
   router
       .get("/", |_, _| Response::ok("Hello from Workers!"))
       .run(req, env)
       .await
}
```

2. Update the `Cargo.toml` file in your `worker-to-text` project directory to use [text-to-png](https://github.com/RookAndPawn/text-to-png), a Rust package for rendering text to PNG. Add the package as a dependency by running:

```sh
cargo add text-to-png@0.2.0
```

3. Import the `text_to_png` library into your `worker-to-text` project's `lib.rs` file.

```rs null {1}
use text_to_png::{TextPng, TextRenderer};
use worker::*;
mod utils;

#[event(fetch)]
pub async fn main(req: Request, env: Env, _ctx: worker::Context) -> Result<Response> {
   // Optionally, get more helpful error messages written to the console in the case of a panic.
   utils::set_panic_hook();

   let router = Router::new();
   router
       .get("/", |_, _| Response::ok("Hello from Workers!"))
       .run(req, env)
       .await
}
```

4. Update `lib.rs` to create a `handle-slash` function that will activate the image transformation based on the text passed to the URL as a query parameter.

```rs null {17}
use text_to_png::{TextPng, TextRenderer};
use worker::*;
mod utils;

#[event(fetch)]
pub async fn main(req: Request, env: Env, _ctx: worker::Context) -> Result<Response> {
   // Optionally, get more helpful error messages written to the console in the case of a panic.
   utils::set_panic_hook();

   let router = Router::new();
   router
       .get("/", |_, _| Response::ok("Hello from Workers!"))
       .run(req, env)
       .await
}

async fn handle_slash(text: String) -> Result<Response> {}
```

5. In the `handle-slash` function, call the `TextRenderer` by assigning it to a renderer value, specifying that you want to use a custom font. Then, use the `render_text_to_png_data` method to transform the text into image format. In this example, the custom font (`Inter-Bold.ttf`) is located in an `/assets` folder at the root of the project which will be used for generating the thumbnail. You must update this portion of the code to point to your custom font file.

```rs null {17,18,19,20,21,22,23,24}
use text_to_png::{TextPng, TextRenderer};
use worker::*;
mod utils;

#[event(fetch)]
pub async fn main(req: Request, env: Env, _ctx: worker::Context) -> Result<Response> {
   // Optionally, get more helpful error messages written to the console in the case of a panic.
   utils::set_panic_hook();

   let router = Router::new();
   router
       .get("/", |_, _| Response::ok("Hello from Workers!"))
       .run(req, env)
       .await
}

async fn handle_slash(text: String) -> Result<Response> {
  let renderer = TextRenderer::try_new_with_ttf_font_data(include_bytes!("../assets/Inter-Bold.ttf"))
    .expect("Example font is definitely loadable");

  let text_png: TextPng = renderer.render_text_to_png_data(text.replace("+", " "), 60, "003682").unwrap();
}
```

6. Rewrite the `Router` function to call `handle_slash` when a query is passed in the URL, otherwise return the `"Hello Worker!"` as the response.

```rs null {11,12,13,14,15,16,17,18,19,20}
use text_to_png::{TextPng, TextRenderer};
use worker::*;
mod utils;

#[event(fetch)]
pub async fn main(req: Request, env: Env, _ctx: worker::Context) -> Result<Response> {
   // Optionally, get more helpful error messages written to the console in the case of a panic.
   utils::set_panic_hook();

  let router = Router::new();
    router
      .get_async("/", |req, _| async move {
        if let Some(text) = req.url()?.query() {
          handle_slash(text.into()).await
        } else {
          handle_slash("Hello Worker!".into()).await
        }
      })
      .run(req, env)
        .await
}

async fn handle_slash(text: String) -> Result<Response> {
  let renderer = TextRenderer::try_new_with_ttf_font_data(include_bytes!("../assets/Inter-Bold.ttf"))
    .expect("Example font is definitely loadable");

  let text_png: TextPng = renderer.render_text_to_png_data(text.replace("+", " "), 60, "003682").unwrap();
}
```

7. In your `lib.rs` file, set the headers to `content-type: image/png` so that the response is correctly rendered as a PNG image.

```rs null {29,30,31,32}
use text_to_png::{TextPng, TextRenderer};
use worker::*;
mod utils;

#[event(fetch)]
pub async fn main(req: Request, env: Env, _ctx: worker::Context) -> Result<Response> {
   // Optionally, get more helpful error messages written to the console in the case of a panic.
   utils::set_panic_hook();

   let router = Router::new();
    router
      .get_async("/", |req, _| async move {
        if let Some(text) = req.url()?.query() {
          handle_slash(text.into()).await
        } else {
          handle_slash("Hello Worker!".into()).await
        }
      })
      .run(req, env)
        .await
}

async fn handle_slash(text: String) -> Result<Response> {
  let renderer = TextRenderer::try_new_with_ttf_font_data(include_bytes!("../assets/Inter-Bold.ttf"))
    .expect("Example font is definitely loadable");

  let text_png: TextPng = renderer.render_text_to_png_data(text.replace("+", " "), 60, "003682").unwrap();

  let mut headers = Headers::new();
  headers.set("content-type", "image/png")?;

  Ok(Response::from_bytes(text_png.data)?.with_headers(headers))
}
```

The final `lib.rs` file should look as follows. Find the full code as an example repository on [GitHub](https://github.com/cloudflare/workers-sdk/tree/main/templates/examples/worker-to-text).

```rs
use text_to_png::{TextPng, TextRenderer};
use worker::*;

mod utils;

#[event(fetch)]
pub async fn main(req: Request, env: Env, _ctx: worker::Context) -> Result<Response> {
    // Optionally, get more helpful error messages written to the console in the case of a panic.
    utils::set_panic_hook();

    let router = Router::new();

    router
        .get_async("/", |req, _| async move {
            if let Some(text) = req.url()?.query() {
                handle_slash(text.into()).await
            } else {
                handle_slash("Hello Worker!".into()).await
            }
        })
        .run(req, env)
        .await
}

async fn handle_slash(text: String) -> Result<Response> {
    let renderer = TextRenderer::try_new_with_ttf_font_data(include_bytes!("../assets/Inter-Bold.ttf"))
    .expect("Example font is definitely loadable");

    let text = if text.len() > 128 {
        "Nope".into()
    } else {
        text
    };

    let text = urlencoding::decode(&text).map_err(|_| worker::Error::BadEncoding)?;

    let text_png: TextPng = renderer.render_text_to_png_data(text.replace("+", " "), 60, "003682").unwrap();

    let mut headers = Headers::new();
    headers.set("content-type", "image/png")?;

    Ok(Response::from_bytes(text_png.data)?.with_headers(headers))
}
```

After you have finished updating your project, start a local server for developing your Worker by running:

```sh
npx wrangler dev
```

This should spin up a `localhost` instance with the image displayed:

![Run wrangler dev to start a local server for your Worker](~/assets/images/workers/tutorials/youtube-thumbnails/hello-worker.png)

Adding a query parameter with custom text, you should receive:

![Follow the instructions above to receive an output image](~/assets/images/workers/tutorials/youtube-thumbnails/build-serverles.png)

To deploy your Worker, open your Wrangler file and update the `name` key with your project's name. Below is an example with this tutorial's project name:

<WranglerConfig>

```toml
name = "worker-to-text"

```

</WranglerConfig>

Then run the `npx wrangler deploy` command to deploy your Worker.

```sh
npx wrangler deploy
```

A `.workers.dev` domain will be generated for your Worker after running `wrangler deploy`. You will use this domain in the main thumbnail image.

## Create a Worker to display the original image

Create a Worker to serve the image you uploaded to Images by running:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"thumbnail-image"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

To start developing your Worker, `cd` into your new project directory:

```sh
cd thumbnail-image
```

This will create a new Worker project named `thumbnail-image`. In the `src/index.js` file, add the following code block:

```js
export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		if (url.pathname === "/original-image") {
			const image = await fetch(
				`https://imagedelivery.net/${env.CLOUDFLARE_ACCOUNT_HASH}/${IMAGE_ID}/public`,
			);
			return image;
		}
		return new Response("Image Resizing with a Worker");
	},
};
```

Update `env.CLOUDFLARE_ACCOUNT_HASH` with your [Cloudflare account ID](/fundamentals/account/find-account-and-zone-ids/). Update `env.IMAGE_ID` with your [image ID](/images/get-started/).

Run your Worker and go to the `/original-image` route to review your image.

## Add custom text on your image

You will now use [Cloudflare image transformations](/images/transform-images/), with the `fetch` method, to add your dynamic text image as an overlay on top of your background image. Start by displaying the resulting image on a different route. Call the new route `/thumbnail`.

```js null {11}
export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		if (url.pathname === "/original-image") {
			const image = await fetch(
				`https://imagedelivery.net/${env.CLOUDFLARE_ACCOUNT_HASH}/${IMAGE_ID}/public`,
			);
			return image;
		}

		if (url.pathname === "/thumbnail") {
		}

		return new Response("Image Resizing with a Worker");
	},
};
```

Next, use the `fetch` method to apply the image transformation changes on top of the background image. The overlay options are nested in `options.cf.image`.

```js null {12,13,14,15,16,17,18}
export default {
	async fetch(request, env) {
		const url = new URL(request.url);

		if (url.pathname === "/original-image") {
			const image = await fetch(
				`https://imagedelivery.net/${env.CLOUDFLARE_ACCOUNT_HASH}/${IMAGE_ID}/public`,
			);
			return image;
		}

		if (url.pathname === "/thumbnail") {
			fetch(imageURL, {
				cf: {
					image: {},
				},
			});
		}

		return new Response("Image Resizing with a Worker");
	},
};
```

The `imageURL` is the URL of the image you want to use as a background image. In the `cf.image` object, specify the options you want to apply to the background image.

:::note

At time of publication, Cloudflare image transformations do not allow resizing images in a Worker that is stored in Cloudflare Images. Instead of using the image you served on the `/original-image` route, you will use the same image from a different source.

:::

Add your background image to an assets directory on GitHub and push your changes to GitHub. Copy the URL of the image upload by performing a left click on the image and selecting the **Copy Remote File Url** option.

Replace the `imageURL` value with the copied remote URL.

```js null {2,3}
if (url.pathname === "/thumbnail") {
	const imageURL =
		"https://github.com/lauragift21/social-image-demo/blob/1ed9044463b891561b7438ecdecbdd9da48cdb03/assets/cover.png?raw=true";
	fetch(imageURL, {
		cf: {
			image: {},
		},
	});
}
```

Next, add overlay options in the image object. Resize the image to the preferred width and height for YouTube thumbnails and use the [draw](/images/transform-images/draw-overlays/) option to add overlay text using the deployed URL of your `text-to-image` Worker.

```js null {3,4,5,6,7,8,9,10,11,12}
fetch(imageURL, {
	cf: {
		image: {
			width: 1280,
			height: 720,
			draw: [
				{
					url: "https://text-to-image.examples.workers.dev",
					left: 40,
				},
			],
		},
	},
});
```

Image transformations can only be tested when you deploy your Worker.

To deploy your Worker, open your Wrangler file and update the `name` key with your project's name. Below is an example with this tutorial's project name:

<WranglerConfig>

```toml
name = "thumbnail-image"

```

</WranglerConfig>

Deploy your Worker by running:

```sh
npx wrangler deploy
```

The command deploys your Worker to custom `workers.dev` subdomain. Go to your `.workers.dev` subdomain and go to the `/thumbnail` route.

You should see the resized image with the text `Hello Workers!`.

![Follow the steps above to generate your resized image.](~/assets/images/workers/tutorials/youtube-thumbnails/thumbnail.png)

You will now make text applied dynamic. Making your text dynamic will allow you change the text and have it update on the image automatically.

To add dynamic text, append any text attached to the `/thumbnail` URL using query parameters and pass it down to the `text-to-image` Worker URL as a parameter.

```js
for (const title of url.searchParams.values()) {
	try {
		const editedImage = await fetch(imageURL, {
			cf: {
				image: {
					width: 1280,
					height: 720,
					draw: [
						{
							url: `https://text-to-image.examples.workers.dev/?${title}`,
							left: 50,
						},
					],
				},
			},
		});
		return editedImage;
	} catch (error) {
		console.log(error);
	}
}
```

This will always return the text you pass as a query string in the generated image. This example URL, [https://socialcard.cdnuptime.com/thumbnail?Getting%20Started%20With%20Cloudflare%20Images](https://socialcard.cdnuptime.com/thumbnail?Getting%20Started%20With%20Cloudflare%20Images), will generate the following image:

![An example thumbnail.](~/assets/images/workers/tutorials/youtube-thumbnails/thumbnail2.png)

By completing this tutorial, you have successfully made a custom YouTube thumbnail generator.

## Related resources

In this tutorial, you learned how to use Cloudflare Workers and Cloudflare image transformations to generate custom YouTube thumbnails. To learn more about Cloudflare Workers and image transformations, refer to [Resize an image with a Worker](/images/transform-images/transform-via-workers/).

---

# Handle form submissions with Airtable

URL: https://developers.cloudflare.com/workers/tutorials/handle-form-submissions-with-airtable/

import { Render, PackageManagers, WranglerConfig } from "~/components";

In this tutorial, you will use [Cloudflare Workers](/workers/) and [Airtable](https://airtable.com) to persist form submissions from a front-end user interface. Airtable is a free-to-use spreadsheet solution that has an approachable API for developers. Workers will handle incoming form submissions and use Airtable's [REST API](https://airtable.com/api) to asynchronously persist the data in an Airtable base (Airtable's term for a spreadsheet) for later reference.

![GIF of a complete Airtable and serverless function integration](/images/workers/tutorials/airtable/example.gif)

<Render file="tutorials-before-you-start" />

## 1. Create a form

For this tutorial, you will be building a Workers function that handles input from a contact form. The form this tutorial references will collect a first name, last name, email address, phone number, message subject, and a message.

:::note[Build a form]

If this is your first time building a form and you would like to follow a tutorial to create a form with Cloudflare Pages, refer to the [HTML forms](/pages/tutorials/forms) tutorial.
:::

Review a simplified example of the form used in this tuttorial. Note that the `action` parameter of the `<form>` tag should point to the deployed Workers application that you will build in this tutorial.

```html title="Your front-end code" {1}
<form action="https://workers-airtable-form.signalnerve.workers.dev/submit" method="POST">
  <div>
    <label for="first_name">First name</label>
    <input type="text" name="first_name" id="first_name" autocomplete="given-name" placeholder="Ellen" required />
  </div>

  <div>
    <label for="last_name">Last name</label>
    <input type="text" name="last_name" id="last_name" autocomplete="family-name" placeholder="Ripley" required />
  </div>

  <div>
    <label for="email">Email</label>
      <input id="email" name="email" type="email" autocomplete="email" placeholder="eripley@nostromo.com" required />
    </div>
  </div>

  <div>
    <label for="phone">
      Phone
      <span>Optional</span>
    </label>
    <input type="text" name="phone" id="phone" autocomplete="tel" placeholder="+1 (123) 456-7890" />
  </div>

  <div>
    <label for="subject">Subject</label>
    <input type="text" name="subject" id="subject" placeholder="Your example subject" required />
  </div>

  <div>
    <label for="message">
      Message
      <span>Max 500 characters</span>
    </label>
    <textarea id="message" name="message" rows="4" placeholder="Tenetur quaerat expedita vero et illo. Tenetur explicabo dolor voluptatem eveniet. Commodi est beatae id voluptatum porro laudantium. Quam placeat accusamus vel officiis vel. Et perferendis dicta ut perspiciatis quos iste. Tempore autem molestias voluptates in sapiente enim doloremque." required></textarea>
  </div>

  <div>
    <button type="submit">
      Submit
    </button>
  </div>
</form>
```

## 2. Create a Worker project

To handle the form submission, create and deploy a Worker that parses the incoming form data and prepares it for submission to Airtable.

Create a new `airtable-form-handler` Worker project:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"airtable-form-handler"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Then, move into the newly created directory:

```sh
cd airtable-form-handler
```

## 3. Configure an Airtable base

When your Worker is complete, it will send data up to an Airtable base via Airtable's REST API.

If you do not have an Airtable account, create one (the free plan is sufficient to complete this tutorial). In Airtable's dashboard, create a new base by selecting **Start from scratch**.

After you have created a new base, set it up for use with the front-end form. Delete the existing columns, and create six columns, with the following field types:

| Field name   | Airtable field type |
| ------------ | ------------------- |
| First Name   | "Single line text"  |
| Last Name    | "Single line text"  |
| Email        | "Email"             |
| Phone Number | "Phone number"      |
| Subject      | "Single line text"  |
| Message      | "Long text"         |

Note that the field names are case-sensitive. If you change the field names, you will need to exactly match your new field names in the API request you make to Airtable later in the tutorial. Finally, you can optionally rename your table -- by defaulte it will have a name like Table 1. In the below code, we assume the table has been renamed with a more descriptive name, like `Form Submissions`.

Next, navigate to [Airtable's API page](https://airtable.com/api) and select your new base. Note that you must be logged into Airtable to see your base information. In the API documentation page, find your **Airtable base ID**.

You will also need to create a **Personal access token** that you'll use to access your Airtable base. You can do so by visiting the [Personal access tokens](https://airtable.com/create/tokens) page on Airtable's website and creating a new token. Make sure that you configure the token in the following way:

- Scope: the `data.records:write` scope must be set on the token
- Access: access should be granted to the base you have been working with in this tutorial

The results access token should now be set in your application. To make the token available in your codebase, use the [`wrangler secret`](/workers/wrangler/commands/#secret) command. The `secret` command encrypts and stores environment variables for use in your function, without revealing them to users.

Run `wrangler secret put`, passing `AIRTABLE_ACCESS_TOKEN` as the name of your secret:

```sh
npx wrangler secret put AIRTABLE_ACCESS_TOKEN
```

```sh output
Enter the secret text you would like assigned to the variable AIRTABLE_ACCESS_TOKEN on the script named airtable-form-handler:
******
🌀  Creating the secret for script name airtable-form-handler
✨  Success! Uploaded secret AIRTABLE_ACCESS_TOKEN.
```

Before you continue, review the keys that you should have from Airtable:

1. **Airtable Table Name**: The name for your table, like Form Submissions.
2. **Airtable Base ID**: The alphanumeric base ID found at the top of your base's API page.
3. **Airtable Access Token**: A Personal Access Token created by the user to access information about your new Airtable base.

## 4. Submit data to Airtable

With your Airtable base set up, and the keys and IDs you need to communicate with the API ready, you will now set up your Worker to persist data from your form into Airtable.

In your Worker project's `index.js` file, replace the default code with a Workers fetch handler that can respond to requests. When the URL requested has a pathname of `/submit`, you will handle a new form submission, otherwise, you will return a `404 Not Found` response.

```js
export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		if (url.pathname === "/submit") {
			await submitHandler(request, env);
		}
		return new Response("Not found", { status: 404 });
	},
};
```

The `submitHandler` has two functions. First, it will parse the form data coming from your HTML5 form. Once the data is parsed, use the Airtable API to persist a new row (a new form submission) to your table:

```js
async function submitHandler(request, env) {
	if (request.method !== "POST") {
		return new Response("Method Not Allowed", {
			status: 405,
		});
	}
	const body = await request.formData();

	const { first_name, last_name, email, phone, subject, message } =
		Object.fromEntries(body);

	// The keys in "fields" are case-sensitive, and
	// should exactly match the field names you set up
	// in your Airtable table, such as "First Name".
	const reqBody = {
		fields: {
			"First Name": first_name,
			"Last Name": last_name,
			Email: email,
			"Phone Number": phone,
			Subject: subject,
			Message: message,
		},
	};
	await createAirtableRecord(env, reqBody);
}

// Existing code
// export default ...
```

<Render file="request-dot-clone-warning" product="workers" />

While the majority of this function is concerned with parsing the request body (the data being sent as part of the request), there are two important things to note. First, if the HTTP method sent to this function is not `POST`, you will return a new response with the status code of [`405 Method Not Allowed`](https://httpstatuses.com/405).

The variable `reqBody` represents a collection of fields, which are key-value pairs for each column in your Airtable table. By formatting `reqBody` as an object with a collection of fields, you are creating a new record in your table with a value for each field.

Then you call `createAirtableRecord` (the function you will define next). The `createAirtableRecord` function accepts a `body` parameter, which conforms to the Airtable API's required format — namely, a JavaScript object containing key-value pairs under `fields`, representing a single record to be created on your table:

```js
async function createAirtableRecord(env, body) {
	try {
		const result = fetch(
			`https://api.airtable.com/v0/${env.AIRTABLE_BASE_ID}/${encodeURIComponent(env.AIRTABLE_TABLE_NAME)}`,
			{
				method: "POST",
				body: JSON.stringify(body),
				headers: {
					Authorization: `Bearer ${env.AIRTABLE_ACCESS_TOKEN}`,
					"Content-Type": "application/json",
				},
			},
		);
		return result;
	} catch (error) {
		console.error(error);
	}
}

// Existing code
// async function submitHandler
// export default ...
```

To make an authenticated request to Airtable, you need to provide four constants that represent data about your Airtable account, base, and table name. You have already set `AIRTABLE_ACCESS_TOKEN` using `wrangler secret`, since it is a value that should be encrypted. The **Airtable base ID** and **table name**, and `FORM_URL` are values that can be publicly shared in places like GitHub. Use Wrangler's [`vars`](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration/#vars) feature to pass public environment variables from your Wrangler file.

Add a `vars` table at the end of your Wrangler file:

<WranglerConfig>

```toml null {7}
name = "workers-airtable-form"
main = "src/index.js"
compatibility_date = "2023-06-13"

[vars]
AIRTABLE_BASE_ID = "exampleBaseId"
AIRTABLE_TABLE_NAME = "Form Submissions"
```

</WranglerConfig>

With all these fields submitted, it is time to deploy your Workers serverless function and get your form communicating with it. First, publish your Worker:

```sh title="Deploy your Worker"
npx wrangler deploy
```

Your Worker project will deploy to a unique URL — for example, `https://workers-airtable-form.cloudflare.workers.dev`. This represents the first part of your front-end form's `action` attribute — the second part is the path for your form handler, which is `/submit`. In your front-end UI, configure your `form` tag as seen below:

```html
<form
	action="https://workers-airtable-form.cloudflare.workers.dev/submit"
	method="POST"
	class="..."
>
	<!-- The rest of your HTML form -->
</form>
```

After you have deployed your new form (refer to the [HTML forms](/pages/tutorials/forms) tutorial if you need help creating a form), you should be able to submit a new form submission and see the value show up immediately in Airtable:

![Example GIF of complete Airtable and serverless function integration](/images/workers/tutorials/airtable/example.gif)

## Conclusion

With this tutorial completed, you have created a Worker that can accept form submissions and persist them to Airtable. You have learned how to parse form data, set up environment variables, and use the `fetch` API to make requests to external services outside of your Worker.

## Related resources

- [Build a Slackbot](/workers/tutorials/build-a-slackbot)
- [Build a To-Do List Jamstack App](/workers/tutorials/build-a-jamstack-app)
- [Build a blog using Nuxt.js and Sanity.io on Cloudflare Pages](/pages/tutorials/build-a-blog-using-nuxt-and-sanity)
- [James Quick's video on building a Cloudflare Workers + Airtable integration](https://www.youtube.com/watch?v=tFQ2kbiu1K4)

---

# Build Live Cursors with Next.js, RPC and Durable Objects

URL: https://developers.cloudflare.com/workers/tutorials/live-cursors-with-nextjs-rpc-do/

import { Render, PackageManagers, Steps, TabItem, Tabs, Details } from "~/components";

In this tutorial, you will learn how to build a real-time [Next.js](https://nextjs.org/) app that displays the live cursor location of each connected user using [Durable Objects](/durable-objects/), the Workers' built-in [RPC (Remote Procedure Call)](/workers/runtime-apis/rpc/) system, and the [OpenNext](https://opennext.js.org/cloudflare) Cloudflare adapter.

The application works like this:
- An ID is generated for each user that navigates to the application, which is used for identifying the WebSocket connection in the Durable Object.
- Once the WebSocket connection is established, the application sends a message to the WebSocket Durable Object to determine the current number of connected users.
- A user can close all active WebSocket connections via a Next.js server action that uses an RPC method.
- It handles WebSocket and mouse movement events to update the location of other users' cursors in the UI and to send updates about the user's own cursor, as well as join and leave WebSocket events.

![Animated gif of real-time Next.js app for visualizing live cursors](~/assets/images/workers/tutorials/live-cursors-nextjs/demo-live-cursors-nextjs-do.gif)

---

## 1. Create a Next.js Workers Project

<Steps>

1. Run the following command to create your Next.js Worker named `next-rpc`:

	<PackageManagers
		type="create"
		pkg="cloudflare@latest"
		args="next-rpc --framework=next"
	/>

	<Render
		file="c3-post-run-steps"
		product="workers"
		params={{
			category: "web-framework",
			framework: "Next.js",
		}}
	/>

2. Change into your new directory:

	```sh
	cd next-rpc
	```

3. Install [nanoid](https://www.npmjs.com/package/nanoid) so that string IDs can be generated for clients:
	<PackageManagers type="add" pkg="nanoid" frame="none" />

4. Install [perfect-cursors](https://www.npmjs.com/package/perfect-cursors) to interpolate cursor positions:
	<PackageManagers type="add" pkg="perfect-cursors" frame="none" />

5. Define workspaces for each Worker:

	<Tabs> <TabItem label="npm">

	Update your `package.json` file.


	```json title="package.json" ins={14-17}
	{
		"name": "next-rpc",
		"version": "0.1.0",
		"private": true,
		"scripts": {
			"dev": "next dev",
			"build": "next build",
			"start": "next start",
			"lint": "next lint",
			"deploy": "cloudflare && wrangler deploy",
			"preview": "cloudflare && wrangler dev",
			"cf-typegen": "wrangler types --env-interface CloudflareEnv env.d.ts"
		},
		"workspaces": [
			".",
			"worker"
		],
		// ...
	}
	```

	</TabItem> <TabItem label="pnpm">

	Create a new file `pnpm-workspace.yaml`.

	```yaml title="pnpm-workspace.yaml"
	packages:
		- "worker"
		- "."
	```
	</TabItem> </Tabs>

</Steps>

## 2. Create a Durable Object Worker

This Worker will manage the Durable Object and also have internal APIs
that will be made available to the Next.js Worker using a [`WorkerEntrypoint`](/workers/runtime-apis/bindings/service-bindings/rpc/) class.

<Steps>
1. Create another Worker named `worker` inside the Next.js directory:

	<PackageManagers
		type="create"
		pkg="cloudflare@latest"
		args={"worker"}
	/>

	<Render
		file="c3-post-run-steps"
		product="workers"
		params={{
			category: "hello-world",
			type: "Worker + Durable Objects",
			lang: "TypeScript",
		}}
	/>
</Steps>

## 3. Build Durable Object Worker functionality
<Steps>
1. In your `worker/wrangler.toml` file, update the Durable Object binding:
	```toml {4,5,9} title="worker/wrangler.toml"
	# ... Other wrangler configuration settings

	[[durable_objects.bindings]]
	name = "CURSOR_SESSIONS"
	class_name = "CursorSessions"

	[[migrations]]
	tag = "v1"
	new_sqlite_classes = ["CursorSessions"]
	```
2. Initialize the main methods for the Durable Object and define types for WebSocket messages and cursor sessions in your `worker/src/index.ts`
	to support type-safe interaction:
	- `WsMessage`. Specifies the structure of WebSocket messages handled by the Durable Object.
	- `Session`. Represents the connected user's ID and current cursor coordinates.

	```ts title="worker/src/index.ts"
	import { DurableObject } from 'cloudflare:workers';

	export type WsMessage =
		| { type: "message"; data: string }
		| { type: "quit"; id: string }
		| { type: "join"; id: string }
		| { type: "move"; id: string; x: number; y: number }
		| { type: "get-cursors" }
		| { type: "get-cursors-response"; sessions: Session[] };

	export type Session = { id: string; x: number; y: number };

	export class CursorSessions extends DurableObject<Env> {
		constructor(ctx: DurableObjectState, env: Env) {}
		broadcast(message: WsMessage, self?: string) {}
		async webSocketMessage(ws: WebSocket, message: string) {}
		async webSocketClose(ws: WebSocket, code: number) {}
		closeSessions() {}
		async fetch(request: Request) {
			return new Response("Hello");
		}
	}

	export default {
		async fetch(request, env, ctx) {
			return new Response("Ok");
		},
	} satisfies ExportedHandler<Env>;
	```

	Now update `worker-configuration.d.ts` by running:

	```sh
	cd worker && npm run cf-typegen
	```


3. Update the Durable Object to manage WebSockets:
	```ts title="worker/src/index.ts" {29-34,36-43,56,79,89-100}
	// Rest of the code

	export class CursorSessions extends DurableObject<Env> {
		sessions: Map<WebSocket, Session>;

		constructor(ctx: DurableObjectState, env: Env) {
			super(ctx, env);
			this.sessions = new Map();
			this.ctx.getWebSockets().forEach((ws) => {
				const meta = ws.deserializeAttachment();
				this.sessions.set(ws, { ...meta });
			});
		}

		broadcast(message: WsMessage, self?: string) {
			this.ctx.getWebSockets().forEach((ws) => {
				const { id } = ws.deserializeAttachment();
				if (id !== self) ws.send(JSON.stringify(message));
			});
		}

		async webSocketMessage(ws: WebSocket, message: string) {
			if (typeof message !== "string") return;
			const parsedMsg: WsMessage = JSON.parse(message);
			const session = this.sessions.get(ws);
			if (!session) return;

			switch (parsedMsg.type) {
				case "move":
					session.x = parsedMsg.x;
					session.y = parsedMsg.y;
					ws.serializeAttachment(session);
					this.broadcast(parsedMsg, session.id);
					break;

				case "get-cursors":
					const sessions: Session[] = [];
					this.sessions.forEach((session) => {
						sessions.push(session);
					});
					const wsMessage: WsMessage = { type: "get-cursors-response", sessions };
					ws.send(JSON.stringify(wsMessage));
					break;

				case "message":
					this.broadcast(parsedMsg);
					break;

				default:
					break;
			}
		}

		async webSocketClose(ws: WebSocket, code: number) {
			const id = this.sessions.get(ws)?.id;
			id && this.broadcast({ type: 'quit', id });
			this.sessions.delete(ws);
			ws.close();
		}

		closeSessions() {
			this.ctx.getWebSockets().forEach((ws) => ws.close());
		}

		async fetch(request: Request) {
			const url = new URL(request.url);
			const webSocketPair = new WebSocketPair();
			const [client, server] = Object.values(webSocketPair);
			this.ctx.acceptWebSocket(server);
			const id = url.searchParams.get("id");
			if (!id) {
				return new Response("Missing id", { status: 400 });
			}

			// Set Id and Default Position
			const sessionInitialData: Session = { id, x: -1, y: -1 };
			server.serializeAttachment(sessionInitialData);
			this.sessions.set(server, sessionInitialData);
			this.broadcast({ type: "join", id }, id);

			return new Response(null, {
				status: 101,
				webSocket: client,
			});
		}
	}

	export default {
		async fetch(request, env, ctx) {
			if (request.url.match("/ws")) {
				const upgradeHeader = request.headers.get("Upgrade");
				if (!upgradeHeader || upgradeHeader !== "websocket") {
					return new Response("Durable Object expected Upgrade: websocket", {
						status: 426,
					});
				}
				const id = env.CURSOR_SESSIONS.idFromName("globalRoom");
				const stub = env.CURSOR_SESSIONS.get(id);
				return stub.fetch(request);
			}
			return new Response(null, {
				status: 400,
				statusText: "Bad Request",
				headers: {
					"Content-Type": "text/plain",
				},
			});
		},
	} satisfies ExportedHandler<Env>;

	```
	- The main `fetch` handler routes requests with a `/ws` URL to the `CursorSessions` Durable Object where a WebSocket connection is established.
	- The `CursorSessions` class manages WebSocket connections, session states, and broadcasts messages to other connected clients.
		- When a new WebSocket connection is established, the Durable Object broadcasts a `join` message to all connected clients; similarly, a `quit` message is broadcast when a client disconnects.
		- It tracks each WebSocket client's last cursor position under the `move` message, which is broadcasted to all active clients.
		- When a `get-cursors` message is received, it sends the number of currently active clients to the specific client that requested it.


4. Extend the `WorkerEntrypoint` class for RPC:
	:::note[Note]
	A service binding to `SessionsRPC` is used here because Durable Object RPC is not yet supported in multiple `wrangler dev` sessions. In this case, two `wrangler dev` sessions are used: one for the Next.js Worker and one for the Durable Object Worker. In production, however, Durable Object RPC is not an issue. For convenience in local development, a service binding is used instead of directly invoking the Durable Object RPC method.
	:::


	```ts title="worker/src/index.ts" ins={2,5-12} del={1}
	import { DurableObject } from 'cloudflare:workers';
	import { DurableObject, WorkerEntrypoint } from 'cloudflare:workers';
	// ... rest of the code

	export class SessionsRPC extends WorkerEntrypoint<Env> {
		async closeSessions() {
			const id = this.env.CURSOR_SESSIONS.idFromName("globalRoom");
			const stub = this.env.CURSOR_SESSIONS.get(id);
			// Invoking Durable Object RPC method. Same `wrangler dev` session.
			await stub.closeSessions();
		}
	}

	export default {
		async fetch(request, env, ctx) {
			if (request.url.match("/ws")) {
	// ...
	```

5. Leave the Durable Object Worker running. It's used for RPC and serves as a local WebSocket server:
	<PackageManagers type="run" pkg="dev" frame="none" />

6. Use the resulting address from the previous step to set the Worker host as a public environment variable in your Next.js project:
	```text title="next-rpc/.env.local" ins={1}
	NEXT_PUBLIC_WS_HOST=localhost:8787
	```

</Steps>

## 4. Build Next.js Worker functionality
<Steps>
1. In your Next.js Wrangler file, declare the external Durable Object binding and the Service binding to `SessionsRPC`:

	```toml title="next-rpc/wrangler.toml" ins={10-18}
	# ... rest of the configuration
	compatibility_flags = ["nodejs_compat"]

	# Minification helps to keep the Worker bundle size down and improve start up time.
	minify = true

	# Use the new Workers + Assets to host the static frontend files
	assets = { directory = ".worker-next/assets", binding = "ASSETS" }

	[[durable_objects.bindings]]
	name = "CURSOR_SESSIONS"
	class_name = "CursorSessions"
	script_name = "worker"

	[[services]]
	binding = "RPC_SERVICE"
	service = "worker"
	entrypoint = "SessionsRPC"
	```

2. Update your `env.d.ts` file for type-safety:
	```ts title="next-rpc/env.d.ts" {2-5}
	interface CloudflareEnv {
		CURSOR_SESSIONS: DurableObjectNamespace<
			import("./worker/src/index").CursorSessions
		>;
		RPC_SERVICE: Service<import("./worker/src/index").SessionsRPC>;
		ASSETS: Fetcher;
	}
	```
3. Include Next.js server side logic:
	- Add a server action to close all active WebSocket connections.
	- Use the RPC method `closeSessions` from the `RPC_SERVICE` Service binding instead of invoking the Durable Object RPC method because of the limitation mentioned in the note above.
	- The server component generates unique IDs using `nanoid` to identify the WebSocket connection within the Durable Object.
	- Set the [`dynamic`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config) value to `force-dynamic` to ensure unique ID generation and avoid static rendering

	```tsx title="src/app/page.tsx" {5,9-10,19,25-27,33}
	import { getCloudflareContext } from "@opennextjs/cloudflare";
	import { Cursors } from "./cursor";
	import { nanoid } from "nanoid";

	export const dynamic = "force-dynamic";

	async function closeSessions() {
		"use server";
		const cf = await getCloudflareContext();
		await cf.env.RPC_SERVICE.closeSessions();

		// Note: Not supported in `wrangler dev`
		// const id = cf.env.CURSOR_SESSIONS.idFromName("globalRoom");
		// const stub = cf.env.CURSOR_SESSIONS.get(id);
		// await stub.closeSessions();
	}

	export default function Home() {
		const id = `ws_${nanoid(50)}`;
		return (
			<main className="flex min-h-screen flex-col items-center p-24 justify-center">
				<div className="border border-dashed w-full">
					<p className="pt-2 px-2">Server Actions</p>
					<div className="p-2">
						<form action={closeSessions}>
							<button className="border px-2 py-1">Close WebSockets</button>
						</form>
					</div>
				</div>
				<div className="border border-dashed w-full mt-2.5">
					<p className="py-2 px-2">Live Cursors</p>
					<div className="px-2 space-y-2">
						<Cursors id={id}></Cursors>
					</div>
				</div>
			</main>
		);
	}
	```

4. Create a client component to manage WebSocket and mouse movement events:

	<Details header="src/app/cursor.tsx">
	```tsx title="src/app/cursor.tsx"
	"use client";
	import { useCallback, useEffect, useLayoutEffect, useReducer, useRef, useState } from "react";
	import type { Session, WsMessage } from "../../worker/src/index";
	import { PerfectCursor } from "perfect-cursors";

	const INTERVAL = 55;

	export function Cursors(props: { id: string }) {
		const wsRef = useRef<WebSocket | null>(null);
		const [cursors, setCursors] = useState<Map<string, Session>>(new Map());
		const lastSentTimestamp = useRef(0);
		const [messageState, dispatchMessage] = useReducer(messageReducer, {
			in: "",
			out: "",
		});
		const [highlightedIn, highlightIn] = useHighlight();
		const [highlightedOut, highlightOut] = useHighlight();

		function startWebSocket() {
			const wsProtocol = window.location.protocol === "https:" ? "wss" : "ws";
			const ws = new WebSocket(
				`${wsProtocol}://${process.env.NEXT_PUBLIC_WS_HOST}/ws?id=${props.id}`,
			);
			ws.onopen = () => {
				highlightOut();
				dispatchMessage({ type: "out", message: "get-cursors" });
				const message: WsMessage = { type: "get-cursors" };
				ws.send(JSON.stringify(message));
			};
			ws.onmessage = (message) => {
				const messageData: WsMessage = JSON.parse(message.data);
				highlightIn();
				dispatchMessage({ type: "in", message: messageData.type });
				switch (messageData.type) {
					case "quit":
						setCursors((prev) => {
							const updated = new Map(prev);
							updated.delete(messageData.id);
							return updated;
						});
						break;
					case "join":
						setCursors((prev) => {
							const updated = new Map(prev);
							if (!updated.has(messageData.id)) {
								updated.set(messageData.id, { id: messageData.id, x: -1, y: -1 });
							}
							return updated;
						});
						break;
					case "move":
						setCursors((prev) => {
							const updated = new Map(prev);
							const session = updated.get(messageData.id);
							if (session) {
								session.x = messageData.x;
								session.y = messageData.y;
							} else {
								updated.set(messageData.id, messageData);
							}
							return updated;
						});
						break;
					case "get-cursors-response":
						setCursors(
							new Map(
								messageData.sessions.map((session) => [session.id, session]),
							),
						);
						break;
					default:
						break;
				}
			};
			ws.onclose = () => setCursors(new Map());
			return ws;
		}

		useEffect(() => {
			const abortController = new AbortController();
			document.addEventListener(
				"mousemove",
				(ev) => {
					const x = ev.pageX / window.innerWidth,
						y = ev.pageY / window.innerHeight;
					const now = Date.now();
					if (
						now - lastSentTimestamp.current > INTERVAL &&
						wsRef.current?.readyState === WebSocket.OPEN
					) {
						const message: WsMessage = { type: "move", id: props.id, x, y };
						wsRef.current.send(JSON.stringify(message));
						lastSentTimestamp.current = now;
						highlightOut();
						dispatchMessage({ type: "out", message: "move" });
					}
				},
				{
					signal: abortController.signal,
				},
			);
			return () => abortController.abort();
			// eslint-disable-next-line react-hooks/exhaustive-deps
		}, []);

		useEffect(() => {
			wsRef.current = startWebSocket();
			return () => wsRef.current?.close();
			// eslint-disable-next-line react-hooks/exhaustive-deps
		}, [props.id]);

		function sendMessage() {
			highlightOut();
			dispatchMessage({ type: "out", message: "message" });
			wsRef.current?.send(
				JSON.stringify({ type: "message", data: "Ping" } satisfies WsMessage),
			);
		}

		const otherCursors = Array.from(cursors.values()).filter(
			({ id, x, y }) => id !== props.id && x !== -1 && y !== -1,
		);

		return (
			<>
				<div className="flex border">
					<div className="px-2 py-1 border-r">WebSocket Connections</div>
					<div className="px-2 py-1"> {cursors.size} </div>
				</div>
				<div className="flex border">
					<div className="px-2 py-1 border-r">Messages</div>
					<div className="flex flex-1">
						<div className="px-2 py-1 border-r">↓</div>
						<div
							className="w-full px-2 py-1 [word-break:break-word] transition-colors duration-500"
							style={{
								backgroundColor: highlightedIn ? "#ef4444" : "transparent",
							}}
						>
							{messageState.in}
						</div>
					</div>
					<div className="flex flex-1">
						<div className="px-2 py-1 border-x">↑</div>
						<div
							className="w-full px-2 py-1 [word-break:break-word] transition-colors duration-500"
							style={{
								backgroundColor: highlightedOut ? "#60a5fa" : "transparent",
							}}
						>
							{messageState.out}
						</div>
					</div>
				</div>
				<div className="flex gap-2">
					<button onClick={sendMessage} className="border px-2 py-1">
						ws message
					</button>
					<button
						className="border px-2 py-1 disabled:opacity-80"
						onClick={() => {
							wsRef.current?.close();
							wsRef.current = startWebSocket();
						}}
					>
						ws reconnect
					</button>
					<button
						className="border px-2 py-1"
						onClick={() => wsRef.current?.close()}
					>
						ws close
					</button>
				</div>
				<div>
					{otherCursors.map((session) => (
						<SvgCursor
							key={session.id}
							point={[
								session.x * window.innerWidth,
								session.y * window.innerHeight,
							]}
						/>
					))}
				</div>
			</>
		);
	}

	function SvgCursor({ point }: { point: number[] }) {
		const refSvg = useRef<SVGSVGElement>(null);
		const animateCursor = useCallback((point: number[]) => {
			refSvg.current?.style.setProperty(
				"transform",
				`translate(${point[0]}px, ${point[1]}px)`,
			);
		}, []);
		const onPointMove = usePerfectCursor(animateCursor);
		useLayoutEffect(() => onPointMove(point), [onPointMove, point]);
		const [randomColor] = useState(
			`#${Math.floor(Math.random() * 16777215)
				.toString(16)
				.padStart(6, "0")}`,
		);
		return (
			<svg
				ref={refSvg}
				height="32"
				width="32"
				viewBox="0 0 32 32"
				xmlns="http://www.w3.org/2000/svg"
				className={"absolute -top-[12px] -left-[12px] pointer-events-none"}
			>
				<defs>
					<filter id="shadow" x="-40%" y="-40%" width="180%" height="180%">
						<feDropShadow dx="1" dy="1" stdDeviation="1.2" floodOpacity="0.5" />
					</filter>
				</defs>
				<g fill="none" transform="rotate(0 16 16)" filter="url(#shadow)">
					<path
						d="M12 24.4219V8.4069L23.591 20.0259H16.81l-.411.124z"
						fill="white"
					/>
					<path
						d="M21.0845 25.0962L17.4795 26.6312L12.7975 15.5422L16.4835 13.9892z"
						fill="white"
					/>
					<path
						d="M19.751 24.4155L17.907 25.1895L14.807 17.8155L16.648 17.04z"
						fill={randomColor}
					/>
					<path
						d="M13 10.814V22.002L15.969 19.136l.428-.139h4.768z"
						fill={randomColor}
					/>
				</g>
			</svg>
		);
	}

	function usePerfectCursor(cb: (point: number[]) => void, point?: number[]) {
		const [pc] = useState(() => new PerfectCursor(cb));

		useLayoutEffect(() => {
			if (point) pc.addPoint(point);
			return () => pc.dispose();
			// eslint-disable-next-line react-hooks/exhaustive-deps
		}, [pc]);

		useLayoutEffect(() => {
			PerfectCursor.MAX_INTERVAL = 58;
		}, []);

		const onPointChange = useCallback(
			(point: number[]) => pc.addPoint(point),
			[pc],
		);

		return onPointChange;
	}

	type MessageState = { in: string; out: string };
	type MessageAction = { type: "in" | "out"; message: string };
	function messageReducer(state: MessageState, action: MessageAction) {
		switch (action.type) {
			case "in":
				return { ...state, in: action.message };
			case "out":
				return { ...state, out: action.message };
			default:
				return state;
		}
	}

	function useHighlight(duration = 250) {
		const timestampRef = useRef(0);
		const [highlighted, setHighlighted] = useState(false);
		function highlight() {
			timestampRef.current = Date.now();
			setHighlighted(true);
			setTimeout(() => {
				const now = Date.now();
				if (now - timestampRef.current >= duration) {
					setHighlighted(false);
				}
			}, duration);
		}
		return [highlighted, highlight] as const;
	}
	```
	</Details>
	The generated ID is used here and passed as a parameter to the WebSocket server:

	```ts
	const ws = new WebSocket(
		`${wsProtocol}://${process.env.NEXT_PUBLIC_WS_HOST}/ws?id=${props.id}`,
	);
	```

	The component starts the WebSocket connection and handles 4 types of WebSocket messages, which trigger updates to React's state:
		- `join`. Received when a new WebSocket connection is established.
		- `quit`. Received when a WebSocket connection is closed.
		- `move`. Received when a user's cursor moves.
		- `get-cursors-response`. Received	when a client sends a `get-cursors` message, which is triggered once the WebSocket connection is open.

	It sends the user's cursor coordinates to the WebSocket server during the [`mousemove`](https://developer.mozilla.org/en-US/docs/Web/API/Element/mousemove_event) event, which then broadcasts them to all active WebSocket clients.

	Although there are multiple strategies you can use together for real-time cursor synchronization (e.g., batching, interpolation, etc.), in this tutorial throttling, spline interpolation and position normalization are used:

	```ts {4-5,8-9}
	document.addEventListener(
		"mousemove",
		(ev) => {
			const x = ev.pageX / window.innerWidth,
				y = ev.pageY / window.innerHeight;
			const now = Date.now();
			if (
					now - lastSentTimestamp.current > INTERVAL &&
					wsRef.current?.readyState === WebSocket.OPEN
			) {
				const message: WsMessage = { type: "move", id: props.id, x, y };
				wsRef.current.send(JSON.stringify(message));
				lastSentTimestamp.current = now;
				// ...
			}
		}
	);
	```

	Each animated cursor is controlled by a `PerfectCursor` instance, which animates its position along a spline curve defined by the cursor's latest positions:
	```ts {9-11}
	// SvgCursor react component
	const refSvg = useRef<SVGSVGElement>(null);
	const animateCursor = useCallback((point: number[]) => {
		refSvg.current?.style.setProperty(
			"transform",
			`translate(${point[0]}px, ${point[1]}px)`,
		);
	}, []);
	const onPointMove = usePerfectCursor(animateCursor);
	// A `point` is added to the path whenever its vule updates;
	useLayoutEffect(() => onPointMove(point), [onPointMove, point]);
	// ...
	```


5. Run Next.js development server:
	:::note[Note]
	The Durable Object Worker must also be running.
	:::
	<PackageManagers type="run" pkg="dev" frame="none" />

6. Open the App in the browser.

</Steps>


## 5. Deploy the project

<Steps>
1. Change into your Durable Object Worker directory:
	```sh
	cd worker
	```

	Deploy the Worker:
	<PackageManagers type="run" pkg="deploy" frame="none" />

	Copy only the host from the generated Worker URL, excluding the protocol, and set `NEXT_PUBLIC_WS_HOST` in `.env.local` to this value (e.g., `worker-unique-identifier.workers.dev`).

	```txt title="next-rpc/.env.local" ins={2} del={1}
	NEXT_PUBLIC_WS_HOST=localhost:8787
	NEXT_PUBLIC_WS_HOST=worker-unique-identifier.workers.dev
	```

2. Change into your root directory and deploy your Next.js app:
	:::note[Optional Step]
	Invoking Durable Object RPC methods between separate workers are fully supported in Cloudflare deployments. You can opt to use them instead of Service Bindings RPC:
	```ts title="src/app/page.tsx" ins={7-9} del={4}
	async function closeSessions() {
		"use server";
		const cf = await getCloudflareContext();
		await cf.env.RPC_SERVICE.closeSessions();

		// Note: Not supported in `wrangler dev`
		const id = cf.env.CURSOR_SESSIONS.idFromName("globalRoom");
		const stub = cf.env.CURSOR_SESSIONS.get(id);
		await stub.closeSessions();
	}
	```
	:::

	<PackageManagers type="run" pkg="deploy" frame="none" />


</Steps>


## Summary

In this tutorial, you learned how to integrate Next.js with Durable Objects to build a real-time application to visualize cursors. You also learned how to use Workers' built-in RPC system alongside Next.js server actions. The complete code for this tutorial is available on [GitHub](https://github.com/exectx/next-live-cursors-do-rpc).

## Related resources

You can check other Cloudflare tutorials or related resources:

- [Workers RPC](/workers/runtime-apis/bindings/service-bindings/rpc/).
- [Next.js and Workers Static Assets](/workers/framework-guides/web-apps/nextjs/).
- [Build a seat booking app with SQLite in Durable Objects](/durable-objects/tutorials/build-a-seat-booking-app/).

---

# Connect to a MySQL database with Cloudflare Workers

URL: https://developers.cloudflare.com/workers/tutorials/mysql/

import { Render, PackageManagers, WranglerConfig } from "~/components";

In this tutorial, you will learn how to create a Cloudflare Workers application and connect it to a MySQL database using [TCP Sockets](/workers/runtime-apis/tcp-sockets/) and [Hyperdrive](/hyperdrive/). The Workers application you create in this tutorial will interact with a product database inside of MySQL.

:::note[Note]

We recommend using [Hyperdrive](/hyperdrive/) to connect to your MySQL database. Hyperdrive provides optimal performance and will ensure secure connectivity between your Worker and your MySQL database.

When connecting directly to your MySQL database (without Hyperdrive), the MySQL drivers rely on unsupported Node.js APIs to create secure connections, which prevents connections.
:::

## Prerequisites

To continue:

1. Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages) if you have not already.
2. Install [`npm`](https://docs.npmjs.com/getting-started).
3. Install [`Node.js`](https://nodejs.org/en/). Use a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change Node.js versions. [Wrangler](/workers/wrangler/install-and-update/) requires a Node version of `16.17.0` or later.
4. Make sure you have access to a MySQL database.

## 1. Create a Worker application

First, use the [`create-cloudflare` CLI](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare) to create a new Worker application. To do this, open a terminal window and run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"mysql-tutorial"}
/>

This will prompt you to install the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) package and lead you through a setup wizard.

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

If you choose to deploy, you will be asked to authenticate (if not logged in already), and your project will be deployed. If you deploy, you can still modify your Worker code and deploy again at the end of this tutorial.

Now, move into the newly created directory:

```sh
cd mysql-tutorial
```

## 2. Enable Node.js compatibility

[Node.js compatibility](/workers/runtime-apis/nodejs/) is required for database drivers, including mysql2, and needs to be configured for your Workers project.

<Render file="nodejs_compat" product="workers" />

## 3. Create a Hyperdrive configuration

Create a Hyperdrive configuration using the connection string for your MySQL database.

```bash
npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="mysql://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"
```

This command outputs the Hyperdrive configuration `id` that will be used for your Hyperdrive [binding](/workers/runtime-apis/bindings/). Set up your binding by specifying the `id` in the Wrangler file.

<WranglerConfig>

```toml {7-9}
name = "hyperdrive-example"
main = "src/index.ts"
compatibility_date = "2024-08-21"
compatibility_flags = ["nodejs_compat"]

# Pasted from the output of `wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string=[...]` above.
[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"
```

</WranglerConfig>

## 4. Query your database from your Worker

<Render file="use-mysql2-to-make-query" product="hyperdrive" />

## 5. Deploy your Worker

Run the following command to deploy your Worker:

```sh
npx wrangler deploy
```

Your application is now live and accessible at `<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev`.

## Next steps

To build more with databases and Workers, refer to [Tutorials](/workers/tutorials) and explore the [Databases documentation](/workers/databases).

If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on [Discord](https://discord.cloudflare.com) to connect with fellow developers and the Cloudflare team.

---

# OpenAI GPT function calling with JavaScript and Cloudflare Workers

URL: https://developers.cloudflare.com/workers/tutorials/openai-function-calls-workers/

import { Render, PackageManagers } from "~/components";

In this tutorial, you will build a project that leverages [OpenAI's function calling](https://platform.openai.com/docs/guides/function-calling) feature, available in OpenAI's latest Chat Completions API models.

The function calling feature allows the AI model to intelligently decide when to call a function based on the input, and respond in JSON format to match the function's signature. You will use the function calling feature to request for the model to determine a website URL which contains information relevant to a message from the user, retrieve the text content of the site, and, finally, return a final response from the model informed by real-time web data.

## What you will learn

- How to use OpenAI's function calling feature.
- Integrating OpenAI's API in a Cloudflare Worker.
- Fetching and processing website content using Cheerio.
- Handling API responses and function calls in JavaScript.
- Storing API keys as secrets with Wrangler.

---

<Render file="tutorials-before-you-start" />

## 1. Create a new Worker project

Create a Worker project in the command line:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"openai-function-calling-workers"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "JavaScript",
	}}
/>

Go to your new `openai-function-calling-workers` Worker project:

```sh
cd openai-function-calling-workers
```

Inside of your new `openai-function-calling-workers` directory, find the `src/index.js` file. You will configure this file for most of the tutorial.

You will also need an OpenAI account and API key for this tutorial. If you do not have one, [create a new OpenAI account](https://platform.openai.com/signup) and [create an API key](https://platform.openai.com/account/api-keys) to continue with this tutorial. Make sure to store you API key somewhere safe so you can use it later.

## 2. Make a request to OpenAI

With your Worker project created, make your first request to OpenAI. You will use the OpenAI node library to interact with the OpenAI API. In this project, you will also use the Cheerio library to handle processing the HTML content of websites

<PackageManagers pkg="openai cheerio" />

Now, define the structure of your Worker in `index.js`:

```js
export default {
	async fetch(request, env, ctx) {
		// Initialize OpenAI API
		// Handle incoming requests
		return new Response("Hello World!");
	},
};
```

Above `export default`, add the imports for `openai` and `cheerio`:

```js
import OpenAI from "openai";
import * as cheerio from "cheerio";
```

Within your `fetch` function, instantiate your `OpenAI` client:

```js
async fetch(request, env, ctx) {
  const openai = new OpenAI({
    apiKey: env.OPENAI_API_KEY,
  });

  // Handle incoming requests
  return new Response('Hello World!');
},
```

Use [`wrangler secret put`](/workers/wrangler/commands/#put) to set `OPENAI_API_KEY`. This [secret's](/workers/configuration/secrets/) value is the API key you created earlier in the OpenAI dashboard:

```sh
npx wrangler secret put <OPENAI_API_KEY>
```

For local development, create a new file `.dev.vars` in your Worker project and add this line. Make sure to replace `OPENAI_API_KEY` with your own OpenAI API key:

```txt
OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"
```

Now, make a request to the OpenAI [Chat Completions API](https://platform.openai.com/docs/guides/gpt/chat-completions-api):

```js
export default {
	async fetch(request, env, ctx) {
		const openai = new OpenAI({
			apiKey: env.OPENAI_API_KEY,
		});

		const url = new URL(request.url);
		const message = url.searchParams.get("message");

		const messages = [
			{
				role: "user",
				content: message ? message : "What's in the news today?",
			},
		];

		const tools = [
			{
				type: "function",
				function: {
					name: "read_website_content",
					description: "Read the content on a given website",
					parameters: {
						type: "object",
						properties: {
							url: {
								type: "string",
								description: "The URL to the website to read",
							},
						},
						required: ["url"],
					},
				},
			},
		];

		const chatCompletion = await openai.chat.completions.create({
			model: "gpt-4o-mini",
			messages: messages,
			tools: tools,
			tool_choice: "auto",
		});

		const assistantMessage = chatCompletion.choices[0].message;
		console.log(assistantMessage);

		//Later you will continue handling the assistant's response here
		return new Response(assistantMessage.content);
	},
};
```

Review the arguments you are passing to OpenAI:

- **model**: This is the model you want OpenAI to use for your request. In this case, you are using `gpt-4o-mini`.
- **messages**: This is an array containing all messages that are part of the conversation. Initially you provide a message from the user, and we later add the response from the model. The content of the user message is either the `message` query parameter from the request URL or the default "What's in the news today?".
- **tools**: An array containing the actions available to the AI model. In this example you only have one tool, `read_website_content`, which reads the content on a given website.
  - **name**: The name of your function. In this case, it is `read_website_content`.
  - **description**: A short description that lets the model know the purpose of the function. This is optional but helps the model know when to select the tool.
  - **parameters**: A JSON Schema object which describes the function. In this case we request a response containing an object with the required property `url`.
- **tool_choice**: This argument is technically optional as `auto` is the default. This argument indicates that either a function call or a normal message response can be returned by OpenAI.

## 3. Building your `read_website_content()` function

You will now need to define the `read_website_content` function, which is referenced in the `tools` array. The `read_website_content` function fetches the content of a given URL and extracts the text from `<p>` tags using the `cheerio` library:

Add this code above the `export default` block in your `index.js` file:

```js
async function read_website_content(url) {
	console.log("reading website content");

	const response = await fetch(url);
	const body = await response.text();
	let cheerioBody = cheerio.load(body);
	const resp = {
		website_body: cheerioBody("p").text(),
		url: url,
	};
	return JSON.stringify(resp);
}
```

In this function, you take the URL that you received from OpenAI and use JavaScript's [`Fetch API`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) to pull the content of the website and extract the paragraph text. Now we need to determine when to call this function.

## 4. Process the Assistant's Messages

Next, we need to process the response from the OpenAI API to check if it includes any function calls. If a function call is present, you should execute the corresponding function in your Worker. Note that the assistant may request multiple function calls.

Modify the fetch method within the `export default` block as follows:

```js
// ... your previous code ...

if (assistantMessage.tool_calls) {
	for (const toolCall of assistantMessage.tool_calls) {
		if (toolCall.function.name === "read_website_content") {
			const url = JSON.parse(toolCall.function.arguments).url;
			const websiteContent = await read_website_content(url);
			messages.push({
				role: "tool",
				tool_call_id: toolCall.id,
				name: toolCall.function.name,
				content: websiteContent,
			});
		}
	}

	const secondChatCompletion = await openai.chat.completions.create({
		model: "gpt-4o-mini",
		messages: messages,
	});

	return new Response(secondChatCompletion.choices[0].message.content);
} else {
	// this is your existing return statement
	return new Response(assistantMessage.content);
}
```

Check if the assistant message contains any function calls by checking for the `tool_calls` property. Because the AI model can call multiple functions by default, you need to loop through any potential function calls and add them to the `messages` array. Each `read_website_content` call will invoke the `read_website_content` function you defined earlier and pass the URL generated by OpenAI as an argument. \`

The `secondChatCompletion` is needed to provide a response informed by the data you retrieved from each function call. Now, the last step is to deploy your Worker.

Test your code by running `npx wrangler dev` and open the provided url in your browser. This will now show you OpenAI’s response using real-time information from the retrieved web data.

## 5. Deploy your Worker application

To deploy your application, run the `npx wrangler deploy` command to deploy your Worker application:

```sh
npx wrangler deploy
```

You can now preview your Worker at `<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev`. Going to this URL will display the response from OpenAI. Optionally, add the `message` URL parameter to write a custom message: for example, `https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/?message=What is the weather in NYC today?`.

## 6. Next steps

Reference the [finished code for this tutorial on GitHub](https://github.com/LoganGrasby/Cloudflare-OpenAI-Functions-Demo/blob/main/src/worker.js).

To continue working with Workers and AI, refer to [the guide on using LangChain and Cloudflare Workers together](https://blog.cloudflare.com/langchain-and-cloudflare/) or [how to build a ChatGPT plugin with Cloudflare Workers](https://blog.cloudflare.com/magic-in-minutes-how-to-build-a-chatgpt-plugin-with-cloudflare-workers/).

If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on [Discord](https://discord.cloudflare.com) to connect with fellow developers and the Cloudflare team.

---

# Connect to a PostgreSQL database with Cloudflare Workers

URL: https://developers.cloudflare.com/workers/tutorials/postgres/

import { Render, PackageManagers, WranglerConfig } from "~/components";

In this tutorial, you will learn how to create a Cloudflare Workers application and connect it to a PostgreSQL database using [TCP Sockets](/workers/runtime-apis/tcp-sockets/) and [Hyperdrive](/hyperdrive/). The Workers application you create in this tutorial will interact with a product database inside of PostgreSQL.

## Prerequisites

To continue:

1. Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages) if you have not already.
2. Install [`npm`](https://docs.npmjs.com/getting-started).
3. Install [`Node.js`](https://nodejs.org/en/). Use a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change Node.js versions. [Wrangler](/workers/wrangler/install-and-update/) requires a Node version of `16.17.0` or later.
4. Make sure you have access to a PostgreSQL database.

## 1. Create a Worker application

First, use the [`create-cloudflare` CLI](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare) to create a new Worker application. To do this, open a terminal window and run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"postgres-tutorial"}
/>

This will prompt you to install the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) package and lead you through a setup wizard.

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

If you choose to deploy, you will be asked to authenticate (if not logged in already), and your project will be deployed. If you deploy, you can still modify your Worker code and deploy again at the end of this tutorial.

Now, move into the newly created directory:

```sh
cd postgres-tutorial
```

### Enable Node.js compatibility

[Node.js compatibility](/workers/runtime-apis/nodejs/) is required for database drivers, including Postgres.js, and needs to be configured for your Workers project.

<Render file="nodejs_compat" product="workers" />

## 2. Add the PostgreSQL connection library

To connect to a PostgreSQL database, you will need the `postgres` library. In your Worker application directory, run the following command to install the library:

<PackageManagers pkg="postgres" />

Make sure you are using `postgres` (`Postgres.js`) version `3.4.4` or higher. `Postgres.js` is compatible with both Pages and Workers.

## 3. Configure the connection to the PostgreSQL database

Choose one of the two methods to connect to your PostgreSQL database:

1. [Use a connection string](#use-a-connection-string).
2. [Set explicit parameters](#set-explicit-parameters).

### Use a connection string

A connection string contains all the information needed to connect to a database. It is a URL that contains the following information:

```
postgresql://username:password@host:port/database
```

Replace `username`, `password`, `host`, `port`, and `database` with the appropriate values for your PostgreSQL database.

Set your connection string as a [secret](/workers/configuration/secrets/) so that it is not stored as plain text. Use [`wrangler secret put`](/workers/wrangler/commands/#secret) with the example variable name `DB_URL`:

```sh
npx wrangler secret put DB_URL
```

```sh output
➜  wrangler secret put DB_URL
-------------------------------------------------------
? Enter a secret value: › ********************
✨ Success! Uploaded secret DB_URL
```

Set your `DB_URL` secret locally in a `.dev.vars` file as documented in [Local Development with Secrets](/workers/configuration/secrets/).

```toml title='.dev.vars'
DB_URL="<ENTER YOUR POSTGRESQL CONNECTION STRING>"
```

### Set explicit parameters

Configure each database parameter as an [environment variable](/workers/configuration/environment-variables/) via the [Cloudflare dashboard](/workers/configuration/environment-variables/#add-environment-variables-via-the-dashboard) or in your Wrangler file. Refer to an example of aWrangler file configuration:

<WranglerConfig>

```toml
[vars]
DB_USERNAME = "postgres"
# Set your password by creating a secret so it is not stored as plain text
DB_HOST = "ep-aged-sound-175961.us-east-2.aws.neon.tech"
DB_PORT = "5432"
DB_NAME = "productsdb"
```

</WranglerConfig>

To set your password as a [secret](/workers/configuration/secrets/) so that it is not stored as plain text, use [`wrangler secret put`](/workers/wrangler/commands/#secret). `DB_PASSWORD` is an example variable name for this secret to be accessed in your Worker:

```sh
npx wrangler secret put DB_PASSWORD
```

```sh output
-------------------------------------------------------
? Enter a secret value: › ********************
✨ Success! Uploaded secret DB_PASSWORD
```

## 4. Connect to the PostgreSQL database in the Worker

Open your Worker's main file (for example, `worker.ts`) and import the `Client` class from the `pg` library:

```typescript
import postgres from "postgres";
```

In the `fetch` event handler, connect to the PostgreSQL database using your chosen method, either the connection string or the explicit parameters.

### Use a connection string

```typescript
const sql = postgres(env.DB_URL);
```

### Set explicit parameters

```typescript
const sql = postgres({
	username: env.DB_USERNAME,
	password: env.DB_PASSWORD,
	host: env.DB_HOST,
	port: env.DB_PORT,
	database: env.DB_NAME,
});
```

## 5. Interact with the products database

To demonstrate how to interact with the products database, you will fetch data from the `products` table by querying the table when a request is received.

:::note

If you are following along in your own PostgreSQL instance, set up the `products` using the following SQL `CREATE TABLE` statement. This statement defines the columns and their respective data types for the `products` table:

```sql
CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  description TEXT,
  price DECIMAL(10, 2) NOT NULL
);
```

:::

Replace the existing code in your `worker.ts` file with the following code:

```typescript
import postgres from "postgres";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const sql = postgres(env.DB_URL, {
			// Workers limit the number of concurrent external connections, so be sure to limit
			// the size of the local connection pool that postgres.js may establish.
			max: 5,

			// If you are using array types in your Postgres schema, it is necessary to fetch
			// type information to correctly de/serialize them. However, if you are not using
			// those, disabling this will save you an extra round-trip every time you connect.
			fetch_types: false,
		});

		// Query the products table
		const result = await sql`SELECT * FROM products;`;

		// Return the result as JSON
		const resp = new Response(JSON.stringify(result), {
			headers: { "Content-Type": "application/json" },
		});

		return resp;
	},
} satisfies ExportedHandler<Env>;
```

This code establishes a connection to the PostgreSQL database within your Worker application and queries the `products` table, returning the results as a JSON response.

## 6. Deploy your Worker

Run the following command to deploy your Worker:

```sh
npx wrangler deploy
```

Your application is now live and accessible at `<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev`.

After deploying, you can interact with your PostgreSQL products database using your Cloudflare Worker. Whenever a request is made to your Worker's URL, it will fetch data from the `products` table and return it as a JSON response. You can modify the query as needed to retrieve the desired data from your products database.

## 7. Insert a new row into the products database

To insert a new row into the `products` table, create a new API endpoint in your Worker that handles a `POST` request. When a `POST` request is received with a JSON payload, the Worker will insert a new row into the `products` table with the provided data.

Assume the `products` table has the following columns: `id`, `name`, `description`, and `price`.

Add the following code snippet inside the `fetch` event handler in your `worker.ts` file, before the existing query code:

```typescript {9-32}
import postgres from "postgres";

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const sql = postgres(env.DB_URL);

		const url = new URL(request.url);
		if (request.method === "POST" && url.pathname === "/products") {
			// Parse the request's JSON payload
			const productData = await request.json();

			// Insert the new product into the database
			const values = {
				name: productData.name,
				description: productData.description,
				price: productData.price,
			};
			const insertResult = await sql`
				INSERT INTO products ${sql(values)}
				RETURNING *
			`;

			// Return the inserted row as JSON
			const insertResp = new Response(JSON.stringify(insertResult), {
				headers: { "Content-Type": "application/json" },
			});

			// Clean up the client
			return insertResp;
		}

		// Query the products table
		const result = await sql`SELECT * FROM products;`;

		// Return the result as JSON
		const resp = new Response(JSON.stringify(result), {
			headers: { "Content-Type": "application/json" },
		});

		return resp;
	},
} satisfies ExportedHandler<Env>;
```

This code snippet does the following:

1. Checks if the request is a `POST` request and the URL path is `/products`.
2. Parses the JSON payload from the request.
3. Constructs an `INSERT` SQL query using the provided product data.
4. Executes the query, inserting the new row into the `products` table.
5. Returns the inserted row as a JSON response.

Now, when you send a `POST` request to your Worker's URL with the `/products` path and a JSON payload, the Worker will insert a new row into the `products` table with the provided data. When a request to `/` is made, the Worker will return all products in the database.

After making these changes, deploy the Worker again by running:

```sh
npx wrangler deploy
```

You can now use your Cloudflare Worker to insert new rows into the `products` table. To test this functionality, send a `POST` request to your Worker's URL with the `/products` path, along with a JSON payload containing the new product data:

```json
{
	"name": "Sample Product",
	"description": "This is a sample product",
	"price": 19.99
}
```

You have successfully created a Cloudflare Worker that connects to a PostgreSQL database and handles fetching data and inserting new rows into a products table.

## 8. Use Hyperdrive to accelerate queries

Create a Hyperdrive configuration using the connection string for your PostgreSQL database.

```bash
npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"
```

This command outputs the Hyperdrive configuration `id` that will be used for your Hyperdrive [binding](/workers/runtime-apis/bindings/). Set up your binding by specifying the `id` in the Wrangler file.

<WranglerConfig>

```toml {7-9}
name = "hyperdrive-example"
main = "src/index.ts"
compatibility_date = "2024-08-21"
compatibility_flags = ["nodejs_compat"]

# Pasted from the output of `wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string=[...]` above.
[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"
```

</WranglerConfig>

Create the types for your Hyperdrive binding using the following command:

```bash
npx wrangler types
```

Replace your existing connection string in your Worker code with the Hyperdrive connection string.

```js {3-3}
export default {
	async fetch(request, env, ctx): Promise<Response> {
		const sql = postgres(env.HYPERDRIVE.connectionString)

		const url = new URL(request.url);

		//rest of the routes and database queries
	},
} satisfies ExportedHandler<Env>;

```

## 9. Redeploy your Worker

Run the following command to deploy your Worker:

```sh
npx wrangler deploy
```

Your Worker application is now live and accessible at `<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev`, using Hyperdrive. Hyperdrive accelerates database queries by pooling your connections and caching your requests across the globe.

## Next steps

To build more with databases and Workers, refer to [Tutorials](/workers/tutorials) and explore the [Databases documentation](/workers/databases).

If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on [Discord](https://discord.cloudflare.com) to connect with fellow developers and the Cloudflare team.

---

# Send Emails With Postmark

URL: https://developers.cloudflare.com/workers/tutorials/send-emails-with-postmark/

In this tutorial, you will learn how to send transactional emails from Workers using [Postmark](https://postmarkapp.com/). At the end of this tutorial, you’ll be able to:

- Create a Worker to send emails.
- Sign up and add a Cloudflare domain to Postmark.
- Send emails from your Worker using Postmark.
- Store API keys securely with secrets.

## Prerequisites

To continue with this tutorial, you’ll need:

- A [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages), if you don’t already have one.
- A [registered](/registrar/get-started/register-domain/) domain.
- Installed [npm](https://docs.npmjs.com/getting-started).
- A [Postmark account](https://account.postmarkapp.com/sign_up).

## Create a Worker project

Start by using [C3](/pages/get-started/c3/) to create a Worker project in the command line, then, answer the prompts:

```sh
npm create cloudflare@latest
```

Alternatively, you can use CLI arguments to speed things up:

```sh
npm create cloudflare@latest email-with-postmark -- --type=hello-world --ts=false --git=true --deploy=false
```

This creates a simple hello-world Worker having the following content:

```js
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello World!");
	},
};
```

## Add your domain to Postmark

If you don’t already have a Postmark account, you can sign up for a [free account here](https://account.postmarkapp.com/sign_up). After signing up, check your inbox for a link to confirm your sender signature. This verifies and enables you to send emails from your registered email address.

To enable email sending from other addresses on your domain, navigate to `Sender Signatures` on the Postmark dashboard, `Add Domain or Signature` > `Add Domain`, then type in your domain and click on `Verify Domain`.

Next, you’re presented with a list of DNS records to add to your Cloudflare domain. On your Cloudflare dashboard, select the domain you entered earlier and navigate to `DNS` > `Records`. Copy/paste the DNS records (DKIM, and Return-Path) from Postmark to your Cloudflare domain.

![Image of adding DNS records to a Cloudflare domain](~/assets/images/workers/tutorials/postmarkapp/add_dns_records.png)

:::note

If you need more help adding DNS records in Cloudflare, refer to [Manage DNS records](/dns/manage-dns-records/how-to/create-dns-records/).

:::

When that’s done, head back to Postmark and click on the `Verify` buttons. If all records are properly configured, your domain status should be updated to `Verified`.

![Image of domain verification on the Postmark dashboard](~/assets/images/workers/tutorials/postmarkapp/verified_domain.png)

To grab your API token, navigate to the `Servers` tab, then `My First Server` > `API Tokens`, then copy your API key to a safe place.

## Send emails from your Worker

The final step is putting it all together in a Worker. In your Worker, make a post request with `fetch` to Postmark’s email API and include your token and message body:

:::note

[Postmark’s JavaScript library](https://www.npmjs.com/package/postmark) is currently not supported on Workers. Use the [email API](https://postmarkapp.com/developer/user-guide/send-email-with-api) instead.

:::

```jsx
export default {
	async fetch(request, env, ctx) {
		return await fetch("https://api.postmarkapp.com/email", {
			method: "POST",
			headers: {
				"Content-Type": "application/json",
				"X-Postmark-Server-Token": "your_postmark_api_token_here",
			},
			body: JSON.stringify({
				From: "hello@example.com",
				To: "someone@example.com",
				Subject: "Hello World",
				HtmlBody: "<p>Hello from Workers</p>",
			}),
		});
	},
};
```

To test your code locally, run the following command and navigate to [http://localhost:8787/](http://localhost:8787/) in a browser:

```sh
npm start
```

Deploy your Worker with `npm run deploy`.

## Move API token to Secrets

Sensitive information such as API keys and token should always be stored in secrets. All secrets are encrypted to add an extra layer of protection. That said, it’s a good idea to move your API token to a secret and access it from the environment of your Worker.

To add secrets for local development, create a `.dev.vars` file which works exactly like a `.env` file:

```txt
POSTMARK_API_TOKEN=your_postmark_api_token_here
```

Also ensure the secret is added to your deployed worker by running:

```sh title="Add secret to deployed Worker"
npx wrangler secret put POSTMARK_API_TOKEN
```

The added secret can be accessed on via the `env` parameter passed to your Worker’s fetch event handler:

```jsx
export default {
	async fetch(request, env, ctx) {
		return await fetch("https://api.postmarkapp.com/email", {
			method: "POST",
			headers: {
				"Content-Type": "application/json",
				"X-Postmark-Server-Token": env.POSTMARK_API_TOKEN,
			},
			body: JSON.stringify({
				From: "hello@example.com",
				To: "someone@example.com",
				Subject: "Hello World",
				HtmlBody: "<p>Hello from Workers</p>",
			}),
		});
	},
};
```

And finally, deploy this update with `npm run deploy`.

## Related resources

- [Storing API keys and tokens with Secrets](/workers/configuration/secrets/).
- [Transferring your domain to Cloudflare](/registrar/get-started/transfer-domain-to-cloudflare/).
- [Send emails from Workers](/email-routing/email-workers/send-email-workers/)

---

# Send Emails With Resend

URL: https://developers.cloudflare.com/workers/tutorials/send-emails-with-resend/

In this tutorial, you will learn how to send transactional emails from Workers using [Resend](https://resend.com/). At the end of this tutorial, you’ll be able to:

- Create a Worker to send emails.
- Sign up and add a Cloudflare domain to Resend.
- Send emails from your Worker using Resend.
- Store API keys securely with secrets.

## Prerequisites

To continue with this tutorial, you’ll need:

- A [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages), if you don’t already have one.
- A [registered](/registrar/get-started/register-domain/) domain.
- Installed [npm](https://docs.npmjs.com/getting-started).
- A [Resend account](https://resend.com/signup).

## Create a Worker project

Start by using [C3](/pages/get-started/c3/) to create a Worker project in the command line, then, answer the prompts:

```sh
npm create cloudflare@latest
```

Alternatively, you can use CLI arguments to speed things up:

```sh
npm create cloudflare@latest email-with-resend -- --type=hello-world --ts=false --git=true --deploy=false
```

This creates a simple hello-world Worker having the following content:

```js
export default {
	async fetch(request, env, ctx) {
		return new Response("Hello World!");
	},
};
```

## Add your domain to Resend

If you don’t already have a Resend account, you can sign up for a [free account here](https://resend.com/signup). After signing up, go to `Domains` using the side menu, and click the button to add a new domain. On the modal, enter the domain you want to add and then select a region.

Next, you’re presented with a list of DNS records to add to your Cloudflare domain. On your Cloudflare dashboard, select the domain you entered earlier and navigate to `DNS` > `Records`. Copy/paste the DNS records (DKIM, SPF, and DMARC records) from Resend to your Cloudflare domain.

![Image of adding DNS records to a Cloudflare domain](~/assets/images/workers/tutorials/resend/add_dns_records.png)

:::note

If you need more help adding DNS records in Cloudflare, refer to [Manage DNS records](/dns/manage-dns-records/how-to/create-dns-records/).

:::

When that’s done, head back to Resend and click on the `Verify DNS Records` button. If all records are properly configured, your domain status should be updated to `Verified`.

![Image of domain verification on the Resend dashboard](~/assets/images/workers/tutorials/resend/verified_domain.png)

Lastly, navigate to `API Keys` with the side menu, to create an API key. Give your key a descriptive name and the appropriate permissions. Click the button to add your key and then copy your API key to a safe location.

## Send emails from your Worker

The final step is putting it all together in a Worker. Open up a terminal in the directory of the Worker you created earlier. Then, install the Resend SDK:

```sh
npm i resend
```

In your Worker, import and use the Resend library like so:

```jsx
import { Resend } from "resend";

export default {
	async fetch(request, env, ctx) {
		const resend = new Resend("your_resend_api_key");

		const { data, error } = await resend.emails.send({
			from: "hello@example.com",
			to: "someone@example.com",
			subject: "Hello World",
			html: "<p>Hello from Workers</p>",
		});

		return Response.json({ data, error });
	},
};
```

To test your code locally, run the following command and navigate to [http://localhost:8787/](http://localhost:8787/) in a browser:

```sh
npm start
```

Deploy your Worker with `npm run deploy`.

## Move API keys to Secrets

Sensitive information such as API keys and token should always be stored in secrets. All secrets are encrypted to add an extra layer of protection. That said, it’s a good idea to move your API key to a secret and access it from the environment of your Worker.

To add secrets for local development, create a `.dev.vars` file which works exactly like a `.env` file:

```txt
RESEND_API_KEY=your_resend_api_key
```

Also ensure the secret is added to your deployed worker by running:

```sh title="Add secret to deployed Worker"
npx wrangler secret put RESEND_API_KEY
```

The added secret can be accessed on via the `env` parameter passed to your Worker’s fetch event handler:

```jsx
import { Resend } from "resend";

export default {
	async fetch(request, env, ctx) {
		const resend = new Resend(env.RESEND_API_KEY);

		const { data, error } = await resend.emails.send({
			from: "hello@example.com",
			to: "someone@example.com",
			subject: "Hello World",
			html: "<p>Hello from Workers</p>",
		});

		return Response.json({ data, error });
	},
};
```

And finally, deploy this update with `npm run deploy`.

## Related resources

- [Storing API keys and tokens with Secrets](/workers/configuration/secrets/).
- [Transferring your domain to Cloudflare](/registrar/get-started/transfer-domain-to-cloudflare/).
- [Send emails from Workers](/email-routing/email-workers/send-email-workers/)

---

# Securely access and upload assets with Cloudflare R2

URL: https://developers.cloudflare.com/workers/tutorials/upload-assets-with-r2/

import { Render, PackageManagers, WranglerConfig } from "~/components";

This tutorial explains how to create a TypeScript-based Cloudflare Workers project that can securely access files from and upload files to a [Cloudflare R2](/r2/) bucket. Cloudflare R2 allows developers to store large amounts of unstructured data without the costly egress bandwidth fees associated with typical cloud storage services.

## Prerequisites

To continue:

1. Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages) if you have not already.
2. Install [`npm`](https://docs.npmjs.com/getting-started).
3. Install [`Node.js`](https://nodejs.org/en/). Use a Node version manager like [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm) to avoid permission issues and change Node.js versions. [Wrangler](/workers/wrangler/install-and-update/) requires a Node version of `16.17.0` or later.

## Create a Worker application

First, use the [`create-cloudflare` CLI](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare) to create a new Worker. To do this, open a terminal window and run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args={"upload-r2-assets"}
/>

<Render
	file="c3-post-run-steps"
	product="workers"
	params={{
		category: "hello-world",
		type: "Worker only",
		lang: "TypeScript",
	}}
/>

Move into your newly created directory:

```sh
cd upload-r2-assets
```

## Create an R2 bucket

Before you integrate R2 bucket access into your Worker application, an R2 bucket must be created:

```sh
npx wrangler r2 bucket create <YOUR_BUCKET_NAME>
```

Replace `<YOUR_BUCKET_NAME>` with the name you want to assign to your bucket. List your account's R2 buckets to verify that a new bucket has been added:

```sh
npx wrangler r2 bucket list
```

## Configure access to an R2 bucket

After your new R2 bucket is ready, use it inside your Worker application.

Use your R2 bucket inside your Worker project by modifying the [Wrangler configuration file](/workers/wrangler/configuration/) to include an R2 bucket [binding](/workers/runtime-apis/bindings/). Add the following R2 bucket binding to your Wrangler file:

<WranglerConfig>

```toml
[[r2_buckets]]
binding = 'MY_BUCKET'
bucket_name = '<YOUR_BUCKET_NAME>'
```

</WranglerConfig>

Give your R2 bucket binding name. Replace `<YOUR_BUCKET_NAME>` with the name of the R2 bucket you created earlier.

Your Worker application can now access your R2 bucket using the `MY_BUCKET` variable. You can now perform CRUD (Create, Read, Update, Delete) operations on the contents of the bucket.

## Fetch from an R2 bucket

After setting up an R2 bucket binding, you will implement the functionalities for the Worker to interact with the R2 bucket, such as, fetching files from the bucket and uploading files to the bucket.

To fetch files from the R2 bucket, use the `BINDING.get` function. In the below example, the R2 bucket binding is called `MY_BUCKET`. Using `.get(key)`, you can retrieve an asset based on the URL pathname as the key. In this example, the URL pathname is `/image.png`, and the asset key is `image.png`.

```ts
interface Env {
	MY_BUCKET: R2Bucket;
}
export default {
	async fetch(request, env): Promise<Response> {
		// For example, the request URL my-worker.account.workers.dev/image.png
		const url = new URL(request.url);
		const key = url.pathname.slice(1);
		// Retrieve the key "image.png"
		const object = await env.MY_BUCKET.get(key);

		if (object === null) {
			return new Response("Object Not Found", { status: 404 });
		}

		const headers = new Headers();
		object.writeHttpMetadata(headers);
		headers.set("etag", object.httpEtag);

		return new Response(object.body, {
			headers,
		});
	},
} satisfies ExportedHandler<Env>;
```

The code written above fetches and returns data from the R2 bucket when a `GET` request is made to the Worker application using a specific URL path.

## Upload securely to an R2 bucket

Next, you will add the ability to upload to your R2 bucket using authentication. To securely authenticate your upload requests, use [Wrangler's secret capability](/workers/wrangler/commands/#secret). Wrangler was installed when you ran the `create cloudflare@latest` command.

Create a secret value of your choice -- for instance, a random string or password. Using the Wrangler CLI, add the secret to your project as `AUTH_SECRET`:

```sh
npx wrangler secret put AUTH_SECRET
```

Now, add a new code path that handles a `PUT` HTTP request. This new code will check that the previously uploaded secret is correctly used for authentication, and then upload to R2 using `MY_BUCKET.put(key, data)`:

```ts
interface Env {
	MY_BUCKET: R2Bucket;
	AUTH_SECRET: string;
}
export default {
	async fetch(request, env): Promise<Response> {
		if (request.method === "PUT") {
			// Note that you could require authentication for all requests
			// by moving this code to the top of the fetch function.
			const auth = request.headers.get("Authorization");
			const expectedAuth = `Bearer ${env.AUTH_SECRET}`;

			if (!auth || auth !== expectedAuth) {
				return new Response("Unauthorized", { status: 401 });
			}

			const url = new URL(request.url);
			const key = url.pathname.slice(1);
			await env.MY_BUCKET.put(key, request.body);
			return new Response(`Object ${key} uploaded successfully!`);
		}

		// include the previous code here...
	},
} satisfies ExportedHandler<Env>;
```

This approach ensures that only clients who provide a valid bearer token, via the `Authorization` header equal to the `AUTH_SECRET` value, will be permitted to upload to the R2 bucket. If you used a different binding name than `AUTH_SECRET`, replace it in the code above.

## Deploy your Worker application

After completing your Cloudflare Worker project, deploy it to Cloudflare. Make sure you are in your Worker application directory that you created for this tutorial, then run:

```sh
npx wrangler deploy
```

Your application is now live and accessible at `<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev`.

You have successfully created a Cloudflare Worker that allows you to interact with an R2 bucket to accomplish tasks such as uploading and downloading files. You can now use this as a starting point for your own projects.

## Next steps

To build more with R2 and Workers, refer to [Tutorials](/workers/tutorials/) and the [R2 documentation](/r2/).

If you have any questions, need assistance, or would like to share your project, join the Cloudflare Developer community on [Discord](https://discord.cloudflare.com) to connect with fellow developers and the Cloudflare team.

---

# Set up and use a Prisma Postgres database

URL: https://developers.cloudflare.com/workers/tutorials/using-prisma-postgres-with-workers/

import { PackageManagers } from "~/components";

[Prisma Postgres](https://www.prisma.io/postgres) is a managed, serverless PostgreSQL database. It supports features like connection pooling, caching, real-time subscriptions, and query optimization recommendations.

In this tutorial, you will learn how to:

- Set up a Cloudflare Workers project with [Prisma ORM](https://www.prisma.io/docs).
- Create a Prisma Postgres instance from the Prisma CLI.
- Model data and run migrations with Prisma Postgres.
- Query the database from Workers.
- Deploy the Worker to Cloudflare.

## Prerequisites

To follow this guide, ensure you have the following:

- Node.js `v18.18` or higher installed.
- An active [Cloudflare account](https://dash.cloudflare.com/).
- A basic familiarity with installing and using command-line interface (CLI) applications.

## 1. Create a new Worker project

Begin by using [C3](/pages/get-started/c3/) to create a Worker project in the command line:

```sh
npm create cloudflare@latest prisma-postgres-worker -- --type=hello-world --ts=true --git=true --deploy=false
```

Then navigate into your project:

```sh
cd ./prisma-postgres-worker
```

Your initial `src/index.ts` file currently contains a simple request handler:

```ts title="src/index.ts"
export default {
	async fetch(request, env, ctx): Promise<Response> {
		return new Response("Hello World!");
	},
} satisfies ExportedHandler<Env>;
```

## 2. Setup Prisma in your project

In this step, you will set up Prisma ORM with a Prisma Postgres database using the CLI. Then you will create and execute helper scripts to create tables in the database and generate a Prisma client to query it.

### 2.1. Install required dependencies

Install Prisma CLI as a dev dependency:

<PackageManagers pkg="prisma" dev />

Install the [Prisma Accelerate client extension](https://www.npmjs.com/package/@prisma/extension-accelerate) as it is required for Prisma Postgres:

<PackageManagers pkg="@prisma/extension-accelerate" />

Install the [`dotenv-cli` package](https://www.npmjs.com/package/dotenv-cli) to load environment variables from `.dev.vars`:

<PackageManagers pkg="dotenv-cli" dev />

### 2.2. Create a Prisma Postgres database and initialize Prisma

Initialize Prisma in your application:

<PackageManagers type="dlx" pkg="prisma@latest" args="init --db" />

If you do not have a [Prisma Data Platform](https://console.prisma.io/) account yet, or if you are not logged in, the command will prompt you to log in using one of the available authentication providers. A browser window will open so you can log in or create an account. Return to the CLI after you have completed this step.

Once logged in (or if you were already logged in), the CLI will prompt you to select a project name and a database region.

Once the command has terminated, it will have created:

- A project in your [Platform Console](https://console.prisma.io/) containing a Prisma Postgres database instance.
- A `prisma` folder containing `schema.prisma`, where you will define your database schema.
- An `.env` file in the project root, which will contain the Prisma Postgres database url `DATABASE_URL=<your-prisma-postgres-database-url>`.

Note that Cloudflare Workers do not support `.env` files. You will use a file called `.dev.vars` instead of the `.env` file that was just created.

### 2.3. Prepare environment variables

Rename the `.env` file in the root of your application to `.dev.vars` file:

```sh
mv .env .dev.vars
```

### 2.4. Apply database schema changes

Open the `schema.prisma` file in the `prisma` folder and add the following `User` model to your database:

```prisma title="prisma/schema.prisma"
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id  Int @id @default(autoincrement())
  email String
	name 	String
}
```

Next, add the following helper scripts to the `scripts` section of your `package.json`:

```json title="package.json"
"scripts": {
  "migrate": "dotenv -e .dev.vars -- npx prisma migrate dev",
	"generate": "dotenv -e .dev.vars -- npx prisma generate --no-engine",
	"studio": "dotenv -e .dev.vars -- npx prisma studio",
  // Additional worker scripts...
}
```

Run the migration script to apply changes to the database:

```sh
npm run migrate
```

When prompted, provide a name for the migration (for example, `init`).

After these steps are complete, Prisma ORM is fully set up and connected to your Prisma Postgres database.

## 3. Develop the application

Modify the `src/index.ts` file and replace its contents with the following code:

```ts title="src/index.ts"
import { PrismaClient } from "@prisma/client/edge";
import { withAccelerate } from "@prisma/extension-accelerate";

export interface Env {
	DATABASE_URL: string;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const path = new URL(request.url).pathname;
		if (path === "/favicon.ico")
			return new Response("Resource not found", {
				status: 404,
				headers: {
					"Content-Type": "text/plain",
				},
			});

		const prisma = new PrismaClient({
			datasourceUrl: env.DATABASE_URL,
		}).$extends(withAccelerate());

		const user = await prisma.user.create({
			data: {
				email: `Jon${Math.ceil(Math.random() * 1000)}@gmail.com`,
				name: "Jon Doe",
			},
		});

		const userCount = await prisma.user.count();

		return new Response(`\
Created new user: ${user.name} (${user.email}).
Number of users in the database: ${userCount}.
		`);
	},
} satisfies ExportedHandler<Env>;
```

Run the development server:

```sh
npm run dev
```

Visit [`https://localhost:8787`](https://localhost:8787) to see your app display the following output:

```sh
Number of users in the database: 1
```

Every time you refresh the page, a new user is created. The number displayed will increment by `1` with each refresh as it returns the total number of users in your database.

## 4. Deploy the application to Cloudflare

When the application is deployed to Cloudflare, it needs access to the `DATABASE_URL` environment variable that is defined locally in `.dev.vars`. You can use the [`npx wrangler secret put`](/workers/configuration/secrets/#adding-secrets-to-your-project) command to upload the `DATABASE_URL` to the deployment environment:

```sh
npx wrangler secret put DATABASE_URL
```

When prompted, paste the `DATABASE_URL` value (from `.dev.vars`). If you are logged in via the Wrangler CLI, you will see a prompt asking if you'd like to create a new Worker. Confirm by choosing "yes":

```sh
✔ There doesn't seem to be a Worker called "prisma-postgres-worker". Do you want to create a new Worker with that name and add secrets to it? … yes
```

Then execute the following command to deploy your project to Cloudflare Workers:

```sh
npm run deploy
```

The `wrangler` CLI will bundle and upload your application.

If you are not already logged in, the `wrangler` CLI will open a browser window prompting you to log in to the [Cloudflare dashboard](https://dash.cloudflare.com/).

:::note
If you belong to multiple accounts, select the account where you want to deploy the project.
:::

Once the deployment completes, verify the deployment by visiting the live URL provided in the deployment output, such as `https://{PROJECT_NAME}.workers.dev`. If you encounter any issues, ensure the secrets were added correctly and check the deployment logs for errors.

## Next steps

Congratulations on building and deploying a simple application with Prisma Postgres and Cloudflare Workers!

To enhance your application further:

- Add [caching](https://www.prisma.io/docs/postgres/caching) to your queries.
- Explore the [Prisma Postgres documentation](https://www.prisma.io/docs/postgres/getting-started).

To see how to build a real-time application with Cloudflare Workers and Prisma Postgres, read [this](https://www.prisma.io/docs/guides/prisma-postgres-realtime-on-cloudflare) guide.

---

# Use Workers KV directly from Rust

URL: https://developers.cloudflare.com/workers/tutorials/workers-kv-from-rust/

import { Render, WranglerConfig } from "~/components";

This tutorial will teach you how to read and write to KV directly from Rust
using [workers-rs](https://github.com/cloudflare/workers-rs).

<Render file="tutorials-before-you-start" />

## Prerequisites

To complete this tutorial, you will need:

- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
- [Wrangler](/workers/wrangler/) CLI.
- The [Rust](https://www.rust-lang.org/tools/install) toolchain.
- And `cargo-generate` sub-command by running:

```sh
cargo install cargo-generate
```

## 1. Create your Worker project in Rust

Open a terminal window, and run the following command to generate a Worker project template in Rust:

```sh
cargo generate cloudflare/workers-rs
```

Then select `template/hello-world-http` template, give your project a descriptive name and select enter. A new project should be created in your directory. Open the project in your editor and run `npx wrangler dev` to compile and run your project.

In this tutorial, you will use Workers KV from Rust to build an app to store and retrieve cities by a given country name.

## 2. Create a KV namespace

In the terminal, use Wrangler to create a KV namespace for `cities`. This generates a configuration to be added to the project:

```sh
npx wrangler kv namespace create cities
```

To add this configuration to your project, open the Wrangler file and create an entry for `kv_namespaces` above the build command:

<WranglerConfig>

```toml
kv_namespaces = [
  { binding = "cities", id = "e29b263ab50e42ce9b637fa8370175e8" }
]

# build command...
```

</WranglerConfig>

With this configured, you can access the KV namespace with the binding `"cities"` from Rust.

## 3. Write data to KV

For this app, you will create two routes: A `POST` route to receive and store the city in KV, and a `GET` route to retrieve the city of a given country. For example, a `POST` request to `/France` with a body of `{"city": "Paris"}` should create an entry of Paris as a city in France. A `GET` request to `/France` should retrieve from KV and respond with Paris.

Install [Serde](https://serde.rs/) as a project dependency to handle JSON `cargo add serde`. Then create an app router and a struct for `Country` in `src/lib.rs`:

```rust null {1,6,8,9,10,11,15,17}
use serde::{Deserialize, Serialize};
use worker::*;

#[event(fetch)]
async fn fetch(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    let router = Router::new();

    #[derive(Serialize, Deserialize, Debug)]
    struct Country {
        city: String,
    }

    router
        // TODO:
        .post_async("/:country", |_, _| async move { Response::empty() })
        // TODO:
        .get_async("/:country", |_, _| async move { Response::empty() })
        .run(req, env)
        .await
}

```

For the post handler, you will retrieve the country name from the path and the city name from the request body. Then, you will save this in KV with the country as key and the city as value. Finally, the app will respond with the city name:

```rust
.post_async("/:country", |mut req, ctx| async move {
    let country = ctx.param("country").unwrap();
    let city = match req.json::<Country>().await {
        Ok(c) => c.city,
        Err(_) => String::from(""),
    };
    if city.is_empty() {
        return Response::error("Bad Request", 400);
    };
    return match ctx.kv("cities")?.put(country, &city)?.execute().await {
        Ok(_) => Response::ok(city),
        Err(_) => Response::error("Bad Request", 400),
    };
})
```

Save the file and make a `POST` request to test this endpoint:

```sh
curl --json '{"city": "Paris"}' http://localhost:8787/France
```

## 4. Read data from KV

To retrieve cities stored in KV, write a `GET` route that pulls the country name from the path and searches KV. You also need some error handling if the country is not found:

```rust
.get_async("/:country", |_req, ctx| async move {
    if let Some(country) = ctx.param("country") {
        return match ctx.kv("cities")?.get(country).text().await? {
            Some(city) => Response::ok(city),
            None => Response::error("Country not found", 404),
        };
    }
    Response::error("Bad Request", 400)
})
```

Save and make a curl request to test the endpoint:

```sh
curl http://localhost:8787/France
```

## 5. Deploy your project

The source code for the completed app should include the following:

```rust
use serde::{Deserialize, Serialize};
use worker::*;

#[event(fetch)]
async fn fetch(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    let router = Router::new();

    #[derive(Serialize, Deserialize, Debug)]
    struct Country {
        city: String,
    }

    router
        .post_async("/:country", |mut req, ctx| async move {
            let country = ctx.param("country").unwrap();
            let city = match req.json::<Country>().await {
                Ok(c) => c.city,
                Err(_) => String::from(""),
            };
            if city.is_empty() {
                return Response::error("Bad Request", 400);
            };
            return match ctx.kv("cities")?.put(country, &city)?.execute().await {
                Ok(_) => Response::ok(city),
                Err(_) => Response::error("Bad Request", 400),
            };
        })
        .get_async("/:country", |_req, ctx| async move {
            if let Some(country) = ctx.param("country") {
                return match ctx.kv("cities")?.get(country).text().await? {
                    Some(city) => Response::ok(city),
                    None => Response::error("Country not found", 404),
                };
            }
            Response::error("Bad Request", 400)
        })
        .run(req, env)
        .await
}
```

To deploy your Worker, run the following command:

```sh
npx wrangler deploy
```

## Related resources

- [Rust support in Workers](/workers/languages/rust/).
- [Using KV in Workers](/kv/get-started/).

---

# Migrate from Wrangler v2 to v3

URL: https://developers.cloudflare.com/workers/wrangler/migration/update-v2-to-v3/

There are no special instructions for migrating from Wrangler v2 to v3. You should be able to update Wrangler by following the instructions in [Install/Update Wrangler](/workers/wrangler/install-and-update/#update-wrangler). You should experience no disruption to your workflow.

:::caution


If you tried to update to Wrangler v3 prior to v3.3, you may have experienced some compatibility issues with older operating systems. Please try again with the latest v3 where those have been resolved.


:::

## Deprecations

Refer to [Deprecations](/workers/wrangler/deprecations/#wrangler-v3) for more details on what is no longer supported in v3.

## Additional assistance

If you do have an issue or need further assistance, [file an issue](https://github.com/cloudflare/workers-sdk/issues/new/choose) in the `workers-sdk` repo on GitHub.

---

# Migrations

URL: https://developers.cloudflare.com/workers/wrangler/migration/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Migrate from Wrangler v3 to v4

URL: https://developers.cloudflare.com/workers/wrangler/migration/update-v3-to-v4/

Wrangler v4 is a major release focused on updates to underlying systems and dependencies, along with improvements to keep Wrangler commands consistent and clear. Unlike previous major versions of Wrangler, which were [foundational rewrites](https://blog.cloudflare.com/wrangler-v2-beta/) and [rearchitectures](https://blog.cloudflare.com/wrangler3/) — Version 4 of Wrangler includes a much smaller set of changes. If you use Wrangler today, your workflow is very unlikely to change.

While many users should expect a no-op upgrade, the following sections outline the more significant changes and steps for migrating where necessary.

### Summary of changes

- **Updated Node.js support policy:**
  Node.js v16, which reached End-of-Life in 2022, is no longer supported in Wrangler v4. Wrangler now follows Node.js's [official support lifecycle](https://nodejs.org/en/about/previous-releases).

- **Upgraded esbuild version**: Wrangler uses [esbuild](https://esbuild.github.io/) to bundle Worker code before deploying it, and was previously pinned to esbuild v0.17.19. Wrangler v4 uses esbuild v0.24, which could impact dynamic wildcard imports. Going forward, Wrangler will be periodically updating the `esbuild` version included with Wrangler, and since `esbuild` is a pre-1.0.0 tool, this may sometimes include breaking changes to how bundling works. In particular, we may bump the `esbuild` version in a Wrangler minor version.

- **Commands default to local mode**: All commands that can run in either local or remote mode now default to local, requiring a `--remote` flag for API queries.

- **Deprecated commands and configurations removed:** Legacy commands, flags, and configurations are removed.

## Detailed Changes

### Updated Node.js support policy

Wrangler now supports only Node.js versions that align with [Node.js's official lifecycle](https://nodejs.org/en/about/previous-releases):

- **Supported**: Current, Active LTS, Maintenance LTS
- **No longer supported:** Node.js v16 (EOL in 2022)

Wrangler tests no longer run on v16, and users still on this version may encounter unsupported behavior. Users still using Node.js v16 must upgrade to a supported version to continue receiving support and compatibility with Wrangler.

### Upgraded esbuild version

Wrangler v4 upgrades esbuild from **v0.17.19** to **v0.24**, bringing improvements (such as the ability to use the `using` keyword with RPC) and changes to bundling behavior:

- **Dynamic imports:** Wildcard imports (for example, `import('./data/' + kind + '.json')`) now automatically include all matching files in the bundle.

Users relying on wildcard dynamic imports may see unwanted files bundled. Prior to esbuild v0.19, `import` statements with dynamic paths ( like `import('./data/' + kind + '.json')`) did not bundle all files matches the glob pattern (`*.json`) . Only files explicitly referenced or included using `find_additional_modules` were bundled. With esbuild v0.19, wildcard imports now automatically bundle all files matching the glob pattern. This could result in unwanted files being bundled, so users might want to avoid wildcard dynamic imports and use explicit imports instead.

### Commands default to local mode

All commands now run in **local mode by default.** Wrangler has many commands for accessing resources like KV and R2, but the commands were previously inconsistent in whether they ran in a local or remote environment. For example, D1 defaulted to querying a local datastore, and required the `--remote` flag to query via the API. KV, on the other hand, previously defaulted to querying via the API (implicitly using the `--remote` flag) and required a `--local` flag to query a local datastore. In order to make the behavior consistent across Wrangler, each command now uses the `--local` flag by default, and requires an explicit `--remote` flag to query via the API.

For example:

- **Previous Behavior (Wrangler v3):** `wrangler kv get` queried remotely by default.
- **New Behavior (Wrangler v4):** `wrangler kv get` queries locally unless `--remote` is specified.

Those using `wrangler kv key` and/or `wrangler r2 object` commands to query or write to their data store will need to add the `--remote` flag in order to replicate previous behavior.

### Deprecated commands and configurations removed

All previously deprecated features in [Wrangler v2](https://developers.cloudflare.com/workers/wrangler/deprecations/#wrangler-v2) and in [Wrangler v3](https://developers.cloudflare.com/workers/wrangler/deprecations/#wrangler-v3) are now removed. Additionally, the following features that were deprecated during the Wrangler v3 release are also now removed:

- Legacy Assets (using `wrangler dev/deploy --legacy-assets` or the `legacy_assets` config file property). Instead, we recommend you [migrate to Workers assets](https://developers.cloudflare.com/workers/static-assets/).
- Legacy Node.js compatibility (using `wrangler dev/deploy --node-compat` or the `node_compat` config file property). Instead, use the [`nodejs_compat` compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs). This includes the functionality from legacy `node_compat` polyfills and natively implemented Node.js APIs.
- `wrangler version`. Instead, use `wrangler --version` to check the current version of Wrangler.
- `getBindingsProxy()` (via `import { getBindingsProxy } from "wrangler"`). Instead, use the [`getPlatformProxy()` API](https://developers.cloudflare.com/workers/wrangler/api/#getplatformproxy), which takes exactly the same arguments.
- `usage_model`. This no longer has any effect, after the [rollout of Workers Standard Pricing](https://blog.cloudflare.com/workers-pricing-scale-to-zero/).

---

# AI & agents

URL: https://developers.cloudflare.com/workers/framework-guides/ai-and-agents/

import {
	Description,
	DirectoryListing
} from "~/components";

<Description>
Create full-stack applications deployed to Cloudflare Workers with AI & agent frameworks.
</Description>

<DirectoryListing folder="workers/framework-guides/ai-and-agents" maxDepth={2}/>

---

# APIs

URL: https://developers.cloudflare.com/workers/framework-guides/apis/

import {
	Description,
	DirectoryListing
} from "~/components";

<Description>
Create full-stack applications deployed to Cloudflare Workers using APIs.
</Description>

<DirectoryListing folder="workers/framework-guides/apis" maxDepth={2}/>

---

# Mobile applications

URL: https://developers.cloudflare.com/workers/framework-guides/mobile-apps/

import {
	Description,
	DirectoryListing
} from "~/components";

<Description>
Create full-stack mobile applications deployed to Cloudflare Workers.
</Description>

<DirectoryListing folder="workers/framework-guides/mobile-apps" maxDepth={2}/>

---

# Astro

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/astro/

import {
	Badge,
	Details,
	Steps,
	WranglerConfig,
	Description,
	InlineBadge,
	Render,
	TabItem,
	Tabs,
	PackageManagers,
} from "~/components";

**Start from CLI**: Scaffold an Astro project on Workers, and pick your template.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-astro-app --framework=astro"
/>

---

**Or just deploy**: Create a static blog with Astro and deploy it on Cloudflare Workers, with CI/CD and previews all set up for you.

[![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create/deploy-to-workers&repository=https://github.com/cloudflare/templates/tree/main/astro-blog-starter-template)

## What is Astro?

[Astro](https://astro.build/) is a JavaScript web framework designed for creating websites that display large amounts of content (such as blogs, documentation sites, or online stores).

Astro emphasizes performance through minimal client-side JavaScript - by default, it renders as much content as possible at build time, or [on-demand](https://docs.astro.build/en/guides/on-demand-rendering/) on the "server" - this can be a Cloudflare Worker. [“Islands”](https://docs.astro.build/en/concepts/islands/) of JavaScript are added only where interactivity or personalization is needed.

Astro is also framework-agnostic, and supports every major UI framework, including React, Preact, Svelte, Vue, SolidJS, via its official [integrations](https://astro.build/integrations/).

## Deploy a new Astro project on Workers

<Steps>
1. **Create a new project with the create-cloudflare CLI (C3).**
    <PackageManagers
    	type="create"
    	pkg="cloudflare@latest"
    	args="my-astro-app --framework=astro"
    />

     <Details header="What's happening behind the scenes?">
     When you run this command, C3 creates a new project directory, initiates [Astro's official setup tool](https://docs.astro.build/en/tutorial/1-setup/2/), and configures the project for Cloudflare. It then offers the option to instantly deploy your application to Cloudflare.

    </Details>

2.  **Develop locally.**

        After creating your project, run the following command in your project directory to start a local development server.

    <PackageManagers type="run" args="dev" />

3.  **Deploy your project.**

        You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly.

        <PackageManagers type="run" args="deploy" />

  </Steps>

## Deploy an existing Astro project on Workers

### If you have a static site

If your Astro project is entirely pre-rendered, follow these steps:

<Steps>
1.  **Add a Wrangler configuration file**

    In your project root, create a Wrangler configuration file with the following content:

    <WranglerConfig>

    ```json
    {
    	"name": "my-astro-app",
    	// Update to today's date
    	"compatibility_date": "2025-03-25",
    	"assets": {
    		"directory": "./dist"
    	}
    }
    ```

    </WranglerConfig>
    <Details header="What's this configuration doing?">
    	The key part of this config is the `assets` field, which tells Wrangler where to find your static assets. In this case, we're telling Wrangler to look in the `./dist` directory. If your assets are in a different directory, update the `directory` value accordingly.
    		Read about other [asset configuration options](/workers/wrangler/configuration/#assets).

    			Also note how there's no `main` field in this config - this is because you're only serving static assets, so no Worker code is needed for on demand rendering/SSR.
    </Details>

2.  **Build and deploy your project**

        		You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly.

        		<PackageManagers type="exec" pkg="astro" args="build" />
        		<PackageManagers type="exec" pkg="wrangler@latest" args="deploy" />

</Steps>

### If your site uses on demand rendering

If your Astro project uses [on demand rendering (also known as SSR)](https://docs.astro.build/en/guides/on-demand-rendering/), follow these steps:

<Steps>
1. **Install the Astro Cloudflare adapter**
		<PackageManagers
			type="exec"
			pkg="astro"
			args="add cloudflare"
		/>

    	<Details header="What's happening behind the scenes?">
    		This command installs the Cloudflare adapter and makes the appropriate changes to your `astro.config.mjs` file in one step. By default, this sets the build output configuration to `output: 'server'`, which server renders all your pages by default. If there are certain pages that *don't* need on demand rendering/SSR, for example static pages like a privacy policy, you should set `export const prerender = true` for that page or route to pre-render it. You can read more about the adapter configuration options [in the Astro docs](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#options).
    	</Details>

2.  **Add a `.assetsignore` file**
    Create a `.assetsignore` file in your `public/` folder, and add the following lines to it:

    ```txt title=".assetsignore"
    _worker.js
    _routes.json
    ```

3.  **Add a Wrangler configuration file**

        In your project root, create a Wrangler configuration file with the following content:

        <WranglerConfig>
        ```json
        {
        	"name": "my-astro-app",
        	"main": "./dist/_worker.js/index.js",
        	// Update to today's date
        	"compatibility_date": "2025-03-25",
        	"compatibility_flags": ["nodejs_compat"],
        	"assets": {
        		"binding": "ASSETS",
        		"directory": "./dist"
        	},
        	"observability": {
        		"enabled": true
        	}
        }
        ```
        </WranglerConfig>
        <Details header="What's this configuration doing?">
        	The key parts of this config are:
        	- `main` points to the entry point of your Worker script. This is generated by the Astro adaptor, and is what powers your server-rendered pages.
        	- `assets.directory` tells Wrangler where to find your static assets. In this case, we're telling Wrangler to look in the `./dist` directory. If your assets are in a different directory, update the `directory` value accordingly.

        	Read more about [Wrangler configuration options](/workers/wrangler/configuration/) and [asset configuration options](/workers/wrangler/configuration/#assets).
        </Details>

4.  **Build and deploy your project**

        		You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly.

        		<PackageManagers type="exec" pkg="astro" args="build" />
        		<PackageManagers type="exec" pkg="wrangler@latest" args="deploy" />

</Steps>

## Bindings

:::note
You cannot use bindings if you're using Astro to generate a purely static site.
:::

With bindings, your Astro application can be fully integrated with the Cloudflare Developer Platform, giving you access to compute, storage, AI and more. Refer to the [bindings overview](/workers/runtime-apis/bindings/) for more information on what's available and how to configure them.

The [Astro docs](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#cloudflare-runtime) provide information about how you can access them in your `locals`.

## Astro's build configuration

The Astro Cloudflare adapter sets the build output configuration to `output: 'server'`, which means all pages are rendered on-demand in your Cloudflare Worker. If there are certain pages that _don't_ need on demand rendering/SSR, for example static pages such as a privacy policy, you should set `export const prerender = true` for that page or route to pre-render it. You can read more about on-demand rendering [in the Astro docs](https://docs.astro.build/en/guides/on-demand-rendering/).

If you want to use Astro as a static site generator, you do not need the Astro Cloudflare adapter. Astro will pre-render all pages at build time by default, and you can simply upload those static assets to be served by Cloudflare.

---

# Web applications

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/

import {
	Description,
	DirectoryListing
} from "~/components";

<Description>
Create full-stack web applications deployed to Cloudflare Workers.
</Description>

<DirectoryListing folder="workers/framework-guides/web-apps" maxDepth={2}/>

---

# Next.js

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/nextjs/

import {
	Description,
	Details,
	Render,
	PackageManagers,
	Steps,
	WranglerConfig,
} from "~/components";

**Start from CLI** - scaffold a Next.js project on Workers.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-next-app --framework=next"
/>

This is a simple getting started guide. For detailed documentation on how the to use the Cloudflare OpenNext adapter, visit the [OpenNext website](https://opennext.js.org/cloudflare).

## What is Next.js?

[Next.js](https://nextjs.org/) is a [React](https://react.dev/) framework for building full stack applications.

Next.js supports Server-side and Client-side rendering, as well as Partial Prerendering which lets you combine static and dynamic components in the same route.

You can deploy your Next.js app to Cloudflare Workers using the OpenNext adaptor.

## Next.js supported features

Most Next.js features are supported by the Cloudflare OpenNext adapter:

| Feature                               | Cloudflare adapter   | Notes                                                                        |
| ------------------------------------- | -------------------- | ---------------------------------------------------------------------------- |
| App Router                            | 🟢 supported         |                                                                              |
| Pages Router                          | 🟢 supported         |                                                                              |
| Route Handlers                        | 🟢 supported         |                                                                              |
| React Server Components               | 🟢 supported         |                                                                              |
| Static Site Generation (SSG)          | 🟢 supported         |                                                                              |
| Server-Side Rendering (SSR)           | 🟢 supported         |                                                                              |
| Incremental Static Regeneration (ISR) | 🟢 supported         |                                                                              |
| Server Actions                        | 🟢 supported         |                                                                              |
| Response streaming                    | 🟢 supported         |                                                                              |
| asynchronous work with `next/after`   | 🟢 supported         |                                                                              |
| Middleware                            | 🟢 supported         |                                                                              |
| Image optimization                    | 🟢 supported         | Supported via [Cloudflare Images](/images/) |
| Partial Prerendering (PPR)            | 🟢 supported         | PPR is experimental in Next.js                                               |
| Composable Caching ('use cache')      | 🟢 supported         | Composable Caching is experimental in Next.js                                |
| Node.js in Middleware                 | ⚪ not yet supported | Node.js middleware introduced in 15.2 are not yet supported                  |

## Deploy a new Next.js project on Workers

<Steps>

1. **Create a new project with the create-cloudflare CLI (C3).**

   <PackageManagers
   	type="create"
   	pkg="cloudflare@latest"
   	args="my-next-app --framework=next"
   />

   <Details header="What's happening behind the scenes?">
   	When you run this command, C3 creates a new project directory, initiates
   	[Next.js's official setup
   	tool](https://nextjs.org/docs/app/api-reference/cli/create-next-app), and
   	configures the project for Cloudflare. It then offers the option to
   	instantly deploy your application to Cloudflare.
   </Details>

2. **Develop locally.**

   After creating your project, run the following command in your project directory to start a local development server.
   The command uses the Next.js development server. It offers the best developer experience by quickly reloading your app every time the source code is updated.

   <PackageManagers type="run" args="dev" />

3. **Test and preview your site with the Cloudflare adapter.**

   <PackageManagers type="run" args="preview" />

   <Details header="What's the difference between dev and preview?">
   	The command used in the previous step uses the Next.js development server,
   	which runs in Node.js. However, your deployed application will run on
   	Cloudflare Workers, which uses the `workerd` runtime. Therefore when
   	running integration tests and previewing your application, you should use
   	the preview command, which is more accurate to production, as it executes
   	your application in the `workerd` runtime using `wrangler dev`.
   </Details>

4. **Deploy your project.**

   You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly.

   <PackageManagers type="run" args="deploy" />

</Steps>

## Deploy an existing Next.js project on Workers

You can convert an existing Next.js application to run on Cloudflare

<Steps>

1.  **Install [`@opennextjs/cloudflare`](https://www.npmjs.com/package/@opennextjs/cloudflare)**

    <PackageManagers pkg="@opennextjs/cloudflare@latest" />

2.  **Install [`wrangler CLI`](https://developers.cloudflare.com/workers/wrangler) as a devDependency**

    <PackageManagers pkg="wrangler@latest" dev />

3.  **Add a Wrangler configuration file**

    In your project root, create a [Wrangler configuration file](/workers/wrangler/configuration/) with the following content:

        		<WranglerConfig>
        		```toml
        			main = ".open-next/worker.js"
        			name = "my-app"
        			compatibility_date = "2025-03-25"
        			compatibility_flags = ["nodejs_compat"]
        			[assets]
        			directory = ".open-next/assets"
        			binding = "ASSETS"
        		```
        	</WranglerConfig>

    :::note
    As shown above, you must enable the [`nodejs_compat` compatibility flag](/workers/runtime-apis/nodejs/) _and_ set your [compatibility date](/workers/configuration/compatibility-dates/) to `2024-09-23` or later for your Next.js app to work with @opennextjs/cloudflare.
    :::

4.  **Add a configuration file for OpenNext**

    In your project root, create an OpenNext configuration file named `open-next.config.ts` with the following content:

    ```ts
    import { defineCloudflareConfig } from "@opennextjs/cloudflare";

    export default defineCloudflareConfig();
    ```

    :::note
    `open-next.config.ts` is where you can configure the caching, see the [adapter documentation](https://opennext.js.org/cloudflare/caching) for more information
    :::

5.  **Update `package.json`**

    You can add the following scripts to your `package.json`:

    ```json
    "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
    "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
    "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
    ```

    <Details header="Usage">
    	- `preview`: Builds your app and serves it locally, allowing you to
    	quickly preview your app running locally in the Workers runtime, via a
    	single command. - `deploy`: Builds your app, and then deploys it to
    	Cloudflare - `cf-typegen`: Generates a `cloudflare-env.d.ts` file at the
    	root of your project containing the types for the env.
    </Details>

6.  **Develop locally.**

    After creating your project, run the following command in your project directory to start a local development server.
    The command uses the Next.js development server. It offers the best developer experience by quickly reloading your app after your source code is updated.

    <PackageManagers type="run" args="dev" />

7.  **Test your site with the Cloudflare adapter.**

    The command used in the previous step uses the Next.js development server to offer a great developer experience.
    However your application will run on Cloudflare Workers so you want to run your integration tests and verify that your application workers correctly in this environment.

    <PackageManagers type="run" args="preview" />

8.  **Deploy your project.**

    You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly.

    <PackageManagers type="run" args="deploy" />

</Steps>

---

# React Router (formerly Remix)

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/react-router/

import {
	Render,
	PackageManagers,
	Steps,
	Details,
	FileTree,
	WranglerConfig,
} from "~/components";

**Start from CLI**: Scaffold a full-stack app with [React Router v7](https://reactrouter.com/) and the [Cloudflare Vite plugin](/workers/vite-plugin/) for lightning-fast development.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-react-router-app --framework=react-router"
/>

**Or just deploy**: Create a full-stack app using React Router v7, with CI/CD and previews all set up for you.

[![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/templates/tree/main/react-router-starter-template)

## What is React Router?

[React Router v7](https://reactrouter.com/) is a full-stack React framework for building web applications.
It combines with the [Cloudflare Vite plugin](/workers/vite-plugin/) to provide a first-class experience for developing, building and deploying your apps on Cloudflare.

## Creating a full-stack React Router app

<Steps>

1.  **Create a new project with the create-cloudflare CLI (C3)**

    <PackageManagers
    	type="create"
    	pkg="cloudflare@latest"
    	args="my-react-router-app --framework=react-router"
    />

    <Details header="How is this project set up?">

        Below is a simplified file tree of the project.

        <FileTree>
        - my-react-router-app
        		- app
        				- routes
        						- ...
        				- entry.server.ts
        				- root.tsx
        				- routes.ts
        	- workers
        			- app.ts
        	- react-router.config.ts
        	- vite.config.ts
        	- wrangler.jsonc
        </FileTree>

        `react-router.config.ts` is your [React Router config file](https://reactrouter.com/explanation/special-files#react-routerconfigts).
        In this file:
        	- `ssr` is set to `true`, meaning that your application will use server-side rendering.
        	- `future.unstable_viteEnvironmentApi` is set to `true` to enable compatibility with the [Cloudflare Vite plugin](/workers/vite-plugin/).

        :::note
        SPA mode and prerendering are not currently supported when using the [Cloudflare Vite plugin](/workers/vite-plugin/).
        If you wish to use React Router in an SPA then we recommend starting with the [React template](/workers/framework-guides/web-apps/react/) and using React Router [as a library](https://reactrouter.com/start/data/installation).
        :::

        `vite.config.ts` is your [Vite config file](https://vite.dev/config/).
        The React Router and Cloudflare plugins are included in the `plugins` array.
        The [Cloudflare Vite plugin](/workers/vite-plugin/) runs your server code in the Workers runtime, ensuring your local development environment is as close to production as possible.

        `wrangler.jsonc` is your [Worker config file](/workers/wrangler/configuration/).
        In this file:
        		- `main` points to `./workers/app.ts`.
        				This is the entry file for your Worker.
        					The default export includes a [`fetch` handler](/workers/runtime-apis/fetch/), which delegates the request to React Router.
        		- If you want to add [bindings](/workers/runtime-apis/bindings/) to resources on Cloudflare's developer platform, you configure them here.

    </Details>

2.  **Develop locally**

        After creating your project, run the following command in your project directory to start a local development server.

        <PackageManagers type="run" args="dev" />

        <Details header="What's happening in local development?">
        		This project uses React Router in combination with the [Cloudflare Vite plugin](/workers/vite-plugin/).
        		This means that your application runs in the Cloudflare Workers runtime, just like in production, and enables access to local emulations of bindings.
        </Details>

3.  **Deploy your project**

        Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/) from your own machine or from any CI/CD system, including Cloudflare's own [Workers Builds](/workers/ci-cd/builds/).

        The following command will build and deploy your project. If you are using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

        <PackageManagers type="run" args={"deploy"} />

</Steps>

## Use bindings with React Router

With bindings, your application can be fully integrated with the Cloudflare Developer Platform, giving you access to compute, storage, AI and more.

Once you have configured the bindings in the Wrangler configuration file, they are then available within `context.cloudflare` in your loader or action functions:

```ts title="app/routes/home.tsx"
export function loader({ context }: Route.LoaderArgs) {
	return { message: context.cloudflare.env.VALUE_FROM_CLOUDFLARE };
}

export default function Home({ loaderData }: Route.ComponentProps) {
	return <Welcome message={loaderData.message} />;
}
```

As you have direct access to your Worker entry file (`workers/app.ts`), you can also add additional exports such as [Durable Objects](/durable-objects/) and [Workflows](/workflows/)

<Details header="Example: Using Workflows">

    Here is an example of how to set up a simple Workflow in your Worker entry file.

    ```ts title="workers/app.ts"
    import { createRequestHandler } from "react-router";
    import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';

    declare global {
    	interface CloudflareEnvironment extends Env {}
    }

    type Env = {
    	MY_WORKFLOW: Workflow;
    };

    export class MyWorkflow extends WorkflowEntrypoint<Env> {
    	override async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    		await step.do("first step", async () => {
    			return { output: "First step result" };
    		});

    		await step.sleep("sleep", "1 second");

    		await step.do("second step", async () => {
    			return { output: "Second step result" };
    		});

    		return "Workflow output";
    	}
    }

    const requestHandler = createRequestHandler(
    	() => import("virtual:react-router/server-build"),
    	import.meta.env.MODE
    );

    export default {
    	async fetch(request, env, ctx) {
    		return requestHandler(request, {
    			cloudflare: { env, ctx },
    		});
    	},
    } satisfies ExportedHandler<CloudflareEnvironment>;
    ```

    Configure it in your Wrangler configuration file:

    <WranglerConfig>

    ```toml
    [[workflows]]
    name = "my-workflow"
    binding = "MY_WORKFLOW"
    class_name = "MyWorkflow"
    ```

    </WranglerConfig>

    And then use it in your application:

    ```ts title="app/routes/home.tsx"
    export function action({ context }: Route.LoaderArgs) {
    	const instance = await env.MY_WORKFLOW.create({ params: { "hello": "world" })
    	return { id: instance.id, details: instance.status() };
    }
    ```

</Details>

<Render file="frameworks-bindings" />

---

# React + Vite

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/react/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
	Details,
	FileTree,
	Steps,
} from "~/components";

**Start from CLI** - scaffold a full-stack app with a React SPA, Cloudflare Workers API, and the [Cloudflare Vite plugin](/workers/vite-plugin/) for lightning-fast development.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-react-app --framework=react"
/>
---

**Or just deploy** - create a full-stack app using React, Hono API and Vite, with CI/CD and previews all set up for you.

[![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create/deploy-to-workers&repository=https://github.com/cloudflare/templates/tree/main/vite-react-template)

## What is React?

[React](https://react.dev/) is a framework for building user interfaces. It allows you to create reusable UI components and manage the state of your application efficiently. You can use React to build a single-page application (SPA), and combine it with a backend API running on Cloudflare Workers to create a full-stack application.

## Creating a full-stack app with React

<Steps>
1. **Create a new project with the create-cloudflare CLI (C3)**

    	<PackageManagers
    		type="create"
    		pkg="cloudflare@latest"
    		args="my-react-app --framework=react"
    	/>
    		 <Details header="How is this project set up?">
        			Below is a simplified file tree of the project.
        			<FileTree>
    							- my-react-app
    								- src/
    										- App.tsx
    								- worker/
    									- index.ts
    								- index.html
    								- vite.config.ts
    								- wrangler.jsonc
        			</FileTree>

        			`wrangler.jsonc` is your [Wrangler configuration file](/workers/wrangler/configuration/).
        			In this file:
        					- `main` points to `worker/index.ts`. This is your Worker, which is going to act as your backend API.
        					- `assets.not_found_handling` is set to `single-page-application`, which means that routes that are handled by your React SPA do not go to the Worker, and are thus free.
        					- If you want to add bindings to resources on Cloudflare's developer platform, you configure them here. Read more about [bindings](/workers/runtime-apis/bindings/).

    						`vite.config.ts` is set up to use the [Cloudflare Vite plugin](/workers/vite-plugin/). This runs your Worker in the Cloudflare Workers runtime, ensuring your local development environment is as close to production as possible.

    						`worker/index.ts` is your backend API, which contains a single endpoint, `/api/`, that returns a text response.
    						At `src/App.tsx`, your React app calls this endpoint to get a message back and displays this.
        		</Details>

2.  **Develop locally with the [Cloudflare Vite plugin](/workers/vite-plugin/)**

        After creating your project, run the following command in your project directory to start a local development server.
        <PackageManagers type="run" args="dev" />
        		<Details header="What's happening in local development?">
        			This project uses Vite for local development and build, and thus comes with all of Vite's features, including hot module replacement (HMR).

        			In addition, `vite.config.ts` is set up to use the Cloudflare Vite plugin. This runs your application in the Cloudflare Workers runtime, just like in production, and enables access to local emulations of bindings.
        		</Details>

3.  **Deploy your project**

        	Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including Cloudflare's own [Workers Builds](/workers/ci-cd/builds/).

        	The following command will build and deploy your project. If you are using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

        	<PackageManagers type="run" args={"deploy"} />

</Steps>

---

## Asset Routing

If you're using React as a SPA, you will want to set `not_found_handling = "single_page_application"` in your Wrangler configuration file.

<Render file="workers-assets-routing-summary" />

## Use bindings with React

Your new project also contains a Worker at `./worker/index.ts`, which you can use as a backend API for your React application. While your React application cannot directly access Workers bindings, it can interact with them through this Worker. You can make [`fetch()` requests](/workers/runtime-apis/fetch/) from your React application to the Worker, which can then handle the request and use bindings. Learn how to [configure Workers bindings](/workers/runtime-apis/bindings/).

<Render file="frameworks-bindings" />

---

# RedwoodSDK

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/redwoodsdk/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
	Steps,
} from "~/components";

In this guide, you will create a new [RedwoodSDK](https://rwsdk.com/) application and deploy it to Cloudflare Workers.

RedwoodSDK is a composable framework for building server-side web apps on Cloudflare. It starts as a Vite plugin that unlocks SSR, React Server Components, Server Functions, and realtime capabilities.

## Deploy a new RedwoodSDK application on Workers

<Steps>
1. **Create a new project.**

	Run the following command, replacing `<project-name>` with your desired project name:
		<PackageManagers
			type="exec"
			pkg="degit"
			args={"redwoodjs/sdk/starters/standard#main <project-name>"}
		/>

2. **Change the directory.**
	```sh
	cd <project-name>
	```

3. **Install dependencies.**
	<PackageManagers type="install" />

4. **Develop locally.**

	Run the following command in the project directory to start a local development server. RedwoodSDK is just a plugin for Vite, so you can use the same dev workflow as any other Vite project:
		<PackageManagers type="run" args={"dev"} />

5. **Deploy your project.**

	You can deploy your project to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), either from your local machine or from any CI/CD system, including [Cloudflare Workers CI/CD](/workers/ci-cd/builds/).

	Use the following command to build and deploy. If you are using CI, make sure to update your [deploy command](/workers/ci-cd/builds/configuration/#build-settings) configuration accordingly.
		<PackageManagers type="run" args={"release"} />

</Steps>

---

# Svelte

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/svelte/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
} from "~/components";

In this guide, you will create a new [Svelte](https://svelte.dev/) application and deploy to Cloudflare Workers (with the new [Workers Assets](/workers/static-assets/)).

## 1. Set up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Svelte's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Svelte project with Workers Assets, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-svelte-app --framework=svelte"
/>

After setting up your project, change your directory by running the following command:

```sh
cd my-svelte-app
```

## 2. Develop locally

After you have created your project, run the following command in the project directory to start a local server. This will allow you to preview your project locally during development.

<PackageManagers type="run" args={"dev"} />

## 3. Deploy your Project

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).

The following command will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

---

## Bindings

Your Svelte application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using product bindings. The [Svelte documentation](https://kit.svelte.dev/docs/adapter-cloudflare#runtime-apis) provides information about configuring bindings and how you can access them in your Svelte hooks and endpoints.

<Render file="frameworks-bindings" />

---

# TanStack

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/tanstack/

import { WranglerConfig, Steps, PackageManagers, Details } from "~/components";

## What is TanStack Start?

TanStack Start is a full-stack React framework powered by TanStack Router. It provides a full-document SSR, streaming, server functions, bundling, and more using Vite and modern web standards.

## Create a new TanStack Start

TanStack Start Beta has significantly improved Cloudflare compatibility compared to the Alpha version, making deployment and development much more straightforward.

<Steps>

1.  **Create a new TanStack Start project**

    ```sh
    npx gitpick TanStack/router/tree/main/examples/react/start-basic start-basic
    cd start-basic
    npm install
    ```
    
    <Details header="How is this project set up?">
    			This command will clone the TanStack Start basic project to your local machine, change directory to the project, and install the dependencies. TanStack [provides other examples](https://tanstack.com/start/latest/docs/framework/react/quick-start#examples) that you can use by replacing `start-basic` with the example you want to use.
    </Details>

2.  **Develop locally**

    After creating your project, run the following command in your project directory to start a local development server. By default this starts a local development server on `http://localhost:3000/`

    <PackageManagers type="run" args="dev" />

</Steps>

## Preparing for Deployment to Cloudflare Workers

Whether you created a new TanStack Start project or are using an existing project, you'll need to make some changes to prepare for deployment to Cloudflare Workers.

<Steps>

1. **Configure Vite for Cloudflare compatibility**

   Update your `vite.config.ts` file to use the `cloudflare-module` target for a compatible build:

   ```ts title="vite.config.ts" {14}
   import { tanstackStart } from "@tanstack/react-start/plugin/vite";
   import { defineConfig } from "vite";
   import tsConfigPaths from "vite-tsconfig-paths";

   export default defineConfig({
     server: {
       port: 3000,
     },
     plugins: [
       tsConfigPaths({
         projects: ["./tsconfig.json"],
       }),
       tanstackStart({
         target: "cloudflare-module", // Key configuration for Cloudflare compatibility
       }),
     ],
   });
   ```

   This single configuration change is all that's needed to make your TanStack Start application compatible with Cloudflare Workers.

2. **Add a Wrangler file**

   Create a `wrangler.jsonc` or `wrangler.toml` file in the root of your project, `wrangler.jsonc` is the recommended approach. This file is used to configure the Cloudflare Workers deployment.

   <WranglerConfig>

   ```json
   {
   	"$schema": "node_modules/wrangler/config-schema.json",
   	"name": "my-start-app",
   	"main": ".output/server/index.mjs",
   	"compatibility_date": "$today",
   	"compatibility_flags": ["nodejs_compat"],
   	"assets": {
   		"directory": ".output/public"
   	},
   	"observability": {
   		"enabled": true
   	},
   	"kv_namespaces": [
   		{
   			"binding": "CACHE",
   			"id": "<Your KV ID>"
   		}
   	]
   }
   ```

   </WranglerConfig>

   Note that the `directory` key is set to `.output/public`, which is the folder that will be filled with the build output. Additionally, the `main` key is set to `.output/server/index.mjs`, indicating to Cloudflare Workers where to locate the entry point for your application. The `kv_namespaces` section shows an example of how to configure a KV namespace binding.

3. **Add deployment scripts to package.json**

   Add the following scripts to your `package.json` file to streamline deployment and type generation:

   ```json title="package.json
   {
     "scripts": {
       ...
       "deploy": "npm run build && wrangler deploy",
       "cf-typegen": "wrangler types --env-interface Env"
     }
   }
   ```

   The `deploy` script combines building and deploying in one command, while `cf-typegen` generates TypeScript types for your Cloudflare bindings.
   
4. **Build the application**

   You must build your application before deploying it to Cloudflare Workers.

   <PackageManagers type="run" args={"build"} />

5. **Deploy the application**

   You can now use the deploy script to build and deploy your application in one command:

   <PackageManagers type="run" args={"deploy"} />

   Alternatively, you can still deploy directly with Wrangler:

   ```sh
   npx wrangler deploy
   ```

</Steps>

## Using Cloudflare Bindings

<Steps>

1. **Generate TypeScript types for your bindings**

   Before using Cloudflare bindings in your code, generate the TypeScript types to ensure proper type safety:

   <PackageManagers type="run" args={"cf-typegen"} />

   This command reads your `wrangler.jsonc` configuration and generates an `Env` interface with all your configured bindings.

2. **Create a helper function to get access to Cloudflare bindings**

   Create a helper function named `bindings.ts` in the `src/utils` folder (create the folder if it doesn't exist), and paste in the below code. The example assumes you have a KV namespace with a binding name of `CACHE` already created in your account and added to the wrangler file.
   

   ```ts title="src/utils/bindings.ts"

   let cachedEnv: Env | null = null;

   // This gets called once at startup when running locally
   const initDevEnv = async () => {
   	const { getPlatformProxy } = await import("wrangler");
   	const proxy = await getPlatformProxy();
   	cachedEnv = proxy.env as unknown as Env;
   };

   if (import.meta.env.DEV) {
   	await initDevEnv();
   }

   /**
    * Will only work when being accessed on the server. Obviously, CF bindings are not available in the browser.
    * @returns
    */
   export function getBindings(): Env {
   	if (import.meta.env.DEV) {
   		if (!cachedEnv) {
   			throw new Error(
   				"Dev bindings not initialized yet. Call initDevEnv() first."
   			);
   		}
   		return cachedEnv;
   	}

   	return process.env as unknown as Env;
   }
   ```

   <Details header="How is this code working?">
   	The helper function uses [getPlatformProxy](/workers/wrangler/api/#getplatformproxy) method from wrangler to provide access to your Cloudflare bindings during local development. The bindings are cached at startup for better performance. In production, bindings are accessed via `process.env`. Make sure you've run `npm run cf-typegen` to generate the `Env` types that this code references.
   </Details>

3. **Example using a Cloudflare Binding in Server Functions**

   Now that you have a helper function to get access to your Cloudflare bindings, you can use them in your server functions.

   Remember bindings are only available on the server.

   ```ts
   import { createServerFn } from "@tanstack/react-start";
   import { getBindings } from "~/utils/bindings";

   const personServerFn = createServerFn({ method: "GET" })
   	.validator((d: string) => d)
   	.handler(async ({ data: name }) => {
   		const env = getBindings();
   		let growingAge = Number((await env.CACHE.get("age")) || 0);
   		growingAge++;
   		await env.CACHE.put("age", growingAge.toString());
   		return { name, randomNumber: growingAge };
   	});
   ```

   A special thanks to GitHub user [backpine](https://github.com/backpine) for the code that supports Cloudflare Bindings in TanStack Start, which is demonstrated in their [TanStack Start Beta on Cloudflare example](https://github.com/backpine/tanstack-start-beta-on-cloudflare).

</Steps>

## Environment Handling

The TanStack Start Beta version provides seamless environment handling:

- **Development**: Bindings are accessed via [`getPlatformProxy()`](/workers/wrangler/api/#getplatformproxy) from Wrangler and cached at startup
- **Production**: Bindings are accessed via [`process.env`](/workers/runtime-apis/nodejs/process/#processenv)

This approach ensures your bindings are properly typed throughout your project and provides a smooth development experience.

By following the steps above, you will have deployed your TanStack Start application to Cloudflare Workers.

---

# Vue

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/vue/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
	Steps,
	Details,
	FileTree,
} from "~/components";

In this guide, you will create a new [Vue](https://vuejs.org/) application and deploy to Cloudflare Workers (with the new [Workers Assets](/workers/static-assets/)).

## 1. Set up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, use code from the official Vue template, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Vue project with Workers Assets, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-vue-app --framework=vue"
/>

    		 <Details header="How is this project set up?">
        			Below is a simplified file tree of the project.
        			<FileTree>
    						- my-vue-app
    							- src/
    									- App.vue
    							- server/
    								- index.ts
    							- index.html
    							- vite.config.ts
    							- wrangler.jsonc
        			</FileTree>

        			`wrangler.jsonc` is your [Wrangler configuration file](/workers/wrangler/configuration/).
        			In this file:
        					- `main` points to `server/index.ts`. This is your Worker, which is going to act as your backend API.
        					- `assets.not_found_handling` is set to `single-page-application`, which means that routes that are handled by your Vue SPA do not go to the Worker, and are thus free.
        					- If you want to add bindings to resources on Cloudflare's developer platform, you configure them here. Read more about [bindings](/workers/runtime-apis/bindings/).

    						`vite.config.ts` is set up to use the [Cloudflare Vite plugin](/workers/vite-plugin/). This runs your Worker in the Cloudflare Workers runtime, ensuring your local development environment is as close to production as possible.

    						`server/index.ts` is your backend API, which contains a single endpoint, `/api/`, that returns a text response.
    						At `src/App.vue`, your Vue app calls this endpoint to get a message back and displays this.
        		</Details>

## **Develop locally with the [Cloudflare Vite plugin](/workers/vite-plugin/)**

After you have created your project, run the following command in the project directory to start a local server. This will allow you to preview your project locally during development.

<PackageManagers type="run" args={"dev"} />
<Details header="What's happening in local development?">
	This project uses Vite for local development and build, and thus comes with
	all of Vite's features, including hot module replacement (HMR). In addition,
	`vite.config.ts` is set up to use the [Cloudflare Vite
	plugin](/workers/vite-plugin/). This runs your application in the Cloudflare
	Workers runtime, just like in production, and enables access to local
	emulations of bindings.
</Details>

## 3. Deploy your project

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).

The following command will build and deploy your project. If you are using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

---

## Asset Routing

If you're using Vue as a SPA, you will want to set `not_found_handling = "single_page_application"` in your Wrangler configuration file.

<Render file="workers-assets-routing-summary" />

## Use bindings with Vue

Your new project also contains a Worker at `./server/index.ts`, which you can use as a backend API for your Vue application. While your Vue application cannot directly access Workers bindings, it can interact with them through this Worker. You can make [`fetch()` requests](/workers/runtime-apis/fetch/) from your Vue application to the Worker, which can then handle the request and use bindings.

<Render file="frameworks-bindings" />

---

# Custom CSRs

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/reference/status-codes/custom-csrs/

## Success codes

| Endpoint                                            | Method | HTTP Status Code |
| --------------------------------------------------- | ------ | ---------------- |
| `/api/v4/zones/:zone_id/custom_csrs`                | POST   | 201 Created      |
| `/api/v4/zones/:zone_id/custom_csrs`                | GET    | 200 OK           |
| `/api/v4/zones/:zone_id/custom_csrs/:custom_csr_id` | GET    | 200 OK           |
| `/api/v4/zones/:zone_id/custom_csrs/:custom_csr_id` | DELETE | 200 OK           |

## Error codes

| HTTP Status Code | API Error Code | Error Message                                                                                                                                                                                                                                                                                                                        |
| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400              | 1400           | Unable to decode the JSON request body. Check your input and try again.                                                                                                                                                                                                                                                              |
| 400              | 1401           | Zone ID is required. Check your input and try again.                                                                                                                                                                                                                                                                                 |
| 400              | 1402           | The request has no Authorization header. Check your input and try again.                                                                                                                                                                                                                                                             |
| 400              | 1405           | Country field is required. Check your input and try again.                                                                                                                                                                                                                                                                           |
| 400              | 1406           | State field is required. Check your input and try again.                                                                                                                                                                                                                                                                             |
| 400              | 1407           | Locality field is required. Check your input and try again.                                                                                                                                                                                                                                                                          |
| 400              | 1408           | Organization field is required. Check your input and try again.                                                                                                                                                                                                                                                                      |
| 400              | 1409           | Common Name field is required. Check your input and try again.                                                                                                                                                                                                                                                                       |
| 400              | 1410           | The specified Common Name is too long. Maximum allowed length is %d characters. Check your input and try again.                                                                                                                                                                                                                      |
| 400              | 1411           | At least one subject alternative name (SAN) is required. Check your input and try again.                                                                                                                                                                                                                                             |
| 400              | 1412           | Invalid subject alternative name(s) (SAN). SANs have to be smaller than 256 characters in length, cannot be IP addresses, cannot contain any special characters such as ~`!@#$%^&*()=+{}[]                                                                                                                                       |
| 400              | 1413           | Subject Alternative Names (SANs) with non-ASCII characters are not supported. Check your input and try again.                                                                                                                                                                                                                        |
| 400              | 1414           | Reserved top domain subject alternative names (SAN), such as 'test', 'example', 'invalid' or 'localhost', is not supported. Check your input and try again.                                                                                                                                                                          |
| 400              | 1415           | Unable to parse subject alternative name(s) (SAN) - :reason. Check your input and try again. Reasons: publicsuffix: cannot derive eTLD+1 for domain %q; publicsuffix: invalid public suffix %q for domain %q;                                                                                                                        |
| 400              | 1416           | Subject Alternative Names (SANs) ending in example.com, example.net, or example.org are prohibited. Check your input and try again.                                                                                                                                                                                                  |
| 400              | 1417           | Invalid key type. Only 'rsa2048' or 'p256v1' is accepted. Check your input and try again.                                                                                                                                                                                                                                            |
| 400              | 1418           | The custom CSR ID is invalid. Check your input and try again.                                                                                                                                                                                                                                                                        |
| 401              | 1000           | Unable to extract bearer token                                                                                                                                                                                                                                                                                                       |
| 401              | 1001           | Unable to parse JWT token                                                                                                                                                                                                                                                                                                            |
| 401              | 1002           | Bad JWT header                                                                                                                                                                                                                                                                                                                       |
| 401              | 1003           | Failed to verify JWT token                                                                                                                                                                                                                                                                                                           |
| 401              | 1004           | Failed to get claims from JWT token                                                                                                                                                                                                                                                                                                  |
| 401              | 1005           | JWT token does not have required claims                                                                                                                                                                                                                                                                                              |
| 403              | 1403           | No quota has been allocated for this zone. If you are already a paid Cloudflare for SaaS customer, contact your Customer Success Manager for additional provisioning. If you are not yet enrolled, [fill out this contact form](https://www.cloudflare.com/plans/enterprise/contact/) and our sales team will contact you.                   |
| 403              | 1404           | Access to generating CSRs has not been granted for this zone. If you are already a paid Cloudflare for SaaS customer, contact your Customer Success Manager for additional provisioning. If you are not yet enrolled, [fill out this contact form](https://www.cloudflare.com/plans/enterprise/contact/) and our sales team will contact you. |
| 404              | 1419           | The custom CSR was not found.                                                                                                                                                                                                                                                                                                        |
| 409              | 1420           | The custom CSR is associated with an active certificate pack. You will need to delete all associated active certificate packs before you can delete the custom CSR.                                                                                                                                                                  |
| 500              | 1500           | Internal Server Error                                                                                                                                                                                                                                                                                                                |

---

# Custom hostnames

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/reference/status-codes/custom-hostnames/

***

## Success codes

| Endpoint                                                  | Method | Code         |
| --------------------------------------------------------- | ------ | ------------ |
| `/v4/zones/:zone_id/custom_hostnames`                     | POST   | 201 Created  |
| `/v4/zones/:zone_id/custom_hostnames/:custom_hostname_id` | GET    | 200 OK       |
| `/v4/zones/:zone_id/custom_hostnames`                     | GET    | 200 OK       |
| `/v4/zones/:zone_id/custom_hostnames/:custom_hostname_id` | DELETE | 200 OK       |
| `/v4/zones/:zone_id/custom_hostnames/:custom_hostname_id` | PATCH  | 202 Accepted |

***

## Error codes

| HTTP Status Code | API Error Code | Error Message                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400              | 1400           | Unable to decode the JSON request body. Check your input and try again.                                                                                                                                                                                                                                                                                                                                        |
| 400              | 1401           | Unable to encode the Custom Metadata as JSON. Check your input and try again.                                                                                                                                                                                                                                                                                                                                  |
| 400              | 1402           | Zone ID is required. Check your input and try again.                                                                                                                                                                                                                                                                                                                                                           |
| 400              | 1403           | The request has no Authorization header. Check your input and try again.                                                                                                                                                                                                                                                                                                                                       |
| 400              | 1407           | Invalid custom hostname. Custom hostnames have to be smaller than 256 characters in length, cannot be IP addresses, cannot contain any special characters such as \`\`\~\`!@#$%^&\*()=+{}\[]\\                                                                                                                                                                                                                 |
| 400              | 1408           | Custom hostnames with non-ASCII characters are not supported. Check your input and try again.                                                                                                                                                                                                                                                                                                                  |
| 400              | 1409           | Reserved top domain custom hostnames, such as 'test', 'example', 'invalid' or 'localhost', is not supported. Check your input and try again.                                                                                                                                                                                                                                                                   |
| 400              | 1410           | Unable to parse custom hostname - `:reason`. Check your input and try again. <br/> **Reasons:** <br/> publicsuffix: cannot derive eTLD+1 for domain `:domain` <br/> publicsuffix: invalid public suffix `:suffix` for domain `:domain`                                                                                                                                                                         |
| 400              | 1411           | Custom hostnames ending in example.com, example.net, or example.org are prohibited. Check your input and try again.                                                                                                                                                                                                                                                                                            |
| 400              | 1412           | Custom metadata for wildcard custom hostnames is not supported. Check your input and try again.                                                                                                                                                                                                                                                                                                                |
| 400              | 1415           | Invalid custom origin hostname. Custom origin hostnames have to be smaller than 256 characters in length, cannot be IP addresses, cannot contain any special characters such as ~~\`\`~~\`!@#$%^&\*()=+{}\[]\\                                                                                                                                                                                                 |
| 400              | 1416           | Custom origin hostnames with non-ASCII characters are not supported. Check your input and try again.                                                                                                                                                                                                                                                                                                           |
| 400              | 1417           | Reserved top domain custom origin hostnames, such as 'test', 'example', 'invalid' or 'localhost', is not supported. Check your input and try again.                                                                                                                                                                                                                                                            |
| 400              | 1418           | Unable to parse custom origin hostname - `:reason`. Check your input and try again. <br/> **Reasons:** <br/> publicsuffix: cannot derive eTLD+1 for domain `:domain`<br/> publicsuffix: invalid public suffix`:suffix`for domain`:domain`                                                                                                                                                                      |
| 400              | 1419           | Custom origin hostnames ending in example.com, example.net, or example.org are prohibited. Check your input and try again.                                                                                                                                                                                                                                                                                     |
| 400              | 1420           | Wildcard custom origin hostnames are not supported. Check your input and try again.                                                                                                                                                                                                                                                                                                                            |
| 400              | 1421           | The custom origin hostname you specified does not exist on Cloudflare as a DNS record (A, AAAA or CNAME) in your zone:`:zone\_tag`. Check your input and try again.                                                                                                                                                                                                                                            |
| 400              | 1422           | Invalid `http2`setting. Only 'on' or 'off' is accepted. Check your input and try again.                                                                                                                                                                                                                                                                                                                        |
| 400              | 1423           | Invalid`tls\_1\_2\_only`setting. Only 'on' or 'off' is accepted. Check your input and try again.                                                                                                                                                                                                                                                                                                               |
| 400              | 1424           | Invalid`tls\_1\_3`setting. Only 'on' or 'off' is accepted. Check your input and try again.                                                                                                                                                                                                                                                                                                                     |
| 400              | 1425           | Invalid`min\_tls\_version`setting. Only '1.0','1.1','1.2' or '1.3' is accepted. Check your input and try again.                                                                                                                                                                                                                                                                                                |
| 400              | 1426           | The certificate that you uploaded cannot be parsed. Check your input and try again.                                                                                                                                                                                                                                                                                                                            |
| 400              | 1427           | The certificate that you uploaded is empty. Check your input and try again.                                                                                                                                                                                                                                                                                                                                    |
| 400              | 1428           | The private key you uploaded cannot be parsed. Check your input and try again.                                                                                                                                                                                                                                                                                                                                 |
| 400              | 1429           | The private key you uploaded does not match the certificate. Check your input and try again.                                                                                                                                                                                                                                                                                                                   |
| 400              | 1430           | The custom CSR ID is invalid. Check your input and try again.                                                                                                                                                                                                                                                                                                                                                  |
| 404              | 1431           | The custom CSR was not found.                                                                                                                                                                                                                                                                                                                                                                                  |
| 400              | 1432           | The validation method is not supported. Only`http`, `email`, or `txt` are accepted. Check your input and try again.                                                                                                                                                                                                                                                                                            |
| 400              | 1433           | The validation type is not supported. Only 'dv' is accepted. Check your input and try again.                                                                                                                                                                                                                                                                                                                   |
| 400              | 1434           | The SSL attribute is invalid. Refer to the API documentation, check your input and try again.                                                                                                                                                                                                                                                                                                                  |
| 400              | 1435           | The custom hostname ID is invalid. Check your input and try again.                                                                                                                                                                                                                                                                                                                                             |
| 404              | 1436           | The custom hostname was not found.                                                                                                                                                                                                                                                                                                                                                                             |
| 400              | 1437           | Invalid hostname.contain query parameter. The hostname.contain query parameter has to be smaller than 256 characters in length, cannot be IP addresses, cannot contain any special characters such as \`\`\~\`!@#$%^&\*()=+{}\[]\\                                                                                                                                                                             |
| 400              | 1438           | Cannot specify other filter parameters in addition to `id`. Only one must be specified. Check your input and try again.                                                                                                                                                                                                                                                                                        |
| 409              | 1439           | Modifying the custom hostname is not supported. Check your input and try again.                                                                                                                                                                                                                                                                                                                                |
| 400              | 1440           | Both validation type and validation method are required. Check your input and try again.                                                                                                                                                                                                                                                                                                                       |
| 400              | 1441           | The certificate that you uploaded is having trouble bundling against the public trust store. Check your input and try again.                                                                                                                                                                                                                                                                                   |
| 400              | 1442           | Invalid `ciphers` setting. Refer to the documentation for the list of accepted cipher suites. Check your input and try again.                                                                                                                                                                                                                                                                                  |
| 400              | 1443           | Cipher suite selection is not supported for a minimum TLS version of 1.3. Check your input and try again.                                                                                                                                                                                                                                                                                                      |
| 400              | 1444           | The certificate chain that you uploaded has multiple leaf certificates. Check your input and try again.                                                                                                                                                                                                                                                                                                        |
| 400              | 1445           | The certificate chain that you uploaded has no leaf certificates. Check your input and try again.                                                                                                                                                                                                                                                                                                              |
| 400              | 1446           | The certificate that you uploaded does not include the custom hostname - `:custom_hostname`. Review your input and try again.                                                                                                                                                                                                                                                                                  |
| 400              | 1447           | The certificate that you uploaded does not use a supported signature algorithm. Only SHA-256/ECDSA, SHA-256/RSA, and SHA-1/RSA signature algorithms are supported. Review your input and try again.                                                                                                                                                                                                            |
| 400              | 1448           | Custom hostnames with wildcards are not supported for certificates managed by Cloudflare. Review your input and try again.                                                                                                                                                                                                                                                                                     |
| 400              | 1449           | The request input `bundle_method` must be one of: ubiquitous, optimal, force.                                                                                                                                                                                                                                                                                                                                  |
| 401              | 1000           | Unable to extract bearer token                                                                                                                                                                                                                                                                                                                                                                                 |
| 401              | 1001           | Unable to parse JWT token                                                                                                                                                                                                                                                                                                                                                                                      |
| 401              | 1002           | Bad JWT header                                                                                                                                                                                                                                                                                                                                                                                                 |
| 401              | 1003           | Failed to verify JWT token                                                                                                                                                                                                                                                                                                                                                                                     |
| 401              | 1004           | Failed to get claims from JWT token                                                                                                                                                                                                                                                                                                                                                                            |
| 401              | 1005           | JWT token does not have required claims                                                                                                                                                                                                                                                                                                                                                                        |
| 403              | 1404           | No quota has been allocated for this zone. If you are already a paid Cloudflare for SaaS customer, contact your Customer Success Manager for additional provisioning. If you are not yet enrolled, [fill out this contact form](https://www.cloudflare.com/plans/enterprise/contact/) and our sales team will reach out to you.                                                                                |
| 403              | 1405           | Quota exceeded. If you are already a paid Cloudflare for SaaS customer, contact your Customer Success Manager for additional provisioning. If you are not yet enrolled, [fill out this contact form](https://www.cloudflare.com/plans/enterprise/contact/) and our sales team will reach out to you.                                                                                                           |
| 403              | 1413           | No [custom metadata](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/custom-metadata/) access has been allocated for this zone. If you are already a paid  customer, contact your Customer Success Manager for additional provisioning. If you are not yet enrolled, [fill out this contact form](https://www.cloudflare.com/plans/enterprise/contact/) and our sales team will reach out to you. |
| 403              | 1414           | Access to setting a custom origin server has not been granted for this zone. If you are already a paid Cloudflare for SaaS customer, contact your Customer Success Manager for additional provisioning. If you are not yet enrolled, [fill out this contact form](https://www.cloudflare.com/plans/enterprise/contact/) and our sales team will reach out to you.                                              |
| 409              | 1406           | Duplicate custom hostname found.                                                                                                                                                                                                                                                                                                                                                                               |
| 500              | 1500           | Internal Server Error                                                                                                                                                                                                                                                                                                                                                                                          |

---

# Status codes

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/reference/status-codes/

import { DirectoryListing } from "~/components";

Cloudflare uses many different status codes for Cloudflare for SaaS. They can be related to:

<DirectoryListing />

---

# TLS Management

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/enforce-mtls/

import { AvailableNotifications, Details, Render } from "~/components"

[Mutual TLS (mTLS)](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/) adds an extra layer of protection to application connections by validating certificates on the server and the client. When building a SaaS application, you may want to enforce mTLS to protect sensitive endpoints related to payment processing, database updates, and more.

[Minimum TLS Version](/ssl/edge-certificates/additional-options/minimum-tls/) allows you to choose a cryptographic standard per custom hostname. Cloudflare recommends TLS 1.2 to comply with the Payment Card Industry (PCI) Security Standards Council.

[Cipher suites](/ssl/edge-certificates/additional-options/cipher-suites/) are a combination of ciphers used to negotiate security settings during the [SSL/TLS handshake](https://www.cloudflare.com/learning/ssl/what-happens-in-a-tls-handshake/). As a SaaS provider, you can [specify configurations for cipher suites](#cipher-suites) on your zone as a whole and cipher suites on individual custom hostnames via the API.


:::caution
When you [issue a custom hostname certificate](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/) with wildcards enabled, any cipher suites or Minimum TLS settings applied to that hostname will only apply to the direct hostname.

However, if you want to update the Minimum TLS settings for all wildcard hostnames, you can change Minimum TLS version at the [zone level](/ssl/edge-certificates/additional-options/minimum-tls/).
:::

## Enable mTLS

Once you have [added a custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/), you can enable mTLS by using Cloudflare Access. Go to [Cloudflare Zero Trust](https://one.dash.cloudflare.com/) and [add mTLS authentication](/cloudflare-one/identity/devices/access-integrations/mutual-tls-authentication/) with a few clicks.

:::note


Currently, you cannot add mTLS policies for custom hostnames using [API Shield](/api-shield/security/mtls/).


:::

## Enable Minimum TLS Version

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and navigate to your account and website.

2. Select **SSL/TLS** > **Custom Hostnames**.

3. Find the hostname to which you want to apply Minimum TLS Version. Select **Edit**.

4. Choose the desired TLS version under **Minimum TLS Version** and click **Save**.

:::note

While TLS 1.3 is the most recent and secure version, it is not supported by some older devices. Refer to Cloudflare's recommendations when [deciding what version to use](/ssl/reference/protocols/#decide-which-version-to-use).
:::

## Cipher suites

For security and regulatory reasons, you may want to only allow connections from certain cipher suites. Cloudflare provides recommended values and full cipher suite reference in our [Cipher suites documentation](/ssl/edge-certificates/additional-options/cipher-suites/#resources).


<Details header="Restrict cipher suites for your zone">

Refer to [Customize cipher suites - SSL/TLS](/ssl/edge-certificates/additional-options/cipher-suites/customize-cipher-suites/).

</Details>


<Details header="Restrict cipher suites for custom hostname">

In the API documentation, refer to [SSL properties of a custom hostname](/api/resources/custom_hostnames/methods/edit/).

<Render file="edit-custom-hostname-api" params={{ one: "When making the request," }} />


</Details>

## Alerts for mutual TLS certificates

You can configure alerts to receive notifications before your mutual TLS certificates expire.

<AvailableNotifications product="SSL/TLS" notificationFilter="Access mTLS Certificate Expiration Alert" />

<Render file="get-started" product="notifications" />

---

# Certificate management

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/

import { DirectoryListing } from "~/components";

Cloudflare for SaaS takes away the burden of certificate issuance and management from you, as the SaaS provider, by proxying traffic through Cloudflare's edge. You can choose between Cloudflare managing all the certificate issuance and renewals on your behalf, or maintain control over your TLS private keys by uploading your customers' own certificates.

## Resources

<DirectoryListing />

---

# Webhook definitions

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/webhook-definitions/

import { AvailableNotifications, Render } from "~/components"

When you [create a webhook notification](/notifications/get-started/configure-webhooks/) for **SSL for SaaS Custom Hostnames**, you may want to automate responses to specific events (certificate issuance, failed validation, etc.).

The following section details the data Cloudflare sends to a webhook destination.

## Certificate validation

Before a Certificate Authority will issue a certificate for a domain, the requester must prove they have control over that domain. This process is known as [domain control validation (DCV)](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/).

### Validation succeeded

Cloudflare sends this alert when certificates move from a status of `pending_validation` to `pending_issuance`.

```json
{
  "metadata": {
    "event": {
      "id": "<<WEBHOOK_ID>",
      "type": "ssl.custom_hostname_certificate.validation.succeeded",
      "created_at": "2022-02-09T00:03:28.385080Z"
    },
    "account": {
      "id": "<<ACCOUNT_ID>"
    },
    "zone": {
      "id": "<<ZONE_ID>"
    }
  },
  "data": {
    "id": "<<CUSTOM_HOSTNAME_ID>",
    "hostname": "blog.com",
    "ssl": {
      "id": "<<CERTIFICATE_ID>",
      "type": "dv",
      "method": "cname",
      "status": "pending_issuance",
      "settings": {
        "min_tls_version": "1.2",
        "http2": "on"
      }
    },
    "custom_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "custom_origin_server": "0001.blog.com"
  }
}
```

### Validation failed

Cloudflare sends this alert each time a certificate remains in a `pending_validation` status during [DCV retries](/ssl/edge-certificates/changing-dcv-method/validation-backoff-schedule/).

```json
{
  "metadata": {
    "event": {
      "id": "<<WEBHOOK_ID>",
      "type": "ssl.custom_hostname_certificate.validation.failed",
      "created_at": "2018-02-09T00:03:28.385080Z"
    },
    "account": {
      "id": "<<ACCOUNT_ID>"
    },
    "zone": {
      "id": "<<ZONE_ID>"
    }
  },
  "data": {
    "id": "<<CUSTOM_HOSTNAME_ID>",
    "hostname": "blog.com",
    "ssl": {
      "id": "<<CERTIFICATE_ID>",
      "type": "dv",
      "method": "cname",
      "status": "pending_validation",
      "cname": "_ca3-64ce913ebfe74edeb2e8813e3928e359.app.example2.com",
      "cname_target": "dcv.digicert.com",
      "validation_errors": [
        {
          "message": "blog.example.com reported as potential risk: google_safe_browsing"
        }
      ],
      "settings": {
        "min_tls_version": "1.2",
        "http2": "on"
      }
    },
    "custom_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "custom_origin_server": "0001.blog.com"
  }
}
```

***

## Certificate issuance

Once validated, certificates are issued by Cloudflare in conjunction with your chosen [certificate authority](/ssl/reference/certificate-authorities/).

### Issuance succeeded

Cloudflare sends this alert when certificates move from a status of `pending_validation` or `pending_issuance` to `pending_deployment`.

```json
{
  "metadata": {
    "event": {
      "id": "<<WEBHOOK_ID>",
      "type": "ssl.custom_hostname_certificate.issuance.succeeded",
      "created_at": "2022-02-09T00:03:28.385080Z"
    },
    "account": {
      "id": "<<ACCOUNT_ID>"
    },
    "zone": {
      "id": "<<ZONE_ID>"
    }
  },
  "data": {
    "id": "<<CUSTOM_HOSTNAME_ID>",
    "hostname": "blog.com",
    "ssl": {
      "id": "<<CERTIFICATE_ID>",
      "type": "dv",
      "method": "cname",
      "status": "pending_deployment",
      "settings": {
        "min_tls_version": "1.2",
        "http2": "on"
      }
    },
    "custom_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "custom_origin_server": "0001.blog.com"
  }
}
```

### Issuance failed

Cloudflare sends this alert each time a certificate remains in a status of `pending_issuance` during [DCV retries](/ssl/edge-certificates/changing-dcv-method/validation-backoff-schedule/).

```json
{
  "metadata": {
    "event": {
      "id": "<<WEBHOOK_ID>",
      "type": "ssl.custom_hostname_certificate.issuance.failed",
      "created_at": "2022-02-09T00:03:28.385080Z"
    },
    "account": {
      "id": "<<ACCOUNT_ID>"
    },
    "zone": {
      "id": "<<ZONE_ID>"
    }
  },
  "data": {
    "id": "<<CUSTOM_HOSTNAME_ID>",
    "hostname": "blog.com",
    "ssl": {
      "id": "<<CERTIFICATE_ID>",
      "type": "dv",
      "method": "cname",
      "status": "pending_issuance",
      "cname": "_ca3-64ce913ebfe74edeb2e8813e3928e359.app.example2.com",
      "cname_target": "dcv.digicert.com",
      "validation_errors": [
        {
          "message": "caa_error: blog.example.com"
        }
      ],
      "settings": {
        "min_tls_version": "1.2",
        "http2": "on"
      }
    },
    "custom_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "custom_origin_server": "0001.blog.com"
  }
}
```

***

## Certificate deployment

Once issued, certificates are deployed to Cloudflare's global edge network.

### Deployment succeeded

Cloudflare sends this alert when certificates move from a status of `pending_deployment` to `active`.

```json
{
  "metadata": {
    "event": {
      "id": "<<WEBHOOK_ID>",
      "type": "ssl.custom_hostname_certificate.deployment.succeeded",
      "created_at": "2022-02-09T00:03:28.385080Z"
    },
    "account": {
      "id": "<<ACCOUNT_ID>"
    },
    "zone": {
      "id": "<<ZONE_ID>"
    }
  },
  "data": {
    "id": "<<CUSTOM_HOSTNAME_ID>",
    "hostname": "blog.com",
    "ssl": {
      "id": "<<CERTIFICATE_ID>",
      "type": "dv",
      "method": "cname",
      "status": "active",
      "settings": {
        "min_tls_version": "1.2",
        "http2": "on"
      }
    },
    "custom_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "custom_origin_server": "0001.blog.com"
  }
}
```

### Deployment failed

Cloudflare sends this alert each time a certificate remains in a status of `pending_deployment` during [DCV retries](/ssl/edge-certificates/changing-dcv-method/validation-backoff-schedule/).

```json
{
  "metadata": {
    "event": {
      "id": "<<WEBHOOK_ID>",
      "type": "ssl.custom_hostname_certificate.deployment.failed",
      "created_at": "2022-02-09T00:03:28.385080Z"
    },
    "account": {
      "id": "<<ACCOUNT_ID>"
    },
    "zone": {
      "id": "<<ZONE_ID>"
    }
  },
  "data": {
    "id": "<<CUSTOM_HOSTNAME_ID>",
    "hostname": "blog.com",
    "ssl": {
      "id": "<<CERTIFICATE_ID>",
      "type": "dv",
      "method": "cname",
      "status": "pending_deployment",
      "settings": {
        "min_tls_version": "1.2",
        "http2": "on"
      }
    },
    "custom_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "custom_origin_server": "0001.blog.com"
  }
}
```

***

## Certificate deletion

### Deletion succeeded

Cloudflare sends this alert when certificates move from a status of `pending_deletion` to `deleted`.

```json
{
  "metadata": {
    "event": {
      "id": "<<WEBHOOK_ID>",
      "type": "ssl.custom_hostname_certificate.deletion.succeeded",
      "created_at": "2022-02-09T00:03:28.385080Z"
    },
    "account": {
      "id": "<<ACCOUNT_ID>"
    },
    "zone": {
      "id": "<<ZONE_ID>"
    }
  },
  "data": {
    "id": "<<CUSTOM_HOSTNAME_ID>",
    "hostname": "blog.com",
    "ssl": {
      "id": "<<CERTIFICATE_ID>",
      "type": "dv",
      "method": "cname",
      "status": "deleted"
    },
    "custom_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "custom_origin_server": "0001.blog.com"
  }
}
```

### Deletion failed

Cloudflare sends this alert each time a certificate remains in status of `pending_deletion` during [DCV retries](/ssl/edge-certificates/changing-dcv-method/validation-backoff-schedule/).

```json
{
  "metadata": {
    "event": {
      "id": "<<WEBHOOK_ID>",
      "type": "ssl.custom_hostname_certificate.deletion.failed",
      "created_at": "2022-02-09T00:03:28.385080Z"
    },
    "account": {
      "id": "<<ACCOUNT_ID>"
    },
    "zone": {
      "id": "<<ZONE_ID>"
    }
  },
  "data": {
    "id": "<<CUSTOM_HOSTNAME_ID>",
    "hostname": "blog.com",
    "ssl": {
      "id": "<<CERTIFICATE_ID>",
      "type": "dv",
      "method": "cname",
      "status": "pending_deletion"
    },
    "custom_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "custom_origin_server": "0001.blog.com"
  }
}
```

***

## Certificate renewal

Once issued, certificates are valid for a period of time depending on the [certificate authority](/ssl/reference/certificate-validity-periods/).

The actions that you need to perform to renew certificates depend on your [validation method](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/renew-certificates/).

### Upcoming renewal

```json
{
  "metadata": {
    "event": {
      "id": "<<WEBHOOK_ID>",
      "type": "ssl.custom_hostname_certificate.renewal.upcoming_certificate_expiration_notification",
      "created_at": "2022-02-09T00:03:28.385080Z"
    },
    "account": {
      "id": "<<ACCOUNT_ID>"
    },
    "zone": {
      "id": "<<ZONE_ID>"
    }
  },
  "data": {
    "id": "<<CUSTOM_HOSTNAME_ID>",
    "hostname": "blog.com",
    "ssl": {
      "id": "<<CERTIFICATE_ID>",
      "status": "active",
      "hosts": ["blog.example.com"],
      "issuer": "DigiCertInc",
      "serial_number": "1001172778337169491",
      "signature": "ECDSAWithSHA256",
      "uploaded_on": "2021-11-17T04:33:54.561747Z",
      "expires_on": "2022-11-21T12:00:00Z",
      "custom_csr_id": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752",
      "settings": {
        "min_tls_version": "1.2",
        "http2": "on"
      }
    },
    "custom_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "custom_origin_server": "0001.blog.com"
  }
}
```

### Renewal succeeded

Cloudflare sends this alert when certificates move from a status of `active` to `pending_deployment`.

```json
{
  "metadata": {
    "event": {
      "id": "<<WEBHOOK_ID>",
      "type": "ssl.custom_hostname_certificate.renewal.succeeded",
      "created_at": "2022-02-09T00:03:28.385080Z"
    },
    "account": {
      "id": "<<ACCOUNT_ID>"
    },
    "zone": {
      "id": "<<ZONE_ID>"
    }
  },
  "data": {
    "id": "<<CUSTOM_HOSTNAME_ID>",
    "hostname": "blog.com",
    "ssl": {
      "id": "<<CERTIFICATE_ID>",
      "type": "dv",
      "method": "cname",
      "status": "pending_deployment",
      "settings": {
        "min_tls_version": "1.2",
        "http2": "on"
      }
    },
    "custom_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "custom_origin_server": "0001.blog.com"
  }
}
```

### Renewal failed

Cloudflare sends this alert when certificates move from a status of `active` to `pending_issuance`.

```json
{
  "metadata": {
    "event": {
      "id": "<<WEBHOOK_ID>",
      "type": "ssl.custom_hostname_certificate.renewal.failed",
      "created_at": "2022-02-09T00:03:28.385080Z"
    },
    "account": {
      "id": "<<ACCOUNT_ID>"
    },
    "zone": {
      "id": "<<ZONE_ID>"
    }
  },
  "data": {
    "id": "<<CUSTOM_HOSTNAME_ID>",
    "hostname": "blog.com",
    "ssl": {
      "id": "<<CERTIFICATE_ID>",
      "type": "dv",
      "method": "cname",
      "status": "pending_issuance",
      "cname": "_ca3-64ce913ebfe74edeb2e8813e3928e359.app.example2.com",
      "cname_target": "dcv.digicert.com",
      "validation_errors": [
        {
          "message": "caa_error: blog.example.com"
        }
      ],
      "settings": {
        "min_tls_version": "1.2",
        "http2": "on"
      }
    },
    "custom_metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "custom_origin_server": "0001.blog.com"
  }
}
```

## Troubleshooting

Occasionally, you may see webhook notifications that do not include a corresponding `<<CUSTOM_HOSTNAME_ID>>` and `hostname` values.

This behavior is because each custom hostname can only have one certificate attached to it. Previously attached certificates can still emit webhook events but will not include the associated hostname and ID values.

## Alerts

You can configure alerts to receive notifications for changes in your custom hostname certificates.

<AvailableNotifications product="SSL/TLS" notificationFilter="SSL for SaaS Custom Hostnames Alert" />

<Render file="get-started" product="notifications" />

---

# HubSpot

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/provider-guides/hubspot/

import { Render } from "~/components";

<Render file="provider-guide-intro" params={{ providerName: "HubSpot" }} />

## Benefits

<Render file="provider-guide-benefits" params={{ providerName: "HubSpot" }} />

## How it works

For more details about how O2O is different than other Cloudflare setups, refer to [How O2O works](/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/).

## Enable

O2O is enabled per hostname, so to enable O2O for a specific hostname within your Cloudflare zone, [create](/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records) a Proxied `CNAME` DNS record with a target of your corresponding HubSpot CNAME. Which HubSpot CNAME is targeted will depend on your current [HubSpot proxy settings](https://developers.hubspot.com/docs/cms/developer-reference/reverse-proxy-support#configure-the-proxy).

| Type    | Name              | Target                                 | Proxy status |
| ------- | ----------------- | -------------------------------------- | ------------ |
| `CNAME` | `<YOUR_HOSTNAME>` | `<HUBID>.sites-proxy.hscoscdn<##>.net` | Proxied      |

:::note

For questions about your HubSpot setup, refer to [HubSpot's reverse proxy support guide](https://developers.hubspot.com/docs/cms/developer-reference/reverse-proxy-support).

:::

## Product compatibility

<Render file="provider-guide-compatibility" />

## Zone hold

Because you have your own Cloudflare zone, you have access to the zone hold feature, which is a toggle that prevents your domain name from being created as a zone in a different Cloudflare account. Additionally, if the zone hold feature is enabled, it prevents the activation of custom hostnames onboarded to HubSpot. HubSpot would receive the following error message for your custom hostname: `The hostname is associated with a held zone. Please contact the owner of this domain to have the hold removed.`

To successfully activate the custom hostname on HubSpot, the owner of the zone needs to [temporarily release the hold](/fundamentals/account/account-security/zone-holds/#release-zone-holds). If you are only onboarding a subdomain as a custom hostname to HubSpot, only the subfeature titled `Also prevent Subdomains` needs to be temporarily disabled.

Once the zone hold is temporarily disabled, follow HubSpot's instructions to refresh the custom hostname and it should activate.

## Additional support

<Render file="provider-guide-help" params={{ providerName: "HubSpot" }} />

---

# Provider guides

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/provider-guides/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# BigCommerce

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/provider-guides/bigcommerce/

import { Render } from "~/components";

<Render file="provider-guide-intro" params={{ providerName: "BigCommerce" }} />

## Benefits

<Render
	file="provider-guide-benefits"
	params={{ providerName: "BigCommerce" }}
/>

## How it works

For more details about how O2O is different than other Cloudflare setups, refer to [How O2O works](/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/).

## Enable

BigCommerce customers can enable O2O on any Cloudflare zone plan.

To enable O2O on your account, [create](/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records) a `CNAME` DNS record.

| Type    | Name              | Target                    | Proxy status |
| ------- | ----------------- | ------------------------- | ------------ |
| `CNAME` | `<YOUR_HOSTNAME>` | `shops.mybigcommerce.com` | Proxied      |

:::note

For more details about a BigCommerce setup, refer to their [support guide](https://support.bigcommerce.com/s/article/Cloudflare-for-Performance-and-Security?language=en_US#orange-to-orange).

If you cannot activate your domain using [proxied DNS records](/dns/proxy-status/), reach out to your account team.

:::

## Product compatibility

<Render file="provider-guide-compatibility" />

## Additional support

<Render file="provider-guide-help" params={{ providerName: "BigCommerce" }} />

---

# Render

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/provider-guides/render/

import { Render } from "~/components";

<Render
	file="provider-guide-intro"
	params={{
		providerName: "Render",
		providerUrl: "https://render.com",
		providerAssets: "web services and static sites",
	}}
/>

## Benefits

<Render
	file="provider-guide-benefits"
	params={{ providerName: "Render", providerAssets: "services" }}
/>

## How it works

For additional detail about how traffic routes when O2O is enabled, refer to [How O2O works](/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/).

## Enable

Render customers can enable O2O on any Cloudflare zone plan. Cloudflare support for O2O setups is only available for Enterprise customers.

To enable O2O for a specific hostname within a Cloudflare zone, [create](/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records) a Proxied `CNAME` DNS record with your Render site name as the target. Render's domain addition setup will walk you through other validation steps.

| Type    | Name              | Target                                                     | Proxy status |
| ------- | ----------------- | ---------------------------------------------------------- | ------------ |
| `CNAME` | `<YOUR_HOSTNAME>` | `<RENDER_SUBDOMAIN>` (for example, `example.onrender.com`) | Proxied      |

:::note

For more details about Render setup, refer to their [documentation](https://render.com/docs/configure-cloudflare-dns).

If you cannot activate your domain using [proxied DNS records](/dns/proxy-status/), reach out to your Cloudflare account team or your Render support team.

:::

### Additional requirements for wildcard subdomains

With O2O enabled, adding a wildcard subdomain to a Render service requires that the corresponding root domain is also routed to Render. If the root domain is routed elsewhere, wildcard routing will fail.

If your root domain needs to route somewhere besides Render, add individual subdomains to your Render service instead of a wildcard.

## Product compatibility

<Render file="provider-guide-compatibility" />

## Additional support

<Render file="provider-guide-help" params={{ providerName: "Render" }} />

### Resolving SSL errors

If you encounter SSL errors, check if you have a `CAA` record.

If you have a `CAA` record, verify that it permits SSL certificates to be issued by Google Trust Services (`pki.goog`).

For more details, refer to [CAA records](/ssl/edge-certificates/troubleshooting/caa-records/#what-caa-records-are-added-by-cloudflare).

---

# Kinsta

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/provider-guides/kinsta/

import { Render } from "~/components";

<Render file="provider-guide-intro" params={{ providerName: "Kinsta" }} />

## Benefits

<Render file="provider-guide-benefits" params={{ providerName: "Kinsta" }} />

## How it works

For additional detail about how traffic routes when O2O is enabled, refer to [How O2O works](/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/).

## Enable

Kinsta customers can enable O2O on any Cloudflare zone plan.

To enable O2O for a specific hostname within a Cloudflare zone, [create](/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records) a Proxied `CNAME` DNS record with your Kinsta site name as the target. Kinsta’s domain addition setup will walk you through other validation steps.

| Type    | Name              | Target                          | Proxy status |
| ------- | ----------------- | ------------------------------- | ------------ |
| `CNAME` | `<YOUR_HOSTNAME>` | `sitename.hosting.kinsta.cloud` | Proxied      |

## Product compatibility

<Render file="provider-guide-compatibility" />

## Additional support

<Render file="provider-guide-help" params={{ providerName: "Kinsta" }} />

### Resolving SSL errors using Cloudflare Managed Certificates

If you encounter SSL errors when attempting to activate a Cloudflare Managed Certificate, verify if you have a `CAA` record on your domain name with command `dig +short example.com CAA`.

If you do have a `CAA` record, verify that it permits SSL certificates to be issued by the [certificate authorities supported by Cloudflare](/ssl/reference/certificate-authorities/).

---

# Salesforce Commerce Cloud

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/provider-guides/salesforce-commerce-cloud/

import { Details, Render } from "~/components";

<Render
	file="provider-guide-intro"
	params={{ providerName: "Salesforce Commerce Cloud" }}
/>

## Benefits

<Render
	file="provider-guide-benefits"
	params={{ providerName: "Salesforce Commerce Cloud" }}
/>

## How it works

For additional detail about how traffic routes when O2O is enabled, refer to [How O2O works](/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/).

## Enable

To enable O2O requires the following:

1. You must configure your SFCC environment as an "SFCC Proxy Zone". If you currently have an "SFCC Legacy Zone", you cannot enable O2O.
   - For more details on the different types of SFCC configurations, refer to the [Salesforce FAQ on SFCC Proxy Zones](https://help.salesforce.com/s/articleView?id=cc.b2c_ecdn_proxy_zone_faq.htm&type=5).
   - For instructions on how to migrate your SFCC environment to an "SFCC Proxy Zone", refer to the [SFCC Legacy Zone to SFCC Proxy Zone migration guide](https://help.salesforce.com/s/articleView?id=cc.b2c_migrate_legacy_zone_to_proxy_zone.htm&type=5).
2. Your own Cloudflare zone on an Enterprise plan.

If you meet the above requirements, O2O can then be enabled per hostname. To enable O2O for a specific hostname within your Cloudflare zone, [create](/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records) a Proxied CNAME DNS record with a target of the CNAME provided by SFCC Business Manager, which is the dashboard used by SFCC customers to configure their storefront environment.

The CNAME provided by SFCC Business Manager will resemble `commcloud.prod-abcd-example-com.cc-ecdn.net` and contains 3 distinct parts. For each hostname routing traffic to SFCC, be sure to update each part of the example CNAME to match your SFCC environment:

1. **Environment**: `prod` should be changed to `prod` or `dev` or `stg`.
2. **Realm**: `abcd` should be changed to the Realm ID assigned to you by SFCC.
3. **Domain Name**: `example-com` should be changed to match your domain name in a hyphenated format.

| Type    | Name              | Target                                        | Proxy status |
| ------- | ----------------- | --------------------------------------------- | ------------ |
| `CNAME` | `<YOUR_HOSTNAME>` | `commcloud.prod-abcd-example-com.cc-ecdn.net` | Proxied      |

For O2O to be configured properly, make sure your Proxied DNS record targets your SFCC CNAME **directly**. Do not indirectly target the SFCC CNAME by targeting another Proxied DNS record in your Cloudflare zone which targets the SFCC CNAME.

<Details header="Correct configuration">

For example, if the hostnames routing traffic to SFCC are `www.example.com` and `preview.example.com`, the following is a **correct** configuration in your Cloudflare zone:

| Type    | Name                  | Target                                        | Proxy status |
| ------- | --------------------- | --------------------------------------------- | ------------ |
| `CNAME` | `www.example.com`     | `commcloud.prod-abcd-example-com.cc-ecdn.net` | Proxied      |
| `CNAME` | `preview.example.com` | `commcloud.prod-abcd-example-com.cc-ecdn.net` | Proxied      |

</Details>

<Details header="Incorrect configuration">

And, the following is an **incorrect** configuration because `preview.example.com` indirectly targets the SFCC CNAME via the `www.example.com` Proxied DNS record, which means O2O will not be properly enabled for hostname `preview.example.com`:

| Type    | Name                  | Target                                        | Proxy status |
| ------- | --------------------- | --------------------------------------------- | ------------ |
| `CNAME` | `www.example.com`     | `commcloud.prod-abcd-example-com.cc-ecdn.net` | Proxied      |
| `CNAME` | `preview.example.com` | `www.example.com`                             | Proxied      |

</Details>

## Product compatibility

<Render file="provider-guide-compatibility" />

## Additional support

<Render
	file="provider-guide-help"
	params={{ providerName: "Salesforce Commerce Cloud" }}
/>

### Resolving SSL errors using Cloudflare Managed Certificates

If you encounter SSL errors when attempting to activate a Cloudflare Managed Certificate, verify if you have a `CAA` record on your domain name with command `dig +short example.com CAA`.

If you do have a `CAA` record, verify that it permits SSL certificates to be issued by the [certificate authorities supported by Cloudflare](/ssl/reference/certificate-authorities/).

### Best practice Zone-level configuration

1. Set **Minimum TLS version** to **TLS 1.2**
   1. Navigate to **SSL/TLS > Edge Certificates**, scroll down the page to find **Minimum TLS Version**, and set it to _TLS 1.2_. This setting applies to every Proxied DNS record in your Zone.
2. Match the **Security Level** set in **SFCC Business Manager**
   1. _Option 1: Zone-level_ - Navigate to **Security > Settings**, find **Security Level** and set **Security Level** to match what is configured in **SFCC Business Manager**. This setting applies to every Proxied DNS record in your Cloudflare zone.
   2. _Option 2: Per Proxied DNS record_ - If the **Security Level** differs between the Proxied DNS records targeting your SFCC environment and other Proxied DNS records in your Cloudflare zone, use a **Configuration Rule** to set the **Security Level** specifically for the Proxied DNS records targeting your SFCC environment. For example:
      1. Create a new **Configuration Rule** by navigating to **Rules** > **Overview** and selecting **Create rule** next to **Configuration Rules**:
         1. **Rule name:** `Match Security Level on SFCC hostnames`
         2. **Field:** _Hostname_
         3. **Operator:** _is in_ (this will match against multiple hostnames specified in the **Value** field)
         4. **Value:** `www.example.com` `dev.example.com`
         5. Scroll down to **Security Level** and click **+ Add**
            1. **Select Security Level:** _Medium_ (this should match the **Security Level** set in **SFCC Business Manager**)
         6. Scroll to the bottom of the page and click **Deploy**
3. Disable **Browser Integrity Check**
   1. _Option 1: Zone-level_ - Navigate to **Security > Settings**, find **Browser Integrity Check** and toggle it off to disable it. This setting applies to every Proxied DNS record in your Cloudflare zone.
   2. _Option 2: Per Proxied DNS record_ - If you want to keep **Browser Integrity Check** enabled for other Proxied DNS records in your Cloudflare zone but want to disable it on Proxied DNS records targeting your SFCC environment, keep the Zone-level **Browser Integrity Check** feature enabled and use a **Configuration Rule** to disable **Browser Integrity Check** specifically for the hostnames targeting your SFCC environment. For example:
      1. Create a new **Configuration Rule** by navigating to **Rules** > **Overview** and selecting **Create rule** next to **Configuration Rules**:
         1. **Rule name:** `Disable Browser Integrity Check on SFCC hostnames`
         2. **Field:** _Hostname_
         3. **Operator:** _is in_ (this will match against multiple hostnames specified in the **Value** field)
         4. **Value:** `www.example.com` `dev.example.com`
         5. Scroll down to **Browser Integrity Check** and click the **+ Add** button:
            1. Set the toggle to **Off** (a grey X will be displayed)
         6. Scroll to the bottom of the page and click **Deploy**
4. Bypass **Cache** on Proxied DNS records targeting your SFCC environment
   1. Your SFCC environment, also called a **Realm**, will contain one to many SFCC Proxy Zones, which is where caching will always occur. In the corresponding SFCC Proxy Zone for your domain, SFCC performs their own cache optimization, so it is recommended to bypass the cache on the Proxied DNS records in your Cloudflare zone which target your SFCC environment to prevent a "double caching" scenario. This can be accomplished with a **Cache Rule**.
   2. If the **Cache Rule** is not created, caching will occur in both your Cloudflare zone and your corresponding SFCC Proxy Zone, which can cause issues if and when the cache is invalidated or purged in your SFCC environment.
      1. Additional information on caching in your SFCC environment can be found in [SFCC's Content Cache Documentation](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-content-cache.html)
   3. Create a new **Cache Rule** by navigating to **Rules** > **Overview** and selecting **Create rule** next to **Cache Rules**:
      1. **Rule name:** `Bypass cache on SFCC hostnames`
      2. **Field:** _Hostname_
      3. **Operator:** _is in_ (this will match against multiple hostnames specified in the **Value** field)
      4. **Value:** `www.example.com` `dev.example.com`
      5. **Cache eligibility:** Select **Bypass cache**.
      6. Scroll to the bottom of the page and select **Deploy**.
5. _Optional_ - Upload your Custom Certificate from **SFCC Business Manager** to your Cloudflare zone:
   1. The Custom Certificate you uploaded via **SFCC Business Manager** or **SFCC CDN-API**, which exists within your corresponding SFCC Proxy Zone, will terminate TLS connections for your SFCC storefront hostnames. Because of that, it is optional if you want to upload the same Custom Certificate to your own Cloudflare zone. Doing so will allow Cloudflare users with specific roles in your Cloudflare account to receive expiration notifications for your Custom Certificates. Please read [renew custom certificates](/ssl/edge-certificates/custom-certificates/renewing/#renew-custom-certificates) for further details.
   2. Additionally, since you now have your own Cloudflare zone, you have access to Cloudflare's various edge certificate products which means you could have more than one certificate covering the same SANs. In that scenario, a certificate priority process occurs to determine which certificate to serve at the Cloudflare edge. If you find your SFCC storefront hostnames are presenting a different certificate compared to what you uploaded via **SFCC Business Manager** or **SFCC CDN-API**, the certificate priority process is likely the reason. Please read [certificate priority](/ssl/reference/certificate-and-hostname-priority/#certificate-deployment) for further details.

---

# Shopify

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/provider-guides/shopify/

import { Render } from "~/components";

<Render file="provider-guide-intro" params={{ providerName: "Shopify" }} />

## Benefits

O2O routing also enables you to take advantage of Cloudflare zones specifically customized for Shopify traffic.

## How it works

For more details about how O2O is different than other Cloudflare setups, refer to [How O2O works](/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/).

When you [set up O2O routing for your Shopify website](#enable), Cloudflare enables specific configurations for this SaaS provider. Currently, this includes the following:

- Workers and Snippets are disabled on the `/checkout` URI path.

## Enable

You can enable O2O on any Cloudflare zone plan.

To enable O2O on your account, [create](/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records) a `CNAME` DNS record.

| Type    | Name                 | Target                | Proxy status |
| ------- | -------------------- | --------------------- | ------------ |
| `CNAME` | `<YOUR_SHOP_DOMAIN>` | `shops.myshopify.com` | Proxied      |

Once you save the new DNS record, the Cloudflare dashboard will show a Shopify icon next to the CNAME record value. For example:

![](~/assets/images/cloudflare-for-platforms/provider-guides/shopify-dns-entry.png)

:::note

For questions about Shopify setup, refer to their [support guide](https://help.shopify.com/en/manual/domains/add-a-domain/connecting-domains/connect-domain-manual).

If you cannot activate your domain using [proxied DNS records](/dns/proxy-status/), reach out to your account team or the [Cloudflare Community](https://community.cloudflare.com).

:::

## Product compatibility

<Render file="provider-guide-compatibility" />

## Additional support

<Render file="provider-guide-help" params={{ providerName: "Shopify" }} />

### DNS CAA records

Shopify issues SSL/TLS certificates for merchant domains using Let’s Encrypt. If you add any DNS CAA records, you must select Let’s Encrypt as the Certificate Authority (CA) or HTTPS connections may fail.

For more details, refer to [CAA records](/ssl/edge-certificates/caa-records/#caa-records-added-by-cloudflare).

---

# WP Engine

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/provider-guides/wpengine/

import { Render } from "~/components";

<Render file="provider-guide-intro" params={{ providerName: "WP Engine" }} />

## Benefits

<Render file="provider-guide-benefits" params={{ providerName: "WP Engine" }} />

## How it works

For more details about how O2O is different than other Cloudflare setups, refer to [How O2O works](/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/).

## Enable

WP Engine customers can enable O2O on any Cloudflare zone plan.

To enable O2O for a specific hostname within a Cloudflare zone, [create](/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records) a Proxied `CNAME` DNS record with a target of one of the following WP Engine CNAMEs. Which WP Engine CNAME is used will depend on your current [WP Engine network type](https://wpengine.com/support/network/).

| Type    | Name              | Target                                                                                        | Proxy status |
| ------- | ----------------- | --------------------------------------------------------------------------------------------- | ------------ |
| `CNAME` | `<YOUR_HOSTNAME>` | `wp.wpewaf.com` (Global Edge Security)<br/>or<br/>`wp.wpenginepowered.com` (Advanced Network) | Proxied      |

:::note

For questions about WP Engine setup, refer to their [support guide](https://wpengine.com/support/wordpress-best-practice-configuring-dns-for-wp-engine/#Point_DNS_Using_CNAME_Flattening).

If you cannot activate your domain using [proxied DNS records](/dns/proxy-status/), reach out to your account team.

:::

## Product compatibility

<Render file="provider-guide-compatibility" />

## Zone hold

If your own Cloudflare zone is on the Enterprise plan, you have access to the [zone hold feature](/fundamentals/account/account-security/zone-holds/), which is a toggle that prevents your domain name from being created as a zone in a different Cloudflare account. Additionally, if the zone hold is enabled, it prevents the activation of custom hostnames onboarded to WP Engine. WP Engine would receive the following error message for your custom hostname: `The hostname is associated with a held zone. Please contact the owner of this domain to have the hold removed.`

To successfully activate the custom hostname on WP Engine, the owner of the zone needs to [temporarily release the hold](/fundamentals/account/account-security/zone-holds/#release-zone-holds). If you are only onboarding a subdomain as a custom hostname to WP Engine, only the subfeature titled `Also prevent Subdomains` needs to be temporarily disabled.

Once the zone hold is temporarily disabled, follow WP Engine's instructions to refresh the custom hostname and it should activate.

## Additional support

<Render file="provider-guide-help" params={{ providerName: "WP Engine" }} />

### Resolving SSL errors

If you encounter SSL errors, check if you have a `CAA` record.

If you do have a `CAA` record, check that it permits SSL certificates to be issued by `letsencrypt.org`.

For more details, refer to [CAA records](/ssl/edge-certificates/troubleshooting/caa-records/#what-caa-records-are-added-by-cloudflare).

---

# WAF for SaaS

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/waf-for-saas/

import { APIRequest } from "~/components";

[Web Application Firewall (WAF)](/waf/) allows you to create additional security measures through Cloudflare. As a SaaS provider, you can link custom rules, rate limiting rules, and managed rules to your custom hostnames. This provides more control to keep your domains safe from malicious traffic.

As a SaaS provider, you may want to apply different security measures to different custom hostnames. With WAF for SaaS, you can create multiple WAF configuration that you can apply to different sets of custom hostnames. This added flexibility and security leads to optimal protection across the domains of your end customers.

---

## Prerequisites

Before you can use WAF for SaaS, you need to create a custom hostname. Review [Get started with Cloudflare for SaaS](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/) if you have not already done so.

You can also create a custom hostname through the API:

<APIRequest
  path="/zones/{zone_id}/custom_hostnames"
  method="POST"
  json={{
		"hostname": "<CUSTOM_HOSTNAME>",
		"ssl": {
			wildcard: false
		},
	}}
/>

## 1. Associate custom metadata to a custom hostname

To apply WAF to your custom hostname, you need to create an association between your customer's domain and the WAF configuration that you would like to attach to it. Cloudflare's product, [custom metadata](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/custom-metadata/) allows you to do this via the API.

1. [Locate your zone ID](/fundamentals/account/find-account-and-zone-ids/), available in the Cloudflare dashboard.

2. Locate your Authentication Key by selecting **My Profile** > **API tokens** > **Global API Key**.

3. Locate your custom hostname ID by making a `GET` call in the API:

<APIRequest
  path="/zones/{zone_id}/custom_hostnames"
  method="GET"
/>

4. Plan your [custom metadata](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/custom-metadata/). It is fully customizable. In the example below, we have chosen the tag `"security_level"` to which we expect to assign three values (low, medium, and high).

:::note

One instance of low, medium, and high rules could be rate limiting. You can specify three different thresholds: low - 100 requests/minute, medium - 85 requests/minute, high - 50 requests/minute, for example. Another possibility is a WAF custom rule in which low challenges requests and high blocks them.

:::

5. Make an API call in the format below using your Cloudflare email and the IDs gathered above:

<APIRequest
  path="/zones/{zone_id}/custom_hostnames/{custom_hostname_id}"
  method="PATCH"
  json={{
		"custom_metadata": {
    "customer_id": "12345",
    "security_level": "low"
		},
	}}
/>

This assigns custom metadata to your custom hostname so that it has a security tag associated with its ID.

## 2. Trigger security products based on tags

1. Locate the custom metadata field in the Ruleset Engine where the WAF runs. This can be used to trigger different configurations of products such as [WAF custom rules](/waf/custom-rules/), [rate limiting rules](/waf/rate-limiting-rules/), and [Transform Rules](/rules/transform/).

2. Build your rules either [through the dashboard](/waf/custom-rules/create-dashboard/) or via the API. An example rate limiting rule, corresponding to `"security_level"` low, is shown below as an API call.

<APIRequest
  path="/zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint"
  method="PUT"
  json={{
		"rules": [
			{
				"action": "block",
				"ratelimit": {
					"characteristics": [
						"cf.colo.id",
						"ip.src"
					],
					"period": 10,
					"requests_per_period": 2,
					"mitigation_timeout": 60
				},
				"expression": "lookup_json_string(cf.hostname.metadata, \"security_level\") eq \"low\" and http.request.uri contains \"login\""
			}
		]
	}}
	parameters={{
		ruleset_phase: "http_ratelimit"
	}}
/>

To build rules through the dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and navigate to your account and website.

2. Select **Security** > **WAF**.

3. Follow the instructions on the dashboard specific to custom rules, rate limiting rules, or managed rules, depending on your security goal.

4. Once the rule is active, you should see it under the applicable tab (custom rules, rate limiting, or managed rules).

![Rule Active](~/assets/images/cloudflare-for-platforms/active-rule.png)

---

# Managed Rulesets

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/waf-for-saas/managed-rulesets/

If you are interested in [WAF for SaaS](/cloudflare-for-platforms/cloudflare-for-saas/security/waf-for-saas/) but unsure of where to start, Cloudflare recommends using WAF Managed Rules. The Cloudflare security team creates and manages a variety of rules designed to detect common attack vectors and protect applications from vulnerabilities. These rules are offered in [managed rulesets](/waf/managed-rules/), like Cloudflare Managed and OWASP, which can be deployed with different settings and sensitivity levels.

***

## Prerequisites

WAF for SaaS is available for customers on an Enterprise plan.

If you would like to deploy a managed ruleset at the account level, refer to the [Ruleset Engine documentation](/ruleset-engine/managed-rulesets/deploy-managed-ruleset/).

Ensure you have reviewed [Get Started with Cloudflare for SaaS](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/) and familiarize yourself with [WAF for SaaS](/cloudflare-for-platforms/cloudflare-for-saas/security/waf-for-saas/).

Customers can automate the [custom metadata](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/custom-metadata/) tagging by adding it to the custom hostnames at creation. For more information on tagging a custom hostname with custom metadata, refer to the [API documentation](/api/resources/custom_hostnames/methods/edit/).

***

## 1. Choose security tagging system

1. Outline `security_tag` buckets. These are fully customizable with no strict limit on quantity. For example, you can set `security_tag` to `low`,`medium`, and `high` as a default, with one tag per custom hostname.

2. If you have not already done so, [associate your custom metadata to custom hostnames](/cloudflare-for-platforms/cloudflare-for-saas/security/waf-for-saas/#1-associate-custom-metadata-to-a-custom-hostname) by including the `security_tag`in the custom metadata associated with the custom hostname. The JSON blob associated with the custom hostname is fully customizable.

:::note


After the association is complete, the JSON blob is added to the defined custom hostname. This blob is then associated to every incoming request and exposed in the WAF through the new field `cf.hostname.metadata`. In the rule, you can access `cf.hostname.metadata` and get whatever data you need from that blob.


:::

***

## 2. Deploy Rulesets

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and navigate to your account.

2. Select Account Home > **WAF**.

:::note


**WAF** at the account level will only be visible on Enterprise plans. If you do not see this option, contact your account manager.


:::

3. Select **Deploy a managed ruleset**.

4. Under **Field**, Select *Hostname*. Set the operator as *equals*. The complete expression should look like this, plus any logic you would like to add:

![Rule expression](~/assets/images/cloudflare-for-platforms/rule-expression.png)

5. Beneath **Value**, add the custom hostname.

6. Select **Next**.

7. Find the **Cloudflare Managed Ruleset** card and select **Use this Ruleset**.

8. Click the checkbox next to each rule you want to deploy.

9. Toggle the **Status** button next to each rule to enable or disable it. Then select **Next**.

10. On the review page, give your rule a descriptive name. You can modify the ruleset configuration by changing, for example, what rules are enabled or what action should be the default.

11. Select **Deploy**.

:::note


While this tutorial uses Cloudflare Managed Rulesets, you can also create a custom ruleset and deploy on your custom hostnames. To do this, select **Browse Rulesets** > **Create new ruleset**. For examples of a low/medium/high ruleset, refer to [WAF for SaaS](/cloudflare-for-platforms/cloudflare-for-saas/security/waf-for-saas/).


:::

---

# Advanced Settings

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Custom origin server

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/custom-origin/

import { GlossaryTooltip, Render } from "~/components"

<Render file="custom-origin-server-definition" />

<Render file="ssl-for-saas-plan-limitation" />

## Requirements

To use a custom origin server, you need to meet the following requirements:

* Each custom origin needs to be a valid hostname with a proxied (orange-clouded) A, AAAA, or CNAME record in your account's DNS. You cannot use an IP address.
* The DNS record for the custom origin server does not currently support wildcard values.

## Use a custom origin

To use a custom origin, select that option when [creating a new custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/) in the dashboard or include the `"custom_origin_server": your_custom_origin_server` parameter when using the API [POST command](/api/resources/custom_hostnames/methods/create/).

## SNI rewrites

When Cloudflare establishes a connection to your default origin server, the `Host` header and <GlossaryTooltip term="Server Name Indication (SNI)">SNI</GlossaryTooltip> will both be the value of the original custom hostname.

However, if you configure that custom hostname with a custom origin, the value of the SNI will be that of the custom origin and the `Host` header will be the original custom hostname. Since these values will not match, you will not be able to use the [Full (strict)](/ssl/origin-configuration/ssl-modes/full-strict/) on your origins.

To solve this problem, you can contact your account team to request an entitlement for **SNI rewrites**.

### SNI rewrite options

Choose how your custom hostname populates the SNI value with SNI rewrites:

* **Origin server name** (default): Set SNI to the custom origin

  * If custom origin is `custom-origin.example.com`, then the SNI is `custom-origin.example.com`.

* **Host header**: Set SNI to the host header (or a host header override)

  * If wildcards are not enabled and the hostname is `example.com`, then the SNI is `example.com`.
  * If wildcards are enabled, the hostname is `example.com`, and a request comes to `www.example.com`, then the SNI is `www.example.com`.

* **Subdomain of zone**: Choose what to set as the SNI value (custom hostname or any subdomain)
  * If wildcards are not enabled and a request comes to `example.com`, choose whether to set the SNI as `example.com` or `www.example.com`.
  * If wildcards are enabled, you set the SNI to `example.com`, and a request comes to `www.example.com`, then the SNI is `example.com`.

:::caution[Important]


* Currently, SNI Rewrite is not supported for wildcard custom hostnames. Subdomains covered by a wildcard custom hostname send the custom origin server name as the SNI value.

* In the [O2O context](/cloudflare-for-platforms/cloudflare-for-saas/saas-customers/how-it-works/) (when requests are originating from a proxied hostname on a zone also on Cloudflare), changing the SNI value to use host header is currently not supported.

* SNI overrides defined in an [Origin Rule](/rules/origin-rules/) will take precedence over SNI rewrites.

* SNI Rewrite usage is subject to the [Service-Specific Terms](https://www.cloudflare.com/service-specific-terms-application-services/#ssl-for-saas-terms).


:::

### Set an SNI rewrite

To set an SNI rewrite in the dashboard, choose your preferred option from **Origin SNI value** when [creating a custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/).

To set an SNI rewrite via the API, set the `custom_origin_sni` parameter when [creating a custom hostname](/api/resources/custom_hostnames/methods/create/):

* **Custom origin name** (default): Applies if you do not set the parameter
* **Host header**: Specify `":request_host_header:"`
* **Subdomain of zone**: Set to `"example.com"` or another subdomain of the custom hostname

---

# Workers as your fallback origin

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/worker-as-origin/

If you are building your application on [Cloudflare Workers](/workers/), you can use a Worker as the origin for your SaaS zone (also known as your fallback origin).

1. In your SaaS zone, [create and set a fallback origin](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/#1-create-fallback-origin). Ensure the fallback origin only has an [originless DNS record](/dns/troubleshooting/faq/#what-ip-should-i-use-for-parked-domain--redirect-only--originless-setup):

   * **Example**: `service.example.com AAAA 100::`

2. In that same zone, navigate to **Workers Routes**.

3. Click **Add route**.

4. Decide whether you want traffic bound for your SaaS zone (`example.com`) to go to that Worker:

   * If *yes*, set the following values:

     * **Route**: `*/*` (routes everything — including custom hostnames — to the Worker).
     * **Worker**: Select the Worker used for your SaaS application.

   * If *no*, set the following values:

     * **Route**: `*.<zonename>.com/*` (only routes custom hostname traffic to the Worker)
     * **Worker**: **None**

5. Click **Save**.

---

# Backoff schedule

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/backoff-schedule/

After you create a custom hostname, Cloudflare has to [validate that hostname](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/).

Attempts to validate a Custom Hostname are distributed over seven days (a total of 75 retries). At the end of this schedule, if the validation is unsuccessful, the custom hostname will be deleted. The function that determines the next check varies based on the number of attempts:

* For the first 10 attempts:

```txt
now() + min((floor(60 * pow(1.05, retry_attempt)) * INTERVAL '1 second'), INTERVAL '4 hours')
```

* For the remaining 65 attempts:

```txt
now() + min((floor(60 * pow(1.15, retry_attempt)) * INTERVAL '1 second'), INTERVAL '4 hours')
```

The first 10 checks complete within 20 minutes and most checks complete in the first four hours. The check back off is capped to a maximum of four hours to avoid exponential growth. The back off behavior causes larger gaps between check intervals towards the end of the back off schedule:

| Retry Attempt | In Seconds | In Minutes | In Hours |
| ------------- | ---------- | ---------- | -------- |
| 0             | 60         | 1          | 0.016667 |
| 1             | 63         | 1.05       | 0.0175   |
| 2             | 66         | 1.1        | 0.018333 |
| 3             | 69         | 1.15       | 0.019167 |
| 4             | 72         | 1.2        | 0.02     |
| 5             | 76         | 1.266667   | 0.021111 |
| 6             | 80         | 1.333333   | 0.022222 |
| 7             | 84         | 1.4        | 0.023333 |
| 8             | 88         | 1.466667   | 0.024444 |
| 9             | 93         | 1.55       | 0.025833 |
| 10            | 242        | 4.033333   | 0.067222 |
| 11            | 279        | 4.65       | 0.0775   |
| 12            | 321        | 5.35       | 0.089167 |
| 13            | 369        | 6.15       | 0.1025   |
| 14            | 424        | 7.066667   | 0.117778 |
| 15            | 488        | 8.133333   | 0.135556 |
| 16            | 561        | 9.35       | 0.155833 |
| 17            | 645        | 10.75      | 0.179167 |
| 18            | 742        | 12.366667  | 0.206111 |
| 19            | 853        | 14.216667  | 0.236944 |
| 20            | 981        | 16.35      | 0.2725   |
| 21            | 1129       | 18.816667  | 0.313611 |
| 22            | 1298       | 21.633333  | 0.360556 |
| 23            | 1493       | 24.883333  | 0.414722 |
| 24            | 1717       | 28.616667  | 0.476944 |
| 25            | 1975       | 32.916667  | 0.548611 |
| 26            | 2271       | 37.85      | 0.630833 |
| 27            | 2612       | 43.533333  | 0.725556 |
| 28            | 3003       | 50.05      | 0.834167 |
| 29            | 3454       | 57.566667  | 0.959444 |
| 30            | 3972       | 66.2       | 1.103333 |
| 31            | 4568       | 76.133333  | 1.268889 |
| 32            | 5253       | 87.55      | 1.459167 |
| 33            | 6041       | 100.683333 | 1.678056 |
| 34            | 6948       | 115.8      | 1.93     |
| 35            | 7990       | 133.166667 | 2.219444 |
| 36            | 9189       | 153.15     | 2.5525   |
| 37            | 10567      | 176.116667 | 2.935278 |
| 38            | 12152      | 202.533333 | 3.375556 |
| 39            | 13975      | 232.916667 | 3.881944 |
| 40            | 14400      | 240        | 4        |
| 41            | 14400      | 240        | 4        |
| 42            | 14400      | 240        | 4        |
| 43            | 14400      | 240        | 4        |
| 44            | 14400      | 240        | 4        |
| 45            | 14400      | 240        | 4        |
| 46            | 14400      | 240        | 4        |
| 47            | 14400      | 240        | 4        |
| 48            | 14400      | 240        | 4        |
| 49            | 14400      | 240        | 4        |
| 50            | 14400      | 240        | 4        |
| 51            | 14400      | 240        | 4        |
| 52            | 14400      | 240        | 4        |
| 53            | 14400      | 240        | 4        |
| 54            | 14400      | 240        | 4        |
| 55            | 14400      | 240        | 4        |
| 56            | 14400      | 240        | 4        |
| 57            | 14400      | 240        | 4        |
| 58            | 14400      | 240        | 4        |
| 59            | 14400      | 240        | 4        |
| 60            | 14400      | 240        | 4        |
| 61            | 14400      | 240        | 4        |
| 62            | 14400      | 240        | 4        |
| 63            | 14400      | 240        | 4        |
| 64            | 14400      | 240        | 4        |
| 65            | 14400      | 240        | 4        |
| 66            | 14400      | 240        | 4        |
| 67            | 14400      | 240        | 4        |
| 68            | 14400      | 240        | 4        |
| 69            | 14400      | 240        | 4        |
| 70            | 14400      | 240        | 4        |
| 71            | 14400      | 240        | 4        |
| 72            | 14400      | 240        | 4        |
| 73            | 14400      | 240        | 4        |
| 74            | 14400      | 240        | 4        |
| 75            | 14400      | 240        | 4        |

---

# Error codes

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/error-codes/

When you [validate a custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/), you might encounter the following error codes.

| Error                                                                                                                       | Cause                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Zone does not have a fallback origin set.                                                                                   | Fallback is not active.                                                                                                                                                                                   |
| Fallback origin is in a status of `initializing`, `pending_deployment`, `pending_deletion`, or `deleted`.                   | Fallback is not active.                                                                                                                                                                                   |
| Custom hostname does not `CNAME` to this zone.                                                                              | Zone does not have [apex proxying entitlement](/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/apex-proxying/) and custom hostname does not CNAME to zone.                          |
| None of the `A` or `AAAA` records are owned by this account and the pre-generated ownership validation token was not found. | Account has [apex proxying enabled](/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/apex-proxying/) but the custom hostname failed the hostname validation check on the `A` record. |
| This account and the pre-generated ownership validation token was not found.                                                | Hostname does not `CNAME` to zone or none of the `A`/`AAAA` records match reserved IPs for zone.                                                                                                          |

---

# Hostname validation

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/

import { DirectoryListing } from "~/components";

Before Cloudflare can proxy traffic through a custom hostname, we need to verify your customer's ownership of that hostname.

:::note
If a custom hostname is already on Cloudflare, using the [pre-validation methods](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/pre-validation/) will not shift the traffic to the SaaS zone. That will only happen once the [DNS target](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/#3-have-customer-create-cname-record) of the custom hostnames changes to point to the SaaS zone.
:::

## Options

If minimizing downtime is more important to you, refer to our [pre-validation methods](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/pre-validation/).

If ease of use for your customers is more important, review our [real-time validation methods](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/realtime-validation/).

## Limitations

Custom hostnames using another CDN are not compatible with Cloudflare for SaaS. Since Cloudflare must be able to validate your customer's ownership of the hostname you add, if their usage of another CDN obfuscates their DNS records, hostname validation will fail.

## Related resources

<DirectoryListing />

---

# Pre-validation

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/pre-validation/

Pre-validation methods help verify domain ownership before your customer's traffic is proxying through Cloudflare.

## Use when

Use pre-validation methods when your customers cannot tolerate any downtime, which often occurs with production domains.

The downside is that these methods require an additional setup step for your customers. Especially if you already need them to add something to their domain for [certificate validation](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/), pre-validation might make their onboarding more complicated.

If your customers can tolerate a bit of downtime and you want their setup to be simpler, review our [real-time validation methods](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/realtime-validation/).

## How to

### TXT records

TXT validation is when your customer adds a `TXT` record to their authoritative DNS to verify domain ownership.

:::note


If your customer cannot update their authoritative DNS, you could also use [HTTP validation](#http-tokens).


:::

To set up `TXT` validation:

1. When you [create a custom hostname](/api/resources/custom_hostnames/methods/create/), save the `ownership_verification` information.

   ```json null {11-12}
   {
   "result": [
       {
       "id": "3537a672-e4d8-4d89-aab9-26cb622918a1",
       "hostname": "app.example.com",
       // ...
       "status": "pending",
       "verification_errors": ["custom hostname does not CNAME to this zone."],
       "ownership_verification": {
           "type": "txt",
           "name": "_cf-custom-hostname.app.example.com",
           "value": "0e2d5a7f-1548-4f27-8c05-b577cb14f4ec"
       },
       "created_at": "2020-03-04T19:04:02.705068Z"
       }
   ]
   }
   ```

2. Have your customer add a `TXT` record with that `name` and `value` at their authoritative DNS provider.

3. After a few minutes, you will see the hostname status become **Active** in the UI.

4. Once you activate the custom hostname, your customer can remove the `TXT` record.

### HTTP tokens

HTTP validation is when you or your customer places an HTTP token on their origin server to verify domain ownership.

To set up HTTP validation:

When you [create a custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/issue-certificates/) using the API, Cloudflare provides an HTTP `ownership_verification` record in the response.

To get and use the `ownership_verification` record:

1. Make an API call to [create a Custom Hostname](/api/resources/custom_hostnames/methods/create/).

2. In the response, copy the `http_url` and `http_body` from the `ownership_verification_http` object:

   ```json title="Example response (truncated)" {8-9}
   {
     "result": [
       {
         "id": "24c8c68e-bec2-49b6-868e-f06373780630",
         "hostname": "app.example.com",
         // ...
         "ownership_verification_http": {
             "http_url": "http://app.example.com/.well-known/cf-custom-hostname-challenge/24c8c68e-bec2-49b6-868e-f06373780630",
             "http_body": "48b409f6-c886-406b-8cbc-0fbf59983555"
         },
         "created_at": "2020-03-04T20:06:04.117122Z"
       }
     ]
   }
   ```

3. Have your customer place the `http_url` and `http_body` on their origin web server.

   ```txt title="Example response (truncated)"
   location "/.well-known/cf-custom-hostname-challenge/24c8c68e-bec2-49b6-868e-f06373780630" {
       return 200 "48b409f6-c886-406b-8cbc-0fbf59983555\n";
   }
   ```

   Cloudflare will access this token by sending `GET` requests to the `http_url` using `User-Agent: Cloudflare Custom Hostname Verification`.

   :::note
   If you can serve these tokens on behalf of your customers, you can simplify their overall setup.
   :::

4. After a few minutes, you will see the hostname status become **Active** in the UI.

5. Once the hostname is active, your customer can remove the token from their origin server.

---

# Real-time validation

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/realtime-validation/

import { Render } from "~/components"

When you use a real-time validation method, Cloudflare verifies your customer's hostname when your customers adds their [DNS routing record](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/#3-have-customer-create-cname-record) to their authoritative DNS.

## Use when

Real-time validation methods put less burden on your customers because it does not require any additional actions.

However, it may cause some downtime since Cloudflare takes a few seconds to iterate over DNS records. This downtime also can increase - due to the increasing [validation backoff schedule](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/backoff-schedule/) - if your customer takes additional time to add their DNS routing record.

To minimize this downtime, you can continually send no-change [`PATCH` requests](/api/resources/custom_hostnames/methods/edit/) for the specific custom hostname until it validates (which resets the validation backoff schedule).

To avoid any chance of downtime, use a [pre-validation method](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/pre-validation/)

## How to

Real-time validation occurs automatically when your customer adds their [DNS routing record](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/#3-have-customer-create-cname-record).

The exact record depends on your Cloudflare for SaaS setup.

### Normal setup (CNAME target)

<Render file="cname-target-process" />

### Apex proxying

<Render file="apex-proxying-process" />

---

# Validation status

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/validation-status/

When you [validate a custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/), that hostname can be in several different statuses.

| Status              | Description                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pending             | Custom hostname is pending hostname validation.                                                                                                                                                                                                                                                                                                                                              |
| Active              | Custom hostname has completed hostname validation and is active.                                                                                                                                                                                                                                                                                                                             |
| Active re-deploying | Customer hostname is active and the changes have been processed.                                                                                                                                                                                                                                                                                                                             |
| Blocked             | Custom hostname cannot be added to Cloudflare at this time. Custom hostname was likely associated with Cloudflare previously and flagged for abuse.<br/><br/>If you are an Enterprise customer, contact your Customer Success Manager. Otherwise, email `abusereply@cloudflare.com` with the name of the web property and a detailed explanation of your association with this web property. |
| Moved               | Custom hostname is not active after **Pending** for the entirety of the [Validation Backoff Schedule](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/backoff-schedule/) or it no longer points to the fallback origin.                                                                                                                                     |
| Deleted             | Custom hostname was deleted from the zone. Occurs when status is **Moved** for more than seven days.                                                                                                                                                                                                                                                                                         |

## Refresh validation

To run the custom hostname validation check again, select **Refresh** on the dashboard or send a `PATCH` request to the [Edit custom hostname endpoint](/api/resources/custom_hostnames/methods/edit/). If using the API, make sure that the `--data` field contains an `ssl` object with the same `method` and `type` as the original request.

If the hostname is in a **Moved** or **Deleted** state, the refresh will set the custom hostname back to **Pending validation**.

---

# AWS RDS and Aurora

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-mysql/mysql-database-providers/aws-rds-aurora/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to an Amazon Relational Database Service (Amazon RDS) or Amazon Aurora MySQL database instance.

## 1. Allow Hyperdrive access

To allow Hyperdrive to connect to your database, you will need to ensure that Hyperdrive has valid user credentials and network access.

<Render file="public-connectivity" />

### AWS Console

When creating or modifying an instance in the AWS console:

1. Configure a **database cluster** and other settings you wish to customize.
2. Under **Settings** > **Credential settings**, note down the **Master username** and **Master password** (Aurora only).
3. Under the **Connectivity** header, ensure **Public access** is set to **Yes**.
4. Select an **Existing VPC security group** that allows public Internet access from `0.0.0.0/0` to the port your database instance is configured to listen on (default: `5432` for PostgreSQL instances).
5. Select **Create database**.

:::caution

You must ensure that the [VPC security group](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-security-groups.html) associated with your database allows public IPv4 access to your database port.

Refer to AWS' [database server rules](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-group-rules-reference.html#sg-rules-db-server) for details on how to configure rules specific to your RDS database.

:::

### Retrieve the database endpoint (Aurora)

To retrieve the database endpoint (hostname) for Hyperdrive to connect to:

1. Go to **Databases** view under **RDS** in the AWS console.
2. Select the database you want Hyperdrive to connect to.
3. Under the **Endpoints** header, note down the **Endpoint name** with the type `Writer` and the **Port**.

### Retrieve the database endpoint (RDS MySQL)

For regular RDS instances (non-Aurora), you will need to fetch the endpoint and port of the database:

1. Go to **Databases** view under **RDS** in the AWS console.
2. Select the database you want Hyperdrive to connect to.
3. Under the **Connectivity & security** header, note down the **Endpoint** and the **Port**.

The endpoint will resemble `YOUR_DATABASE_NAME.cpuo5rlli58m.AWS_REGION.rds.amazonaws.com`, and the port will default to `3306`.

:::note[Support for MySQL-compatible providers]

Support for AWS Aurora MySQL databases is coming soon. Join our early preview support by reaching out to us in the [Hyperdrive Discord channel](https://discord.cloudflare.com/).

:::

## 2. Create your user

Once your database is created, you will need to create a user for Hyperdrive to connect as. Although you can use the **Master username** configured during initial database creation, best practice is to create a less privileged user.

To create a new user, log in to the database and use the `CREATE ROLE` command:

```sh
# Log in to the database
psql postgresql://MASTER_USERNAME:MASTER_PASSWORD@ENDPOINT_NAME:PORT/database_name
```

Run the following SQL statements:

```sql
-- Create a role for Hyperdrive
CREATE ROLE hyperdrive;

-- Allow Hyperdrive to connect
GRANT CONNECT ON DATABASE postgres TO hyperdrive;

-- Grant database privileges to the hyperdrive role
GRANT ALL PRIVILEGES ON DATABASE postgres to hyperdrive;

-- Create a specific user for Hyperdrive to log in as
CREATE ROLE hyperdrive_user LOGIN PASSWORD 'sufficientlyRandomPassword';

-- Grant this new user the hyperdrive role privileges
GRANT hyperdrive to hyperdrive_user;
```

Refer to AWS' [documentation on user roles in PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.Roles.html) for more details.

With a database user, password, database endpoint (hostname and port), and database name (default: `postgres`), you can now set up Hyperdrive.

## 3. Create a database configuration

<Render file="create-hyperdrive-config-mysql" />
<Render file="create-hyperdrive-config-mysql-next-steps" />

---

# Azure Database

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-mysql/mysql-database-providers/azure/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to an Azure Database for PostgreSQL instance.

## 1. Allow Hyperdrive access

To allow Hyperdrive to connect to your database, you will need to ensure that Hyperdrive has valid credentials and network access.

<Render file="public-connectivity" />

### Azure Portal

#### Public access networking

To connect to your Azure Database for MySQL instance using public Internet connectivity:

1. In the [Azure Portal](https://portal.azure.com/), select the instance you want Hyperdrive to connect to.
2. Expand **Settings** > **Networking** > ensure **Public access** is enabled > in **Firewall rules** add `0.0.0.0` as **Start IP address** and `255.255.255.255` as **End IP address**.
3. Select **Save** to persist your changes.
4. Select **Overview** from the sidebar and note down the **Server name** of your instance.

With the username, password, server name, and database name (default: `mysql`), you can now create a Hyperdrive database configuration.

#### Private access networking

To connect to a private Azure Database for MySQL instance, refer to [Connect to a private database using Tunnel](/hyperdrive/configuration/connect-to-private-database/).

## 2. Create a database configuration

<Render file="create-hyperdrive-config-mysql" />
<Render file="create-hyperdrive-config-mysql-next-steps" />

---

# Google Cloud SQL

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-mysql/mysql-database-providers/google-cloud-sql/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a Google Cloud SQL MySQL database instance.

## 1. Allow Hyperdrive access

To allow Hyperdrive to connect to your database, you will need to ensure that Hyperdrive has valid user credentials and network access.

<Render file="public-connectivity" />

### Cloud Console

When creating the instance or when editing an existing instance in the [Google Cloud Console](https://console.cloud.google.com/sql/instances):

To allow Hyperdrive to reach your instance:

1. In the [Cloud Console](https://console.cloud.google.com/sql/instances), select the instance you want Hyperdrive to connect to.
2. Expand **Connections** > **Networking** > ensure **Public IP** is enabled > **Add a Network** and input `0.0.0.0/0`.
3. Select **Done** > **Save** to persist your changes.
4. Select **Overview** from the sidebar and note down the **Public IP address** of your instance.

To create a user for Hyperdrive to connect as:

1. Select **Users** in the sidebar.
2. Select **Add User Account** > select **Built-in authentication**.
3. Provide a name (for example, `hyperdrive-user`), then select **Generate** to generate a password.
4. Copy this password to your clipboard before selecting **Add** to create the user.

With the username, password, public IP address and (optional) database name (default: `mysql`), you can now create a Hyperdrive database configuration.

## 2. Create a database configuration

<Render file="create-hyperdrive-config-mysql" />
<Render file="create-hyperdrive-config-mysql-next-steps" />

---

# Database Providers

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-mysql/mysql-database-providers/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# PlanetScale

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-mysql/mysql-database-providers/planetscale/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a [PlanetScale](https://planetscale.com/) MySQL database.

<Render file="planetscale-partial" />

---

# Drizzle ORM

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/drizzle-orm/

import { Render, Steps } from "~/components";

[Drizzle ORM](https://orm.drizzle.team/) is a lightweight TypeScript ORM with a focus on type safety. This example demonstrates how to use Drizzle ORM with MySQL via Cloudflare Hyperdrive in a Workers application.

## Prerequisites

- A Cloudflare account with Workers access
- A MySQL database
- A [Hyperdrive configuration to your MySQL database](/hyperdrive/get-started/#3-connect-hyperdrive-to-a-database)

## 1. Install Drizzle

Install the Drizzle ORM and its dependencies such as the [mysql2](https://github.com/sidorares/node-mysql2) driver:

```sh
# mysql2 v3.13.0 or later is required
npm i drizzle-orm mysql2 dotenv
npm i -D drizzle-kit tsx @types/node
```

Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file:

<Render file="hyperdrive-node-compatibility-requirement" product="hyperdrive"/>

## 2. Configure Drizzle

### 2.1. Define a schema

With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL.

<Steps>
1. Create a folder `/db/` in `/src/`.
2. Create a `schema.ts` file.
3. In `schema.ts`, define a `users` table as shown below.

	```ts title="src/db/schema.ts"
	// src/schema.ts
	import { mysqlTable, int, varchar, timestamp } from "drizzle-orm/mysql-core";

	export const users = mysqlTable("users", {
		id: int("id").primaryKey().autoincrement(),
		name: varchar("name", { length: 255 }).notNull(),
		email: varchar("email", { length: 255 }).notNull().unique(),
		createdAt: timestamp("created_at").defaultNow(),
	});
	```
</Steps>

### 2.2. Connect Drizzle ORM to the database with Hyperdrive

Use your the credentials of your Hyperdrive configuration for your database when using the Drizzle ORM.

Populate your `index.ts` file as shown below.

```ts title="src/index.ts"
// src/index.ts

import { drizzle } from "drizzle-orm/mysql2";
import { createConnection } from "mysql2";
import { users } from "./db/schema";

export interface Env {
	HYPERDRIVE: Hyperdrive;
  }

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a connection using the mysql2 driver with the Hyperdrive credentials (only accessible from your Worker).
		const connection = await createConnection({
			host: env.HYPERDRIVE.host,
			user: env.HYPERDRIVE.user,
			password: env.HYPERDRIVE.password,
			database: env.HYPERDRIVE.database,
			port: env.HYPERDRIVE.port,

			// Required to enable mysql2 compatibility for Workers
			disableEval: true,
		});

		// Create the Drizzle client with the mysql2 driver connection
		const db = drizzle(connection);

		// Sample query to get all users
		const allUsers = await db.select().from(users);

		return Response.json(allUsers);
	},
} satisfies ExportedHandler<Env>;
```

### 2.3. Configure Drizzle-Kit for migrations (optional)

:::note
You need to set up the tables in your database so that Drizzle ORM can make queries that work.

If you have already set it up (for example, if another user has applied the schema to your database), or if you are starting to use Drizzle ORM and the schema matches what already exists in your database, then you do not need to run the migration.
:::

You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/mysql-new) for additional guidance.

<Steps>
1. Create a `.env` file in the root folder of your project, and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations.

   ```toml title=".env"
   # .env
   # Replace with your direct database connection string
   DATABASE_URL='mysql://user:password@db-host.cloud/database-name'
   ```

2. Create a `drizzle.config.ts` file in the root folder of your project to configure Drizzle Kit and add the following content:

   ```ts title="drizzle.config.ts"
   import 'dotenv/config';
   import { defineConfig } from 'drizzle-kit';
   export default defineConfig({
   out: './drizzle',
   schema: './src/db/schema.ts',
   dialect: 'mysql',
   dbCredentials: {
   url: process.env.DATABASE_URL!,
     },
   });
   ```

3. Generate the migration file for your database according to your schema files and apply the migrations to your database.

   ```bash
   npx drizzle-kit generate
   ```
   ```bash output
   No config path provided, using default 'drizzle.config.ts'
   Reading config file 'drizzle.config.ts'
   Reading schema files:
   /src/db/schema.ts

   1 tables
   users 4 columns 0 indexes 0 fks

   [✓] Your SQL migration file ➜ drizzle/0000_daffy_rhodey.sql 🚀
   ```
   ```bash
   npx drizzle-kit migrate
   ```
   ```bash output
   No config path provided, using default 'drizzle.config.ts'
   Reading config file 'drizzle.config.ts'
   ```
</Steps>

## 3. Deploy your Worker

Deploy your Worker.

```bash
npx wrangler deploy
```

<Render file="create-hyperdrive-config-next-steps" product="hyperdrive" />

---

# Libraries and Drivers

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# mysql

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql/

import { Render } from "~/components";

The [mysql](https://github.com/mysqljs/mysql) package is a MySQL driver for Node.js.
This example demonstrates how to use it with Cloudflare Workers and Hyperdrive.

<Render file="use-mysql-to-make-query" product="hyperdrive" />

---

# mysql2

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-mysql/mysql-drivers-and-libraries/mysql2/

import { Render } from "~/components";

The [mysql2](https://github.com/sidorares/node-mysql2) package is a modern MySQL driver for Node.js with better performance and built-in Promise support.
This example demonstrates how to use it with Cloudflare Workers and Hyperdrive.

<Render file="use-mysql2-to-make-query" product="hyperdrive" />

---

# AWS RDS and Aurora

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/aws-rds-aurora/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to an Amazon Relational Database Service (Amazon RDS) Postgres or Amazon Aurora database instance.

## 1. Allow Hyperdrive access

To allow Hyperdrive to connect to your database, you will need to ensure that Hyperdrive has valid user credentials and network access.

<Render file="public-connectivity" />

### AWS Console

When creating or modifying an instance in the AWS console:

1. Configure a **DB cluster identifier** and other settings you wish to customize.
2. Under **Settings** > **Credential settings**, note down the **Master username** and **Master password** (Aurora only).
3. Under the **Connectivity** header, ensure **Public access** is set to **Yes**.
4. Select an **Existing VPC security group** that allows public Internet access from `0.0.0.0/0` to the port your database instance is configured to listen on (default: `5432` for PostgreSQL instances).
5. Select **Create database**.

:::caution

You must ensure that the [VPC security group](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-security-groups.html) associated with your database allows public IPv4 access to your database port.

Refer to AWS' [database server rules](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/security-group-rules-reference.html#sg-rules-db-server) for details on how to configure rules specific to your RDS or Aurora database.

:::

### Retrieve the database endpoint (Aurora)

To retrieve the database endpoint (hostname) for Hyperdrive to connect to:

1. Go to **Databases** view under **RDS** in the AWS console.
2. Select the database you want Hyperdrive to connect to.
3. Under the **Endpoints** header, note down the **Endpoint name** with the type `Writer` and the **Port**.

### Retrieve the database endpoint (RDS PostgreSQL)

For regular RDS instances (non-Aurora), you will need to fetch the endpoint and port of the database:

1. Go to **Databases** view under **RDS** in the AWS console.
2. Select the database you want Hyperdrive to connect to.
3. Under the **Connectivity & security** header, note down the **Endpoint** and the **Port**.

The endpoint will resemble `YOUR_DATABASE_NAME.cpuo5rlli58m.AWS_REGION.rds.amazonaws.com` and the port will default to `5432`.

## 2. Create your user

Once your database is created, you will need to create a user for Hyperdrive to connect as. Although you can use the **Master username** configured during initial database creation, best practice is to create a less privileged user.

To create a new user, log in to the database and use the `CREATE ROLE` command:

```sh
# Log in to the database
psql postgresql://MASTER_USERNAME:MASTER_PASSWORD@ENDPOINT_NAME:PORT/database_name
```

Run the following SQL statements:

```sql
-- Create a role for Hyperdrive
CREATE ROLE hyperdrive;

-- Allow Hyperdrive to connect
GRANT CONNECT ON DATABASE postgres TO hyperdrive;

-- Grant database privileges to the hyperdrive role
GRANT ALL PRIVILEGES ON DATABASE postgres to hyperdrive;

-- Create a specific user for Hyperdrive to log in as
CREATE ROLE hyperdrive_user LOGIN PASSWORD 'sufficientlyRandomPassword';

-- Grant this new user the hyperdrive role privileges
GRANT hyperdrive to hyperdrive_user;
```

Refer to AWS' [documentation on user roles in PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.Roles.html) for more details.

With a database user, password, database endpoint (hostname and port) and database name (default: `postgres`), you can now set up Hyperdrive.

## 3. Create a database configuration

<Render file="create-hyperdrive-config" />
<Render file="create-hyperdrive-config-next-steps" />

---

# Azure Database

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/azure/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to an Azure Database for PostgreSQL instance.

## 1. Allow Hyperdrive access

To allow Hyperdrive to connect to your database, you will need to ensure that Hyperdrive has valid credentials and network access.

<Render file="public-connectivity" />

### Azure Portal

#### Public access networking

To connect to your Azure Database for PostgreSQL instance using public Internet connectivity:

1. In the [Azure Portal](https://portal.azure.com/), select the instance you want Hyperdrive to connect to.
2. Expand **Settings** > **Networking** > ensure **Public access** is enabled > in **Firewall rules** add `0.0.0.0` as **Start IP address** and `255.255.255.255` as **End IP address**.
3. Select **Save** to persist your changes.
4. Select **Overview** from the sidebar and note down the **Server name** of your instance.

With the username, password, server name, and database name (default: `postgres`), you can now create a Hyperdrive database configuration.

#### Private access networking

To connect to a private Azure Database for PostgreSQL instance, refer to [Connect to a private database using Tunnel](/hyperdrive/configuration/connect-to-private-database/).

## 2. Create a database configuration

<Render file="create-hyperdrive-config" />
<Render file="create-hyperdrive-config-next-steps" />

---

# CockroachDB

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a [CockroachDB](https://www.cockroachlabs.com/) database cluster. CockroachDB is a PostgreSQL-compatible distributed SQL database with strong consistency guarantees.

## 1. Allow Hyperdrive access

To allow Hyperdrive to connect to your database, you will need to ensure that Hyperdrive has valid user credentials and network access.

### CockroachDB Console

The steps below assume you have an [existing CockroachDB Cloud account](https://www.cockroachlabs.com/docs/cockroachcloud/quickstart) and database cluster created.

To create and/or fetch your database credentials:

1. Go to the [CockroachDB Cloud console](https://cockroachlabs.cloud/clusters) and select the cluster you want Hyperdrive to connect to.
2. Select **SQL Users** from the sidebar on the left, and select **Add User**.
3. Enter a username (for example, \`hyperdrive-user), and select **Generate & Save Password**.
4. Note down the username and copy the password to a temporary location.

To retrieve your database connection details:

1. Go to the [CockroachDB Cloud console](https://cockroachlabs.cloud/clusters) and select the cluster you want Hyperdrive to connect to.
2. Select **Connect** in the top right.
3. Choose the user you created, for example,`hyperdrive-user`.
4. Select the database, for example `defaultdb`.
5. Select **General connection string** as the option.
6. In the text box below, select **Copy** to copy the connection string.

By default, the CockroachDB cloud enables connections from the public Internet (`0.0.0.0/0`). If you have changed these settings on an existing cluster, you will need to allow connections from the public Internet for Hyperdrive to connect.

## 2. Create a database configuration

<Render file="create-hyperdrive-config" />
<Render file="create-hyperdrive-config-next-steps" />

---

# Digital Ocean

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/digital-ocean/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a Digital Ocean database instance.

## 1. Allow Hyperdrive access

To allow Hyperdrive to connect to your database, you will need to ensure that Hyperdrive has valid user credentials and network access.

### DigitalOcean Dashboard

1. Go to the DigitalOcean dashboard and select the database you wish to connect to.
2. Go to the **Overview** tab.
3. Under the **Connection Details** panel, select **Public network**.
4. On the dropdown menu, select **Connection string** > **show-password**.
5. Copy the connection string.

With the connection string, you can now create a Hyperdrive database configuration.

## 2. Create a database configuration

<Render file="create-hyperdrive-config" />
<Render file="create-hyperdrive-config-next-steps" />

:::note
If you see a DNS-related error, it is possible that the DNS for your vendor's database has not yet been propagated. Try waiting 10 minutes before retrying the operation. Refer to [DigitalOcean support page](https://docs.digitalocean.com/support/why-does-my-domain-fail-to-resolve/) for more information.
:::

---

# Fly

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/fly/

import { Render, Steps } from "~/components";

This example shows you how to connect Hyperdrive to a Fly Postgres database instance.

## 1. Allow Hyperdrive access

You can connect Hyperdrive to any existing Fly database by:

1. Allocating a public IP address to your Fly database instance
2. Configuring an external service
3. Deploying the configuration
4. Obtain the connection string, which is used to connect the database to Hyperdrive.

<Steps>
1. Run the following command to [allocate a public IP address](https://fly.io/docs/postgres/connecting/connecting-external/#allocate-an-ip-address).

    ```txt
    fly ips allocate-v6 --app <pg-app-name>
    ```

    :::note
    Cloudflare recommends using IPv6, but some Internet service providers may not support IPv6. In this case, [you can allocate an IPv4 address](https://fly.io/docs/postgres/connecting/connecting-with-flyctl/).
    :::

2.  [Configure an external service](https://fly.io/docs/postgres/connecting/connecting-external/#configure-an-external-service) by modifying the contents of your `fly.toml` file. Run the following command to download the `fly.toml` file.

    ```txt
    fly config save --app <pg-app-name>
    ```

    Then, replace the `services` and `services.ports` section of the file with the following `toml` snippet:

    ```toml
    [[services]]
    	internal_port = 5432 # Postgres instance
    	protocol = "tcp"

    [[services.ports]]
    	handlers = ["pg_tls"]
    	port = 5432
    ```

3.  [Deploy the new configuration](https://fly.io/docs/postgres/connecting/connecting-external/#deploy-with-the-new-configuration).
4.  [Obtain the connection string](https://fly.io/docs/postgres/connecting/connecting-external/#adapting-the-connection-string), which is in the form of:

        ```txt
        postgres://{username}:{password}@{public-hostname}:{port}/{database}?options
        ```

</Steps>

## 2. Create a database configuration

<Render file="create-hyperdrive-config" />
<Render file="create-hyperdrive-config-next-steps" />

---

# Database Providers

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Google Cloud SQL

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/google-cloud-sql/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a Google Cloud SQL Postgres database instance.

## 1. Allow Hyperdrive access

To allow Hyperdrive to connect to your database, you will need to ensure that Hyperdrive has valid user credentials and network access.

<Render file="public-connectivity" />

### Cloud Console

When creating the instance or when editing an existing instance in the [Google Cloud Console](https://console.cloud.google.com/sql/instances):

To allow Hyperdrive to reach your instance:

1. In the [Cloud Console](https://console.cloud.google.com/sql/instances), select the instance you want Hyperdrive to connect to.
2. Expand **Connections** > **Networking** > ensure **Public IP** is enabled > **Add a Network** and input `0.0.0.0/0`.
3. Select **Done** > **Save** to persist your changes.
4. Select **Overview** from the sidebar and note down the **Public IP address** of your instance.

To create a user for Hyperdrive to connect as:

1. Select **Users** in the sidebar.
2. Select **Add User Account** > select **Built-in authentication**.
3. Provide a name (for example, `hyperdrive-user`) > select **Generate** to generate a password.
4. Copy this password to your clipboard before selecting **Add** to create the user.

With the username, password, public IP address and (optional) database name (default: `postgres`), you can now create a Hyperdrive database configuration.

### gcloud CLI

The [gcloud CLI](https://cloud.google.com/sdk/docs/install) allows you to create a new user and enable Hyperdrive to connect to your database.

Use `gcloud sql` to create a new user (for example, `hyperdrive-user`) with a strong password:

```sh
gcloud sql users create hyperdrive-user --instance=YOUR_INSTANCE_NAME --password=SUFFICIENTLY_LONG_PASSWORD
```

Run the following command to enable [Internet access](https://cloud.google.com/sql/docs/postgres/configure-ip) to your database instance:

```sh
# If you have any existing authorized networks, ensure you provide those as a comma separated list.
# The gcloud CLI will replace any existing authorized networks with the list you provide here.
gcloud sql instances patch YOUR_INSTANCE_NAME --authorized-networks="0.0.0.0/0"
```

Refer to [Google Cloud's documentation](https://cloud.google.com/sql/docs/postgres/create-manage-users) for additional configuration options.

## 2. Create a database configuration

<Render file="create-hyperdrive-config" />
<Render file="create-hyperdrive-config-next-steps" />

---

# Materialize

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/materialize/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a [Materialize](https://materialize.com/) database. Materialize is a Postgres-compatible streaming database that can automatically compute real-time results against your streaming data sources.

## 1. Allow Hyperdrive access

To allow Hyperdrive to connect to your database, you will need to ensure that Hyperdrive has valid user credentials and network access to your database.

### Materialize Console

:::note

Read the Materialize [Quickstart guide](https://materialize.com/docs/get-started/quickstart/) to set up your first database. The steps below assume you have an existing Materialize database ready to go.

:::

You will need to create a new application user and password for Hyperdrive to connect with:

1. Log in to the [Materialize Console](https://console.materialize.com/).
2. Under the **App Passwords** section, select **Manage app passwords**.
3. Select **New app password** and enter a name, for example, `hyperdrive-user`.
4. Select **Create Password**.
5. Copy the provided password: it will only be shown once.

To retrieve the hostname and database name of your Materialize configuration:

1. Select **Connect** in the sidebar of the Materialize Console.
2. Select **External tools**.
3. Copy the **Host**, **Port** and **Database** settings.

With the username, app password, hostname, port and database name, you can now connect Hyperdrive to your Materialize database.

## 2. Create a database configuration

<Render file="create-hyperdrive-config" />
<Render file="create-hyperdrive-config-next-steps" />

---

# Neon

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/neon/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a [Neon](https://neon.tech/) Postgres database.

<Render file="neon-partial" />

---

# Nile

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/nile/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a [Nile](https://thenile.dev) PostgreSQL database instance.

Nile is PostgreSQL re-engineered for multi-tenant applications. Nile's virtual tenant databases provide you with isolation, placement, insight, and other features for your tenant's data and embedding. Refer to [Nile documentation](https://www.thenile.dev/docs/getting-started/whatisnile) to learn more.

## 1. Allow Hyperdrive access

You can connect Cloudflare Hyperdrive to any Nile database in your workspace using its connection string - either with a new set of credentials, or using an existing set.

### Nile console

To get a connection string from Nile console:

1. Log in to [Nile console](https://console.thenile.dev), then select a database.
2. On the left hand menu, click **Settings** (the bottom-most icon) and then select **Connection**.
3. Select the PostgreSQL logo to show the connection string.
4. Select "Generate credentials" to generate new credentials.
5. Copy the connection string (without the "psql" part).

You will have obtained a connection string similar to the following:

```txt
    postgres://0191c898-...:4d7d8b45-...@eu-central-1.db.thenile.dev:5432/my_database
```

With the connection string, you can now create a Hyperdrive database configuration.

## 2. Create a database configuration

<Render file="create-hyperdrive-config" />
<Render file="create-hyperdrive-config-next-steps" />

---

# pgEdge Cloud

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/pgedge/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a [pgEdge](https://pgedge.com/) Postgres database. pgEdge Cloud provides easy deployment of fully-managed, fully-distributed, and secure Postgres.

## 1. Allow Hyperdrive access

You can connect Hyperdrive to any existing pgEdge database with the default user and password provided by pgEdge.

### pgEdge dashboard

To retrieve your connection string from the pgEdge dashboard:

1. Go to the [**pgEdge dashboard**](https://app.pgedge.com) and select the database you wish to connect to.
2. From the **Connect to your database** section, note down the connection string (starting with `postgres://app@...`) from the **Connection String** text box.

## 2. Create a database configuration

<Render file="create-hyperdrive-config" />
<Render file="create-hyperdrive-config-next-steps" />

---

# Supabase

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a [Supabase](https://supabase.com/) Postgres database.

## 1. Allow Hyperdrive access

You can connect Hyperdrive to any existing Supabase database as the Postgres user which is set up during project creation.
Alternatively, to create a new user for Hyperdrive, run these commands in the [SQL Editor](https://supabase.com/dashboard/project/_/sql/new).

```sql
CREATE ROLE hyperdrive_user LOGIN PASSWORD 'sufficientlyRandomPassword';

-- Here, you are granting it the postgres role. In practice, you want to create a role with lesser privileges.
GRANT postgres to hyperdrive_user;
```

The database endpoint can be found in the [database settings page](https://supabase.com/dashboard/project/_/settings/database).

With a database user, password, database endpoint (hostname and port) and database name (default: postgres), you can now set up Hyperdrive.

## 2. Create a database configuration

<Render file="create-hyperdrive-config" />

:::note

When connecting to a Supabase database with Hyperdrive, you should use a driver like [node-postgres (pg)](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) to connect directly to the underlying database instead of the [Supabase JavaScript client](https://github.com/supabase/supabase-js). Hyperdrive is optimized for database access for Workers and will perform global connection pooling and fast query routing by connecting directly to your database.

:::

<Render file="create-hyperdrive-config-next-steps" />

---

# Timescale

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/timescale/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a [Timescale](https://www.timescale.com/) time-series database. Timescale is built on PostgreSQL, and includes powerful time-series, event and analytics features.

You can learn more about Timescale by referring to their [Timescale services documentation](https://docs.timescale.com/getting-started/latest/services/).

## 1. Allow Hyperdrive access

You can connect Hyperdrive to any existing Timescale database by creating a new user and fetching your database connection string.

### Timescale Dashboard

:::note

Similar to most services, Timescale requires you to reset the password associated with your database user if you do not have it stored securely. You should ensure that you do not break any existing clients if when you reset the password.

:::

To retrieve your credentials and database endpoint in the [Timescale Console](https://console.cloud.timescale.com/):

1. Select the service (database) you want Hyperdrive to connect to.
2. Expand **Connection info**.
3. Copy the **Service URL**. The Service URL is the connection string that Hyperdrive will use to connect. This string includes the database hostname, port number and database name.

If you do not have your password stored, you will need to select **Forgot your password?** and set a new **SCRAM** password. Save this password, as Timescale will only display it once.

You will end up with a connection string resembling the below:

```txt
postgres://tsdbadmin:YOUR_PASSWORD_HERE@pn79dztyy0.xzhhbfensb.tsdb.cloud.timescale.com:31358/tsdb
```

With the connection string, you can now create a Hyperdrive database configuration.

## 2. Create a database configuration

<Render file="create-hyperdrive-config" />
<Render file="create-hyperdrive-config-next-steps" />

---

# Xata

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/xata/

import { Render } from "~/components";

This example shows you how to connect Hyperdrive to a Xata PostgreSQL database instance.

<Render file="xata-partial" />

---

# Drizzle ORM

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/drizzle-orm/

import { Render, Steps } from "~/components";

[Drizzle ORM](https://orm.drizzle.team/) is a lightweight TypeScript ORM with a focus on type safety. This example demonstrates how to use Drizzle ORM with PostgreSQL via Cloudflare Hyperdrive in a Workers application.

## Prerequisites

- A Cloudflare account with Workers access
- A PostgreSQL database
- A [Hyperdrive configuration to your PostgreSQL database](/hyperdrive/get-started/#3-connect-hyperdrive-to-a-database)

## 1. Install Drizzle

Install the Drizzle ORM and its dependencies such as the [postgres](https://github.com/porsager/postgres) driver:

```sh
# postgres 3.4.5 or later is recommended
npm i drizzle-orm postgres dotenv
npm i -D drizzle-kit tsx @types/node
```

Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file:

<Render file="hyperdrive-node-compatibility-requirement" product="hyperdrive" />

## 2. Configure Drizzle

### 2.1. Define a schema

With Drizzle ORM, we define the schema in TypeScript rather than writing raw SQL.

<Steps>
1. Create a folder `/db/` in `/src/`.
2. Create a `schema.ts` file.
3. In `schema.ts`, define a `users` table as shown below.

	```ts title="src/db/schema.ts"
	// src/db/schema.ts
	import { pgTable, serial, varchar, timestamp } from "drizzle-orm/pg-core";

	export const users = pgTable("users", {
		id: serial("id").primaryKey(),
		name: varchar("name", { length: 255 }).notNull(),
		email: varchar("email", { length: 255 }).notNull().unique(),
		createdAt: timestamp("created_at").defaultNow(),
	});
	```
</Steps>

### 2.2. Connect Drizzle ORM to the database with Hyperdrive

Use your Hyperdrive configuration for your database when using the Drizzle ORM.

Populate your `index.ts` file as shown below.

```ts title="src/index.ts"
// src/index.ts
import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";
import { users } from "./db/schema";

export interface Env {
	HYPERDRIVE: Hyperdrive;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		// Create a database client with postgres.js driver connected via Hyperdrive
		const sql = postgres(env.HYPERDRIVE.connectionString, {
			// Limit the connections for the Worker request to 5 due to Workers' limits on concurrent external connections
			max: 5,
			// If you are not using array types in your Postgres schema, disable `fetch_types` to avoid an additional round-trip (unnecessary latency)
			fetch_types: false,
		});

		// Create the Drizzle client with the postgres.js connection
		const db = drizzle(sql);

		// Sample query to get all users
		const allUsers = await db.select().from(users);

		// Clean up the connection
		ctx.waitUntil(sql.end());

		return Response.json(allUsers);
	},
} satisfies ExportedHandler<Env>;
```

:::note
You may use [node-postgres](https://orm.drizzle.team/docs/get-started-postgresql#node-postgres) or [Postgres.js](https://orm.drizzle.team/docs/get-started-postgresql#postgresjs)
when using Drizzle ORM. Both are supported and compatible.
:::

### 2.3. Configure Drizzle-Kit for migrations (optional)

:::note
You need to set up the tables in your database so that Drizzle ORM can make queries that work.

If you have already set it up (for example, if another user has applied the schema to your database), or if you are starting to use Drizzle ORM and the schema matches what already exists in your database, then you do not need to run the migration.
:::

You can generate and run SQL migrations on your database based on your schema using Drizzle Kit CLI. Refer to [Drizzle ORM docs](https://orm.drizzle.team/docs/get-started/postgresql-new) for additional guidance.

<Steps>
1. Create a `.env` file the root folder of your project, and add your database connection string. The Drizzle Kit CLI will use this connection string to create and apply the migrations.

   ```toml title=".env"
   # .env
   # Replace with your direct database connection string
   DATABASE_URL='postgres://user:password@db-host.cloud/database-name'
   ```

2. Create a `drizzle.config.ts` file in the root folder of your project to configure Drizzle Kit and add the following content:

   ```ts title="drizzle.config.ts"
   // drizzle.config.ts
   import "dotenv/config";
   import { defineConfig } from "drizzle-kit";
   export default defineConfig({
   	out: "./drizzle",
   	schema: "./src/db/schema.ts",
   	dialect: "postgresql",
   	dbCredentials: {
   		url: process.env.DATABASE_URL!,
   	},
   });
   ```

3. Generate the migration file for your database according to your schema files and apply the migrations to your database.

   Run the following two commands:

   ```bash
   npx drizzle-kit generate
   ```
   ```bash output
   No config path provided, using default 'drizzle.config.ts'
   Reading config file 'drizzle.config.ts'
   1 tables
   users 4 columns 0 indexes 0 fks

   [✓] Your SQL migration file ➜ drizzle/0000_mysterious_queen_noir.sql 🚀
   ```

   ```bash
   npx drizzle-kit migrate
   ```
   ```bash output
   No config path provided, using default 'drizzle.config.ts'
   Reading config file 'drizzle.config.ts'
   Using 'postgres' driver for database querying
   ```
</Steps>

## 3. Deploy your Worker

Deploy your Worker.

```bash
npx wrangler deploy
```

<Render file="create-hyperdrive-config-next-steps" product="hyperdrive" />

---

# node-postgres (pg)

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/

import { Render } from "~/components";

[node-postgres](https://node-postgres.com/) (pg) is a widely-used PostgreSQL driver for Node.js applications. This example demonstrates how to use node-postgres with Cloudflare Hyperdrive in a Workers application.

<Render file="use-node-postgres-to-make-query" product="hyperdrive" />

---

# Libraries and Drivers

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Postgres.js

URL: https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/

import { Render } from "~/components";

[Postgres.js](https://github.com/porsager/postgres) is a modern, fully-featured PostgreSQL driver for Node.js. This example demonstrates how to use Postgres.js with Cloudflare Hyperdrive in a Workers application.

<Render file="use-postgres-js-to-make-query" product="hyperdrive" />

---

# Advanced Usage

URL: https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/advanced/

## Custom Worker Entrypoint

If you need to run code before or after your Next.js application, create your own Worker entrypoint and forward requests to your Next.js application.

This can help you intercept logs from your app, catch and handle uncaught exceptions, or add additional context to incoming requests or outgoing responses.

1. Create a new file in your Next.js project, with a [`fetch()` handler](/workers/runtime-apis/handlers/fetch/), that looks like this:

```ts
import nextOnPagesHandler from "@cloudflare/next-on-pages/fetch-handler";

export default {
	async fetch(request, env, ctx) {
		// do something before running the next-on-pages handler

		const response = await nextOnPagesHandler.fetch(request, env, ctx);

		// do something after running the next-on-pages handler

		return response;
	},
} as ExportedHandler<{ ASSETS: Fetcher }>;
```

This looks like a Worker — but it does not need its own Wrangler file. You can think of it purely as code that `@cloudflare/next-on-pages` will then use to wrap the output of the build that is deployed to your Cloudflare Pages project.

2. Pass the entrypoint argument to the next-on-pages CLI with the path to your handler.

```sh
npx @cloudflare/next-on-pages --custom-entrypoint=./custom-entrypoint.ts
```

---

# Bindings

URL: https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/bindings/

Once you have [set up next-on-pages](/pages/framework-guides/nextjs/ssr/get-started/), you can access [bindings](/workers/runtime-apis/bindings/) from any route of your Next.js app via `getRequestContext`:

```js
import { getRequestContext } from "@cloudflare/next-on-pages";

export const runtime = "edge";

export async function GET(request) {
	let responseText = "Hello World";

	const myKv = getRequestContext().env.MY_KV_NAMESPACE;
	await myKv.put("foo", "bar");
	const foo = await myKv.get("foo");

	return new Response(foo);
}
```

Add bindings to your Pages project by adding them to your [Wrangler configuration file](/pages/functions/wrangler-configuration/).

## TypeScript type declarations for bindings

To ensure that the `env` object from `getRequestContext().env` above has accurate TypeScript types, make sure you have generated types by running [`wrangler types`](/workers/languages/typescript/#generate-types) and followed the setup steps.

## Other Cloudflare APIs (`cf`, `ctx`)

Access context about the incoming request from the [`cf` object](/workers/runtime-apis/request/#incomingrequestcfproperties), as well as [lifecycle methods from the `ctx` object](/workers/runtime-apis/handlers/fetch/) from the return value of [`getRequestContext()`](https://github.com/cloudflare/next-on-pages/blob/main/packages/next-on-pages/src/api/getRequestContext.ts):

```js
import { getRequestContext } from "@cloudflare/next-on-pages";

export const runtime = "edge";

export async function GET(request) {
	const { env, cf, ctx } = getRequestContext();

	// ...
}
```

---

# Caching

URL: https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/caching/

[`@cloudflare/next-on-pages`](https://github.com/cloudflare/next-on-pages) supports [caching](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#caching-data) and [revalidating](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#revalidating-data) data returned by subrequests you make in your app by calling [`fetch()`](/workers/runtime-apis/fetch/).

By default, all `fetch()` subrequests made in your Next.js app are cached. Refer to the [Next.js documentation](https://nextjs.org/docs/app/building-your-application/caching#opting-out-1) for information about how to disable caching for an individual subrequest, or for an entire route.

[The cache persists across deployments](https://nextjs.org/docs/app/building-your-application/caching#data-cache). You are responsible for revalidating/purging this cache.

## Storage options

You can configure your Next.js app to write cache entries to and read from either [Workers KV](/kv/) or the [Cache API](/workers/runtime-apis/cache/).

### Workers KV (recommended)

It takes an extra step to enable, but Cloudflare recommends caching data using [Workers KV](/kv/).

When you write cached data to Workers KV, you write to storage that can be read by any Cloudflare location. This means your app can fetch data, cache it in KV, and then subsequent requests anywhere around the world can read from this cache.

:::note

Workers KV is eventually consistent, which means that it can take up to 60 seconds for updates to be reflected globally.

:::

To use Workers KV as the cache for your Next.js app, [add a KV binding](/pages/functions/bindings/#kv-namespaces) to your Pages project, and set the name of the binding to `__NEXT_ON_PAGES__KV_SUSPENSE_CACHE`.

### Cache API (default)

The [Cache API](https://developers.cloudflare.com/workers/runtime-apis/cache/) is the default option for caching data in your Next.js app. You do not need to take any action to enable the Cache API.

In contrast with Workers KV, when you write data using the Cache API, data is only cached in the Cloudflare location that you are writing data from.

---

# Get started

URL: https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/get-started/

import { PackageManagers, WranglerConfig } from "~/components";

Learn how to deploy full-stack (SSR) Next.js apps to Cloudflare Pages.

:::note
You can now also [deploy Next.js apps to Cloudflare Workers](/workers/framework-guides/web-apps/nextjs/), including apps that use the Node.js "runtime" from Next.js. This allows you to use the [Node.js APIs that Cloudflare Workers provides](/workers/runtime-apis/nodejs/#built-in-nodejs-runtime-apis), and ensures compatibility with a broader set of Next.js features and rendering modes.

Refer to the [OpenNext docs for the `@opennextjs/cloudflare` adapter](https://opennext.js.org/cloudflare) to learn how to get started.
:::

## New apps

To create a new Next.js app, pre-configured to run on Cloudflare, run:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-next-app --framework=next --platform=pages"
/>

For more guidance on developing your app, refer to [Bindings](/pages/framework-guides/nextjs/ssr/bindings/) or the [Next.js documentation](https://nextjs.org).

---

## Existing apps

### 1. Install next-on-pages

First, install [@cloudflare/next-on-pages](https://github.com/cloudflare/next-on-pages):

<PackageManagers pkg="@cloudflare/next-on-pages" dev />

### 2. Add Wrangler file

Then, add a [Wrangler configuration file](/pages/functions/wrangler-configuration/) to the root directory of your Next.js app:

<WranglerConfig>

```toml
name = "my-app"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]
pages_build_output_dir = ".vercel/output/static"
```

</WranglerConfig>

This is where you configure your Pages project and define what resources it can access via [bindings](/workers/runtime-apis/bindings/).

### 3. Update `next.config.mjs`

Next, update the content in your `next.config.mjs` file.

```diff title="next.config.mjs"
+ import { setupDevPlatform } from '@cloudflare/next-on-pages/next-dev';

/** @type {import('next').NextConfig} */
const nextConfig = {};

+ if (process.env.NODE_ENV === 'development') {
+   await setupDevPlatform();
+ }

export default nextConfig;
```

These changes allow you to access [bindings](/pages/framework-guides/nextjs/ssr/bindings/) in local development.

### 4. Ensure all server-rendered routes use the Edge Runtime

Next.js has [two "runtimes"](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) — "Edge" and "Node.js". When you run your Next.js app on Cloudflare, you [can use available Node.js APIs](/workers/runtime-apis/nodejs/) — but you currently can only use Next.js' "Edge" runtime.

This means that for each server-rendered route — ex: an API route or one that uses `getServerSideProps` — you must configure it to use the "Edge" runtime:

```js
export const runtime = "edge";
```

### 5. Update `package.json`

Add the following to the scripts field of your `package.json` file:

```json title="package.json"
"pages:build": "npx @cloudflare/next-on-pages",
"preview": "npm run pages:build && wrangler pages dev",
"deploy": "npm run pages:build && wrangler pages deploy"
```

- `npm run pages:build`: Runs `next build`, and then transforms its output to be compatible with Cloudflare Pages.
- `npm run preview`: Builds your app, and runs it locally in [workerd](https://github.com/cloudflare/workerd), the open-source Workers Runtime. (`next dev` will only run your app in Node.js)
- `npm run deploy`: Builds your app, and then deploys it to Cloudflare

### 6. Deploy to Cloudflare Pages

Either deploy via the command line:

<PackageManagers type="run" args="deploy" />

Or [connect a Github or Gitlab repository](/pages/get-started/git-integration/), and Cloudflare will automatically build and deploy each pull request you merge to your production branch.

### 7. (Optional) Add `eslint-plugin-next-on-pages`

Optionally, you might want to add `eslint-plugin-next-on-pages`, which lints your Next.js app to ensure it is configured correctly to run on Cloudflare Pages.

<PackageManagers pkg="eslint-plugin-next-on-pages" dev />

Once it is installed, add the following to `.eslintrc.json`:

```diff title=".eslintrc.json"
{
  "extends": [
    "next/core-web-vitals",
+    "plugin:eslint-plugin-next-on-pages/recommended"
  ],
  "plugins": [
+    "eslint-plugin-next-on-pages"
  ]
}
```

## Related resources

- [Bindings](/pages/framework-guides/nextjs/ssr/bindings/)
- [Troubleshooting](/pages/framework-guides/nextjs/ssr/troubleshooting/)

---

# Full-stack (SSR)

URL: https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/

import { DirectoryListing } from "~/components";

[Next.js](https://nextjs.org) is an open-source React.js framework for building full-stack applications. This section helps you deploy a full-stack Next.js project to Cloudflare Pages using [`@cloudflare/next-on-pages`](https://github.com/cloudflare/next-on-pages/tree/main/packages/next-on-pages/docs).

:::note
You should consider using [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare), which allows you to build and deploy Next.js apps to [Cloudflare Workers](/workers/static-assets/), use [Node.js APIs](/workers/runtime-apis/nodejs/) that Cloudflare Workers supports, and supports additional Next.js features.

If you're coming from Vercel, you can easily migrate your Next.js app to Cloudflare by using [Diverce](https://github.com/ygwyg/diverce), which will automatically add OpenNext to your project and create a pull request that makes it deployable to Cloudflare.
:::

<DirectoryListing />

---

# Routing static assets

URL: https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/static-assets/

When you use a JavaScript framework like Next.js on Cloudflare Pages, the framework adapter (ex: `@cloudflare/next-on-pages`) automatically generates a [`_routes.json` file](/pages/functions/routing/#create-a-_routesjson-file), which defines specific paths of your app's static assets. This file tells Cloudflare, `for these paths, don't run the Worker, you can just serve the static asset on this path` (an image, a chunk of client-side JavaScript, etc.)

The framework adapter handles this for you — you typically shouldn't need to create your own `_routes.json` file.

If you need to, you can define your own `_routes.json` file in the root directory of your project. For example, you might want to declare the `/favicon.ico` path as a static asset where the Worker should not be invoked.

You would add it to the `excludes` filed of your `_routes.json` file:

```json title="_routes.json"
{
	"version": 1,
	"exclude": ["/favicon.ico"]
}
```

During the build process, `@cloudflare/next-on-pages` will automatically generate its own `_routes.json` file in the output directory. Any entries that are provided in your own `_routes.json` file (in the project's root directory) will be merged with the generated file.

---

# Supported features

URL: https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/supported-features/

import { Details } from "~/components";

## Supported Next.js versions

`@cloudflare/next-on-pages` supports all minor and patch version of Next.js 13 and 14. We regularly run manual and automated tests to ensure compatibility.

### Node.js API support

Next.js has [two "runtimes"](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) — "Edge" and "Node.js".

The `@cloudflare/next-on-pages` adapter supports only the edge "runtime".

The [`@opennextjs/cloudflare` adapter](https://opennext.js.org/cloudflare), which lets you build and deploy Next.js apps to [Cloudflare Workers](/workers/), supports the Node.js "runtime" from Next.js. When you use it, you can use the [full set of Node.js APIs](/workers/runtime-apis/nodejs/) that Cloudflare Workers provide.

`@opennextjs/cloudflare` is pre 1.0, and still in active development. As it approaches 1.0, it will become the clearly better choice for most Next.js apps, since Next.js has been engineered to only support its Node.js "runtime" for many newly introduced features.

Refer to the [OpenNext docs](https://opennext.js.org/cloudflare) and the [Workers vs. Pages compatibility matrix](/workers/static-assets/migration-guides/migrate-from-pages/#compatibility-matrix) for more information to help you decide which to use.

#### Supported Node.js APIs when using `@cloudflare/next-on-pages`

When you use `@cloudflare/next-on-pages`, your Next.js app must use the "edge" runtime from Next.js. The Workers runtime [supports a broad set of Node.js APIs](/workers/runtime-apis/nodejs/) — but [the Next.js Edge Runtime code intentionally constrains this](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/webpack/plugins/middleware-plugin.ts#L820). As a result, only the following Node.js APIs will work in your Next.js app:

- `buffer`
- `events`
- `assert`
- `util`
- `async_hooks`

If you need to use other APIs from Node.js, you should use [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare) instead.

## Supported Features

### Routers

Cloudlflare recommends using the [App router](https://nextjs.org/docs/app) from Next.js.

Cloudflare also supports the older [Pages](https://nextjs.org/docs/pages) router from Next.js.

### next.config.mjs Properties

[`next.config.js` — app router](https://nextjs.org/docs/app/api-reference/next-config-js) and [\`next.config.js - pages router](https://nextjs.org/docs/pages/api-reference/next-config-js)

| Option                              | Next Docs                                                                                                                                                                                    | Support      |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| appDir                              | [app](https://nextjs.org/docs/app/api-reference/next-config-js/appDir)                                                                                                                       | ✅           |
| assetPrefix                         | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/assetPrefix), [app](https://nextjs.org/docs/app/api-reference/next-config-js/assetPrefix)                                 | 🔄           |
| basePath                            | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/basePath), [app](https://nextjs.org/docs/app/api-reference/next-config-js/basePath)                                       | ✅           |
| compress                            | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/compress), [app](https://nextjs.org/docs/app/api-reference/next-config-js/compress)                                       | `N/A`[^1]    |
| devIndicators                       | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/devIndicators), [app](https://nextjs.org/docs/app/api-reference/next-config-js/devIndicators)                             | `N/A`[^2]    |
| distDir                             | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/distDir), [app](https://nextjs.org/docs/app/api-reference/next-config-js/distDir)                                         | `N/A`[^3]    |
| env                                 | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/env), [app](https://nextjs.org/docs/app/api-reference/next-config-js/env)                                                 | ✅           |
| eslint                              | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/eslint), [app](https://nextjs.org/docs/app/api-reference/next-config-js/eslint)                                           | ✅           |
| exportPathMap                       | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/exportPathMap), [app](https://nextjs.org/docs/app/api-reference/next-config-js/exportPathMap)                             | `N/A`[^4]    |
| generateBuildId                     | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/generateBuildId), [app](https://nextjs.org/docs/app/api-reference/next-config-js/generateBuildId)                         | ✅           |
| generateEtags                       | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/generateEtags), [app](https://nextjs.org/docs/app/api-reference/next-config-js/generateEtags)                             | 🔄           |
| headers                             | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/headers), [app](https://nextjs.org/docs/app/api-reference/next-config-js/headers)                                         | ✅           |
| httpAgentOptions                    | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/httpAgentOptions), [app](https://nextjs.org/docs/app/api-reference/next-config-js/httpAgentOptions)                       | `N/A`        |
| images                              | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/images), [app](https://nextjs.org/docs/app/api-reference/next-config-js/images)                                           | ✅           |
| incrementalCacheHandlerPath         | [app](https://nextjs.org/docs/app/api-reference/next-config-js/incrementalCacheHandlerPath)                                                                                                  | 🔄           |
| logging                             | [app](https://nextjs.org/docs/app/api-reference/next-config-js/logging)                                                                                                                      | `N/A`[^5]    |
| mdxRs                               | [app](https://nextjs.org/docs/app/api-reference/next-config-js/mdxRs)                                                                                                                        | ✅           |
| onDemandEntries                     | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/onDemandEntries), [app](https://nextjs.org/docs/app/api-reference/next-config-js/onDemandEntries)                         | `N/A`[^6]    |
| optimizePackageImports              | [app](https://nextjs.org/docs/app/api-reference/next-config-js/optimizePackageImports)                                                                                                       | ✅/`N/A`[^7] |
| output                              | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/output), [app](https://nextjs.org/docs/app/api-reference/next-config-js/output)                                           | `N/A`[^8]    |
| pageExtensions                      | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/pageExtensions), [app](https://nextjs.org/docs/app/api-reference/next-config-js/pageExtensions)                           | ✅           |
| Partial Prerendering (experimental) | [app](https://nextjs.org/docs/app/api-reference/next-config-js/partial-prerendering)                                                                                                         | ❌[^9]       |
| poweredByHeader                     | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/poweredByHeader), [app](https://nextjs.org/docs/app/api-reference/next-config-js/poweredByHeader)                         | 🔄           |
| productionBrowserSourceMaps         | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/productionBrowserSourceMaps), [app](https://nextjs.org/docs/app/api-reference/next-config-js/productionBrowserSourceMaps) | 🔄[^10]      |
| reactStrictMode                     | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/reactStrictMode), [app](https://nextjs.org/docs/app/api-reference/next-config-js/reactStrictMode)                         | ❌[^11]      |
| redirects                           | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/redirects), [app](https://nextjs.org/docs/app/api-reference/next-config-js/redirects)                                     | ✅           |
| rewrites                            | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/rewrites), [app](https://nextjs.org/docs/app/api-reference/next-config-js/rewrites)                                       | ✅           |
| Runtime Config                      | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/runtime-configuration), [app](https://nextjs.org/docs/app/api-reference/next-config-js/runtime-configuration)             | ❌[^12]      |
| serverActions                       | [app](https://nextjs.org/docs/app/api-reference/next-config-js/serverActions)                                                                                                                | ✅           |
| serverComponentsExternalPackages    | [app](https://nextjs.org/docs/app/api-reference/next-config-js/serverComponentsExternalPackages)                                                                                             | `N/A`[^13]   |
| trailingSlash                       | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/trailingSlash), [app](https://nextjs.org/docs/app/api-reference/next-config-js/trailingSlash)                             | ✅           |
| transpilePackages                   | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/transpilePackages), [app](https://nextjs.org/docs/app/api-reference/next-config-js/transpilePackages)                     | ✅           |
| turbo                               | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/turbo), [app](https://nextjs.org/docs/app/api-reference/next-config-js/turbo)                                             | 🔄           |
| typedRoutes                         | [app](https://nextjs.org/docs/app/api-reference/next-config-js/typedRoutes)                                                                                                                  | ✅           |
| typescript                          | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/typescript), [app](https://nextjs.org/docs/app/api-reference/next-config-js/typescript)                                   | ✅           |
| urlImports                          | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/urlImports), [app](https://nextjs.org/docs/app/api-reference/next-config-js/urlImports)                                   | ✅           |
| webpack                             | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/webpack), [app](https://nextjs.org/docs/app/api-reference/next-config-js/webpack)                                         | ✅           |
| webVitalsAttribution                | [pages](https://nextjs.org/docs/pages/api-reference/next-config-js/webVitalsAttribution), [app](https://nextjs.org/docs/app/api-reference/next-config-js/webVitalsAttribution)               | ✅           |

```
- ✅: Supported
- 🔄: Not currently supported
- ❌: Not supported
- N/A: Not applicable
```

[^1]: **compression**: [Cloudflare applies Brotli or Gzip compression](/speed/optimization/content/compression/) automatically. When developing locally with Wrangler, no compression is applied.

[^2]: **dev indicators**: If you're developing using `wrangler pages dev`, it hard refreshes your application the dev indicator doesn't appear. If you run your app locally using `next dev`, this option works fine.

[^3]: **setting custom build directory**: Applications built using `@cloudflare/next-on-pages` don't rely on the `.next` directory so this option isn't really applicable (the `@cloudflare/next-on-pages` equivalent is to use the `--outdir` flag).

[^4]: **exportPathMap**: Option used for SSG not applicable for apps built using `@cloudflare/next-on-pages`.

[^5]: **logging**: If you're developing using `wrangler pages dev`, the extra logging is not applied (since you are effectively running a production build). If you run your app locally using `next dev`, this option works fine.

[^6]: **onDemandEntries**: Not applicable since it's an option for the Next.js server during development which we don't rely on.

[^7]: **optimizePackageImports**: `@cloudflare/next-on-pages` performs chunks deduplication and provides an implementation based on modules lazy loading, based on this applying an `optimizePackageImports` doesn't have an impact on the output produced by the CLI. This configuration can still however be used to speed up the build process (both when running `next dev` or when generating a production build).

[^8]: **output**: `@cloudflare/next-on-pages` works with the standard Next.js output, `standalone` is incompatible with it, `export` is used to generate a static site which doesn't need `@cloudflare/next-on-pages` to run.

[^9]: **Partial Prerendering (experimental)**: As presented in the official [Next.js documentation](https://nextjs.org/docs/app/api-reference/next-config-js/partial-prerendering): `Partial Prerendering is designed for the Node.js runtime only.`, as such it is fundamentally incompatibly with `@cloudflare/next-on-pages` (which only works on the edge runtime).

[^10]: **productionBrowserSourceMaps**: The webpack chunks deduplication performed by `@cloudflare/next-on-pages` doesn't currently preserve source maps in any case so this option can't be implemented either. In the future we might try to preserver source maps, in such case it should be simple to also support this option.

[^11]: **reactStrictMode**: Currently we build the application so react strict mode (being a local dev feature) doesn't work either way. If we can make strict mode work, this option will most likely work straight away.

[^12]: **runtime configuration**: We could look into implementing the runtime configuration but it is probably not worth it since it is a legacy configuration and environment variables should be used instead.

[^13]: **serverComponentsExternalPackages**: This option is for applications running on Node.js so it's not relevant to applications running on Cloudflare Pages.

### Internationalization

Cloudflare also supports Next.js' [internationalized (`i18n`) routing](https://nextjs.org/docs/pages/building-your-application/routing/internationalization).

### Rendering and Data Fetching

#### Incremental Static Regeneration

If you use Incremental Static Regeneration (ISR)[^14], `@cloudflare/next-on-pages` will use static fallback files that are generated by the build process.

This means that your application will still correctly serve your ISR/prerendered pages (but without the regeneration aspect). If this causes issues for your application, change your pages to use server side rendering (SSR) instead.

<Details header="Background">

ISR pages are built by the Vercel CLI to generate Vercel [Prerender Functions](https://vercel.com/docs/build-output-api/v3/primitives#prerender-functions). These are Node.js serverless functions that can be called in the background while serving the page from the cache.

It is not possible to use these with Cloudflare Pages and they are not compatible with the [edge runtime](https://nextjs.org/docs/app/api-reference/edge) currently.

</Details>

[^14]: [Incremental Static Regeneration (ISR)](https://vercel.com/docs/incremental-static-regeneration) is a rendering mode in Next.js that allows you to automatically cache and periodically regenerate pages with fresh data.

#### Dynamic handling of static routes

`@cloudflare/next-on-pages` supports standard statically generated routes.

It does not support dynamic Node.js-based on-demand handling of such routes.

For more details see:

- [troubleshooting `generateStaticParams`](/pages/framework-guides/nextjs/ssr/troubleshooting/#generatestaticparams)
- [troubleshooting `getStaticPaths` ](/pages/framework-guides/nextjs/ssr/troubleshooting/#getstaticpaths)

#### Caching and Data Revalidation

Revalidation and `next/cache` are supported on Cloudflare Pages and can use various bindings. For more information, see our [caching documentation](/pages/framework-guides/nextjs/ssr/caching/).

---

# Troubleshooting

URL: https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/troubleshooting/

Learn more about troubleshooting issues with your Full-stack (SSR) Next.js apps using Cloudflare.

## Edge runtime

You must configure all server-side routes in your Next.js project as [Edge runtime](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) routes, by adding the following to each route:

```js
export const runtime = "edge";
```

:::note

If you are still using the Next.js [Pages router](https://nextjs.org/docs/pages), for page routes, you must use `'experimental-edge'` instead of `'edge'`.
:::

---

## App router

### Not found

Next.js generates a `not-found` route for your application under the hood during the build process. In some circumstances, Next.js can detect that the route requires server-side logic (particularly if computation is being performed in the root layout component) and Next.js automatically creates a [Node.js runtime serverless function](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) that is not compatible with Cloudflare Pages.

To prevent this, you can provide a custom `not-found` route that explicitly uses the edge runtime:

```ts
export const runtime = 'edge'

export default async function NotFound() {
    // ...
    return (
        // ...
    )
}
```

### `generateStaticParams`

When you use [static site generation (SSG)](https://nextjs.org/docs/pages/building-your-application/rendering/static-site-generation) in the [`/app` directory](https://nextjs.org/docs/getting-started/project-structure) and also use the [`generateStaticParams`](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) function, Next.js tries to handle requests for non statically generated routes automatically, and creates a [Node.js runtime serverless function](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) that is not compatible with Cloudflare Pages.

You can opt out of this behavior by setting [`dynamicParams`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams) to `false`:

```diff
+ export const dynamicParams = false

// ...
```

### Top-level `getRequestContext`

You must call `getRequestContext` within the function that handles your route — it cannot be called in global scope.

Don't do this:

```js null {5}
import { getRequestContext } from "@cloudflare/next-on-pages";

export const runtime = "edge";

const myVariable = getRequestContext().env.MY_VARIABLE;

export async function GET(request) {
	return new Response(myVariable);
}
```

Instead, do this:

```js null {6}
import { getRequestContext } from "@cloudflare/next-on-pages";

export const runtime = "edge";

export async function GET(request) {
	const myVariable = getRequestContext().env.MY_VARIABLE;
	return new Response(myVariable);
}
```

---

## Pages router

### `getStaticPaths`

When you use [static site generation (SSG)](https://nextjs.org/docs/pages/building-your-application/rendering/static-site-generation) in the [`/pages` directory](https://nextjs.org/docs/getting-started/project-structure) and also use the [`getStaticPaths`](https://nextjs.org/docs/pages/api-reference/functions/get-static-paths) function, Next.js by default tries to handle requests for non statically generated routes automatically, and creates a [Node.js runtime serverless function](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) that is not compatible with Cloudflare Pages.

You can opt out of this behavior by specifying a [false `fallback`](https://nextjs.org/docs/pages/api-reference/functions/get-static-paths#fallback-false):

```diff
// ...

export async function getStaticPaths() {
    // ...

    return {
        paths,
+       fallback: false,
	}
}
```

:::caution

Note that the `paths` array cannot be empty since an empty `paths` array causes Next.js to ignore the provided `fallback` value.

:::

---

# Get Started

URL: https://developers.cloudflare.com/workers-ai/features/function-calling/embedded/get-started/

import { TypeScriptExample, PackageManagers } from "~/components";

This guide will instruct you through setting up and deploying your first Workers AI project with embedded function calling. You will use Workers, a Workers AI binding, the [`ai-utils package`](https://github.com/cloudflare/ai-utils), and a large language model (LLM) to deploy your first AI-powered application on the Cloudflare global network with embedded function calling.

## 1. Create a Worker project with Workers AI

Follow the [Workers AI Get Started Guide](/workers-ai/get-started/workers-wrangler/) until step 2.

## 2. Install additional npm package

Next, run the following command in your project repository to install the Worker AI utilities package.

<PackageManagers pkg="@cloudflare/ai-utils" />

## 3. Add Workers AI Embedded function calling

Update the `index.ts` file in your application directory with the following code:

<TypeScriptExample filename="index.ts">

```ts
import { runWithTools } from "@cloudflare/ai-utils";

type Env = {
	AI: Ai;
};

export default {
	async fetch(request, env, ctx) {
		// Define function
		const sum = (args: { a: number; b: number }): Promise<string> => {
			const { a, b } = args;
			return Promise.resolve((a + b).toString());
		};
		// Run AI inference with function calling
		const response = await runWithTools(
			env.AI,
			// Model with function calling support
			"@hf/nousresearch/hermes-2-pro-mistral-7b",
			{
				// Messages
				messages: [
					{
						role: "user",
						content: "What the result of 123123123 + 10343030?",
					},
				],
				// Definition of available tools the AI model can leverage
				tools: [
					{
						name: "sum",
						description: "Sum up two numbers and returns the result",
						parameters: {
							type: "object",
							properties: {
								a: { type: "number", description: "the first number" },
								b: { type: "number", description: "the second number" },
							},
							required: ["a", "b"],
						},
						// reference to previously defined function
						function: sum,
					},
				],
			},
		);
		return new Response(JSON.stringify(response));
	},
} satisfies ExportedHandler<Env>;
```

</TypeScriptExample>

This example imports the utils with `import { runWithTools} from "@cloudflare/ai-utils"` and follows the API reference below.

Moreover, in this example we define and describe a list of tools that the LLM can leverage to respond to the user query. Here, the list contains of only one tool, the `sum` function.

Abstracted by the `runWithTools` function, the following steps occur:

```mermaid
sequenceDiagram
    participant Worker as Worker
    participant WorkersAI as Workers AI

    Worker->>+WorkersAI: Send messages, function calling prompt, and available tools
    WorkersAI->>+Worker: Select tools and arguments for function calling
    Worker-->>-Worker: Execute function
    Worker-->>+WorkersAI: Send messages, function calling prompt and function result
    WorkersAI-->>-Worker: Send response incorporating function output
```

The `ai-utils package` is also open-sourced on [Github](https://github.com/cloudflare/ai-utils).

## 4. Local development & deployment

Follow steps 4 and 5 of the [Workers AI Get Started Guide](/workers-ai/get-started/workers-wrangler/) for local development and deployment.

:::note[Workers AI Embedded Function Calling charges]

Embedded function calling runs Workers AI inference requests. Standard charges for inference (e.g. tokens) usage will be charged.
Resources consumed (e.g. CPU time) during embedded functions' code execution will be charged just as any other Worker's code execution.

:::

## API reference

For more details, refer to [API reference](/workers-ai/features/function-calling/embedded/api-reference/).

---

# API Reference

URL: https://developers.cloudflare.com/workers-ai/features/function-calling/embedded/api-reference/

Learn more about the API reference for [embedded function calling](/workers-ai/features/function-calling/embedded).

## runWithTools

This wrapper method enables you to do embedded function calling. You pass it the AI binding, model, inputs (`messages` array and `tools` array), and optional configurations.

- `AI Binding`Ai
  - The AI binding, such as `env.AI`.
- `model`BaseAiTextGenerationModels
  - The ID of the model that supports function calling. For example, `@hf/nousresearch/hermes-2-pro-mistral-7b`.
- `input`Object
  - `messages`RoleScopedChatInput\[]
  - `tools`AiTextGenerationToolInputWithFunction\[]
- `config`Object
  - `streamFinalResponse`boolean optional
  - `maxRecursiveToolRuns`number optional
  - `strictValidation`boolean optional
  - `verbose`boolean optional
  - `trimFunction`boolean optional - For the `trimFunction`, you can pass it `autoTrimTools`, which is another helper method we've devised to automatically choose the correct tools (using an LLM) before sending it off for inference. This means that your final inference call will have fewer input tokens.

## createToolsFromOpenAPISpec

This method lets you automatically create tool schemas based on OpenAPI specs, so you don't have to manually write or hardcode the tool schemas. You can pass the OpenAPI spec for any API in JSON or YAML format.

`createToolsFromOpenAPISpec` has a config input that allows you to perform overrides if you need to provide headers like Authentication or User-Agent.

- `spec`string
  - The OpenAPI specification in either JSON or YAML format, or a URL to a remote OpenAPI specification.
- `config`Config optional - Configuration options for the createToolsFromOpenAPISpec function
  - `overrides`ConfigRule\[] optional
  - `matchPatterns`RegExp\[] optional
  - `options` Object optional \{
    `verbose` boolean optional
    \}

---

# Embedded

URL: https://developers.cloudflare.com/workers-ai/features/function-calling/embedded/

import { DirectoryListing } from "~/components"

Cloudflare has a unique [embedded function calling](https://blog.cloudflare.com/embedded-function-calling) feature that allows you to execute function code alongside your tool call inference. Our npm package [`@cloudflare/ai-utils`](https://www.npmjs.com/package/@cloudflare/ai-utils) is the developer toolkit to get started.

Embedded function calling can be used to easily make complex agents that interact with websites and APIs, like using natural language to create meetings on Google Calendar, saving data to Notion, automatically routing requests to other APIs, saving data to an R2 bucket - or all of this at the same time. All you need is a prompt and an OpenAPI spec to get started.

:::caution[REST API support]


Embedded function calling depends on features native to the Workers platform. This means that embedded function calling is only supported via [Cloudflare Workers](/workers-ai/get-started/workers-wrangler/), not via the [REST API](/workers-ai/get-started/rest-api/).


:::

## Resources

<DirectoryListing />

---

# Troubleshooting

URL: https://developers.cloudflare.com/workers-ai/features/function-calling/embedded/troubleshooting/

This section will describe tools for troubleshooting and address common errors.

## Logging

General [logging](/workers/observability/logs/) capabilities for Workers also apply to embedded function calling.

### Function invocations

The invocations of tools can be logged as in any Worker using `console.log()`:

```ts title="Logging tool invocations" {6}
export default {
	async fetch(request, env, ctx) {
		const sum = (args: { a: number; b: number }): Promise<string> => {
			const { a, b } = args;
      // Logging from within embedded function invocations
      console.log(`The sum function has been invoked with the arguments a: ${a} and b: ${b}`)
			return Promise.resolve((a + b).toString());
		};
    ...
  }
}
```

### Logging within `runWithTools`

The `runWithTools` function has a `verbose` mode that emits helpful logs for debugging of function calls as well input and output statistics.

```ts title="Enabled verbose mode" {13}
const response = await runWithTools(
  env.AI,
  '@hf/nousresearch/hermes-2-pro-mistral-7b',
  {
    messages: [
      ...
    ],
    tools: [
      ...
    ],
  },
  // Enable verbose mode
  { verbose: true }
);
```

## Performance

To respond to a LLM prompt with embedded function, potentially multiple AI inference requests and function invocations are needed, which can have an impact on user experience.

Consider the following to improve performance:

* Shorten prompts (to reduce time for input processing)
* Reduce number of tools provided
* Stream the final response to the end user (to minimize the time to interaction). See example below:

```ts title="Streamed response example" {15}
async fetch(request, env, ctx) {
  const response = (await runWithTools(
    env.AI,
    '@hf/nousresearch/hermes-2-pro-mistral-7b',
    {
      messages: [
        ...
      ],
      tools: [
        ...
      ],
    },
    {
      // Enable response streaming
      streamFinalResponse: true,
    }
  )) as ReadableStream;

  // Set response headers for streaming
  return new Response(response, {
    headers: {
      'content-type': 'text/event-stream',
    },
  });
}
```

## Common Errors

If you are getting a `BadInput` error, your inputs may exceed our current context window for our models. Try reducing input tokens to resolve this error.

---

# Add New AI Models to your Playground (Part 2)

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/image-generation-playground/image-generator-flux-newmodels/

import { Details, DirectoryListing, Stream } from "~/components";

In part 2, Kristian expands upon the existing environment built in part 1, by showing you how to integrate new AI models and introduce new parameters that allow you to customize how images are generated.

<Stream
	id="167ba3a7a86f966650f3315e6cb02e0d"
	title="Add New AI Models to your Playground (Part 2)"
	thumbnail="13.5s"
	showMoreVideos={false}
/>

Refer to the AI Image Playground [GitHub repository](https://github.com/kristianfreeman/workers-ai-image-playground) to follow along locally.

<Details header="Video series" open>

<DirectoryListing folder="workers-ai/guides/tutorials/image-generation-playground" />

</Details>

---

# Build an AI Image Generator Playground (Part 1)

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/image-generation-playground/image-generator-flux/

import { Details, DirectoryListing, Stream } from "~/components";

The new flux models on Workers AI are our most powerful text-to-image AI models yet. In this video, we show you how to deploy your own Workers AI Image Playground in just a few minutes.

There are many businesses being built on top of AI image generation models. Using Workers AI, you can get access to the best models in the industry without having to worry about inference, ops, or deployment. We provide the API for AI image generation, and in a couple of seconds get an image back.

<Stream
	id="aeafae151e84a81be19c52c2348e9bab"
	title="Build an AI Image Generator Playground (Part 1)"
	thumbnail="2.5s"
	showMoreVideos={false}
/>

Refer to the AI Image Playground [GitHub repository](https://github.com/kristianfreeman/workers-ai-image-playground) to follow along locally.

<Details header="Video series" open>

<DirectoryListing folder="workers-ai/guides/tutorials/image-generation-playground" />

</Details>

---

# Store and Catalog AI Generated Images with R2 (Part 3)

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/image-generation-playground/image-generator-store-and-catalog/

import { Details, DirectoryListing, Stream } from "~/components";

In the final part of the AI Image Playground series, Kristian teaches how to utilize Cloudflare's [R2](/r2) object storage in order to maintain and keep track of each AI generated image.

<Stream
	id="86488269da24984c76fb10f69f4abb44"
	title="Store and Catalog AI Generated Images (Part 3)"
	thumbnail="2.5s"
	showMoreVideos={false}
/>

Refer to the AI Image Playground [GitHub repository](https://github.com/kristianfreeman/workers-ai-image-playground) to follow along locally.

<Details header="Video series" open>

<DirectoryListing folder="workers-ai/guides/tutorials/image-generation-playground" />

</Details>

---

# How to Build an Image Generator using Workers AI

URL: https://developers.cloudflare.com/workers-ai/guides/tutorials/image-generation-playground/

import { Details, DirectoryListing, Stream } from "~/components";

In this series of videos, Kristian Freeman builds an AI Image Playground. To get started, click on part 1 below.

<Details header="Video Series" open>

<DirectoryListing folder="workers-ai/guides/tutorials/image-generation-playground" />

</Details>

---

# GitHub integration

URL: https://developers.cloudflare.com/workers/ci-cd/builds/git-integration/github-integration/

Cloudflare supports connecting your GitHub repository to your Cloudflare Worker, and will automatically deploy your code every time you push a change.

## Features

Beyond automatic builds and deployments, the Cloudflare GitHub integration lets you monitor builds directly in GitHub, keeping you informed without leaving your workflow.

### Pull request comment

If a commit is on a pull request, Cloudflare will automatically post a comment on the pull request with the status of the build.

![GitHub pull request comment](~/assets/images/workers/platform/ci-cd/github-pull-request-comment.png)

A [preview URL](/workers/configuration/previews/) will be provided for any builds which perform `wrangler versions upload`. This is particularly useful when reviewing your pull request, as it allows you to compare the code changes alongside an updated version of your Worker.

Comment history reveals any builds completed earlier while the PR was open.

![GitHub pull request comment history](~/assets/images/workers/platform/ci-cd/github-pull-request-comment-history.png)

### Check run

If you have one or multiple Workers connected to a repository (i.e. a [monorepo](/workers/ci-cd/builds/advanced-setups/#monorepos)), you can check on the status of each build within GitHub via [GitHub check runs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks#checks).

You can see the checks by selecting on the status icon next to a commit within your GitHub repository. In the example below, you can select the green check mark to see the results of the check run.

![GitHub status](~/assets/images/workers/platform/ci-cd/gh-status-check-runs.png)

Check runs will appear like the following in your repository. You can select **Details** to view the build (Build ID) and project (Script) associated with each check.

![GitHub check runs](~/assets/images/workers/platform/ci-cd/workers-builds-gh-check-runs.png)

Note that when using [build watch paths](/workers/ci-cd/builds/build-watch-paths/), only projects that trigger a build will generate a check run.

## Manage access

You can deploy projects to Cloudflare Workers from your company or side project on GitHub using the [Cloudflare Workers & Pages GitHub App](https://github.com/apps/cloudflare-workers-and-pages).

### Organizational access

When authorizing Cloudflare Workers to access a GitHub account, you can specify access to your individual account or an organization that you belong to on GitHub.

To add Cloudflare Workers installation to an organization, your user account must be an owner or have the appropriate role within the organization (i.e. the GitHub Apps Manager role). More information on these roles can be seen on [GitHub's documentation](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#github-app-managers).

:::caution[GitHub security consideration]

A GitHub account should only point to one Cloudflare account. If you are setting up Cloudflare with GitHub for your organization, Cloudflare recommends that you limit the scope of the application to only the repositories you intend to build with Pages. To modify these permissions, go to the [Applications page](https://github.com/settings/installations) on GitHub and select **Switch settings context** to access your GitHub organization settings. Then, select **Cloudflare Workers & Pages** > For **Repository access**, select **Only select repositories** > select your repositories.

:::

### Remove access

You can remove Cloudflare Workers' access to your GitHub repository or account by going to the [Applications page](https://github.com/settings/installations) on GitHub (if you are in an organization, select Switch settings context to access your GitHub organization settings). The GitHub App is named Cloudflare Workers and Pages, and it is shared between Workers and Pages projects.

#### Remove Cloudflare access to a GitHub repository

To remove access to an individual GitHub repository, you can navigate to **Repository access**. Select the **Only select repositories** option, and configure which repositories you would like Cloudflare to have access to.

![GitHub Repository Access](~/assets/images/workers/platform/ci-cd/github-repository-access.png)

#### Remove Cloudflare access to the entire GitHub account

To remove Cloudflare Workers and Pages access to your entire Git account, you can navigate to **Uninstall "Cloudflare Workers and Pages"**, then select **Uninstall**. Removing access to the Cloudflare Workers and Pages app will revoke Cloudflare's access to _all repositories_ from that GitHub account. If you want to only disable automatic builds and deployments, follow the [Disable Build](/workers/ci-cd/builds/#disconnecting-builds) instructions.

Note that removing access to GitHub will disable new builds for Workers and Pages project that were connected to those repositories, though your previous deployments will continue to be hosted by Cloudflare Workers.

### Reinstall the Cloudflare GitHub App

When encountering Git integration related issues, one potential troubleshooting step is attempting to uninstall and reinstall the GitHub or GitLab application associated with the Cloudflare Pages installation. The process for each Git provider is provided below.

1. Go to the installation settings page on GitHub:
   - Navigate to **Settings > Builds** for the Workers or Pages project and select **Manage** under Git Repository.
   - Alternatively, visit these links to find the Cloudflare Workers and Pages installation and select **Configure**:

|                  |                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------- |
| **Individual**   | `https://github.com/settings/installations`                                        |
| **Organization** | `https://github.com/organizations/<YOUR_ORGANIZATION_NAME>/settings/installations` |

2. In the Cloudflare Workers and Pages GitHub App settings page, navigate to **Uninstall "Cloudflare Workers and Pages"** and select **Uninstall**.
3. Go back to the [**Workers & Pages** overview](https://dash.cloudflare.com) page. Select **Create application** > **Pages** > **Connect to Git**.
4. Select the **+ Add account** button, select the GitHub account you want to add, and then select **Install & Authorize**.
5. You should be redirected to the create project page with your GitHub account or organization in the account list.
6. Attempt to make a new deployment with your project which was previously broken.

---

# GitLab integration

URL: https://developers.cloudflare.com/workers/ci-cd/builds/git-integration/gitlab-integration/

Cloudflare supports connecting your GitLab repository to your Cloudflare Worker, and will automatically deploy your code every time you push a change.

## Features

Beyond automatic builds and deployments, the Cloudflare GitLab integration lets you monitor builds directly in GitLab, keeping you informed without leaving your workflow.

### Merge request comment

If a commit is on a merge request, Cloudflare will automatically post a comment on the merge request with the status of the build.

![GitLab merge request comment](~/assets/images/workers/platform/ci-cd/gitlab-pull-request-comment.png)

A [preview URL](/workers/configuration/previews/) will be provided for any builds which perform `wrangler versions upload`. This is particularly useful when reviewing your pull request, as it allows you to compare the code changes alongside an updated version of your Worker.

:::note[Enabling GitLab Merge Request events for existing connections]
New GitLab connections are automatically configured to receive merge request events, which enable commenting functionality. For existing connections, you'll need to manually enable `Merge request events` in the Webhooks tab of your project's settings. You can follow GitLab's documentation for guidance on [managing webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/#manage-webhooks).
:::

### Commit Status

If you have one or multiple Workers connected to a repository (i.e. a [monorepo](/workers/ci-cd/builds/advanced-setups/#monorepos)), you can check on the status of each build within GitLab via [GitLab commit status](https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html).

You can see the statuses by selecting the status icon next to a commit or by going to **Build** > **Pipelines** within your GitLab repository. In the example below, you can select on the green check mark to see the results of the check run.

![GitLab Status](~/assets/images/workers/platform/ci-cd/gl-status-checks.png)

Check runs will appear like the following in your repository. You can select one of the statuses to view the build on the Cloudflare Dashboard.

![GitLab Commit Status](~/assets/images/workers/platform/ci-cd/gl-commit-status.png)

Note that when using [build watch paths](/workers/ci-cd/builds/build-watch-paths/), only projects that trigger a build will generate a commit status.

## Manage access

You can deploy projects to Cloudflare Workers from your company or side project on GitLab using the Cloudflare Pages app.

### Organizational access

When you authorize Cloudflare Workers to access your GitLab account, you automatically give Cloudflare Workers access to organizations, groups, and namespaces accessed by your GitLab account. Managing access to these organizations and groups is handled by GitLab.

### Remove access

You can remove Cloudflare Workers' access to your GitLab account by navigating to [Authorized Applications page](https://gitlab.com/-/profile/applications) on GitLab. Find the applications called Cloudflare Pages and select the **Revoke** button to revoke access.

Note that the GitLab application Cloudflare Workers is shared between Workers and Pages projects, and removing access to GitLab will disable new builds for Workers and Pages, though your previous deployments will continue to be hosted by Cloudflare Workers.

### Reinstall the Cloudflare GitLab App

1. Go to your application settings page on GitLab: [https://gitlab.com/-/profile/applications](https://gitlab.com/-/profile/applications)
2. Click the "Revoke" button on your Cloudflare Workers installation if it exists.
3. Go back to the [**Workers & Pages** overview](https://dash.cloudflare.com) page. Select **Create application** > **Pages** > **Connect to Git**.
4. Select the **+ Add account** button, select the GitLab account you want to add, and then select **Install & Authorize**.
5. You should be redirected to the create project page with your GitLab account or organization in the account list.
6. Attempt to make a new deployment with your project which was previously broken.

---

# Git integration

URL: https://developers.cloudflare.com/workers/ci-cd/builds/git-integration/

Cloudflare supports connecting your [GitHub](/workers/ci-cd/builds/git-integration/github-integration/) and [GitLab](/workers/ci-cd/builds/git-integration/gitlab-integration/) repository to your Cloudflare Worker, and will automatically deploy your code every time you push a change.

Adding a Git integration also lets you monitor build statuses directly in your Git provider using [pull request comments](/workers/ci-cd/builds/git-integration/github-integration/#pull-request-comment), [check runs](/workers/ci-cd/builds/git-integration/github-integration/#check-run), or [commit statuses](/workers/ci-cd/builds/git-integration/gitlab-integration/#commit-status), so you can manage deployments without leaving your workflow.

## Supported Git Providers

Cloudflare supports connecting Cloudflare Workers to your GitHub and GitLab repositories. Workers Builds does not currently support connecting self-hosted instances of GitHub or GitLab.

If you using a different Git provider (e.g. Bitbucket), you can use an [external CI/CD provider (e.g. GitHub Actions)](/workers/ci-cd/external-cicd/) and deploy using [Wrangler CLI](/workers/wrangler/commands/#deploy).

## Add a Git Integration

Workers Builds provides direct integration with GitHub and GitLab accounts, including both individual and organization accounts, that are _not_ self-hosted.

If you do not have a Git account linked to your Cloudflare account, you will be prompted to set up an installation to GitHub or GitLab when [connecting a repository](/workers/ci-cd/builds/#get-started) for the first time, or when adding a new Git account. Follow the prompts and authorize the Cloudflare Git integration.

![Git providers](~/assets/images/workers/platform/ci-cd/workers-git-provider.png)

You can check the following pages to see if your Git integration has been installed:

- [GitHub Applications page](https://github.com/settings/installations) (if you are in an organization, select **Switch settings context** to access your GitHub organization settings)
- [GitLab Authorized Applications page](https://gitlab.com/-/profile/applications)

For details on providing access to organization accounts, see [GitHub organizational access](/workers/ci-cd/builds/git-integration/github-integration/#organizational-access) and [GitLab organizational access](/workers/ci-cd/builds/git-integration/gitlab-integration/#organizational-access).

## Manage a Git Integration

To manage your Git installation, go to the [Cloudflare dashboard](https://dash.cloudflare.com) > **Workers & Pages** > your Worker > **Settings** > **Builds** > under **Git Repository**, select **Manage**.

This can be useful for managing repository access or troubleshooting installation issues by reinstalling. For more details, see the [GitHub](/workers/ci-cd/builds/git-integration/github-integration) and [GitLab](/workers/ci-cd/builds/git-integration/gitlab-integration) guides for how to manage your installation.

---

# FastAPI

URL: https://developers.cloudflare.com/workers/languages/python/packages/fastapi/

import { Render } from "~/components"

The FastAPI package is supported in Python Workers.

FastAPI applications use a protocol called the [Asynchronous Server Gateway Interface (ASGI)](https://asgi.readthedocs.io/en/latest/). This means that FastAPI never reads from or writes to a socket itself. An ASGI application expects to be hooked up to an ASGI server, typically [uvicorn](https://www.uvicorn.org/). The ASGI server handles all of the raw sockets on the application’s behalf.

The Workers runtime provides [an ASGI server](https://github.com/cloudflare/workerd/blob/main/src/pyodide/internal/asgi.py) directly to your Python Worker, which lets you use FastAPI in Python Workers.

## Get Started

<Render file="python-workers-beta-packages" product="workers" />

Clone the `cloudflare/python-workers-examples` repository and run the FastAPI example:

```bash
git clone https://github.com/cloudflare/python-workers-examples
cd python-workers-examples/03-fastapi
npx wrangler@latest dev
```

### Example code

```python
from fastapi import FastAPI, Request
from pydantic import BaseModel

async def on_fetch(request, env):
    import asgi

    return await asgi.fetch(app, request, env)

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello, World!"}

@app.get("/env")
async def root(req: Request):
    env = req.scope["env"]
    return {"message": "Here is an example of getting an environment variable: " + env.MESSAGE}

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

@app.post("/items/")
async def create_item(item: Item):
    return item

@app.put("/items/{item_id}")
async def create_item(item_id: int, item: Item, q: str | None = None):
    result = {"item_id": item_id, **item.dict()}
    if q:
        result.update({"q": q})
    return result

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}
```

---

# Packages

URL: https://developers.cloudflare.com/workers/languages/python/packages/

import { Render } from "~/components";

<Render file="python-workers-beta-packages" product="workers" />

To import a Python package, add the package name to the `requirements.txt` file within the same directory as your [Wrangler configuration file](/workers/wrangler/configuration/).

For example, if your Worker depends on [FastAPI](https://fastapi.tiangolo.com/), you would add the following:

```
fastapi
```

## Package versioning

In the example above, you likely noticed that there is no explicit version of the Python package declared in `requirements.txt`.

In Workers, Python package versions are set via [Compatibility Dates](/workers/configuration/compatibility-dates/) and [Compatibility Flags](/workers/configuration/compatibility-flags/). Given a particular compatibility date, a specific version of the [Pyodide Python runtime](https://pyodide.org/en/stable/project/changelog.html) is provided to your Worker, providing a specific set of Python packages pinned to specific versions.

As new versions of Pyodide and additional Python packages become available in Workers, we will publish compatibility flags and their associated compatibility dates here on this page.

## Supported Packages

A subset of the [Python packages that Pyodide supports](https://pyodide.org/en/latest/usage/packages-in-pyodide.html) are provided directly by the Workers runtime:

- aiohttp: 3.9.3
- aiohttp-tests: 3.9.3
- aiosignal: 1.3.1
- annotated-types: 0.6.0
- annotated-types-tests: 0.6.0
- anyio: 4.2.0
- async-timeout: 4.0.3
- attrs: 23.2.0
- certifi: 2024.2.2
- charset-normalizer: 3.3.2
- distro: 1.9.0
- [fastapi](/workers/languages/python/packages/fastapi): 0.110.0
- frozenlist: 1.4.1
- h11: 0.14.0
- h11-tests: 0.14.0
- hashlib: 1.0.0
- httpcore: 1.0.4
- httpx: 0.27.0
- idna: 3.6
- jsonpatch: 1.33
- jsonpointer: 2.4
- langchain: 0.1.8
- langchain-core: 0.1.25
- langchain-openai: 0.0.6
- langsmith: 0.1.5
- lzma: 1.0.0
- micropip: 0.6.0
- multidict: 6.0.5
- numpy: 1.26.4
- numpy-tests: 1.26.4
- openai: 1.12.0
- openssl: 1.1.1n
- packaging: 23.2
- pydantic: 2.6.1
- pydantic-core: 2.16.2
- pydecimal: 1.0.0
- pydoc-data: 1.0.0
- pyyaml: 6.0.1
- regex: 2023.12.25
- regex-tests: 2023.12.25
- requests: 2.31.0
- six: 1.16.0
- sniffio: 1.3.0
- sniffio-tests: 1.3.0
- sqlite3: 1.0.0
- ssl: 1.0.0
- starlette: 0.36.3

Looking for a package not listed here? Tell us what you'd like us to support by [opening a discussion on Github](https://github.com/cloudflare/workerd/discussions/new?category=python-packages).

## HTTP Client Libraries

Only HTTP libraries that are able to make requests asynchronously are supported. Currently, these include [`aiohttp`](https://docs.aiohttp.org/en/stable/index.html) and [`httpx`](https://www.python-httpx.org/). You can also use the [`fetch()` API](/workers/runtime-apis/fetch/) from JavaScript, using Python Workers' [foreign function interface](/workers/languages/python/ffi) to make HTTP requests.

---

# Langchain

URL: https://developers.cloudflare.com/workers/languages/python/packages/langchain/

import { Render } from "~/components"

[LangChain](https://www.langchain.com/) is the most popular framework for building AI applications powered by large language models (LLMs).

LangChain publishes multiple Python packages. The following are provided by the Workers runtime:

* [`langchain`](https://pypi.org/project/langchain/) (version `0.1.8`)
* [`langchain-core`](https://pypi.org/project/langchain-core/) (version `0.1.25`)
* [`langchain-openai`](https://pypi.org/project/langchain-openai/) (version `0.0.6`)

## Get Started

<Render file="python-workers-beta-packages" product="workers" />

Clone the `cloudflare/python-workers-examples` repository and run the LangChain example:

```bash
git clone https://github.com/cloudflare/python-workers-examples
cd 04-langchain
npx wrangler@latest dev
```

### Example code

```python
from workers import Response
from langchain_core.prompts import PromptTemplate
from langchain_openai import OpenAI

async def on_fetch(request, env):
  prompt = PromptTemplate.from_template("Complete the following sentence: I am a {profession} and ")
  llm = OpenAI(api_key=env.API_KEY)
  chain = prompt | llm

  res = await chain.ainvoke({"profession": "electrician"})
  return Response(res.split(".")[0].strip())
```

---

# HTTP

URL: https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/http/

import { WranglerConfig } from "~/components";

Worker A that declares a Service binding to Worker B can forward a [`Request`](/workers/runtime-apis/request/) object to Worker B, by calling the `fetch()` method that is exposed on the binding object.

For example, consider the following Worker that implements a [`fetch()` handler](/workers/runtime-apis/handlers/fetch/):

<WranglerConfig>

```toml
name = "worker_b"
main = "./src/workerB.js"
```

</WranglerConfig>

```js
export default {
  async fetch(request, env, ctx) {
    return new Response("Hello World!");
  }
}
```

The following Worker declares a binding to the Worker above:



<WranglerConfig>

```toml
name = "worker_a"
main = "./src/workerA.js"
services = [
  { binding = "WORKER_B", service = "worker_b" }
]
```

</WranglerConfig>

And then can forward a request to it:

```js
export default {
	async fetch(request, env) {
		return await env.WORKER_B.fetch(request);
	},
};
```

:::note

If you construct a new request manually, rather than forwarding an existing one, ensure that you provide a valid and fully-qualified URL with a hostname. For example:

```js
export default {
  async fetch(request, env) {
    // provide a valid URL
    let newRequest = new Request("https://valid-url.com", { method: "GET" });
    let response = await env.WORKER_B.fetch(newRequest);
    return response;
  }
};
```

:::

---

# Service bindings

URL: https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/

import { WranglerConfig } from "~/components";

## About Service bindings

Service bindings allow one Worker to call into another, without going through a publicly-accessible URL. A Service binding allows Worker A to call a method on Worker B, or to forward a request from Worker A to Worker B.

Service bindings provide the separation of concerns that microservice or service-oriented architectures provide, without configuration pain, performance overhead or need to learn RPC protocols.

- **Service bindings are fast.** When you use Service Bindings, there is zero overhead or added latency. By default, both Workers run on the same thread of the same Cloudflare server. And when you enable [Smart Placement](/workers/configuration/smart-placement/), each Worker runs in the optimal location for overall performance.
- **Service bindings are not just HTTP.** Worker A can expose methods that can be directly called by Worker B. Communicating between services only requires writing JavaScript methods and classes.
- **Service bindings don't increase costs.** You can split apart functionality into multiple Workers, without incurring additional costs. Learn more about [pricing for Service Bindings](/workers/platform/pricing/#service-bindings).

![Service bindings are a zero-cost abstraction](~/assets/images/workers/platform/bindings/service-bindings-comparison.png)

Service bindings are commonly used to:

* **Provide a shared internal service to multiple Workers.** For example, you can deploy an authentication service as its own Worker, and then have any number of separate Workers communicate with it via Service bindings.
* **Isolate services from the public Internet.** You can deploy a Worker that is not reachable via the public Internet, and can only be reached via an explicit Service binding that another Worker declares.
* **Allow teams to deploy code independently.** Team A can deploy their Worker on their own release schedule, and Team B can deploy their Worker separately.

## Configuration

You add a Service binding by modifying the [Wrangler configuration file](/workers/wrangler/configuration/) of the caller — the Worker that you want to be able to initiate requests.

For example, if you want Worker A to be able to call Worker B — you'd add the following to the [Wrangler configuration file](/workers/wrangler/configuration/) for Worker A:

<WranglerConfig>

```toml
services = [
  { binding = "<BINDING_NAME>", service = "<WORKER_NAME>" }
]
```

</WranglerConfig>

* `binding`: The name of the key you want to expose on the `env` object.
* `service`: The name of the target Worker you would like to communicate with. This Worker must be on your Cloudflare account.

## Interfaces

Worker A that declares a Service binding to Worker B can call Worker B in two different ways:

1. [RPC](/workers/runtime-apis/bindings/service-bindings/rpc) lets you communicate between Workers using function calls that you define. For example, `await env.BINDING_NAME.myMethod(arg1)`. This is recommended for most use cases, and allows you to create your own internal APIs that your Worker makes available to other Workers.
2. [HTTP](/workers/runtime-apis/bindings/service-bindings/http) lets you communicate between Workers by calling the [`fetch()` handler](/workers/runtime-apis/handlers/fetch) from other Workers, sending `Request` objects and receiving `Response` objects back. For example, `env.BINDING_NAME.fetch(request)`.

## Example — build your first Service binding using RPC

This example [extends the `WorkerEntrypoint` class](/workers/runtime-apis/bindings/service-bindings/rpc/#the-workerentrypoint-class) to support RPC-based Service bindings.
First, create the Worker that you want to communicate with. Let's call this "Worker B". Worker B exposes the public method, `add(a, b)`:


<WranglerConfig>

```toml
name = "worker_b"
main = "./src/workerB.js"
```

</WranglerConfig>

```js
import { WorkerEntrypoint } from "cloudflare:workers";

export default class WorkerB extends WorkerEntrypoint {
  // Currently, entrypoints without a named handler are not supported
  async fetch() { return new Response(null, {status: 404}); }

  async add(a, b) { return a + b; }
}
```

Next, create the Worker that will call Worker B. Let's call this "Worker A". Worker A declares a binding to Worker B. This is what gives it permission to call public methods on Worker B.



<WranglerConfig>

```toml
name = "worker_a"
main = "./src/workerA.js"
services = [
  { binding = "WORKER_B", service = "worker_b" }
]
```

</WranglerConfig>

```js
export default {
  async fetch(request, env) {
    const result = await env.WORKER_B.add(1, 2);
    return new Response(result);
  }
}
```

To run both Worker A and Worker B in local development, you must run two instances of [Wrangler](/workers/wrangler) in your terminal. For each Worker, open a new terminal and run [`npx wrangler@latest dev`](/workers/wrangler/commands#dev).

Each Worker is deployed separately.

## Lifecycle

The Service bindings API is asynchronous — you must `await` any method you call. If Worker A invokes Worker B via a Service binding, and Worker A does not await the completion of Worker B, Worker B will be terminated early.

For more about the lifecycle of calling a Worker over a Service Binding via RPC, refer to the [RPC Lifecycle](/workers/runtime-apis/rpc/lifecycle) docs.

## Local development

Local development is supported for Service bindings. For each Worker, open a new terminal and use [`wrangler dev`](/workers/wrangler/commands/#dev) in the relevant directory. When running `wrangler dev`, service bindings will show as `connected`/`not connected` depending on whether Wrangler can find a running `wrangler dev` session for that Worker. For example:

```sh
$ wrangler dev
...
Your worker has access to the following bindings:
- Services:
  - SOME_OTHER_WORKER: some-other-worker [connected]
  - ANOTHER_WORKER: another-worker [not connected]
```

Wrangler also supports running multiple Workers at once with one command. To try it out, pass multiple `-c` flags to Wrangler, like this: `wrangler dev -c wrangler.json -c ../other-worker/wrangler.json`. The first config will be treated as the _primary_ worker, which will be exposed over HTTP as usual at `http://localhost:8787`. The remaining config files will be treated as _secondary_ and will only be accessible via a service binding from the primary worker.

:::caution

Support for running multiple Workers at once with one Wrangler command is experimental, and subject to change as we work on the experience. If you run into bugs or have any feedback, [open an issue on the workers-sdk repository](https://github.com/cloudflare/workers-sdk/issues/new)

:::
## Deployment

Workers using Service bindings are deployed separately.

When getting started and deploying for the first time, this means that the target Worker (Worker B in the examples above) must be deployed first, before Worker A. Otherwise, when you attempt to deploy Worker A, deployment will fail, because Worker A declares a binding to Worker B, which does not yet exist.

When making changes to existing Workers, in most cases you should:

* Deploy changes to Worker B first, in a way that is compatible with the existing Worker A. For example, add a new method to Worker B.
* Next, deploy changes to Worker A. For example, call the new method on Worker B, from Worker A.
* Finally, remove any unused code. For example, delete the previously used method on Worker B.

## Smart Placement

[Smart Placement](/workers/configuration/smart-placement) automatically places your Worker in an optimal location that minimizes latency.

You can use Smart Placement together with Service bindings to split your Worker into two services:

![Smart Placement and Service Bindings](~/assets/images/workers/platform/smart-placement-service-bindings.png)

Refer to the [docs on Smart Placement](/workers/configuration/smart-placement/#best-practices) for more.

## Limits

Service bindings have the following limits:

* Each request to a Worker via a Service binding counts toward your [subrequest limit](/workers/platform/limits/#subrequests).
* A single request has a maximum of 32 Worker invocations, and each call to a Service binding counts towards this limit. Subsequent calls will throw an exception.
* Calling a service binding does not count towards [simultaneous open connection limits](/workers/platform/limits/#simultaneous-open-connections)

---

# RPC (WorkerEntrypoint)

URL: https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/rpc/

import { DirectoryListing, Render, WranglerConfig } from "~/components"

[Service bindings](/workers/runtime-apis/bindings/service-bindings) allow one Worker to call into another, without going through a publicly-accessible URL.

You can use Service bindings to create your own internal APIs that your Worker makes available to other Workers. This can be done by extending the built-in `WorkerEntrypoint` class, and adding your own public methods. These public methods can then be directly called by other Workers on your Cloudflare account that declare a [binding](/workers/runtime-apis/bindings) to this Worker.

The [RPC system in Workers](/workers/runtime-apis/rpc) is designed feel as similar as possible to calling a JavaScript function in the same Worker. In most cases, you should be able to write code in the same way you would if everything was in a single Worker.

:::note

You can also use RPC to communicate between Workers and [Durable Objects](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#invoke-rpc-methods).
:::

## Example

For example, the following Worker implements the public method `add(a, b)`:

<Render file="service-binding-rpc-example" product="workers" />

You do not need to learn, implement, or think about special protocols to use the RPC system. The client, in this case Worker A, calls Worker B and tells it to execute a specific procedure using specific arguments that the client provides. This is accomplished with standard JavaScript classes.

## The `WorkerEntrypoint` Class

To provide RPC methods from your Worker, you must extend the `WorkerEntrypoint` class, as shown in the example below:

```js
import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint {
  async add(a, b) { return a + b; }
}
```

A new instance of the class is created every time the Worker is called. Note that even though the Worker is implemented as a class, it is still stateless — the class instance only lasts for the duration of the invocation. If you need to persist or coordinate state in Workers, you should use [Durable Objects](/durable-objects).

### Bindings (`env`)

The [`env`](/workers/runtime-apis/bindings) object is exposed as a class property of the `WorkerEntrypoint` class.

For example, a Worker that declares a binding to the [environment variable](/workers/configuration/environment-variables/) `GREETING`:

<WranglerConfig>

```toml
name = "my-worker"

[vars]
GREETING = "Hello"
```

</WranglerConfig>

Can access it by calling `this.env.GREETING`:

```js
import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint {
  fetch() { return new Response("Hello from my-worker"); }

  async greet(name) {
    return this.env.GREETING + name;
  }
}
```

You can use any type of [binding](/workers/runtime-apis/bindings) this way.

### Lifecycle methods (`ctx`)

The [`ctx`](/workers/runtime-apis/context) object is exposed as a class property of the `WorkerEntrypoint` class.

For example, you can extend the lifetime of the invocation context by calling the `waitUntil()` method:

```js
import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint {
  fetch() { return new Response("Hello from my-worker"); }

  async signup(email, name) {
    // sendEvent() will continue running, even after this method returns a value to the caller
    this.ctx.waitUntil(this.#sendEvent("signup", email))
    // Perform any other work
    return "Success";
  }

  async #sendEvent(eventName, email) {
    //...
  }
}
```

## Named entrypoints

You can also export any number of named `WorkerEntrypoint` classes from within a single Worker, in addition to the default export. You can then declare a Service binding to a specific named entrypoint.

You can use this to group multiple pieces of compute together. For example, you might create a distinct `WorkerEntrypoint` for each permission role in your application, and use these to provide role-specific RPC methods:



<WranglerConfig>

```toml
name = "todo-app"

[[d1_databases]]
binding = "D1"
database_name = "todo-app-db"
database_id = "<unique-ID-for-your-database>"
```

</WranglerConfig>

```js
import { WorkerEntrypoint } from "cloudflare:workers";

export class AdminEntrypoint extends WorkerEntrypoint {
  async createUser(username) {
    await this.env.D1.prepare("INSERT INTO users (username) VALUES (?)")
      .bind(username)
      .run();
  }

  async deleteUser(username) {
    await this.env.D1.prepare("DELETE FROM users WHERE username = ?")
      .bind(username)
      .run();
  }
}

export class UserEntrypoint extends WorkerEntrypoint {
  async getTasks(userId) {
    return await this.env.D1.prepare(
      "SELECT title FROM tasks WHERE user_id = ?"
    )
      .bind(userId)
      .all();
  }

  async createTask(userId, title) {
    await this.env.D1.prepare(
      "INSERT INTO tasks (user_id, title) VALUES (?, ?)"
    )
      .bind(userId, title)
      .run();
  }
}

export default class extends WorkerEntrypoint {
  async fetch(request, env) {
    return new Response("Hello from my to do app");
  }
}
```

You can then declare a Service binding directly to `AdminEntrypoint` in another Worker:



<WranglerConfig>

```toml
name = "admin-app"

[[services]]
binding = "ADMIN"
service = "todo-app"
entrypoint = "AdminEntrypoint"
```

</WranglerConfig>

```js
export default {
  async fetch(request, env) {
    await env.ADMIN.createUser("aNewUser");
    return new Response("Hello from admin app");
  },
};
```

You can learn more about how to configure D1 in the [D1 documentation](/d1/get-started/#3-bind-your-worker-to-your-d1-database).

You can try out a complete example of this to do app, as well as a Discord bot built with named entrypoints, by cloning the [cloudflare/js-rpc-and-entrypoints-demo repository](https://github.com/cloudflare/js-rpc-and-entrypoints-demo) from GitHub.

## Further reading

<DirectoryListing folder="workers/runtime-apis/rpc" />

---

# Developing

URL: https://developers.cloudflare.com/workers/testing/miniflare/developing/

import { DirectoryListing } from "~/components";

<DirectoryListing path="/developing" />

---

# 📅 Compatibility Dates

URL: https://developers.cloudflare.com/workers/testing/miniflare/core/compatibility/

- [Compatibility Dates Reference](/workers/configuration/compatibility-dates)

## Compatibility Dates

Miniflare uses compatibility dates to opt-into backwards-incompatible changes
from a specific date. If one isn't set, it will default to some time far in the
past.

```js
const mf = new Miniflare({
	compatibilityDate: "2021-11-12",
});
```

## Compatibility Flags

Miniflare also lets you opt-in/out of specific changes using compatibility
flags:

```js
const mf = new Miniflare({
	compatibilityFlags: [
		"formdata_parser_supports_files",
		"durable_object_fetch_allows_relative_url",
	],
});
```

---

# 📨 Fetch Events

URL: https://developers.cloudflare.com/workers/testing/miniflare/core/fetch/

- [`FetchEvent` Reference](/workers/runtime-apis/handlers/fetch/)

## HTTP Requests

Whenever an HTTP request is made, a `Request` object is dispatched to your worker, then the generated `Response` is returned. The
`Request` object will include a
[`cf` object](/workers/runtime-apis/request#incomingrequestcfproperties).
Miniflare will log the method, path, status, and the time it took to respond.

If the Worker throws an error whilst generating a response, an error page
containing the stack trace is returned instead.

## Dispatching Events

When using the API, the `dispatchFetch` function can be used to dispatch `fetch`
events to your Worker. This can be used for testing responses. `dispatchFetch`
has the same API as the regular `fetch` method: it either takes a `Request`
object, or a URL and optional `RequestInit` object:

```js
import { Miniflare, Request } from "miniflare";

const mf = new Miniflare({
	modules: true,
	script: `
  export default {
    async fetch(request, env, ctx) {
      const body = JSON.stringify({
        url: event.request.url,
        header: event.request.headers.get("X-Message"),
      });
      return new Response(body, {
        headers: { "Content-Type": "application/json" },
      });
    })
  }
  `,
});

let res = await mf.dispatchFetch("http://localhost:8787/");
console.log(await res.json()); // { url: "http://localhost:8787/", header: null }

res = await mf.dispatchFetch("http://localhost:8787/1", {
	headers: { "X-Message": "1" },
});
console.log(await res.json()); // { url: "http://localhost:8787/1", header: "1" }

res = await mf.dispatchFetch(
	new Request("http://localhost:8787/2", {
		headers: { "X-Message": "2" },
	}),
);
console.log(await res.json()); // { url: "http://localhost:8787/2", header: "2" }
```

When dispatching events, you are responsible for adding
[`CF-*` headers](https://support.cloudflare.com/hc/en-us/articles/200170986-How-does-Cloudflare-handle-HTTP-Request-headers-)
and the
[`cf` object](/workers/runtime-apis/request#incomingrequestcfproperties).
This lets you control their values for testing:

```js
const res = await mf.dispatchFetch("http://localhost:8787", {
	headers: {
		"CF-IPCountry": "GB",
	},
	cf: {
		country: "GB",
	},
});
```

## Upstream

Miniflare will call each `fetch` listener until a response is returned. If no
response is returned, or an exception is thrown and `passThroughOnException()`
has been called, the response will be fetched from the specified upstream
instead:

```js
import { Miniflare } from "miniflare";

const mf = new Miniflare({
	script: `
  addEventListener("fetch", (event) => {
    event.passThroughOnException();
    throw new Error();
  });
  `,
	upstream: "https://miniflare.dev",
});
// If you don't use the same upstream URL when dispatching, Miniflare will
// rewrite it to match the upstream
const res = await mf.dispatchFetch("https://miniflare.dev/core/fetch");
console.log(await res.text()); // Source code of this page
```

---

# Core

URL: https://developers.cloudflare.com/workers/testing/miniflare/core/

import { DirectoryListing } from "~/components";

<DirectoryListing path="/core" />

---

# 🐛 Attaching a Debugger

URL: https://developers.cloudflare.com/workers/testing/miniflare/developing/debugger/

:::caution
This documentation describes breakpoint debugging when using Miniflare directly, which is only relevant for advanced use cases. Instead, most users should refer to the [Workers Observability documentation for how to set this up when using Wrangler](/workers/observability/dev-tools/breakpoints/).
:::

You can use regular Node.js tools to debug your Workers. Setting breakpoints,
watching values and inspecting the call stack are all examples of things you can
do with a debugger.

## Visual Studio Code

### Create configuration

The easiest way to debug a Worker in VSCode is to create a new configuration.

Open the **Run and Debug** menu in the VSCode activity bar and create a
`.vscode/launch.json` file that contains the following:

```json
---
filename: .vscode/launch.json
---
{
  "configurations": [
    {
      "name": "Miniflare",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "cwd": "/",
      "resolveSourceMapLocations": null,
      "attachExistingChildren": false,
      "autoAttachChildProcesses": false,
    }
  ]
}
```

From the **Run and Debug** menu in the activity bar, select the `Miniflare`
configuration, and click the green play button to start debugging.

## WebStorm

Create a new configuration, by clicking **Add Configuration** in the top right.

![WebStorm add configuration button](./debugger-webstorm-node-add.png)

Click the **plus** button in the top left of the popup and create a new
**Node.js/Chrome** configuration. Set the **Host** field to `localhost` and the
**Port** field to `9229`. Then click **OK**.

![WebStorm Node.js debug configuration](./debugger-webstorm-settings.png)

With the new configuration selected, click the green debug button to start
debugging.

![WebStorm configuration debug button](./debugger-webstorm-node-run.png)

## DevTools

Breakpoints can also be added via the Workers DevTools. For more information,
[read the guide](/workers/observability/dev-tools)
in the Cloudflare Workers docs.

---

# ⚡️ Live Reload

URL: https://developers.cloudflare.com/workers/testing/miniflare/developing/live-reload/

Miniflare automatically refreshes your browser when your Worker script
changes when `liveReload` is set to `true`.

```js
const mf = new Miniflare({
	liveReload: true,
});
```

Miniflare will only inject the `<script>` tag required for live-reload at the
end of responses with the `Content-Type` header set to `text/html`:

```js
export default {
	fetch() {
		const body = `
      <!DOCTYPE html>
      <html>
      <body>
        <p>Try update me!</p>
      </body>
      </html>
    `;

		return new Response(body, {
			headers: { "Content-Type": "text/html; charset=utf-8" },
		});
	},
};
```

---

# 🚥 Queues

URL: https://developers.cloudflare.com/workers/testing/miniflare/core/queues/

- [Queues Reference](/queues/)

## Producers

Specify Queue producers to add to your environment as follows:

```js
const mf = new Miniflare({
	queueProducers: { MY_QUEUE: "my-queue" },
	queueProducers: ["MY_QUEUE"], // If binding and queue names are the same
});
```

## Consumers

Specify Workers to consume messages from your Queues as follows:

```js
const mf = new Miniflare({
	queueConsumers: {
		"my-queue": {
			maxBatchSize: 5, // default: 5
			maxBatchTimeout: 1 /* second(s) */, // default: 1
			maxRetries: 2, // default: 2
			deadLetterQueue: "my-dead-letter-queue", // default: none
		},
	},
	queueConsumers: ["my-queue"], // If using default consumer options
});
```

## Manipulating Outside Workers

For testing, it can be valuable to interact with Queues outside a Worker. You can do this by using the `workers` option to run multiple Workers in the same instance:

```js
const mf = new Miniflare({
	workers: [
		{
			name: "a",
			modules: true,
			script: `
			export default {
				async fetch(request, env, ctx) {
					await env.QUEUE.send(await request.text());
				}
			}
			`,
			queueProducers: { QUEUE: "my-queue" },
		},
		{
			name: "b",
			modules: true,
			script: `
			export default {
				async queue(batch, env, ctx) {
					console.log(batch);
				}
			}
			`,
			queueConsumers: { "my-queue": { maxBatchTimeout: 1 } },
		},
	],
});

const queue = await mf.getQueueProducer("QUEUE", "a"); // Get from worker "a"
await queue.send("message"); // Logs "message" 1 second later
```

---

# 📚 Modules

URL: https://developers.cloudflare.com/workers/testing/miniflare/core/modules/

- [Modules Reference](/workers/reference/migrate-to-module-workers/)

## Enabling Modules

Miniflare supports both the traditional `service-worker` and the newer `modules` formats for writing workers. To use the `modules` format, enable it with:

```js
const mf = new Miniflare({
	modules: true,
});
```

You can then use `modules` worker scripts like the following:

```js
export default {
	async fetch(request, env, ctx) {
		// - `request` is the incoming `Request` instance
		// - `env` contains bindings, KV namespaces, Durable Objects, etc
		// - `ctx` contains `waitUntil` and `passThroughOnException` methods
		return new Response("Hello Miniflare!");
	},
	async scheduled(controller, env, ctx) {
		// - `controller` contains `scheduledTime` and `cron` properties
		// - `env` contains bindings, KV namespaces, Durable Objects, etc
		// - `ctx` contains the `waitUntil` method
		console.log("Doing something scheduled...");
	},
};
```

<Aside type="warning" header="Warning">

String scripts via the `script` option are supported using
the `modules` format, but you cannot import other modules using them. You must
use a script file via the `scriptPath` option for this.

</Aside>

## Module Rules

Miniflare supports all module types: `ESModule`, `CommonJS`, `Text`, `Data` and
`CompiledWasm`. You can specify additional module resolution rules as follows:

```js
const mf = new Miniflare({
	modulesRules: [
		{ type: "ESModule", include: ["**/*.js"], fallthrough: true },
		{ type: "Text", include: ["**/*.txt"] },
	],
});
```

### Default Rules

The following rules are automatically added to the end of your modules rules
list. You can override them by specifying rules matching the same `globs`:

```js
[
	{ type: "ESModule", include: ["**/*.mjs"] },
	{ type: "CommonJS", include: ["**/*.js", "**/*.cjs"] },
];
```

---

# ⬆️ Migrating from Version 2

URL: https://developers.cloudflare.com/workers/testing/miniflare/migrations/from-v2/

Miniflare v3 now uses [`workerd`](https://github.com/cloudflare/workerd), the
open-source Cloudflare Workers runtime. This is the same runtime that's deployed
on Cloudflare's network, giving bug-for-bug compatibility and practically
eliminating behavior mismatches. Refer to the
[Miniflare v3](https://blog.cloudflare.com/miniflare-and-workerd/) and
[Wrangler v3 announcements](https://blog.cloudflare.com/wrangler3/) for more
information.

## CLI Changes

Miniflare v3 no longer includes a standalone CLI. To get the same functionality,
you will need to switch over to
[Wrangler](/workers/wrangler/). Wrangler v3
uses Miniflare v3 by default. To start a local development server, run:

```sh
$ npx wrangler@3 dev
```

If there are features from the Miniflare CLI you would like to see in Wrangler,
please open an issue on
[GitHub](https://github.com/cloudflare/workers-sdk/issues/new/choose).

## API Changes

We have tried to keep Miniflare v3's API close to Miniflare v2 where possible,
but many options and methods have been removed or changed with the switch to the
open-source `workerd` runtime. See the [Getting Started guide for the new API docs](/workers/testing/miniflare/get-started)

### Updated Options

- `kvNamespaces/r2Buckets/d1Databases`
  - In addition to `string[]`s, these options now accept
    `Record<string, string>`s, mapping binding names to namespace IDs/bucket
    names/database IDs. This means multiple Workers can bind to the same
    namespace/bucket/database under different names.
- `queueBindings`
  - Renamed to `queueProducers`. This either accepts a `Record<string, string>`
    mapping binding names to queue names, or a `string[]` of binding names to
    queues of the same name.
- `queueConsumers`

  - Either accepts a `Record<string, QueueConsumerOptions>` mapping queue names
    to consumer options, or a `string[]` of queue names to consume with default
    options. `QueueConsumerOptions` has the following type:

    ```ts
    interface QueueConsumerOptions {
    	// /queues/platform/configuration/#consumer
    	maxBatchSize?: number; // default: 5
    	maxBatchTimeout?: number /* seconds */; // default: 1
    	maxRetries?: number; // default: 2
    	deadLetterQueue?: string; // default: none
    }
    ```

- `cfFetch`
  - Renamed to `cf`. Either accepts a `boolean`, `string` (as before), or an
    object to use a the `cf` object for incoming requests.

### Removed Options

- `wranglerConfigPath/wranglerConfigEnv`
  - Miniflare no longer handles Wrangler's configuration. To programmatically
    start up a Worker based on Wrangler configuration, use the
    [`unstable_dev()`](/workers/wrangler/api/#unstable_dev)
    API.
- `packagePath`
  - Miniflare no longer loads script paths from `package.json` files. Use the
    `scriptPath` option to specify your script instead.
- `watch`
  - Miniflare's API is primarily intended for testing use cases, where file
    watching isn't usually required. This option was here to enable Miniflare's
    CLI which has now been removed. If you need to watch files, consider using a
    separate file watcher like
    [`fs.watch()`](https://nodejs.org/api/fs.html#fswatchfilename-options-listener)
    or [`chokidar`](https://github.com/paulmillr/chokidar), and calling
    `setOptions()` with your original configuration on change.
- `logUnhandledRejections`
  - Unhandled rejections can be handled in Workers with
    [`addEventListener("unhandledrejection")`](https://community.cloudflare.com/t/2021-10-21-workers-runtime-release-notes/318571).
- `globals`
  - Injecting arbitrary globals is not supported by
    [`workerd`](https://github.com/cloudflare/workerd). If you're using a
    service worker, `bindings` will be injected as globals, but these must be
    JSON-serialisable.
- `https/httpsKey(Path)/httpsCert(Path)/httpsPfx(Path)/httpsPassphrase`
  - Miniflare does not support starting HTTPS servers yet. These options may be
    added back in a future release.
- `crons`
  - [`workerd`](https://github.com/cloudflare/workerd) does not support
    triggering scheduled events yet. This option may be added back in a future
    release.
- `mounts`

  - Miniflare no longer has the concept of parent and child Workers. Instead,
    all Workers can be defined at the same level, using the new `workers`
    option. Here's an example that uses a service binding to increment a value
    in a shared KV namespace:

    ```ts
    import { Miniflare, Response } from "miniflare";

    const message = "The count is ";
    const mf = new Miniflare({
    	// Options shared between Workers such as HTTP and persistence configuration
    	// should always be defined at the top level.
    	host: "0.0.0.0",
    	port: 8787,
    	kvPersist: true,

    	workers: [
    		{
    			name: "worker",
    			kvNamespaces: { COUNTS: "counts" },
    			serviceBindings: {
    				INCREMENTER: "incrementer",
    				// Service bindings can also be defined as custom functions, with access
    				// to anything defined outside Miniflare.
    				async CUSTOM(request) {
    					// `request` is the incoming `Request` object.
    					return new Response(message);
    				},
    			},
    			modules: true,
    			script: `export default {
            async fetch(request, env, ctx) {
              // Get the message defined outside
              const response = await env.CUSTOM.fetch("http://host/");
              const message = await response.text();

              // Increment the count 3 times
              await env.INCREMENTER.fetch("http://host/");
              await env.INCREMENTER.fetch("http://host/");
              await env.INCREMENTER.fetch("http://host/");
              const count = await env.COUNTS.get("count");

              return new Response(message + count);
            }
          }`,
    		},
    		{
    			name: "incrementer",
    			// Note we're using the same `COUNTS` namespace as before, but binding it
    			// to `NUMBERS` instead.
    			kvNamespaces: { NUMBERS: "counts" },
    			// Worker formats can be mixed-and-matched
    			script: `addEventListener("fetch", (event) => {
            event.respondWith(handleRequest());
          })
          async function handleRequest() {
            const count = parseInt((await NUMBERS.get("count")) ?? "0") + 1;
            await NUMBERS.put("count", count.toString());
            return new Response(count.toString());
          }`,
    		},
    	],
    });
    const res = await mf.dispatchFetch("http://localhost");
    console.log(await res.text()); // "The count is 3"
    await mf.dispose();
    ```

- `metaProvider`
  - The `cf` object and `X-Forwarded-Proto`/`X-Real-IP` headers can be specified
    when calling `dispatchFetch()` instead. A default `cf` object can be
    specified using the new `cf` option too.
- `durableObjectAlarms`
  - Miniflare now always enables Durable Object alarms.
- `globalAsyncIO/globalTimers/globalRandom`
  - [`workerd`](https://github.com/cloudflare/workerd) cannot support these
    options without fundamental changes.
- `actualTime`
  - Miniflare now always returns the current time.
- `inaccurateCpu`
  - Set the `inspectorPort: 9229` option to enable the V8 inspector. Visit
    `chrome://inspect` in Google Chrome to open DevTools and perform CPU
    profiling.

### Updated Methods

- `setOptions()`
  - Miniflare v3 now requires a full configuration object to be passed, instead
    of a partial patch.

### Removed Methods

- `reload()`
  - Call `setOptions()` with the original configuration object to reload
    Miniflare.
- `createServer()/startServer()`
  - Miniflare now always starts a
    [`workerd`](https://github.com/cloudflare/workerd) server listening on the
    configured `host` and `port`, so these methods are redundant.
- `dispatchScheduled()/startScheduled()`
  - The functionality of `dispatchScheduled` can now be done via `getWorker()`. For more information read the [scheduled events documentation](/workers/testing/miniflare/core/scheduled#dispatching-events).
- `dispatchQueue()`
  - Use the `queue()` method on
    [service bindings](/workers/runtime-apis/bindings/service-bindings)
    or
    [queue producer bindings](/queues/configuration/configure-queues/#producer-worker-configuration)
    instead.
- `getGlobalScope()/getBindings()/getModuleExports()`
  - These methods returned objects from inside the Workers sandbox. Since
    Miniflare now uses [`workerd`](https://github.com/cloudflare/workerd), which
    runs in a different process, these methods can no longer be supported.
- `addEventListener()`/`removeEventListener()`
  - Miniflare no longer emits `reload` events. As Miniflare no longer watches
    files, reloads are only triggered by initialisation or `setOptions()` calls.
    In these cases, it's possible to wait for the reload with either
    `await mf.ready` or `await mf.setOptions()` respectively.
- `Response#waitUntil()`
  - [`workerd`](https://github.com/cloudflare/workerd) does not support waiting
    for all `waitUntil()`ed promises yet.

### Removed Packages

- `@miniflare/*`
  - Miniflare is now contained within a single `miniflare` package.

---

# 🕸 Web Standards

URL: https://developers.cloudflare.com/workers/testing/miniflare/core/standards/

- [Web Standards Reference](/workers/runtime-apis/web-standards)
- [Encoding Reference](/workers/runtime-apis/encoding)
- [Fetch Reference](/workers/runtime-apis/fetch)
- [Request Reference](/workers/runtime-apis/request)
- [Response Reference](/workers/runtime-apis/response)
- [Streams Reference](/workers/runtime-apis/streams)
- [Web Crypto Reference](/workers/runtime-apis/web-crypto)

## Mocking Outbound `fetch` Requests

When using the API, Miniflare allows you to substitute custom `Response`s for
`fetch()` calls using `undici`'s
[`MockAgent` API](https://undici.nodejs.org/#/docs/api/MockAgent?id=mockagentgetorigin).
This is useful for testing Workers that make HTTP requests to other services. To
enable `fetch` mocking, create a
[`MockAgent`](https://undici.nodejs.org/#/docs/api/MockAgent?id=mockagentgetorigin)
using the `createFetchMock()` function, then set this using the `fetchMock`
option.

```js
import { Miniflare, createFetchMock } from "miniflare";

// Create `MockAgent` and connect it to the `Miniflare` instance
const fetchMock = createFetchMock();
const mf = new Miniflare({
	modules: true,
	script: `
  export default {
    async fetch(request, env, ctx) {
      const res = await fetch("https://example.com/thing");
      const text = await res.text();
      return new Response(\`response:\${text}\`);
    }
  }
  `,
	fetchMock,
});

// Throw when no matching mocked request is found
// (see https://undici.nodejs.org/#/docs/api/MockAgent?id=mockagentdisablenetconnect)
fetchMock.disableNetConnect();

// Mock request to https://example.com/thing
// (see https://undici.nodejs.org/#/docs/api/MockAgent?id=mockagentgetorigin)
const origin = fetchMock.get("https://example.com");
// (see https://undici.nodejs.org/#/docs/api/MockPool?id=mockpoolinterceptoptions)
origin
	.intercept({ method: "GET", path: "/thing" })
	.reply(200, "Mocked response!");

const res = await mf.dispatchFetch("http://localhost:8787/");
console.log(await res.text()); // "response:Mocked response!"
```

## Subrequests

Miniflare does not support limiting the amount of
[subrequests](/workers/platform/limits#account-plan-limits).
Please keep this in mind if you make a large amount of subrequests from your
Worker.

---

# 🔌 Multiple Workers

URL: https://developers.cloudflare.com/workers/testing/miniflare/core/multiple-workers/

Miniflare allows you to run multiple workers in the same instance. All Workers can be defined at the same level, using the `workers` option.

Here's an example that uses a service binding to increment a value in a shared KV namespace:

```js
import { Miniflare, Response } from "miniflare";

const message = "The count is ";
const mf = new Miniflare({
	// Options shared between workers such as HTTP and persistence configuration
	// should always be defined at the top level.
	host: "0.0.0.0",
	port: 8787,
	kvPersist: true,

	workers: [
		{
			name: "worker",
			kvNamespaces: { COUNTS: "counts" },
			serviceBindings: {
				INCREMENTER: "incrementer",
				// Service bindings can also be defined as custom functions, with access
				// to anything defined outside Miniflare.
				async CUSTOM(request) {
					// `request` is the incoming `Request` object.
					return new Response(message);
				},
			},
			modules: true,
			script: `export default {
        async fetch(request, env, ctx) {
          // Get the message defined outside
          const response = await env.CUSTOM.fetch("http://host/");
          const message = await response.text();

          // Increment the count 3 times
          await env.INCREMENTER.fetch("http://host/");
          await env.INCREMENTER.fetch("http://host/");
          await env.INCREMENTER.fetch("http://host/");
          const count = await env.COUNTS.get("count");

          return new Response(message + count);
        }
      }`,
		},
		{
			name: "incrementer",
			// Note we're using the same `COUNTS` namespace as before, but binding it
			// to `NUMBERS` instead.
			kvNamespaces: { NUMBERS: "counts" },
			// Worker formats can be mixed-and-matched
			script: `addEventListener("fetch", (event) => {
        event.respondWith(handleRequest());
      })
      async function handleRequest() {
        const count = parseInt((await NUMBERS.get("count")) ?? "0") + 1;
        await NUMBERS.put("count", count.toString());
        return new Response(count.toString());
      }`,
		},
	],
});
const res = await mf.dispatchFetch("http://localhost");
console.log(await res.text()); // "The count is 3"
await mf.dispose();
```

## Routing

You can enable routing by specifying `routes` via the API,
using the
[standard route syntax](/workers/configuration/routing/routes/#matching-behavior).
Note port numbers are ignored:

```js
const mf = new Miniflare({
	workers: [
		{
			scriptPath: "./api/worker.js",
			routes: ["http://127.0.0.1/api*", "api.mf/*"],
		},
	],
});
```

When using hostnames that aren't `localhost` or `127.0.0.1`, you
may need to edit your computer's `hosts` file, so those hostnames resolve to
`localhost`. On Linux and macOS, this is usually at `/etc/hosts`. On Windows,
it's at `C:\Windows\System32\drivers\etc\hosts`. For the routes above, we would
need to append the following entries to the file:

```
127.0.0.1 miniflare.test
127.0.0.1 api.mf
```

Alternatively, you can customise the `Host` header when sending the request:

```sh
# Dispatches to the "api" worker
$ curl "http://localhost:8787/todos/update/1" -H "Host: api.mf"
```

When using the API, Miniflare will use the request's URL to determine which
Worker to dispatch to.

```js
// Dispatches to the "api" worker
const res = await mf.dispatchFetch("http://api.mf/todos/update/1", { ... });
```

## Durable Objects

Miniflare supports the `script_name` option for accessing Durable Objects
exported by other scripts. See
[📌 Durable Objects](/workers/testing/miniflare/storage/durable-objects#using-a-class-exported-by-another-script)
for more details.

---

# 🔑 Variables and Secrets

URL: https://developers.cloudflare.com/workers/testing/miniflare/core/variables-secrets/

## Bindings

Variable and secrets are bound as follows:

```js
const mf = new Miniflare({
	bindings: {
		KEY1: "value1",
		KEY2: "value2",
	},
});
```

## Text and Data Blobs

Text and data blobs can be loaded from files. File contents will be read and
bound as `string`s and `ArrayBuffer`s respectively.

```js
const mf = new Miniflare({
	textBlobBindings: { TEXT: "text.txt" },
	dataBlobBindings: { DATA: "data.bin" },
});
```

## Globals

Injecting arbitrary globals is not supported by [workerd](https://github.com/cloudflare/workerd). If you're using a service Worker, bindings will be injected as globals, but these must be JSON-serialisable.

---

# ✉️ WebSockets

URL: https://developers.cloudflare.com/workers/testing/miniflare/core/web-sockets/

- [WebSockets Reference](/workers/runtime-apis/websockets)
- [Using WebSockets](/workers/examples/websockets/)

## Server

Miniflare will always upgrade Web Socket connections. The Worker must respond
with a status `101 Switching Protocols` response including a `webSocket`. For
example, the Worker below implements an echo WebSocket server:

```js
export default {
	fetch(request) {
		const [client, server] = Object.values(new WebSocketPair());

		server.accept();
		server.addEventListener("message", (event) => {
			server.send(event.data);
		});

		return new Response(null, {
			status: 101,
			webSocket: client,
		});
	},
};
```

When using `dispatchFetch`, you are responsible for handling WebSockets by using
the `webSocket` property on `Response`. As an example, if the above worker
script was stored in `echo.mjs`:

```js {13-17}
import { Miniflare } from "miniflare";

const mf = new Miniflare({
	modules: true,
	scriptPath: "echo.mjs",
});

const res = await mf.dispatchFetch("https://example.com", {
	headers: {
		Upgrade: "websocket",
	},
});
const webSocket = res.webSocket;
webSocket.accept();
webSocket.addEventListener("message", (event) => {
	console.log(event.data);
});

webSocket.send("Hello!"); // Above listener logs "Hello!"
```

---

# ⏰ Scheduled Events

URL: https://developers.cloudflare.com/workers/testing/miniflare/core/scheduled/

- [`ScheduledEvent` Reference](/workers/runtime-apis/handlers/scheduled/)

## Cron Triggers

`scheduled` events are automatically dispatched according to the specified cron
triggers:

```js
const mf = new Miniflare({
	crons: ["15 * * * *", "45 * * * *"],
});
```

## HTTP Triggers

Because waiting for cron triggers is annoying, you can also make HTTP requests
to `/cdn-cgi/mf/scheduled` to trigger `scheduled` events:

```sh
$ curl "http://localhost:8787/cdn-cgi/mf/scheduled"
```

To simulate different values of `scheduledTime` and `cron` in the dispatched
event, use the `time` and `cron` query parameters:

```sh
$ curl "http://localhost:8787/cdn-cgi/mf/scheduled?time=1000"
$ curl "http://localhost:8787/cdn-cgi/mf/scheduled?cron=*+*+*+*+*"
```

## Dispatching Events

When using the API, the `getWorker` function can be used to dispatch
`scheduled` events to your Worker. This can be used for testing responses. It
takes optional `scheduledTime` and `cron` parameters, which default to the
current time and the empty string respectively. It will return a promise which
resolves to an array containing data returned by all waited promises:

```js
import { Miniflare } from "miniflare";

const mf = new Miniflare({
	modules: true,
	script: `
  export default {
    async scheduled(controller, env, ctx) {
      const lastScheduledController = controller;
      if (controller.cron === "* * * * *") controller.noRetry();
    }
  }
  `,
});

const worker = await mf.getWorker();

let scheduledResult = await worker.scheduled({
	cron: "* * * * *",
});
console.log(scheduledResult); // { outcome: 'ok', noRetry: true }

scheduledResult = await worker.scheduled({
	scheduledTime: new Date(1000),
	cron: "30 * * * *",
});

console.log(scheduledResult); // { outcome: 'ok', noRetry: false }
```

---

# Migrations

URL: https://developers.cloudflare.com/workers/testing/miniflare/migrations/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# ✨ Cache

URL: https://developers.cloudflare.com/workers/testing/miniflare/storage/cache/

- [Cache Reference](/workers/runtime-apis/cache)
- [How the Cache works](/workers/reference/how-the-cache-works/#cache-api)
  (note that cache using `fetch` is unsupported)

## Default Cache

Access to the default cache is enabled by default:

```js
addEventListener("fetch", (e) => {
	e.respondWith(caches.default.match("http://miniflare.dev"));
});
```

## Named Caches

You can access a namespaced cache using `open`. Note that you cannot name your
cache `default`, trying to do so will throw an error:

```js
await caches.open("cache_name");
```

## Persistence

By default, cached data is stored in memory. It will persist between reloads,
but not different `Miniflare` instances. To enable
persistence to the file system, specify the cache persistence option:

```js
const mf = new Miniflare({
	cachePersist: true, // Defaults to ./.mf/cache
	cachePersist: "./data", // Custom path
});
```

## Manipulating Outside Workers

For testing, it can be useful to put/match data from cache outside a Worker. You
can do this with the `getCaches` method:

```js {23,24,25,26,27,28,29,30,31,32}
import { Miniflare, Response } from "miniflare";

const mf = new Miniflare({
	modules: true,
	script: `
  export default {
    async fetch(request) {
      const url = new URL(request.url);
      const cache = caches.default;
      if(url.pathname === "/put") {
        await cache.put("https://miniflare.dev/", new Response("1", {
          headers: { "Cache-Control": "max-age=3600" },
        }));
      }
      return cache.match("https://miniflare.dev/");
    }
  }
  `,
});
let res = await mf.dispatchFetch("http://localhost:8787/put");
console.log(await res.text()); // 1

const caches = await mf.getCaches(); // Gets the global caches object
const cachedRes = await caches.default.match("https://miniflare.dev/");
console.log(await cachedRes.text()); // 1

await caches.default.put(
	"https://miniflare.dev",
	new Response("2", {
		headers: { "Cache-Control": "max-age=3600" },
	}),
);
res = await mf.dispatchFetch("http://localhost:8787");
console.log(await res.text()); // 2
```

## Disabling

Both default and named caches can be disabled with the `disableCache` option.
When disabled, the caches will still be available in the sandbox, they just
won't cache anything. This may be useful during development:

```js
const mf = new Miniflare({
	cache: false,
});
```

---

# 💾 D1

URL: https://developers.cloudflare.com/workers/testing/miniflare/storage/d1/

- [D1 Reference](/d1/)

## Databases

Specify D1 Databases to add to your environment as follows:

```js
const mf = new Miniflare({
  d1Databases:{
    DB:"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
});
```

## Working with D1 Databases

For testing, it can be useful to put/get data from D1 storage
bound to a Worker. You can do this with the `getD1Database` method:

```js
const db = await mf.getD1Database("DB");
const stmt = await db.prepare("<Query>");
const returnValue = await stmt.run();

return Response.json(returnValue.results);
```

---

# 📌 Durable Objects

URL: https://developers.cloudflare.com/workers/testing/miniflare/storage/durable-objects/

- [Durable Objects Reference](/durable-objects/api/)
- [Using Durable Objects](/durable-objects/)

## Objects

Specify Durable Objects to add to your environment as follows:

```js
const mf = new Miniflare({
	modules: true,
	script: `
  export class Object1 {
    async fetch(request) {
      ...
    }
  }
  export default {
    fetch(request) {
      ...
    }
  }
  `,
	durableObjects: {
		// Note Object1 is exported from main (string) script
		OBJECT1: "Object1",
	},
});
```

## Persistence

By default, Durable Object data is stored in memory. It will persist between
reloads, but not different `Miniflare` instances. To enable persistence to the
file system, specify the Durable Object persistence option:

```js
const mf = new Miniflare({
	durableObjectsPersist: true, // Defaults to ./.mf/do
	durableObjectsPersist: "./data", // Custom path
});
```

## Manipulating Outside Workers

For testing, it can be useful to make requests to your Durable Objects from
outside a worker. You can do this with the `getDurableObjectNamespace` method.

```js {28,29,30,31,32}
import { Miniflare } from "miniflare";

const mf = new Miniflare({
	modules: true,
	durableObjects: { TEST_OBJECT: "TestObject" },
	script: `
  export class TestObject {
    constructor(state) {
      this.storage = state.storage;
    }

    async fetch(request) {
      const url = new URL(request.url);
      if (url.pathname === "/put") await this.storage.put("key", 1);
      return new Response((await this.storage.get("key")).toString());
    }
  }

  export default {
    async fetch(request, env) {
      const stub = env.TEST_OBJECT.get(env.TEST_OBJECT.idFromName("test"));
      return stub.fetch(request);
    }
  }
  `,
});

const ns = await mf.getDurableObjectNamespace("TEST_OBJECT");
const id = ns.idFromName("test");
const stub = ns.get(id);
const doRes = await stub.fetch("http://localhost:8787/put");
console.log(await doRes.text()); // "1"

const res = await mf.dispatchFetch("http://localhost:8787/");
console.log(await res.text()); // "1"
```

## Using a Class Exported by Another Script

Miniflare supports the `script_name` option for accessing Durable Objects
exported by other scripts. This requires mounting the other worker as described
in [🔌 Multiple Workers](/workers/testing/miniflare/core/multiple-workers).

---

# Storage

URL: https://developers.cloudflare.com/workers/testing/miniflare/storage/

import { DirectoryListing } from "~/components";

<DirectoryListing path="/storage" />

---

# 🪣 R2

URL: https://developers.cloudflare.com/workers/testing/miniflare/storage/r2/

- [R2 Reference](/r2/api/workers/workers-api-reference/)

## Buckets

Specify R2 Buckets to add to your environment as follows:

```js
const mf = new Miniflare({
	r2Buckets: ["BUCKET1", "BUCKET2"],
});
```

## Manipulating Outside Workers

For testing, it can be useful to put/get data from R2 storage
outside a worker. You can do this with the `getR2Bucket` method:

```js {18,19,23}
import { Miniflare } from "miniflare";

const mf = new Miniflare({
	modules: true,
	script: `
  export default {
    async fetch(request, env, ctx) {
      const object = await env.BUCKET.get("count");
      const value = parseInt(await object.text()) + 1;
      await env.BUCKET.put("count", value.toString());
      return new Response(value.toString());
    }
  }
  `,
	r2Buckets: ["BUCKET"],
});

const bucket = await mf.getR2Bucket("BUCKET");
await bucket.put("count", "1");

const res = await mf.dispatchFetch("http://localhost:8787/");
console.log(await res.text()); // 2
console.log(await (await bucket.get("count")).text()); // 2
```

---

# 📦 KV

URL: https://developers.cloudflare.com/workers/testing/miniflare/storage/kv/

- [KV Reference](/kv/api/)

## Namespaces

Specify KV namespaces to add to your environment as follows:

```js
const mf = new Miniflare({
	kvNamespaces: ["TEST_NAMESPACE1", "TEST_NAMESPACE2"],
});
```

You can now access KV namespaces in your workers:

```js
export default {
	async fetch(request, env) {
		return new Response(await env.TEST_NAMESPACE1.get("key"));
	},
};
```

Miniflare supports all KV operations and data types.

## Manipulating Outside Workers

For testing, it can be useful to put/get data from KV outside a worker. You can
do this with the `getKVNamespace` method:

```js {17,18,22}
import { Miniflare } from "miniflare";

const mf = new Miniflare({
	modules: true,
	script: `
  export default {
    async fetch(request, env, ctx) {
      const value = parseInt(await env.TEST_NAMESPACE.get("count")) + 1;
      await env.TEST_NAMESPACE.put("count", value.toString());
      return new Response(value.toString());
    },
  }
  `,
	kvNamespaces: ["TEST_NAMESPACE"],
});

const ns = await mf.getKVNamespace("TEST_NAMESPACE");
await ns.put("count", "1");

const res = await mf.dispatchFetch("http://localhost:8787/");
console.log(await res.text()); // 2
console.log(await ns.get("count")); // 2
```

---

# Migration guides

URL: https://developers.cloudflare.com/workers/testing/vitest-integration/migration-guides/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Migrate from Miniflare 2's test environments

URL: https://developers.cloudflare.com/workers/testing/vitest-integration/migration-guides/migrate-from-miniflare-2/

[Miniflare 2](https://github.com/cloudflare/miniflare?tab=readme-ov-file) provided custom environments for Jest and Vitest in the `jest-environment-miniflare` and `vitest-environment-miniflare` packages respectively.
The `@cloudflare/vitest-pool-workers` package provides similar functionality using modern Miniflare versions and the [`workerd` runtime](https://github.com/cloudflare/workerd). `workerd` is the same JavaScript/WebAssembly runtime that powers Cloudflare Workers. Using `workerd` practically eliminates behavior mismatches between your tests and deployed code. Refer to the [Miniflare 3 announcement](https://blog.cloudflare.com/miniflare-and-workerd) for more information.

:::caution

Cloudflare no longer provides a Jest testing environment for Workers. If you previously used Jest, you will need to [migrate to Vitest](https://vitest.dev/guide/migration.html#migrating-from-jest) first, then follow the rest of this guide. Vitest provides built-in support for TypeScript, ES modules, and hot-module reloading for tests out-of-the-box.

:::

:::caution

The Workers Vitest integration does not support testing Workers using the service worker format. [Migrate to ES modules format](/workers/reference/migrate-to-module-workers/) first.

:::

## Install the Workers Vitest integration

First, you will need to uninstall the old environment and install the new pool. Vitest environments can only customize the global scope, whereas pools can run tests using a completely different runtime. In this case, the pool runs your tests inside [`workerd`](https://github.com/cloudflare/workerd) instead of Node.js.

```sh
npm uninstall vitest-environment-miniflare
npm install --save-dev --save-exact vitest@~3.0.0
npm install --save-dev @cloudflare/vitest-pool-workers
```

## Update your Vitest configuration file

After installing the Workers Vitest configuration, update your Vitest configuration file to use the pool instead. Most Miniflare configuration previously specified `environmentOptions` can be moved to `poolOptions.workers.miniflare` instead. Refer to [Miniflare's `WorkerOptions` interface](https://github.com/cloudflare/workers-sdk/blob/main/packages/miniflare/README.md#interface-workeroptions) for supported options and the [Miniflare version 2 to 3 migration guide](/workers/testing/miniflare/migrations/from-v2/) for more information. If you relied on configuration stored in a Wrangler file, set `wrangler.configPath` too.

```diff
+ import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

  export default defineWorkersConfig({
    test: {
-     environment: "miniflare",
-     environmentOptions: { ... },
+     poolOptions: {
+       workers: {
+         miniflare: { ... },
+         wrangler: { configPath: "./wrangler.toml" },
+       },
+     },
    },
  });
```

## Update your TypeScript configuration file

If you are using TypeScript, update your `tsconfig.json` to include the correct ambient `types`:

```diff
  {
    "compilerOptions": {
      ...,
      "types": [
				...
-       "vitest-environment-miniflare/globals"
+       "@cloudflare/vitest-pool-workers"
      ]
    },
  }
```

## Access bindings

To access [bindings](/workers/runtime-apis/bindings/) in your tests, use the `env` helper from the `cloudflare:test` module.

```diff
  import { it } from "vitest";
+ import { env } from "cloudflare:test";

  it("does something", () => {
-   const env = getMiniflareBindings();
    // ...
  });
```

If you are using TypeScript, add an ambient `.d.ts` declaration file defining a `ProvidedEnv` `interface` in the `cloudflare:test` module to control the type of `env`:

```ts
declare module "cloudflare:test" {
	interface ProvidedEnv {
		NAMESPACE: KVNamespace;
	}
	// ...or if you have an existing `Env` type...
	interface ProvidedEnv extends Env {}
}
```

## Use isolated storage

Isolated storage is now enabled by default. You no longer need to include `setupMiniflareIsolatedStorage()` in your tests.

```diff
- const describe = setupMiniflareIsolatedStorage();
+ import { describe } from "vitest";
```

## Work with `waitUntil()`

The `new ExecutionContext()` constructor and `getMiniflareWaitUntil()` function are now `createExecutionContext()` and `waitOnExecutionContext()` respectively. Note `waitOnExecutionContext()` now returns an empty `Promise<void>` instead of a `Promise` resolving to the results of all `waitUntil()`ed `Promise`s.

```diff
+ import { createExecutionContext, waitOnExecutionContext } from "cloudflare:test";

  it("does something", () => {
    // ...
-   const ctx = new ExecutionContext();
+   const ctx = createExecutionContext();
    const response = worker.fetch(request, env, ctx);
-   await getMiniflareWaitUntil(ctx);
+   await waitOnExecutionContext(ctx);
  });
```

## Mock outbound requests

The `getMiniflareFetchMock()` function has been replaced with the new `fetchMock` helper from the `cloudflare:test` module. `fetchMock` has the same type as the return type of `getMiniflareFetchMock()`. There are a couple of differences between `fetchMock` and the previous return value of `getMiniflareFetchMock()`:

- `fetchMock` is deactivated by default, whereas previously it would start activated. This deactivation prevents unnecessary buffering of request bodies if you are not using `fetchMock`. You will need to call `fetchMock.activate()` before calling `fetch()` to enable it.
- `fetchMock` is reset at the start of each test run, whereas previously, interceptors added in previous runs would apply to the current one. This ensures test runs are not affected by previous runs.

```diff
  import { beforeAll, afterAll } from "vitest";
+ import { fetchMock } from "cloudflare:test";

- const fetchMock = getMiniflareFetchMock();
  beforeAll(() => {
+   fetchMock.activate();
    fetchMock.disableNetConnect();
    fetchMock
      .get("https://example.com")
      .intercept({ path: "/" })
      .reply(200, "data");
  });
  afterAll(() => fetchMock.assertNoPendingInterceptors());
```

## Use Durable Object helpers

The `getMiniflareDurableObjectStorage()`, `getMiniflareDurableObjectState()`, `getMiniflareDurableObjectInstance()`, and `runWithMiniflareDurableObjectGates()` functions have all been replaced with a single `runInDurableObject()` function from the `cloudflare:test` module. The `runInDurableObject()` function accepts a `DurableObjectStub` with a callback accepting the Durable Object and corresponding `DurableObjectState` as arguments. Consolidating these functions into a single function simplifies the API surface, and ensures instances are accessed with the correct request context and [gating behavior](https://blog.cloudflare.com/durable-objects-easy-fast-correct-choose-three/). Refer to the [Test APIs page](/workers/testing/vitest-integration/test-apis/) for more details.

```diff
+ import { env, runInDurableObject } from "cloudflare:test";

  it("does something", async () => {
-   const env = getMiniflareBindings();
    const id = env.OBJECT.newUniqueId();
+   const stub = env.OBJECT.get(id);

-   const storage = await getMiniflareDurableObjectStorage(id);
-   doSomethingWith(storage);
+   await runInDurableObject(stub, async (instance, state) => {
+     doSomethingWith(state.storage);
+   });

-   const state = await getMiniflareDurableObjectState(id);
-   doSomethingWith(state);
+   await runInDurableObject(stub, async (instance, state) => {
+     doSomethingWith(state);
+   });

-   const instance = await getMiniflareDurableObjectInstance(id);
-   await runWithMiniflareDurableObjectGates(state, async () => {
-     doSomethingWith(instance);
-   });
+   await runInDurableObject(stub, async (instance) => {
+     doSomethingWith(instance);
+   });
  });
```

The `flushMiniflareDurableObjectAlarms()` function has been replaced with the `runDurableObjectAlarm()` function from the `cloudflare:test` module. The `runDurableObjectAlarm()` function accepts a single `DurableObjectStub` and returns a `Promise` that resolves to `true` if an alarm was scheduled and the `alarm()` handler was executed, or `false` otherwise. To "flush" multiple instances' alarms, call `runDurableObjectAlarm()` in a loop.

```diff
+ import { env, runDurableObjectAlarm } from "cloudflare:test";

  it("does something", async () => {
-   const env = getMiniflareBindings();
    const id = env.OBJECT.newUniqueId();
-   await flushMiniflareDurableObjectAlarms([id]);
+   const stub = env.OBJECT.get(id);
+   const ran = await runDurableObjectAlarm(stub);
  });
```

Finally, the `getMiniflareDurableObjectIds()` function has been replaced with the `listDurableObjectIds()` function from the `cloudflare:test` module. The `listDurableObjectIds()` function now accepts a `DurableObjectNamespace` instance instead of a namespace `string` to provide stricter typing. Note the `listDurableObjectIds()` function now respects isolated storage. If enabled, IDs of objects created in other tests will not be returned.

```diff
+ import { env, listDurableObjectIds } from "cloudflare:test";

  it("does something", async () => {
-   const ids = await getMiniflareDurableObjectIds("OBJECT");
+   const ids = await listDurableObjectIds(env.OBJECT);
  });
```

---

# Migrate from unstable_dev

URL: https://developers.cloudflare.com/workers/testing/vitest-integration/migration-guides/migrate-from-unstable-dev/

The [`unstable_dev`](/workers/wrangler/api/#unstable_dev) API has been a recommended approach to run integration tests. The `@cloudflare/vitest-pool-workers` package integrates directly with Vitest for fast re-runs, supports both unit and integration tests, all whilst providing isolated per-test storage.

This guide demonstrates key differences between tests written with the `unstable_dev` API and the Workers Vitest integration. For more information on writing tests with the Workers Vitest integration, refer to [Write your first test](/workers/testing/vitest-integration/write-your-first-test/).

## Reference a Worker for integration testing

With `unstable_dev`, to trigger a `fetch` event, you would do this:

```js
import { unstable_dev } from "wrangler"

it("dispatches fetch event", () => {
  const worker = await unstable_dev("src/index.ts");
  const resp = await worker.fetch("http://example.com");
  ...
})
```

With the Workers Vitest integration, you can accomplish the same goal using `SELF` from `cloudflare:test`. `SELF` is a [service binding](/workers/runtime-apis/bindings/service-bindings/) to the default export defined by the `main` option in your [Wrangler configuration file](/workers/wrangler/configuration/). This `main` Worker runs in the same isolate as tests so any global mocks will apply to it too.

```js
import { SELF } from "cloudflare:test";
import "../src/"; // Currently required to automatically rerun tests when `main` changes

it("dispatches fetch event", async () => {
	const response = await SELF.fetch("http://example.com");
	...
});
```

## Stop a Worker

With the Workers Vitest integration, there is no need to stop a Worker via `worker.stop()`. This functionality is handled automatically after tests run.

## Import Wrangler configuration

Via the `unstable_dev` API, you can reference a [Wrangler configuration file](/workers/wrangler/configuration/) by adding it as an option:

```js
await unstable_dev("src/index.ts", {
	config: "wrangler.toml",
});
```

With the Workers Vitest integration, you can now set this reference to a [Wrangler configuration file](/workers/wrangler/configuration/) in `vitest.config.js` for all of your tests:

```js null {5-7}
export default defineWorkersConfig({
  test: {
    poolOptions: {
      workers: {
        wrangler: {
          configPath: "wrangler.toml",
        },
      },
    },
  },
});
---
```

## Test service Workers

Unlike the `unstable_dev` API, the Workers Vitest integration does not support testing Workers using the service worker format. You will need to first [migrate to the ES modules format](/workers/reference/migrate-to-module-workers/) in order to use the Workers Vitest integration.

## Define types

You can remove `UnstableDevWorker` imports from your code. Instead, follow the [Write your first test guide](/workers/testing/vitest-integration/write-your-first-test/#define-types) to define types for all of your tests.

```diff
- import { unstable_dev } from "wrangler";
- import type { UnstableDevWorker } from "wrangler";
+ import worker from "src/index.ts";

  describe("Worker", () => {
-   let worker: UnstableDevWorker;
    ...
  });
```

## Related resources

- [Write your first test](/workers/testing/vitest-integration/write-your-first-test/#define-types) - Write unit tests against Workers.

---

# HTML handling

URL: https://developers.cloudflare.com/workers/static-assets/routing/advanced/html-handling/

import { FileTree, WranglerConfig } from "~/components";

Forcing or dropping trailing slashes on request paths (for example, `example.com/page/` vs. `example.com/page`) is often something that developers wish to control for cosmetic reasons. Additionally, it can impact SEO because search engines often treat URLs with and without trailing slashes as different, separate pages. This distinction can lead to duplicate content issues, indexing problems, and overall confusion about the correct canonical version of a page.

The [`assets.html_handling` configuration](/workers/wrangler/configuration/#assets) determines the redirects and rewrites of requests for HTML content. It is used to specify the pattern for canonical URLs, thus where Cloudflare serves HTML content from, and additionally, where Cloudflare redirects non-canonical URLs to.

Take the following directory structure:

<FileTree>

- dist
  - file.html
  - folder
    - index.html

</FileTree>

## Automatic trailing slashes (default)

This will usually give you the desired behavior automatically: individual files (e.g. `foo.html`) will be served _without_ a trailing slash and folder index files (e.g. `foo/index.html`) will be served _with_ a trailing slash.

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "$today",
	"assets": {
		"directory": "./dist/",
		"html_handling": "auto-trailing-slash"
	}
}
```

</WranglerConfig>

Based on the incoming requests, the following assets would be served:

| Incoming Request   | Response        | Asset Served            |
| ------------------ | --------------- | ----------------------- |
| /file              | 200             | /dist/file.html         |
| /file.html         | 307 to /file    | -                       |
| /file/             | 307 to /file    | -                       |
| /file/index        | 307 to /file    | -                       |
| /file/index.html   | 307 to /file    | -                       |
| /folder            | 307 to /folder/ | -                       |
| /folder.html       | 307 to /folder  | -                       |
| /folder/           | 200             | /dist/folder/index.html |
| /folder/index      | 307 to /folder  | -                       |
| /folder/index.html | 307 to /folder  | -                       |

## Force trailing slashes

Alternatively, you can force trailing slashes (`force-trailing-slash`).

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "$today",
	"assets": {
		"directory": "./dist/",
		"html_handling": "force-trailing-slash"
	}
}
```

</WranglerConfig>

Based on the incoming requests, the following assets would be served:

| Incoming Request   | Response        | Asset Served            |
| ------------------ | --------------- | ----------------------- |
| /file              | 307 to /file/   | -                       |
| /file.html         | 307 to /file/   | -                       |
| /file/             | 200             | /dist/file.html         |
| /file/index        | 307 to /file/   | -                       |
| /file/index.html   | 307 to /file/   | -                       |
| /folder            | 307 to /folder/ | -                       |
| /folder.html       | 307 to /folder/ | -                       |
| /folder/           | 200             | /dist/folder/index.html |
| /folder/index      | 307 to /folder/ | -                       |
| /folder/index.html | 307 to /folder/ | -                       |

## Drop trailing slashes

Or you can drop trailing slashes (`drop-trailing-slash`).

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "$today",
	"assets": {
		"directory": "./dist/",
		"html_handling": "drop-trailing-slash"
	}
}
```

</WranglerConfig>

Based on the incoming requests, the following assets would be served:

| Incoming Request   | Response       | Asset Served            |
| ------------------ | -------------- | ----------------------- |
| /file              | 200            | /dist/file.html         |
| /file.html         | 307 to /file   | -                       |
| /file/             | 307 to /file   | -                       |
| /file/index        | 307 to /file   | -                       |
| /file/index.html   | 307 to /file   | -                       |
| /folder            | 200            | /dist/folder/index.html |
| /folder.html       | 307 to /folder | -                       |
| /folder/           | 307 to /folder | -                       |
| /folder/index      | 307 to /folder | -                       |
| /folder/index.html | 307 to /folder | -                       |

## Disable HTML handling

Alternatively, if you have bespoke needs, you can disable the built-in HTML handling entirely (`none`).

<WranglerConfig>

```json
{
	"name": "my-worker",
	"compatibility_date": "$today",
	"assets": {
		"directory": "./dist/",
		"html_handling": "none"
	}
}
```

</WranglerConfig>

Based on the incoming requests, the following assets would be served:

| Incoming Request   | Response                        | Asset Served                    |
| ------------------ | ------------------------------- | ------------------------------- |
| /file              | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /file.html         | 200                             | /dist/file.html                 |
| /file/             | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /file/index        | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /file/index.html   | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /folder            | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /folder.html       | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /folder/           | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /folder/index      | Depends on `not_found_handling` | Depends on `not_found_handling` |
| /folder/index.html | 200                             | /dist/folder/index.html         |

---

# Advanced

URL: https://developers.cloudflare.com/workers/static-assets/routing/advanced/

import { Badge, DirectoryListing } from "~/components";

Learn how to configure advanced routing options for the static assets of your Worker.

<DirectoryListing />

---

# Serving a subdirectory

URL: https://developers.cloudflare.com/workers/static-assets/routing/advanced/serving-a-subdirectory/

import { FileTree, WranglerConfig } from "~/components";

:::note
This feature requires Wrangler v3.98.0 or later.
:::

Like with any other Worker, [you can configure a Worker with assets to run on a path of your domain](/workers/configuration/routing/routes/).
Assets defined for a Worker must be nested in a directory structure that mirrors the desired path.

For example, to serve assets from `example.com/blog/*`, create a `blog` directory in your asset directory.

<FileTree>

- dist
  - blog
    - index.html
    - posts
      - post1.html
      - post2.html

</FileTree>

With a [Wrangler configuration file](/workers/wrangler/configuration/) like so:

<WranglerConfig>

```toml
name = "assets-on-a-path-example"
main = "src/index.js"
route = "example.com/blog/*"

[assets]
directory = "dist"
```

</WranglerConfig>

In this example, requests to `example.com/blog/` will serve the `index.html` file, and requests to `example.com/blog/posts/post1` will serve the `post1.html` file.

If you have a file outside the configured path, it will not be served, unless it is part of the `assets.not_found_handling` for [Single Page Applications](/workers/static-assets/routing/single-page-application/) or [custom 404 pages](/workers/static-assets/routing/static-site-generation/). For example, if you have a `home.html` file in the root of your asset directory, it will not be served when requesting `example.com/blog/home`. However, if needed, these files can still be manually fetched over [the binding](/workers/static-assets/binding/#binding).

---

# 1. Migrate webpack projects

URL: https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/eject-webpack/

import { WranglerConfig, PackageManagers } from "~/components";

This guide describes the steps to migrate a webpack project from Wrangler v1 to Wrangler v2. After completing this guide, [update your Wrangler version](/workers/wrangler/migration/v1-to-v2/update-v1-to-v2/).

Previous versions of Wrangler offered rudimentary support for [webpack](https://webpack.js.org/) with the `type` and `webpack_config` keys in the [Wrangler configuration file](/workers/wrangler/configuration/). Starting with Wrangler v2, Wrangler no longer supports the `type` and `webpack_config` keys, but you can still use webpack with your Workers.

As a developer using webpack with Workers, you may be in one of four categories:

1. [I use `[build]` to run webpack (or another bundler) external to `wrangler`.](#i-use-build-to-run-webpack-or-another-bundler-external-to-wrangler).

2. [I use `type = webpack`, but do not provide my own configuration and let Wrangler take care of it.](#i-use-type--webpack-but-do-not-provide-my-own-configuration-and-let-wrangler-take-care-of-it).

3. [I use `type = webpack` and `webpack_config = <path/to/webpack.config.js>` to handle JSX, TypeScript, WebAssembly, HTML files, and other non-standard filetypes.](#i-use-type--webpack-and-webpack_config--pathtowebpackconfigjs-to-handle-jsx-typescript-webassembly-html-files-and-other-non-standard-filetypes).

4. [I use `type = webpack` and `webpack_config = <path/to/webpack.config.js>` to perform code-transforms and/or other code-modifying functionality.](#i-use-type--webpack-and-webpack_config--pathtowebpackconfigjs-to-perform-code-transforms-andor-other-code-modifying-functionality).

If you do not see yourself represented, [file an issue](https://github.com/cloudflare/workers-sdk/issues/new/choose) and we can assist you with your specific situation and improve this guide for future readers.

### I use `[build]` to run webpack (or another bundler) external to Wrangler.

Wrangler v2 supports the `[build]` key, so your Workers will continue to build using your own setup.

### I use `type = webpack`, but do not provide my own configuration and let Wrangler take care of it.

Wrangler will continue to take care of it. Remove `type = webpack` from your Wrangler file.

### I use `type = webpack` and `webpack_config = <path/to/webpack.config.js>` to handle JSX, TypeScript, WebAssembly, HTML files, and other non-standard filetypes.

As of Wrangler v2, Wrangler has built-in support for this use case. Refer to [Bundling](/workers/wrangler/bundling/) for more details.

The Workers runtime handles JSX and TypeScript. You can `import` any modules you need into your code and the Workers runtime includes them in the built Worker automatically.

You should remove the `type` and `webpack_config` keys from your Wrangler file.

### I use `type = webpack` and `webpack_config = <path/to/webpack.config.js>` to perform code-transforms and/or other code-modifying functionality.

Wrangler v2 drops support for project types, including `type = webpack` and configuration via the `webpack_config` key. If your webpack configuration performs operations beyond adding loaders (for example, for TypeScript) you will need to maintain your custom webpack configuration. In the long term, you should [migrate to an external `[build]` process](/workers/wrangler/custom-builds/). In the short term, it is still possible to reproduce Wrangler v1's build steps in newer versions of Wrangler by following the instructions below.

1. Add [wranglerjs-compat-webpack-plugin](https://www.npmjs.com/package/wranglerjs-compat-webpack-plugin) as a `devDependency`.

[wrangler-js](https://www.npmjs.com/package/wrangler-js), shipped as a separate library from [Wrangler v1](https://www.npmjs.com/package/@cloudflare/wrangler/v/1.19.11), is a Node script that configures and executes [webpack 4](https://unpkg.com/browse/wrangler-js@0.1.11/package.json) for you. When you set `type = webpack`, Wrangler v1 would execute this script for you. We have ported the functionality over to a new package, [wranglerjs-compat-webpack-plugin](https://www.npmjs.com/package/wranglerjs-compat-webpack-plugin), which you can use as a [webpack plugin](https://v4.webpack.js.org/configuration/plugins/).

To do that, you will need to add it as a dependency:

<PackageManagers
	pkg="webpack@^4.46.0 webpack-cli wranglerjs-compat-webpack-plugin"
	dev
/>

You should see this reflected in your `package.json` file:

```json
{
	"name": "my-worker",
	"version": "x.y.z",
	// ...
	"devDependencies": {
		// ...
		"wranglerjs-compat-webpack-plugin": "^x.y.z",
		"webpack": "^4.46.0",
		"webpack-cli": "^x.y.z"
	}
}
```

2. Add `wranglerjs-compat-webpack-plugin` to `webpack.config.js`.

Modify your `webpack.config.js` file to include the plugin you just installed.

```js
const {
	WranglerJsCompatWebpackPlugin,
} = require("wranglerjs-compat-webpack-plugin");

module.exports = {
	// ...
	plugins: [new WranglerJsCompatWebpackPlugin()],
};
```

3. Add a build script your `package.json`.

```json
{
	"name": "my-worker",
	"version": "2.0.0",
	// ...
	"scripts": {
		"build": "webpack" // <-- Add this line!
		// ...
	}
}
```

4. Remove unsupported entries from your [Wrangler configuration file](/workers/wrangler/configuration/).

Remove the `type` and `webpack_config` keys from your Wrangler file, as they are not supported anymore.

<WranglerConfig>

```toml
# Remove these!
type = "webpack"
webpack_config = "webpack.config.js"
```

</WranglerConfig>

5. Tell Wrangler how to bundle your Worker.

Wrangler no longer has any knowledge of how to build your Worker. You will need to tell it how to call webpack and where to look for webpack's output. This translates into two fields:

<WranglerConfig>

```toml
main = "./worker/script.js" # by default, or whatever file webpack outputs
[build]
command = "npm run build" # or "yarn build"
# ...
```

</WranglerConfig>

6. Test your project.

Try running `npx wrangler deploy` to test that your configuration works as expected.

---

# Migrate from Wrangler v1 to v2

URL: https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/

import { DirectoryListing } from "~/components";

This guide details how to migrate from Wrangler v1 to v2.

<DirectoryListing />

---

# 2. Update to Wrangler v2

URL: https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/update-v1-to-v2/

This document describes the steps to migrate a project from Wrangler v1 to Wrangler v2. Before updating your Wrangler version, review and complete [Migrate webpack projects from Wrangler version 1](/workers/wrangler/migration/v1-to-v2/eject-webpack/) if it applies to your project.

Wrangler v2 ships with new features and improvements that may require some changes to your configuration.

The CLI itself will guide you through the upgrade process.

<div style="position: relative; padding-top: 56.25%;">
	<iframe
		src="https://iframe.videodelivery.net/2a60561afea1159f7dd270fd9dce999f?poster=https%3A%2F%2Fcloudflarestream.com%2F2a60561afea1159f7dd270fd9dce999f%2Fthumbnails%2Fthumbnail.jpg%3Ftime%3D%26height%3D600"
		style="border: none; position: absolute; top: 0; left: 0; height: 100%; width: 100%;"
		allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
		allowfullscreen="true"
	></iframe>
</div>

:::note

To learn more about the improvements to Wrangler, refer to [Wrangler v1 and v2 comparison](/workers/wrangler/deprecations/#wrangler-v1-and-v2-comparison-tables).
:::

## Update Wrangler version

### 1. Uninstall Wrangler v1

If you had previously installed Wrangler v1 globally using npm, you can uninstall it with:

```sh
npm uninstall -g @cloudflare/wrangler
```

If you used Cargo to install Wrangler v1, you can uninstall it with:

```sh
cargo uninstall wrangler
```

### 2. Install Wrangler

Now, install the latest version of Wrangler.

```sh
npm install -g wrangler
```

### 3. Verify your install

To check that you have installed the correct Wrangler version, run:

```sh
npx wrangler --version
```

## Test Wrangler v2 on your previous projects

Now you will test that Wrangler v2 can build your Wrangler v1 project. In most cases, it will build just fine. If there are errors, the command line should instruct you with exactly what to change to get it to build.

If you would like to read more on the deprecated [Wrangler configuration file](/workers/wrangler/configuration/) fields that cause Wrangler v2 to error, refer to [Deprecations](/workers/wrangler/deprecations/).

Run the `wrangler dev` command. This will show any warnings or errors that should be addressed.
Note that in most cases, the messages will include actionable instructions on how to resolve the issue.

```sh
npx wrangler dev
```

- Errors need to be fixed before Wrangler can build your Worker.
- In most cases, you will only see warnings.
  These do not stop Wrangler from building your Worker, but consider updating the configuration to remove them.

Here is an example of some warnings and errors:

```bash
 ⛅️ wrangler 2.x
-------------------------------------------------------
▲ [WARNING] Processing wrangler.toml configuration:
  - 😶 Ignored: "type":
    Most common features now work out of the box with wrangler, including modules, jsx,
  typescript, etc. If you need anything more, use a custom build.
  - Deprecation: "zone_id":
    This is unnecessary since we can deduce this from routes directly.
  - Deprecation: "build.upload.format":
    The format is inferred automatically from the code.


✘ [ERROR] Processing wrangler.toml configuration:
  - Expected "route" to be either a string, or an object with shape { pattern, zone_id | zone_name }, but got "".
```

## Deprecations

Refer to [Deprecations](/workers/wrangler/deprecations/) for more details on what is no longer supported.

---

# Angular

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/more-web-frameworks/angular/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
} from "~/components";

In this guide, you will create a new [Angular](https://angular.dev/) application and deploy to Cloudflare Workers (with the new [Workers Assets](/workers/static-assets/)).

## 1. Set up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Angular's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Angular project with Workers Assets, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-angular-app --framework=angular"
/>

After setting up your project, change your directory by running the following command:

```sh
cd my-angular-app
```

## 2. Develop locally

After you have created your project, run the following command in the project directory to start a local server. This will allow you to preview your project locally during development.

<PackageManagers type="run" args={"dev"} />

## 3. Deploy your Project

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).

The following command will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

---

## Static assets

<Render file="workers-assets-routing-summary" />

---

# Docusaurus

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/more-web-frameworks/docusaurus/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
} from "~/components";

In this guide, you will create a new [Docusaurus](https://docusaurus.io/) application and deploy to Cloudflare Workers (with the new [Workers Assets](/workers/static-assets/)).

## 1. Set up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Docusaurus' official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Docusaurus project with Workers Assets, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-docusaurus-app --framework=docusaurus"
/>

After setting up your project, change your directory by running the following command:

```sh
cd my-docusaurus-app
```

## 2. Develop locally

After you have created your project, run the following command in the project directory to start a local server. This will allow you to preview your project locally during development.

<PackageManagers type="run" args={"dev"} />

## 3. Deploy your Project

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).

The following command will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

---

# Gatsby

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/more-web-frameworks/gatsby/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
} from "~/components";

In this guide, you will create a new [Gatsby](https://www.gatsbyjs.com/) application and deploy to Cloudflare Workers (with the new [Workers Assets](/workers/static-assets/)).

## 1. Set up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Gatsby's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Gatsby project with Workers Assets, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-gatsby-app --framework=gatsby"
/>

After setting up your project, change your directory by running the following command:

```sh
cd my-gatsby-app
```

## 2. Develop locally

After you have created your project, run the following command in the project directory to start a local server. This will allow you to preview your project locally during development.

<PackageManagers type="run" args={"dev"} />

## 3. Deploy your Project

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).

The following command will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

---

# Hono

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/more-web-frameworks/hono/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
	Steps,
	Details,
	FileTree,
} from "~/components";

**Start from CLI** - scaffold a full-stack app with a Hono API, React SPA and the [Cloudflare Vite plugin](/workers/vite-plugin/) for lightning-fast development.

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-hono-app --template=cloudflare/templates/vite-react-template"
/>
---

**Or just deploy** - create a full-stack app using Hono, React and Vite, with CI/CD and previews all set up for you.

[![Deploy to Workers](https://deploy.workers.cloudflare.com/button)](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create/deploy-to-workers&repository=https://github.com/cloudflare/templates/tree/main/vite-react-template)

## What is Hono?

[Hono](https://hono.dev/) is an ultra-fast, lightweight framework for building web applications, and works fantastically with Cloudflare Workers.
With Workers Assets, you can easily combine a Hono API running on Workers with a SPA to create a full-stack app.

## Creating a full-stack Hono app with a React SPA

<Steps>
1. **Create a new project with the create-cloudflare CLI (C3)**

    	<PackageManagers
    	type="create"
    	pkg="cloudflare@latest"
    	args="my-hono-app --template=cloudflare/templates/vite-react-template"
    	/>
    		 <Details header="How is this project set up?">
        			Below is a simplified file tree of the project.
        			<FileTree>
        			- my-hono-app
        				- src
        					- worker/
        						- index.ts
        					- react-app/
        				- index.html
        				- vite.config.ts
        				- wrangler.jsonc
        			</FileTree>

        			`wrangler.jsonc` is your [Wrangler configuration file](/workers/wrangler/configuration/).
        			In this file:
        					- `main` points to `src/worker/index.ts`. This is your Hono app, which will run in a Worker.
        					- `assets.not_found_handling` is set to `single-page-application`, which means that routes that are handled by your SPA do not go to the Worker, and are thus free.
        					- If you want to add bindings to resources on Cloudflare's developer platform, you configure them here. Read more about [bindings](/workers/runtime-apis/bindings/).

    						`vite.config.ts` is set up to use the [Cloudflare Vite plugin](/workers/vite-plugin/). This runs your Worker in the Cloudflare Workers runtime, ensuring your local development environment is as close to production as possible.

    						`src/worker/index.ts` is your Hono app, which contains a single endpoint to begin with, `/api`.
    						At `src/react-app/src/App.tsx`, your React app calls this endpoint to get a message back and displays this in your SPA.
        		</Details>

2.  **Develop locally with the [Cloudflare Vite plugin](/workers/vite-plugin/)**

        After creating your project, run the following command in your project directory to start a local development server.
        <PackageManagers type="run" args="dev" />
        		<Details header="What's happening in local development?">
        			This project uses Vite for local development and build, and thus comes with all of Vite's features, including hot module replacement (HMR).

        			In addition, `vite.config.ts` is set up to use the Cloudflare Vite plugin. This runs your application in the Cloudflare Workers runtime, just like in production, and enables access to local emulations of bindings.
        		</Details>

3.  **Deploy your project**

        	Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including Cloudflare's own [Workers Builds](/workers/ci-cd/builds/).

        	The following command will build and deploy your project. If you are using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

        	<PackageManagers type="run" args={"deploy"} />

</Steps>

---

## Bindings

The [Hono documentation](https://hono.dev/docs/getting-started/cloudflare-workers#bindings) provides information on how you can access bindings in your Hono app.

<Render file="frameworks-bindings" />

---

# Nuxt

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/more-web-frameworks/nuxt/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
} from "~/components";

In this guide, you will create a new [Nuxt](https://nuxt.com/) application and deploy to Cloudflare Workers (with the new [Workers Assets](/workers/static-assets/)).

## 1. Set up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Nuxt's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Nuxt project with Workers Assets, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-nuxt-app --framework=nuxt"
/>

After setting up your project, change your directory by running the following command:

```sh
cd my-nuxt-app
```

## 2. Develop locally

After you have created your project, run the following command in the project directory to start a local server. This will allow you to preview your project locally during development.

<PackageManagers type="run" args={"dev"} />

## 3. Deploy your Project

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).

The following command will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

---

## Bindings

Your Nuxt application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using product bindings. The [Nuxt documentation](https://nitro.unjs.io/deploy/providers/cloudflare#direct-access-to-cloudflare-bindings) provides information about configuring bindings and how you can access them in your Nuxt event handlers.

<Render file="frameworks-bindings" />

---

# Qwik

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/more-web-frameworks/qwik/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
} from "~/components";

In this guide, you will create a new [Qwik](https://qwik.dev/) application and deploy to Cloudflare Workers (with the new [Workers Assets](/workers/static-assets/)).

## 1. Set up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Qwik's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Qwik project with Workers Assets, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-qwik-app --framework=qwik"
/>

After setting up your project, change your directory by running the following command:

```sh
cd my-qwik-app
```

## 2. Develop locally

After you have created your project, run the following command in the project directory to start a local server. This will allow you to preview your project locally during development.

<PackageManagers type="run" args={"dev"} />

## 3. Deploy your Project

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).

The following command will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

---

## Bindings

Your Qwik application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using product bindings. The [Qwik documentation](https://qwik.dev/docs/deployments/cloudflare-pages/#context) provides information about configuring bindings and how you can access them in your Qwik endpoint methods.

<Render file="frameworks-bindings" />

---

# Solid

URL: https://developers.cloudflare.com/workers/framework-guides/web-apps/more-web-frameworks/solid/

import {
	Badge,
	Description,
	InlineBadge,
	Render,
	PackageManagers,
} from "~/components";

:::note
Support for SolidStart projects on Cloudflare Workers is currently in beta.
:::

In this guide, you will create a new [Solid](https://www.solidjs.com/) application and deploy to Cloudflare Workers (with the new [Workers Assets](/workers/static-assets/)).

## 1. Set up a new project

Use the [`create-cloudflare`](https://www.npmjs.com/package/create-cloudflare) CLI (C3) to set up a new project. C3 will create a new project directory, initiate Solid's official setup tool, and provide the option to deploy instantly.

To use `create-cloudflare` to create a new Solid project with Workers Assets, run the following command:

<PackageManagers
	type="create"
	pkg="cloudflare@latest"
	args="my-solid-app --framework=solid --experimental"
/>

After setting up your project, change your directory by running the following command:

```sh
cd my-solid-app
```

## 2. Develop locally

After you have created your project, run the following command in the project directory to start a local server. This will allow you to preview your project locally during development.

<PackageManagers type="run" args={"dev"} />

## 3. Deploy your Project

Your project can be deployed to a `*.workers.dev` subdomain or a [Custom Domain](/workers/configuration/routing/custom-domains/), from your own machine or from any CI/CD system, including [Cloudflare's own](/workers/ci-cd/builds/).

The following command will build and deploy your project. If you're using CI, ensure you update your ["deploy command"](/workers/ci-cd/builds/configuration/#build-settings) configuration appropriately.

<PackageManagers type="run" args={"deploy"} />

---

## Bindings

Your Solid application can be fully integrated with the Cloudflare Developer Platform, in both local development and in production, by using product bindings. The [Solid documentation](https://docs.solidjs.com/reference/server-utilities/get-request-event) provides information about how to access platform primitives, including bindings. Specifically, for Cloudflare, you can use [`getRequestEnv().nativeEvent.context.cloudflare.env`](https://docs.solidjs.com/solid-start/advanced/request-events#nativeevent) to access bindings.

<Render file="frameworks-bindings" />

---

# Issue and validate certificates

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/

import { DirectoryListing } from "~/components";

Once you have [set up your Cloudflare for SaaS application](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/), you can start issuing and validating certificates for your customers.

<DirectoryListing />

---

# Issue

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/issue-certificates/

import { Render } from "~/components"

Cloudflare automatically issues certificates when you [create a custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/create-custom-hostnames/).

:::note


There are several required steps before a custom hostname and its certificate can become active. For more details, refer to our [Get started guide](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/).


:::

## Certificate authorities

If you create the custom hostname via API, you can leave the `certificate_authority` parameter empty to set it to “default CA”. With this option, Cloudflare checks the CAA records before requesting the certificates, which helps ensure the certificates can be issued from the CA.

Refer to [this certificate authorities reference page](/ssl/reference/certificate-authorities/) to learn more about the CAs that Cloudflare uses to issue SSL/TLS certificates.

## Certificate details and compatibility

<Render file="issue-certs-preamble" />

---

# Renew

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/renew-certificates/

import { Render } from "~/components"

The exact method for certificate renewal depends on whether that hostname is active[^1] and whether it is a wildcard certificate.

Custom hostnames certificates have a 90-day validity period and are available for renewal 30 days before their expiration.

## Non-wildcard hostnames

If you are using a non-wildcard hostname and the hostname is active, Cloudflare will try to perform DCV automatically on the hostname's behalf by serving the [HTTP token](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/http/).

If the custom hostname is not active, then the custom hostname domain owner will need to add the TXT or HTTP DCV token for the new certificate to validate and issue. As the SaaS provider, you will be responsible for sharing this token with the custom hostname domain owner.

## Wildcard hostnames

With wildcard hostnames, you cannot use HTTP. In this case, you will have to use TXT DCV tokens.

<Render file="txt-validation_preamble" />

<Render file="update-dcv-method" />

After this step, follow the normal steps for [TXT validation](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/txt/).

:::note
To allow Cloudflare to auto-renew all future certificate orders, consider [DCV delegation](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/delegated-dcv/).
:::

[^1]: Meaning Cloudflare could verify your customer's ownership of the hostname and the [hostname status](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/validation-status/) is active.

---

# Certificate signing requests (CSRs)

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/custom-certificates/certificate-signing-requests/

import { Render, APIRequest } from "~/components"

<Render file="csr-definition" product="ssl" />

Once the CSR has been generated, provide it to your customer. Your customer will then pass it along to their preferred CA to obtain a certificate and return it to you. After you receive the certificate, you should upload it to Cloudflare and reference the unique CSR ID that was provided to you during CSR creation.

<Render file="ssl-for-saas-plan-limitation" />

***

## Generate the private key and CSR

### 1. Build the CSR payload

All fields except for organizational\_unit and key\_type are required. If you do not specify a `key_type`, the default of `rsa2048` (RSA 2048 bit) will be used; the other option is `p256v1` (NIST P-256).

Common names are restricted to 64 characters and subject alternative names (SANs) are limited to 255 characters, [per RFC 5280](https://tools.ietf.org/html/rfc5280). You must specify at least one SAN, and the list of SANs should include the common name.

```bash
request_body=$(< <(cat <<EOF
{
  "country": "US",
  "state": "MA",
  "locality": "Boston",
  "organization": "City of Boston",
  "organizational_unit": "Championship Parade Detail",
  "common_name": "app.example.com",
  "sans": [
    "app.example.com",
    "www.example.com",
    "blog.example.com",
    "example.com"
  ],
  "key_type": "p256v1"
}
EOF
))
```

### 2. Generate a CSR

Now, you want to generate a CSR that you can provide to your customer.

```bash
curl https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_csrs \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data "$request_body"

# Response:
{
  "result": {
    "id": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752",
    "country": "US",
    "state": "MA",
    "locality": "Boston",
    "organization": "City of Boston",
    "organizational_unit": "Championship Parade Detail",
    "common_name": "app.example.com",
    "sans": [
      "app.example.com",
      "www.example.com",
      "blog.example.com",
      "example.com",
    ],
    "key_type": "p256v1",
    "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIBSzCB8gIBADBiMQswaQYDVQQGEwJVUzELMAkGA1UECBMCTUExDzANBgNVBAcT\nBkJvc3RvbjEaMBgGA1UEChMRQ2l0eSBvZiBDaGFtcGlvbnMxGTAXBgNVBAMTEGNz\nci1wcm9kLnRscy5mdW4wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAaTKf70NYlwr\n20P6P8xj8/4mTN5q28dbZR/gM3u4m/RPs24+PxAfMZCNvkVKAPVWYfUAadZI4Ha/\ndxLh5Q6X5bhIoC4wLAYJKoZIhvcNAQkOMR8wHTAbBqNVHREEFDASghBjc3ItcHJv\nZC50bHMuZnVuMAoGCCqGSM49BAMCA0gAMEUCIQDgtFUZav466SbT2FGBsIBlahDI\nVkg4y+u+V/K5DlY1+gIgQ9xLfUSKnSnJYbM9TwWr4Z964+lBtB9af4O5pp7/PSA=\n-----END CERTIFICATE REQUEST-----\n"
  },
  "success": true
```

Replace the `\n` characters with actual newlines before passing to your customer. This can be accomplished by piping the output of the prior call to a tool like jq and perl, such as:

```bash
curl https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_csrs \
--header "X-Auth-Email: <EMAIL>" \
--header "X-Auth-Key: <API_KEY>" \
--header "Content-Type: application/json" \
--data "$request_body" | jq .result.csr | perl -npe s'/\\n/\n/g; s/"//g' > csr.txt
```

### 3. Customer obtains certificate

Your customer will take the provided CSR and work with their CA to obtain a signed, publicly trusted certificate.

### 4. Upload the certificate

Upload the certificate and reference the ID that was provided when you generated the CSR.

You should replace newlines in the certificate with literal `\n` characters, as illustrated above in the custom certificate upload example. After doing so, build the request body and provide the ID that was returned in a previous step.

Cloudflare only accepts publicly trusted certificates. If you attempt to upload a self-signed certificate, it will be rejected.

```bash
$ MYCERT="$(cat app_example_com.pem|perl -pe 's/\r?\n/\\n/'|sed -e 's/..$//')"

$ request_body=$(< <(cat <<EOF
{
  "hostname": "app.example.com",
  "ssl": {
    "custom_csr_id": "7b163417-1d2b-4c84-a38a-2fb7a0cd7752",
    "custom_certificate": "$MYCERT"
  }
}
EOF
))
```

With the request body built, [create the custom hostname](/api/resources/custom_hostnames/methods/create/) with the supplied custom certificate. If you intend to use the certificate with multiple hostnames, make multiple API calls replacing the `hostname` field.

***

## Other actions

### List all CSRs

You can request the (paginated) collection of all previously generated custom CSRs by making a `GET` request to `https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_csrs`.

### Delete a CSR

Delete one or more of the CSRs to delete the underlying private key by making a `DELETE` request to `https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_csrs/{csr_id}`.

You may delete a CSR provided there are no custom certificates using the private key that was generated for the CSR. If you attempt to delete a CSR whose private key is still in use, you will receive an error.

---

# Custom certificates

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/custom-certificates/

import { Render } from "~/components"

If your customers need to provide their own key material, you may want to [upload a custom certificate](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/custom-certificates/uploading-certificates/). Cloudflare will automatically bundle the certificate with a certificate chain [optimized for maximum browser compatibility](/ssl/edge-certificates/custom-certificates/bundling-methodologies/#compatible).

As part of this process, you may also want to [generate a Certificate Signing Request (CSR)](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/custom-certificates/certificate-signing-requests/) for your customer so they do not have to manage the private key on their own.

<Render file="ssl-for-saas-plan-limitation" />

## Use cases

This situation commonly occurs when your customers use Extended Validation (EV) certificates (the “green bar”) or when their information security policy prohibits third parties from generating private keys on their behalf.

## Limitations

If you use custom certificates, you are responsible for the entire certificate lifecycle (initial upload, renewal, subsequent upload).

Cloudflare also only accepts publicly trusted certificates of these types:

* `SHA256WithRSA`
* `SHA1WithRSA`
* `ECDSAWithSHA256`

If you attempt to upload another type of certificate or a certificate that has been self-signed, it will be rejected.

---

# Manage custom certificates

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/custom-certificates/uploading-certificates/

import { Render, TabItem, Tabs } from "~/components"

Learn how to manage custom certificates for your Cloudflare for SaaS custom hostnames. For use cases and limitations, refer to [custom certificates](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/custom-certificates/).

## Upload certificates

This section describes the general process for uploading a custom certificate corresponding to one of the [supported types](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/custom-certificates/#limitations).

:::note
If you must support both RSA and ECDSA refer to [certificate packs](#use-certificate-packs-rsa-and-ecdsa) below.
:::

<Tabs syncKey="dashPlusAPI"> <TabItem label="Dashboard">

To upload a custom certificate in the dashboard, select **Custom certificate** while [creating your custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/create-custom-hostnames/).

For information about the **bundle method** options, refer to the [Cloudflare SSL/TLS documentation](/ssl/edge-certificates/custom-certificates/bundling-methodologies/).

</TabItem> <TabItem label="API">

The call below will upload a certificate for use with `app.example.com`.

Note that if you are using an ECC key generated by OpenSSL, you will need to first remove the `-----BEGIN EC PARAMETERS-----...-----END EC PARAMETERS-----` section of the file.

1. Update the file and build the payload

<Render file="custom-cert-file-example" product="ssl" />

```bash
$ echo $MYCERT
-----BEGIN CERTIFICATE-----\nMIIFJDCCBAygAwIBAgIQD0ifmj/Yi5NP/2gdUySbfzANBgkqhkiG9w0BAQsFADBN\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMScwJQYDVQQDEx5E...SzSHfXp5lnu/3V08I72q1QNzOCgY1XeL4GKVcj4or6cT6tX6oJH7ePPmfrBfqI/O\nOeH8gMJ+FuwtXYEPa4hBf38M5eU5xWG7\n-----END CERTIFICATE-----\n

$ request_body=$(< <(cat <<EOF
{
  "hostname": "app.example.com",
  "ssl": {
    "custom_certificate": "$MYCERT",
    "custom_key": "$MYKEY"
  }
}
EOF
))
```

2. Use a [`POST` request](/api/resources/custom_hostnames/methods/create/) to upload your certificate and key.

:::note
The serial number returned is unique to the issuer, but not globally unique. Additionally, it is returned as a string, not an integer.
:::

</TabItem> </Tabs>

## Use certificate packs: RSA and ECDSA

A certificate pack allows you to upload up to one RSA and one ECDSA custom certificates to a custom hostname. This process is currently only supported via API.

To upload an RSA and ECDSA certificate to a custom hostname, set the `bundle_method` to `force` and define the `custom_cert_bundle` property when [creating a custom hostname via API](/api/resources/custom_hostnames/methods/create/).

You can also use `"bundle_method": "force"` and `custom_cert_bundle` with a `PATCH` request to the [Edit Custom Hostname](/api/resources/custom_hostnames/methods/edit/) endpoint.

### Delete a custom certificate and private key

Use the [Delete Single Certificate And Key For Custom Hostname](/api/resources/custom_hostnames/subresources/certificate_pack/subresources/certificates/methods/delete/) endpoint to remove one of the custom certificates and corresponding key from a certificate pack.

You cannot delete a certificate if it is the only remaining certificate in the pack.

### Replace a custom certificate and private key

To replace a single custom certificate within a certificate pack that contains two bundled certificates, use the [Replace Custom Certificate And Custom Key In Custom Hostname](/api/resources/custom_hostnames/subresources/certificate_pack/subresources/certificates/methods/update/) endpoint.

You can only replace an RSA certificate with another RSA certificate, or an ECDSA certificate with another ECDSA certificate.

***

## Move to a Cloudflare certificate

If you want to switch from maintaining a custom certificate to using one issued by Cloudflare, you can migrate that certificate with zero downtime.

Send a [`PATCH` request](/api/resources/custom_hostnames/methods/edit/) to your custom hostname with a value for the DCV `method`. As soon as the [certificate is validated](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/) and the [hostname is validated](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/hostname-validation/), Cloudflare will remove the old custom certificate and begin serving the new one.

---

# Apex proxying

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/apex-proxying/

import { Render } from "~/components";

Apex proxying allows your customers to use their apex domains (`example.com`) with your SaaS application.

<Render file="ssl-for-saas-plan-limitation" />

## Benefits

In a normal Cloudflare for SaaS [setup](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/), your customers route traffic to your hostname by creating a `CNAME` record pointing to your CNAME target.

However, most DNS providers do not allow `CNAME` records at the zone's root[^1]. This means that your customers have to use a subdomain as a vanity domain (`shop.example.com`) instead of their domain apex (`example.com`).

This limitation does not apply with apex proxying. Cloudflare assigns a set of IP prefixes - cost associated, reach out to your account team - to your account (or uses your own if you have [BYOIP](/byoip/)). This means that customers can create a standard `A` record to route traffic to your domain, which can support the domain apex.

[^1]: Cloudflare offers this functionality through [CNAME flattening](/dns/cname-flattening/).

## Setup

- [Set up Apex Proxying](/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/apex-proxying/setup/)

---

# Setup

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/apex-proxying/setup/

import { Render } from "~/components"

To set up Cloudflare for SaaS for [apex proxying](/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/apex-proxying/) - as opposed to the [normal setup](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/) - perform the following steps.

***

<Render file="get-started-prereqs" params={{ one: "(this should be within the account associated with your IP prefixes)." }} />

***

## Initial setup

<Render file="get-started-initial-setup-preamble" /> <br/>

### 1. Get IP range

With apex proxying, you can either [bring your own IP range](/byoip/) or use a set of IP addresses provided by Cloudflare.

For more details on this step, reach out to your account team.

:::caution


These IP addresses are different than those associated with your Cloudflare zone.


:::

### 2. Create fallback origin

<Render file="get-started-fallback-origin" />

***

## Per-hostname setup

<Render file="get-started-per-hostname" />

### 3. Have customer create DNS record

To finish the custom hostname setup, your customer can set up either an A or CNAME record at their authoritative DNS provider.

:::note


If you want your customers to be able to use CNAME records, you will need to complete the [normal setup process](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/) as well.


:::

#### A record

If your customer uses an A record at their authoritative DNS provider, they need to point their hostname to the IP prefixed allocated for your account.

<Render file="get-started-check-statuses" />

Your customer's A record might look like the following:

```txt
example.com.  60  IN  A   192.0.2.1
```

#### CNAME record

If your customer uses a CNAME record at their authoritative DNS, they need to point their hostname to your [CNAME target](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/#2-optional-create-cname-target) [^1].

<Render file="get-started-check-statuses" />

Your customer's CNAME record might look like the following:

```txt
mystore.com CNAME customers.saasprovider.com
```

[^1]: <Render file="regional-services" />

#### Service continuation

<Render file="get-started-service-continuation" />

---

# Use fetch() handler

URL: https://developers.cloudflare.com/workers-ai/features/function-calling/embedded/examples/fetch/

A very common use case is to provide the LLM with the ability to perform API calls via function calling.

In this example the LLM will retrieve the weather forecast for the next 5 days.
To do so a `getWeather` function is defined that is passed to the LLM as tool.

The `getWeather`function extracts the user's location from the request and calls the external weather API via the Workers' [`Fetch API`](/workers/runtime-apis/fetch/) and returns the result.

```ts title="Embedded function calling example with fetch()"
import { runWithTools } from '@cloudflare/ai-utils';

type Env = {
	AI: Ai;
};

export default {
	async fetch(request, env, ctx) {
		// Define function
		const getWeather = async (args: { numDays: number }) => {
			const { numDays } = args;
      // Location is extracted from request based on
      // https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties
      const lat = request.cf?.latitude
      const long = request.cf?.longitude

      // Interpolate values for external API call
			const response = await fetch(
				`https://api.open-meteo.com/v1/forecast?latitude=${lat}&longitude=${long}&daily=temperature_2m_max,precipitation_sum&timezone=GMT&forecast_days=${numDays}`
			);
			return response.text();
		};
		// Run AI inference with function calling
		const response = await runWithTools(
			env.AI,
			// Model with function calling support
			'@hf/nousresearch/hermes-2-pro-mistral-7b',
			{
				// Messages
				messages: [
					{
						role: 'user',
						content: 'What the weather like the next 5 days? Respond as text',
					},
				],
				// Definition of available tools the AI model can leverage
				tools: [
					{
						name: 'getWeather',
						description: 'Get the weather for the next [numDays] days',
						parameters: {
							type: 'object',
							properties: {
								numDays: { type: 'numDays', description: 'number of days for the weather forecast' },
							},
							required: ['numDays'],
						},
						// reference to previously defined function
						function: getWeather,
					},
				],
			}
		);
		return new Response(JSON.stringify(response));
	},
} satisfies ExportedHandler<Env>;

```

---

# Examples

URL: https://developers.cloudflare.com/workers-ai/features/function-calling/embedded/examples/

import { DirectoryListing } from "~/components";

<DirectoryListing />

---

# Tools based on OpenAPI Spec

URL: https://developers.cloudflare.com/workers-ai/features/function-calling/embedded/examples/openapi/

Oftentimes APIs are defined and documented via [OpenAPI specification](https://swagger.io/specification/). The Cloudflare `ai-utils` package's `createToolsFromOpenAPISpec` function creates tools from the OpenAPI spec, which the LLM can then leverage to fulfill the prompt.

In this example the LLM will describe the a Github user, based Github's API and its OpenAPI spec.

```ts title="Embedded function calling example from OpenAPI Spec"
import { createToolsFromOpenAPISpec, runWithTools } from '@cloudflare/ai-utils';

type Env = {
	AI: Ai;
};

const APP_NAME = 'cf-fn-calling-example-app';

export default {
	async fetch(request, env, ctx) {
		const toolsFromOpenAPISpec = [
			// You can pass the OpenAPI spec link or contents directly
			...(await createToolsFromOpenAPISpec(
				'https://gist.githubusercontent.com/mchenco/fd8f20c8f06d50af40b94b0671273dc1/raw/f9d4b5cd5944cc32d6b34cad0406d96fd3acaca6/partial_api.github.com.json',
				{
					overrides: [
						{
							matcher: ({ url }) => {
								return url.hostname === 'api.github.com';
							},
							// for all requests on *.github.com, we'll need to add a User-Agent.
							values: {
								headers: {
									'User-Agent': APP_NAME,
								},
							},
						},
					],
				}
			)),
		];

		const response = await runWithTools(
			env.AI,
			'@hf/nousresearch/hermes-2-pro-mistral-7b',
			{
				messages: [
					{
						role: 'user',
						content: 'Who is cloudflare on Github and how many repos does the organization have?',
					},
				],
				tools: toolsFromOpenAPISpec,
			}
		);

		return new Response(JSON.stringify(response));
	},
} satisfies ExportedHandler<Env>;

```

---

# Use KV API

URL: https://developers.cloudflare.com/workers-ai/features/function-calling/embedded/examples/kv/

Interact with persistent storage to retrieve or store information enables for powerful use cases.

In this example we show how embedded function calling can interact with other resources on the Cloudflare Developer Platform with a few lines of code.
## Pre-Requisites

For this example to work, you need to provision a [KV](/kv/) namespace first. To do so, follow the [KV - Get started ](/kv/get-started/) guide.

Importantly, your Wrangler file must be updated to include the `KV` binding definition to your respective namespace.

## Worker code

```ts title="Embedded function calling example with KV API"
import { runWithTools } from "@cloudflare/ai-utils";

type Env = {
	AI: Ai;
	KV: KVNamespace;
};

export default {
	async fetch(request, env, ctx) {
		// Define function
		const updateKvValue = async ({
			key,
			value,
		}: {
			key: string;
			value: string;
		}) => {
			const response = await env.KV.put(key, value);
			return `Successfully updated key-value pair in database: ${response}`;
		};

		// Run AI inference with function calling
		const response = await runWithTools(
			env.AI,
			"@hf/nousresearch/hermes-2-pro-mistral-7b",
			{
				messages: [
					{ role: "system", content: "Put user given values in KV" },
					{ role: "user", content: "Set the value of banana to yellow." },
				],
				tools: [
					{
						name: "KV update",
						description: "Update a key-value pair in the database",
						parameters: {
							type: "object",
							properties: {
								key: {
									type: "string",
									description: "The key to update",
								},
								value: {
									type: "string",
									description: "The value to update",
								},
							},
							required: ["key", "value"],
						},
						function: updateKvValue,
					},
				],
			},
		);
		return new Response(JSON.stringify(response));
	},
} satisfies ExportedHandler<Env>;
```

## Verify results

To verify the results, run the following command

```sh
npx wrangler kv key get banana --binding KV --local
```

---

# Authentication

URL: https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/wrangler-legacy/authentication/

import { Render } from "~/components";

<Render file="wrangler-v1-deprecation" />

## Background

In Cloudflare’s system, a user can have multiple accounts and zones. As a result, your user is configured globally on your machine via a single Cloudflare Token. Your account(s) and zone(s) will be configured per project, but will use your Cloudflare Token to authenticate all API calls. A configuration file is created in a `.wrangler` directory in your computer’s home directory.

---

### Using commands

To set up Wrangler to work with your Cloudflare user, use the following commands:

- `login`: a command that opens a Cloudflare account login page to authorize Wrangler.
- `config`: an alternative to `login` that prompts you to enter your `email` and `api` key.
- `whoami`: run this command to confirm that your configuration is appropriately set up. When successful, this command will print out your account email and your `account_id` needed for your project's Wrangler file.

### Using environment variables

You can also configure your global user with environment variables. This is the preferred method for using Wrangler in CI (continuous integration) environments.

To customize the authentication tokens that Wrangler uses, you may provide the `CF_ACCOUNT_ID` and `CF_API_TOKEN` environment variables when running any Wrangler command. The account ID may be obtained from the Cloudflare dashboard in **Overview** and you may [create or reuse an existing API token](#generate-tokens).

```sh
CF_ACCOUNT_ID=accountID CF_API_TOKEN=veryLongAPIToken wrangler publish
```

Alternatively, you may use the `CF_EMAIL` and `CF_API_KEY` environment variable combination instead:

```sh
CF_EMAIL=cloudflareEmail CF_API_KEY=veryLongAPI wrangler publish
```

You can also specify or override the target Zone ID by defining the `CF_ZONE_ID` environment variable.

Defining environment variables inline will override the default credentials stored in `wrangler config` or in your Wrangler file.

---

## Generate Tokens

### API token

1. In **Overview**, select [**Get your API token**](/fundamentals/api/get-started/create-token/).
2. After being taken to the **Profile** page, select **Create token**.
3. Under the **API token templates** section, find the **Edit Cloudflare Workers** template and select **Use template**.
4. Fill out the rest of the fields and then select **Continue to summary**, where you can select **Create Token** and issue your token for use.

### Global API Key

1. In **Overview**, select **Get your API token**.
2. After being taken to the **Profile** page, scroll to **API Keys**.
3. Select **View** to copy your **Global API Key**.\*

:::caution[Warning]

\* Treat your Global API Key like a password. It should not be stored in version control or in your code – use environment variables if possible.

:::

---

## Use Tokens

After getting your token or key, you can set up your default credentials on your local machine by running `wrangler config`:

```sh
wrangler config
```

```sh output
Enter API token:
superlongapitoken
```

Use the `--api-key` flag to instead configure with email and global API key:

```sh
wrangler config --api-key
```

```sh output
Enter email:
testuser@example.com
Enter global API key:
superlongapikey
```

---

# Commands

URL: https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/wrangler-legacy/commands/

import { Render, Type, MetaInfo, WranglerConfig } from "~/components";

<Render file="wrangler-v1-deprecation" />

Complete list of all commands available for [`wrangler`](https://github.com/cloudflare/wrangler-legacy), the Workers CLI.

---

## generate

Scaffold a Cloudflare Workers project from a public GitHub repository.

```sh
wrangler generate [$NAME] [$TEMPLATE] [--type=$TYPE] [--site]
```

Default values indicated by =value.

- `$NAME` =worker optional

  - The name of the Workers project. This is both the directory name and `name` property in the generated [Wrangler configuration](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration/) file.

- `$TEMPLATE` =[https://github.com/cloudflare/worker-template](https://github.com/cloudflare/worker-template) optional

  - The GitHub URL of the [repository to use as the template](https://github.com/cloudflare/worker-template) for generating the project.

- `--type=$TYPE` =webpack optional

  - The type of project; one of `webpack`, `javascript`, or `rust`.

- `--site` optional
  - When defined, the default `$TEMPLATE` value is changed to [`cloudflare/workers-sdk/templates/worker-sites`](https://github.com/cloudflare/workers-sdk/tree/main/templates/worker-sites). This scaffolds a [Workers Site](/workers/configuration/sites/start-from-scratch) project.

---

## init

Create a skeleton [Wrangler configuration file](/workers/wrangler/configuration/) in an existing directory. This command can be used as an alternative to `generate` if you prefer to clone a template repository yourself or you already have a JavaScript project and would like to use Wrangler.

```sh
wrangler init [$NAME] [--type=$TYPE] [--site]
```

Default values indicated by =value.

- `$NAME` =(Name of working directory) optional

  - The name of the Workers project. This is both the directory name and `name` property in the generated [Wrangler configuration](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration/) file.

- `--type=$TYPE` =webpack optional

  - The type of project; one of `webpack`, `javascript`, or `rust`.

- `--site` optional
  - When defined, the default `$TEMPLATE` value is changed to [`cloudflare/workers-sdk/templates/worker-sites`](https://github.com/cloudflare/workers-sdk/tree/main/templates/worker-sites). This scaffolds a [Workers Site](/workers/configuration/sites/start-from-scratch) project.

---

## build

Build your project (if applicable). This command looks at your Wrangler file and reacts to the [`"type"` value](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration/#keys) specified.

When using `type = "webpack"`, Wrangler will build the Worker using its internal webpack installation. When using `type = "javascript"` , the [`build.command`](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration/#build-1), if defined, will run.

```sh
wrangler build [--env $ENVIRONMENT_NAME]
```

- `--env` optional
  - If defined, Wrangler will load the matching environment's configuration before building. Refer to [Environments](/workers/wrangler/environments/) for more information.

---

## login

Authorize Wrangler with your Cloudflare account. This will open a login page in your browser and request your account access permissions. This command is the alternative to `wrangler config` and it uses OAuth tokens.

```sh
wrangler login [--scopes-list] [--scopes $SCOPES]
```

All of the arguments and flags to this command are optional:

- `--scopes-list` optional
  - List all the available OAuth scopes with descriptions.
- `--scopes $SCOPES` optional
  - Allows to choose your set of OAuth scopes. The set of scopes must be entered in a whitespace-separated list,
    for example, `wrangler login --scopes account:read user:read`.

`wrangler login` uses all the available scopes by default if no flags are provided.

---

## logout

Remove Wrangler's authorization for accessing your account. This command will invalidate your current OAuth token and delete the configuration file, if present.

```sh
wrangler logout
```

This command only invalidates OAuth tokens acquired through the `wrangler login` command. However, it will try to delete the configuration file regardless of your authorization method.

If you wish to delete your API token, log in to the Cloudflare dashboard and go to **Overview** > **Get your API token** in the right side menu > select the three-dot menu on your Wrangler token and select **Delete** if you wish to delete your API token.

---

## config

Configure Wrangler so that it may acquire a Cloudflare API Token or Global API key, instead of OAuth tokens, in order to access and manage account resources.

```sh
wrangler config [--api-key]
```

- `--api-key` optional
  - To provide your email and global API key instead of a token. (This is not recommended for security reasons.)

You can also use environment variables to authenticate, or `wrangler login` to authorize with OAuth tokens.

---

## publish

Publish your Worker to Cloudflare. Several keys in your Wrangler file determine whether you are publishing to a `*.workers.dev` subdomain or a custom domain. However, custom domains must be proxied (orange-clouded) through Cloudflare. Refer to the [Get started guide](/workers/configuration/routing/custom-domains/) for more information.

```sh
wrangler publish [--env $ENVIRONMENT_NAME]
```

- `--env` optional
  - If defined, Wrangler will load the matching environment's configuration before building and deploying. Refer to [Environments](/workers/wrangler/environments/) for more information.

To use this command, the following fields are required in your Wrangler file:

- `name` string

  - The name of the Workers project. This is both the directory name and `name` property in the generated [Wrangler configuration](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration/) file.

- `type` string

  - The type of project; one of `webpack`, `javascript`, or `rust`.

- `account_id` string
  - The Cloudflare account ID. This can be found in the Cloudflare dashboard, for example, `account_id = "a655bacaf2b4cad0e2b51c5236a6b974"`.

You can publish to [\<your-worker>.\<your-subdomain>.workers.dev](https://workers.dev) or to a custom domain.

When you publish changes to an existing Worker script, all new requests will automatically route to the updated version of the Worker without downtime. Any inflight requests will continue running on the previous version until completion. Once all inflight requests have finished complete, the previous Worker version will be purged and will no longer handle requests.

### Publishing to workers.dev

To publish to [`*.workers.dev`](https://workers.dev), you will first need to have a subdomain registered. You can register a subdomain by executing the [`wrangler subdomain`](#subdomain) command.

After you have registered a subdomain, add `workers_dev` to your Wrangler file.

- `workers_dev` bool
  - When `true`, indicates that the Worker should be deployed to a `*.workers.dev` domain.

### Publishing to your own domain

To publish to your own domain, specify these three fields in your Wrangler file.

- `zone_id` string

  - The Cloudflare zone ID, for example, `zone_id = "b6558acaf2b4cad1f2b51c5236a6b972"`, which can be found in the [Cloudflare dashboard](https://dash.cloudflare.com).

- `route` string

  - The route you would like to publish to, for example, `route = "example.com/my-worker/*"`.

- `routes` Array
  - The routes you would like to publish to, for example, `routes = ["example.com/foo/*", example.com/bar/*]`.

:::note

Make sure to use only `route` or `routes`, not both.

:::

### Publishing the same code to multiple domains

To publish your code to multiple domains, refer to the [documentation for environments](/workers/wrangler/environments/).

---

## dev

`wrangler dev` is a command that establishes a connection between `localhost` and a global network server that operates your Worker in development. A `cloudflared` tunnel forwards all requests to the global network server, which continuously updates as your Worker code changes. This allows full access to Workers KV, Durable Objects and other Cloudflare developer platform products. The `dev` command is a way to test your Worker while developing.

```sh
wrangler dev [--env $ENVIRONMENT_NAME] [--ip <ip>] [--port <port>] [--host <host>] [--local-protocol <http|https>] [--upstream-protocol <http|https>]
```

- `--env` optional

  - If defined, Wrangler will load the matching environment's configuration. Refer to [Environments](/workers/wrangler/environments/) for more information.

- `--ip` optional

  - The IP to listen on, defaults to `127.0.0.1`.

- `--port` optional

  - The port to listen on, defaults to `8787`.

- `--host` optional

  - The host to forward requests to, defaults to the zone of the project or to `tutorial.cloudflareworkers.com` if unauthenticated.

- `--local-protocol` optional

  - The protocol to listen to requests on, defaults to `http`.

- `--upstream-protocol` optional
  - The protocol to forward requests to host on, defaults to `https`.

These arguments can also be set in your Wrangler file. Refer to the [`wrangler dev` configuration](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration/#dev) documentation for more information.

### Usage

You should run `wrangler dev` from your Worker directory. Wrangler will run a local server accepting requests, executing your Worker, and forwarding them to a host. If you want to use another host other than your zone or `tutorials.cloudflare.com`, you can specify with `--host example.com`.

```sh
wrangler dev
```

```sh output
💁  JavaScript project found. Skipping unnecessary build!
💁  watching "./"
👂  Listening on http://127.0.0.1:8787
```

With `wrangler dev` running, you can send HTTP requests to `localhost:8787` and your Worker should execute as expected. You will also see `console.log` messages and exceptions appearing in your terminal. If either of these things do not happen, or you think the output is incorrect, [file an issue](https://github.com/cloudflare/wrangler-legacy).

---

## tail

Start a session to livestream logs from a deployed Worker.

```sh
wrangler tail [--format $FORMAT] [--status $STATUS] [OPTIONS]
```

- `--format $FORMAT` json|pretty
  - The format of the log entries.
- `--status $STATUS`
  - Filter by invocation status \[possible values: `ok`, `error`, `canceled`].
- `--header $HEADER`
  - Filter by HTTP header.
- `--method $METHOD`
  - Filter by HTTP method.
- `--sampling-rate $RATE`
  - Add a percentage of requests to log sampling rate.
- `--search $SEARCH`
  - Filter by a text match in `console.log` messages.

After starting `wrangler tail` in a directory with a project, you will receive a live feed of console and exception logs for each request your Worker receives.

Like all Wrangler commands, run `wrangler tail` from your Worker’s root directory (the directory with your Wrangler file).

:::caution[Legacy issues with existing cloudflared configuration]

`wrangler tail` versions older than version 1.19.0 use `cloudflared` to run. Update to the [latest Wrangler version](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/install-update/) to avoid any issues.

:::

---

## preview

Preview your project using the [Cloudflare Workers preview service](https://cloudflareworkers.com/).

```sh
wrangler preview [--watch] [--env $ENVIRONMENT_NAME] [ --url $URL] [$METHOD] [$BODY]
```

Default values indicated by =value.

- `--env $ENVIRONMENT_NAME` optional

  - If defined, Wrangler will load the matching environment's configuration. Refer to [Environments](/workers/wrangler/environments/) for more information.

- `--watch` recommended

  - When enabled, any changes to the Worker project will continually update the preview service with the newest version of your project. By default, `wrangler preview` will only bundle your project a single time.

- `$METHOD` ="GET" optional

  - The type of request to preview your Worker with (`GET`, `POST`).

- `$BODY` ="Null" optional
  - The body string to post to your preview Worker request. For example, `wrangler preview post hello=hello`.

### kv_namespaces

If you are using [kv_namespaces](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration/#kv_namespaces) with `wrangler preview`, you will need to specify a `preview_id` in your Wrangler file before you can start the session. This is so that you do not accidentally write changes to your production namespace while you are developing. You may make `preview_id` equal to `id` if you would like to preview with your production namespace, but you should ensure that you are not writing values to KV that would break your production Worker.

To create a `preview_id` run:

```sh
wrangler kv:namespace create --preview "NAMESPACE"
```

### Previewing on Windows Subsystem for Linux (WSL 1/2)

#### Setting $BROWSER to your browser binary

WSL is a Linux environment, so Wrangler attempts to invoke `xdg-open` to open your browser. To make `wrangler preview` work with WSL, you should set your `$BROWSER` to the path of your browser binary:

```sh
export BROWSER="/mnt/c/tools/firefox.exe"
wrangler preview
```

Spaces in filepaths are not common in Linux, and some programs like `xdg-open` will break on [paths with spaces](https://github.com/microsoft/WSL/issues/3632#issuecomment-432821522). You can work around this by linking the binary to your `/usr/local/bin`:

```sh
ln -s "/mnt/c/Program Files/Mozilla Firefox/firefox.exe" firefox
export BROWSER=firefox
```

#### Setting $BROWSER to `wsl-open`

Another option is to install [wsl-open](https://github.com/4U6U57/wsl-open#standalone) and set the `$BROWSER` [env variable](/workers/configuration/environment-variables/) to `wsl-open` via `wsl-open -w`. This ensures that `xdg-open` uses `wsl-open` when it attempts to open your browser.

If you are using WSL 2, you will need to install `wsl-open` following their [standalone method](https://github.com/4U6U57/wsl-open#standalone) rather than through `npm`. This is because their npm package has not yet been updated with WSL 2 support.

---

## `route`

List or delete a route associated with a domain:

```sh
wrangler route list [--env $ENVIRONMENT_NAME]
```

Default values indicated by =value.

- `--env $ENVIRONMENT_NAME` optional
  - If defined, the changes will only apply to the specified environment. Refer to [Environments](/workers/wrangler/environments/) for more information.

This command will forward the JSON response from the [List Routes API](/api/resources/workers/subresources/routes/methods/list/). Each object within the JSON list will include the route id, route pattern, and the assigned Worker name for the route. Piping this through a tool such as `jq` will render the output nicely.

```sh
wrangler route delete $ID [--env $ENVIRONMENT_NAME]
```

Default values indicated by =value.

- `$ID` required

  - The hash of the route ID to delete.

- `--env $ENVIRONMENT_NAME` optional
  - If defined, the changes will only apply to the specified environment. Refer to [Environments](/workers/wrangler/environments/) for more information.

---

## subdomain

Create or change your [`*.workers.dev`](https://workers.dev) subdomain.

```sh
wrangler subdomain <name>
```

---

## secret

Interact with your secrets.

### `put`

Create or replace a secret.

```sh
wrangler secret put <name> --env ENVIRONMENT_NAME
Enter the secret text you would like assigned to the variable name on the Worker named my-worker-ENVIRONMENT_NAME:
```

You will be prompted to input the secret's value. This command can receive piped input, so the following example is also possible:

```sh
echo "-----BEGIN PRIVATE KEY-----\nM...==\n-----END PRIVATE KEY-----\n" | wrangler secret put PRIVATE_KEY
```

- `name`

  - The variable name to be accessible in the script.

- `--env $ENVIRONMENT_NAME` optional
  - If defined, the changes will only apply to the specified environment. Refer to [Environments](/workers/wrangler/environments/) for more information.

### `delete`

Delete a secret from a specific script.

```sh
wrangler secret delete <name> --env ENVIRONMENT_NAME
```

- `name`

  - The variable name to be accessible in the script.

- `--env $ENVIRONMENT_NAME` optional
  - If defined, the changes will only apply to the specified environment. Refer to [Environments](/workers/wrangler/environments/) for more information.

### `list`

List all the secret names bound to a specific script.

```sh
wrangler secret list --env ENVIRONMENT_NAME
```

- `--env $ENVIRONMENT_NAME` optional
  - If defined, only the specified environment's secrets will be listed. Refer to [Environments](/workers/wrangler/environments/) for more information.

---

## kv

The `kv` subcommand allows you to store application data in the Cloudflare network to be accessed from Workers using [Workers KV](https://www.cloudflare.com/products/workers-kv/). KV operations are scoped to your account, so in order to use any of these commands, you:

- must configure an `account_id` in your project's Wrangler file.
- run all `wrangler kv:<command>` operations in your terminal from the project's root directory.

### Getting started

To use Workers KV with your Worker, the first thing you must do is create a KV namespace. This is done with
the `kv:namespace` subcommand.

The `kv:namespace` subcommand takes a new binding name as its argument. A Workers KV namespace will be created using a concatenation of your Worker’s name (from your Wrangler file) and the binding name you provide:

```sh
wrangler kv:namespace create "MY_KV"
```

```sh output
🌀  Creating namespace with title "my-site-MY_KV"
✨  Success!
Add the following to your configuration file:
kv_namespaces = [
  { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }
]
```

Successful operations will print a new configuration block that should be copied into your Wrangler file. Add the output to the existing `kv_namespaces` configuration if already present. You can now access the binding from within a Worker:

```js
let value = await MY_KV.get("my-key");
```

To write a value to your KV namespace using Wrangler, run the `wrangler kv:key put` subcommand.

```sh
wrangler kv:key put --binding=MY_KV "key" "value"
```

```sh output
✨  Success
```

Instead of `--binding`, you may use `--namespace-id` to specify which KV namespace should receive the operation:

```sh
wrangler kv:key put --namespace-id=e29b263ab50e42ce9b637fa8370175e8 "key" "value"
```

```sh output
✨  Success
```

Additionally, KV namespaces can be used with environments. This is useful for when you have code that refers to
a KV binding like `MY_KV`, and you want to be able to have these bindings point to different namespaces (like
one for staging and one for production).

A Wrangler file with two environments:

<WranglerConfig>

```toml
[env.staging]
kv_namespaces = [
  { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }
]

[env.production]
kv_namespaces = [
  { binding = "MY_KV", id = "a825455ce00f4f7282403da85269f8ea" }
]
```

</WranglerConfig>

To insert a value into a specific KV namespace, you can use:

```sh
wrangler kv:key put --env=staging --binding=MY_MV "key" "value"
```

```sh output
✨  Success
```

Since `--namespace-id` is always unique (unlike binding names), you do not need to specify an `--env` argument.

### Concepts

Most `kv` commands require you to specify a namespace. A namespace can be specified in two ways:

1. With a `--binding`:

   ```sh
   wrangler kv:key get --binding=MY_KV "my key"
   ```

   - This can be combined with `--preview` flag to interact with a preview namespace instead of a production namespace.

2. With a `--namespace-id`:

   ```sh
   wrangler kv:key get --namespace-id=06779da6940b431db6e566b4846d64db "my key"
   ```

Most `kv` subcommands also allow you to specify an environment with the optional `--env` flag. This allows you to publish Workers running the same code but with different namespaces. For example, you could use separate staging and production namespaces for KV data in your Wrangler file:

<WranglerConfig>

```toml
type = "webpack"
name = "my-worker"
account_id = "<account id here>"
route = "staging.example.com/*"
workers_dev = false

kv_namespaces = [
  { binding = "MY_KV", id = "06779da6940b431db6e566b4846d64db" }
]

[env.production]
route = "example.com/*"
kv_namespaces = [
  { binding = "MY_KV", id = "07bc1f3d1f2a4fd8a45a7e026e2681c6" }
]
```

</WranglerConfig>

With the Wrangler file above, you can specify `--env production` when you want to perform a KV action on the namespace `MY_KV` under `env.production`. For example, with the Wrangler file above, you can get a value out of a production KV instance with:

```sh
wrangler kv:key get --binding "MY_KV" --env=production "my key"
```

To learn more about environments, refer to [Environments](/workers/wrangler/environments/).

### `kv:namespace`

#### `create`

Create a new namespace.

```sh
wrangler kv:namespace create $NAME [--env=$ENVIRONMENT_NAME] [--preview]
```

- `$NAME`

  - The name of the new namespace.

- `--env $ENVIRONMENT_NAME` optional

  - If defined, the changes will only apply to the specified environment. Refer to [Environments](/workers/wrangler/environments/) for more information.

- `--preview` optional
  - Interact with a preview namespace (the `preview_id` value) instead of production.

##### Usage

```sh
wrangler kv:namespace create "MY_KV"
🌀  Creating namespace with title "worker-MY_KV"
✨  Add the following to your wrangler.toml:
kv_namespaces = [
  { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }
]
```

```sh
wrangler kv:namespace create "MY_KV" --preview
🌀  Creating namespace with title "my-site-MY_KV_preview"
✨  Success!
Add the following to your wrangler.toml:
kv_namespaces = [
  { binding = "MY_KV", preview_id = "15137f8edf6c09742227e99b08aaf273" }
]
```

#### `list`

List all KV namespaces associated with an account ID.

```sh
wrangler kv:namespace list
```

##### Usage

This example passes the Wrangler command through the `jq` command:

```sh
wrangler kv:namespace list | jq "."
[
  {
    "id": "06779da6940b431db6e566b4846d64db",
    "title": "TEST_NAMESPACE"
  },
  {
    "id": "32ac1b3c2ed34ed3b397268817dea9ea",
    "title": "STATIC_CONTENT"
  }
]
```

#### `delete`

Delete a given namespace.

```sh
wrangler kv:namespace delete --binding= [--namespace-id=]
```

- `--binding` required (if no <code>--namespace-id</code>)

  - The name of the namespace to delete.

- `--namespace-id` required (if no <code>--binding</code>)

  - The ID of the namespace to delete.

- `--env $ENVIRONMENT_NAME` optional

  - If defined, the changes will only apply to the specified environment. Refer to [Environments](/workers/wrangler/environments/) for more information.

- `--preview` optional
  - Interact with a preview namespace instead of production.

##### Usage

```sh
wrangler kv:namespace delete --binding=MY_KV
Are you sure you want to delete namespace f7b02e7fc70443149ac906dd81ec1791? [y/n]
yes
🌀  Deleting namespace f7b02e7fc70443149ac906dd81ec1791
✨  Success
```

```sh
wrangler kv:namespace delete --binding=MY_KV --preview
Are you sure you want to delete namespace 15137f8edf6c09742227e99b08aaf273? [y/n]
yes
🌀  Deleting namespace 15137f8edf6c09742227e99b08aaf273
✨  Success
```

### `kv:key`

#### `put`

Write a single key-value pair to a particular namespace.

```sh
wrangler kv:key put --binding= [--namespace-id=] $KEY $VALUE
✨  Success
```

- `$KEY` required

  - The key to write to.

- `$VALUE` required

  - The value to write.

- `--binding` required (if no <code>--namespace-id</code>)

  - The name of the namespace to write to.

- `--namespace-id` required (if no <code>--binding</code>)

  - The ID of the namespace to write to.

- `--env $ENVIRONMENT_NAME` optional

  - If defined, the changes will only apply to the specified environment. Refer to [Environments](/workers/wrangler/environments/) for more information.

- `--preview` optional

  - Interact with a preview namespace instead of production. Pass this to the Wrangler file’s `kv_namespaces.preview_id` instead of `kv_namespaces.id`.

- `--ttl` optional

  - The lifetime (in number of seconds) the document should exist before expiring. Must be at least `60` seconds. This option takes precedence over the `expiration` option.

- `--expiration` optional

  - The timestamp, in UNIX seconds, indicating when the key-value pair should expire.

- `--path` optional
  - When defined, Wrangler reads the `--path` file location to upload its contents as KV documents. This is ideal for security-sensitive operations because it avoids saving keys and values into your terminal history.

##### Usage

```sh
wrangler kv:key put --binding=MY_KV "key" "value"
✨  Success
```

```sh
wrangler kv:key put --binding=MY_KV --preview "key" "value"
✨  Success
```

```sh
wrangler kv:key put --binding=MY_KV "key" "value" --ttl=10000
✨  Success
```

```sh
wrangler kv:key put --binding=MY_KV "key" value.txt --path
✨  Success
```

#### `list`

Output a list of all keys in a given namespace.

```sh
wrangler kv:key list --binding= [--namespace-id=] [--prefix] [--env]
```

- `--binding` required (if no <code>--namespace-id</code>)

  - The name of the namespace to list.

- `--namespace-id` required (if no <code>--binding</code>)

  - The ID of the namespace to list.

- `--env $ENVIRONMENT_NAME` optional

  - If defined, the changes will only apply to the specified environment. Refer to [Environments](/workers/wrangler/environments/) for more information.

- `--prefix` optional
  - A prefix to filter listed keys.

##### Usage

This example passes the Wrangler command through the `jq` command:

```sh
wrangler kv:key list --binding=MY_KV --prefix="public" | jq "."
[
  {
    "name": "public_key"
  },
  {
    "name": "public_key_with_expiration",
    "expiration": "2019-09-10T23:18:58Z"
  }
]
```

#### `get`

Read a single value by key from the given namespace.

```sh
wrangler kv:key get --binding= [--env=] [--preview] [--namespace-id=] "$KEY"
```

- `$KEY` required

  - The key value to get.

- `--binding` required (if no <code>--namespace-id</code>)

  - The name of the namespace to get from.

- `--namespace-id` required (if no <code>--binding</code>)

  - The ID of the namespace to get from.

- `--env $ENVIRONMENT_NAME` optional

  - If defined, the operation will only apply to the specified environment. Refer to [Environments](/workers/wrangler/environments/) for more information.

- `--preview` optional
  - Interact with a preview namespace instead of production. Pass this to use your Wrangler file’s `kv_namespaces.preview_id` instead of `kv_namespaces.id`

##### Usage

```sh
wrangler kv:key get --binding=MY_KV "key"
value
```

#### `delete`

Removes a single key value pair from the given namespace.

```sh
wrangler kv:key delete --binding= [--env=] [--preview] [--namespace-id=] "$KEY"
```

- `$KEY` required

  - The key value to delete.

- `--binding` required (if no <code>--namespace-id</code>)

  - The name of the namespace to delete from.

- `--namespace-id` required (if no <code>--binding</code>)

  - The id of the namespace to delete from.

- `--env` optional

  - Perform on a specific environment specified as `$ENVIRONMENT_NAME`.

- `--preview` optional
  - Interact with a preview namespace instead of production. Pass this to use your Wrangler configuration file's `kv_namespaces.preview_id` instead of `kv_namespaces.id`

##### Usage

```sh
wrangler kv:key delete --binding=MY_KV "key"
Are you sure you want to delete key "key"? [y/n]
yes
🌀  Deleting key "key"
✨  Success
```

### `kv:bulk`

#### `put`

Write a file full of key-value pairs to the given namespace.

```sh
wrangler kv:bulk put --binding= [--env=] [--preview] [--namespace-id=] $FILENAME
```

- `$FILENAME` required

  - The file to write to the namespace

- `--binding` required (if no <code>--namespace-id</code>)

  - The name of the namespace to put to.

- `--namespace-id` required (if no <code>--binding</code>)

  - The id of the namespace to put to.

- `--env $ENVIRONMENT_NAME` optional

  - If defined, the changes will only apply to the specified environment. Refer to [Environments](/workers/wrangler/environments/) for more information.

- `--preview` optional
  - Interact with a preview namespace instead of production. Pass this to use your Wrangler file’s `kv_namespaces.preview_id` instead of `kv_namespaces.id`

This command takes a JSON file as an argument with a list of key-value pairs to upload. An example of JSON input:

```json
[
	{
		"key": "test_key",
		"value": "test_value",
		"expiration_ttl": 3600
	}
]
```

In order to save JSON data, cast `value` to a string:

```json
[
	{
		"key": "test_key",
		"value": "{\"name\": \"test_value\"}",
		"expiration_ttl": 3600
	}
]
```

The schema below is the full schema for key-value entries uploaded via the bulk API:

- `key` <Type text="string" /> <MetaInfo text="required" />

  - The key’s name. The name may be 512 bytes maximum. All printable, non-whitespace characters are valid.

- `value` <Type text="string" /> <MetaInfo text="required" />

  - The UTF-8 encoded string to be stored, up to 25 MB in length.

- `expiration` int optional

  - The time, measured in number of seconds since the UNIX epoch, at which the key should expire.

- `expiration_ttl` int optional

  - The number of seconds the document should exist before expiring. Must be at least `60` seconds.

- `base64` bool optional
  - When true, the server will decode the value as base64 before storing it. This is useful for writing values that would otherwise be invalid JSON strings, such as images. Defaults to `false`.

If both `expiration` and `expiration_ttl` are specified for a given key, the API will prefer `expiration_ttl`.

##### Usage

```sh
wrangler kv:bulk put --binding=MY_KV allthethingsupload.json
🌀  uploading 1 key value pairs
✨  Success
```

#### `delete`

Delete all specified keys within a given namespace.

```sh
wrangler kv:bulk delete --binding= [--env=] [--preview] [--namespace-id=] $FILENAME
```

- `$FILENAME` required

  - The file with key-value pairs to delete.

- `--binding` required (if no <code>--namespace-id</code>)

  - The name of the namespace to delete from.

- `--namespace-id` required (if no <code>--binding</code>)

  - The ID of the namespace to delete from.

- `--env $ENVIRONMENT_NAME` optional

  - If defined, the changes will only apply to the specified environment. Refer to [Environments](/workers/wrangler/environments/) for more information.

- `--preview` optional
  - Interact with a preview namespace instead of production. Pass this to use your Wrangler file’s `kv_namespaces.preview_id` instead of `kv_namespaces.id`

This command takes a JSON file as an argument with a list of key-value pairs to delete. An example of JSON input:

```json
[
	{
		"key": "test_key",
		"value": ""
	}
]
```

- `key` <Type text="string" /> <MetaInfo text="required" />

  - The key’s name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid.

- `value` <Type text="string" /> <MetaInfo text="required" />

  - This field must be specified for deserialization purposes, but is unused because the provided keys are being deleted, not written.

##### Usage

```sh
wrangler kv:bulk delete --binding=MY_KV allthethingsdelete.json
```

```sh output
Are you sure you want to delete all keys in allthethingsdelete.json? [y/n]
y
🌀  deleting 1 key value pairs
✨  Success
```

---

## Environment variables

Wrangler supports any [Wrangler configuration file](/workers/wrangler/configuration/) keys passed in as environment variables. This works by passing in `CF_` + any uppercased TOML key. For example:

`CF_NAME=my-worker CF_ACCOUNT_ID=1234 wrangler dev`

---

## --help

```sh
wrangler --help
```

```sh output
👷 ✨  wrangler 1.12.3
The Wrangler Team <wrangler@cloudflare.com>

USAGE:
    wrangler [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    kv:namespace    🗂️  Interact with your Workers KV Namespaces
    kv:key          🔑  Individually manage Workers KV key-value pairs
    kv:bulk         💪  Interact with multiple Workers KV key-value pairs at once
    route           ➡️  List or delete worker routes.
    secret          🤫  Generate a secret that can be referenced in the worker script
    generate        👯  Generate a new worker project
    init            📥  Create a wrangler.toml for an existing project
    build           🦀  Build your worker
    preview         🔬  Preview your code temporarily on cloudflareworkers.com
    dev             👂  Start a local server for developing your worker
    publish         🆙  Publish your worker to the orange cloud
    config          🕵️  Authenticate Wrangler with a Cloudflare API Token or Global API Key
    subdomain       👷  Configure your workers.dev subdomain
    whoami          🕵️  Retrieve your user info and test your auth config
    tail            🦚  Aggregate logs from production worker
    login           🔓  Authorize Wrangler with your Cloudflare username and password
    logout          ⚙️  Remove authorization from Wrangler.
    help            Prints this message or the help of the given subcommand(s)
```

---

# Configuration

URL: https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration/

import { Render, WranglerConfig } from "~/components";

<Render file="wrangler-v1-deprecation" />

## Background

Your project will need some configuration before you can publish your Worker. Configuration is done through changes to keys and values stored in a Wrangler file located in the root of your project directory. You must manually edit this file to edit your keys and values before you can publish.

---

## Environments

The top-level configuration is the collection of values you specify at the top of your Wrangler file. These values will be inherited by all environments, unless otherwise defined in the environment.

The layout of a top-level configuration in a Wrangler file is displayed below:

<WranglerConfig>

```toml
name = "your-worker"
type = "javascript"
account_id = "your-account-id"

# This field specifies that the Worker
# will be deployed to a *.workers.dev domain
workers_dev = true

# -- OR --

# These fields specify that the Worker
# will deploy to a custom domain
zone_id = "your-zone-id"
routes = ["example.com/*"]
```

</WranglerConfig>

Environment configuration (optional): the configuration values you specify under an `[env.name]` in your Wrangler file.

Environments allow you to deploy the same project to multiple places under multiple names. These environments are utilized with the `--env` or `-e` flag on the [commands](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/commands/) that are deploying live Workers:

- `build`
- `dev`
- `preview`
- `publish`
- `secret`

Some environment properties can be [_inherited_](#keys) from the top-level configuration, but if new values are configured in an environment, they will always override those at the top level.

An example of an `[env.name]` configuration looks like this:

<WranglerConfig>

```toml
type = "javascript"

name = "your-worker"
account_id = "your-account-id"

[vars]
FOO = "default FOO value"
BAR = "default BAR value"

[[kv_namespaces]]
binding = "FOO"
id = "1a..."
preview_id = "1b..."

[env.helloworld]
# Now adding configuration keys for the "helloworld" environment.
# These new values will override the top-level configuration.
name = "your-worker-helloworld"
account_id = "your-other-account-id"

[env.helloworld.vars]
FOO = "env-helloworld FOO value"
BAR = "env-helloworld BAR value"

[[env.helloworld.kv_namespaces]]
  # Redeclare kv namespace bindings for each environment
  # NOTE: In this case, passing new IDs because new `account_id` value.
binding = "FOO"
id = "888..."
preview_id = "999..."
```

</WranglerConfig>

To deploy this example Worker to the `helloworld` environment, you would run `wrangler publish --env helloworld`.

---

## Keys

There are three types of keys in a Wrangler file:

- Top level only keys are required to be configured at the top level of your Wrangler file only; multiple environments on the same project must share this key's value.

- Inherited keys can be configured at the top level and/or environment. If the key is defined only at the top level, the environment will use the key's value from the top level. If the key is defined in the environment, the environment value will override the top-level value.

- Non-inherited keys must be defined for every environment individually.

- `name` inherited required

  - The name of your Worker script. If inherited, your environment name will be appended to the top level.

- `type` top level required

  - Specifies how `wrangler build` will build your project. There are three options: `javascript`, `webpack`, and `rust`. `javascript` checks for a build command specified in the `[build]` section, `webpack` builds your project using webpack v4, and `rust` compiles the Rust in your project to WebAssembly.

:::note

Cloudflare will continue to support `rust` and `webpack` project types, but recommends using the `javascript` project type and specifying a custom [`build`](#build) section.

:::

- `account_id` inherited required

  - This is the ID of the account associated with your zone. You might have more than one account, so make sure to use the ID of the account associated with the `zone_id` you provide, if you provide one. It can also be specified through the `CF_ACCOUNT_ID` environment variable.

- `zone_id` inherited optional

  - This is the ID of the zone or domain you want to run your Worker on. It can also be specified through the `CF_ZONE_ID` environment variable. This key is optional if you are using only a `*.workers.dev` subdomain.

- `workers_dev` inherited optional

  - This is a boolean flag that specifies if your Worker will be deployed to your [`*.workers.dev`](https://workers.dev) subdomain. If omitted, it defaults to false.

- `route` not inherited optional

  - A route, specified by URL pattern, on your zone that you would like to run your Worker on. <br />`route = "http://example.com/*"`. A `route` OR `routes` key is only required if you are not using a [`*.workers.dev`](https://workers.dev) subdomain.

- `routes` not inherited optional

  - A list of routes you would like to use your Worker on. These follow exactly the same rules a `route`, but you can specify a list of them.<br />`routes = ["http://example.com/hello", "http://example.com/goodbye"]`. A `route` OR `routes` key is only required if you are not using a `*.workers.dev` subdomain.

- `webpack_config` inherited optional

  - This is the path to a custom webpack configuration file for your Worker. You must specify this field to use a custom webpack configuration, otherwise Wrangler will use a default configuration for you. Refer to the [Wrangler webpack page](/workers/wrangler/migration/v1-to-v2/eject-webpack/) for more information.

- `vars` not inherited optional

  - An object containing text variables that can be directly accessed in a Worker script.

- `kv_namespaces` not inherited optional

  - These specify any [Workers KV](#kv_namespaces) Namespaces you want to access from inside your Worker.

- `site` inherited optional

  - Determines the local folder to upload and serve from a Worker.

- `dev` not inherited optional

  - Arguments for `wrangler dev` that configure local server.

- `triggers` inherited optional

  - Configures cron triggers for running a Worker on a schedule.

- `usage_model` inherited optional

  - Specifies the [Usage Model](/workers/platform/pricing/#workers) for your Worker. There are two options - [`bundled`](/workers/platform/limits/#worker-limits) and [`unbound`](/workers/platform/limits/#worker-limits). For newly created Workers, if the Usage Model is omitted it will be set to the [default Usage Model set on the account](https://dash.cloudflare.com/?account=workers/default-usage-model). For existing Workers, if the Usage Model is omitted, it will be set to the Usage Model configured in the dashboard for that Worker.

- `build` top level optional

  - Configures a custom build step to be run by Wrangler when building your Worker. Refer to the [custom builds documentation](#build) for more details.

### vars

The `vars` key defines a table of [environment variables](/workers/configuration/environment-variables/) provided to your Worker script. All values are plaintext values.

Usage:

<WranglerConfig>

```toml
[vars]
FOO = "some value"
BAR = "some other string"
```

</WranglerConfig>

The table keys are available to your Worker as global variables, which will contain their associated values.

```js
// Worker code:
console.log(FOO);
//=> "some value"

console.log(BAR);
//=> "some other string"
```

Alternatively, you can define `vars` using an inline table format. This style should not include any new lines to be considered a valid TOML configuration:

<WranglerConfig>

```toml
vars = { FOO = "some value", BAR = "some other string" }
```

</WranglerConfig>

:::note

Secrets should be handled using the [`wrangler secret`](/workers/wrangler/commands/#secret) command.

:::

### kv_namespaces

`kv_namespaces` defines a list of KV namespace bindings for your Worker.

Usage:

<WranglerConfig>

```toml
kv_namespaces = [
  { binding = "FOO", id = "0f2ac74b498b48028cb68387c421e279", preview_id = "6a1ddb03f3ec250963f0a1e46820076f" },
  { binding = "BAR", id = "068c101e168d03c65bddf4ba75150fb0", preview_id = "fb69528dbc7336525313f2e8c3b17db0" }
]
```

</WranglerConfig>

Alternatively, you can define `kv namespaces` like so:

<WranglerConfig>

```toml
[[kv_namespaces]]
binding = "FOO"
preview_id = "abc456"
id = "abc123"

[[kv_namespaces]]
binding = "BAR"
preview_id = "xyz456"
id = "xyz123"
```

</WranglerConfig>

Much like environment variables and secrets, the `binding` names are available to your Worker as global variables.

```js
// Worker script:

let value = await FOO.get("keyname");
//=> gets the value for "keyname" from
//=> the FOO variable, which points to
//=> the "0f2ac...e279" KV namespace
```

- `binding` required

  - The name of the global variable your code will reference. It will be provided as a [KV runtime instance](/kv/api/).

- `id` required

  - The ID of the KV namespace that your `binding` should represent. Required for `wrangler publish`.

- `preview_id` required

  - The ID of the KV namespace that your `binding` should represent during `wrangler dev` or `wrangler preview`. Required for `wrangler dev` and `wrangler preview`.

:::note

Creating your KV namespaces can be handled using Wrangler’s [KV Commands](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/commands/#kv).

You can also define your `kv_namespaces` using an [alternative TOML syntax](https://github.com/toml-lang/toml/blob/master/toml.md#user-content-table).

:::

### site

A [Workers Site](/workers/configuration/sites/start-from-scratch) generated with [`wrangler generate --site`](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/commands/#generate) or [`wrangler init --site`](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/commands/#init).

Usage:

<WranglerConfig>

```toml
[site]
bucket = "./public"
entry-point = "workers-site"
```

</WranglerConfig>

- `bucket` required

  - The directory containing your static assets. It must be a path relative to your Wrangler file. Example: `bucket = "./public"`

- `entry-point` optional

  - The location of your Worker script. The default location is `workers-site`. Example: `entry-point = "./workers-site"`

- `include` optional

  - An exclusive list of `.gitignore`-style patterns that match file or directory names from your `bucket` location. Only matched items will be uploaded. Example: `include = ["upload_dir"]`

- `exclude` optional

  - A list of `.gitignore`-style patterns that match files or directories in your `bucket` that should be excluded from uploads. Example: `exclude = ["ignore_dir"]`

You can also define your `site` using an [alternative TOML syntax](https://github.com/toml-lang/toml/blob/master/toml.md#user-content-inline-table).

#### Storage Limits

For exceptionally large pages, Workers Sites may not be ideal. There is a 25 MiB limit per page or file. Additionally, Wrangler will create an asset manifest for your files that will count towards your script’s size limit. If you have too many files, you may not be able to use Workers Sites.

#### Exclusively including files/directories

If you want to include only a certain set of files or directories in your `bucket`, add an `include` field to your
`[site]` section of your Wrangler file:

<WranglerConfig>

```toml
[site]
bucket = "./public"
entry-point = "workers-site"
include = ["included_dir"] # must be an array.
```

</WranglerConfig>

Wrangler will only upload files or directories matching the patterns in the `include` array.

#### Excluding files/directories

If you want to exclude files or directories in your `bucket`, add an `exclude` field to your `[site]` section of your Wrangler file:

<WranglerConfig>

```toml
[site]
bucket = "./public"
entry-point = "workers-site"
exclude = ["excluded_dir"] # must be an array.
```

</WranglerConfig>

Wrangler will ignore files or directories matching the patterns in the `exclude` array when uploading assets to Workers KV.

#### Include > Exclude

If you provide both `include` and `exclude` fields, the `include` field will be used and the `exclude` field will be ignored.

#### Default ignored entries

Wrangler will always ignore:

- `node_modules`
- Hidden files and directories
- Symlinks

#### More about include/exclude patterns

Refer to the [gitignore documentation](https://git-scm.com/docs/gitignore) to learn more about the standard matching patterns.

#### Customizing your Sites Build

Workers Sites projects use webpack by default. Though you can [bring your own webpack configuration](/workers/wrangler/migration/v1-to-v2/eject-webpack/), be aware of your `entry` and `context` settings.

You can also use the `[build]` section with Workers Sites, as long as your build step will resolve dependencies in `node_modules`. Refer to the [custom builds](#build) section for more information.

### triggers

A set of cron triggers used to call a Worker on a schedule.

Usage:

<WranglerConfig>

```toml
[triggers]
crons = ["0 0 * JAN-JUN FRI", "0 0 LW JUL-DEC *"]
```

</WranglerConfig>

- `crons` optional
  - A set of [cron expressions](https://crontab.guru/), where each expression is a separate schedule to run the Worker on.

### dev

Arguments for `wrangler dev` can be configured here so you do not have to repeatedly pass them.

Usage:

<WranglerConfig>

```toml
[dev]
port = 9000
local_protocol = "https"
```

</WranglerConfig>

- `ip` optional

  - IP address for the local `wrangler dev` server to listen on, defaults to `127.0.0.1`.

- `port` optional

  - Port for local `wrangler dev` server to listen on, defaults to `8787`.

- `local_protocol` optional

  - Protocol that local `wrangler dev` server listen to requests on, defaults to `http`.

- `upstream_protocol` optional

  - Protocol that `wrangler dev` forwards requests on, defaults to `https`.

### build

A custom build command for your project. There are two configurations based on the format of your Worker: `service-worker` and `modules`.

#### Service Workers

:::caution[Service Workers are deprecated]

Service Workers are deprecated, but still supported. We recommend using [Module Workers](/workers/reference/migrate-to-module-workers/) instead. New features may not be supported for Service Workers.

:::

This section is for customizing Workers with the `service-worker` format. These Workers use `addEventListener` and look like the following:

```js
addEventListener("fetch", (event) => {
	event.respondWith(new Response("I'm a service Worker!"));
});
```

Usage:

<WranglerConfig>

```toml
[build]
command = "npm install && npm run build"

[build.upload]
format = "service-worker"
```

</WranglerConfig>

##### `[build]`

- `command` optional

  - The command used to build your Worker. On Linux and macOS, the command is executed in the `sh` shell and the `cmd` shell for Windows. The `&&` and `||` shell operators may be used.

- `cwd` optional

  - The working directory for commands, defaults to the project root directory.

- `watch_dir` optional

  - The directory to watch for changes while using `wrangler dev`, defaults to the `src` relative to the project root directory.

##### `[build.upload]`

- `format` required

  - The format of the Worker script, must be `"service-worker"`.

:::note

Ensure the `main` field in your `package.json` references the Worker you want to publish.

:::

#### Modules

Workers now supports the ES Modules syntax. This format allows you to export a collection of files and/or modules, unlike the Service Worker format which requires a single file to be uploaded.

Module Workers `export` their event handlers instead of using `addEventListener` calls.

Modules receive all bindings (KV Namespaces, Environment Variables, and Secrets) as arguments to the exported handlers. With the Service Worker format, these bindings are available as global variables.

:::note

Refer to the [`fetch()` handler documentation](/workers/runtime-apis/handlers/fetch) to learn more about the differences between the Service Worker and Module worker formats.

:::

An uploaded module may `import` other uploaded ES Modules. If using the CommonJS format, you may `require` other uploaded CommonJS modules.

```js
import html from "./index.html";

export default {
	// * request is the same as `event.request` from the service worker format
	// * waitUntil() and passThroughOnException() are accessible from `ctx` instead of `event` from the service worker format
	// * env is where bindings like KV namespaces, Durable Object namespaces, Config variables, and Secrets
	// are exposed, instead of them being placed in global scope.
	async fetch(request, env, ctx) {
		const headers = { "Content-Type": "text/html;charset=UTF-8" };
		return new Response(html, { headers });
	},
};
```

To create a Workers project using Wrangler and Modules, add a `[build]` section:

<WranglerConfig>

```toml
[build]
command = "npm install && npm run build"

[build.upload]
format = "modules"
main = "./worker.mjs"
```

</WranglerConfig>

##### `[build]`

- `command` optional

  - The command used to build your Worker. On Linux and macOS system, the command is executed in the `sh` shell and the `cmd` shell for Windows. The `&&` and `||` shell operators may be used.

- `cwd` optional

  - The working directory for commands, defaults to the project root directory.

- `watch_dir` optional

  - The directory to watch for changes while using `wrangler dev`, defaults to the `src` relative to the project root directory.

##### `[build.upload]`

- `format` required

  - The format of the Workers script, must be `"modules"`.

- `dir` optional

  - The directory you wish to upload your modules from, defaults to the `dist` relative to the project root directory.

- `main` required

  - The relative path of the main module from `dir`, including the `./` prefix. The main module must be an ES module. For projects with a build script, this usually refers to the output of your JavaScript bundler.

:::note

If your project is written using CommonJS modules, you will need to re-export your handlers and Durable Object classes using an ES module shim. Refer to the [modules-webpack-commonjs](https://github.com/cloudflare/modules-webpack-commonjs) template as an example.

:::

- `rules` optional

  - An ordered list of rules that define which modules to import, and what type to import them as.
    You will need to specify rules to use Text, Data, and CompiledWasm modules, or when you wish to
    have a `.js` file be treated as an `ESModule` instead of `CommonJS`.

Defaults:

<WranglerConfig>

```toml
[build.upload]
format = "modules"
main = "./worker.mjs"

# You do not need to include these default rules in your [Wrangler configuration file](/workers/wrangler/configuration/), they are implicit.
# The default rules are treated as the last two rules in the list.

[[build.upload.rules]]
type = "ESModule"
globs = ["**/*.mjs"]

[[build.upload.rules]]
type = "CommonJS"
globs = ["**/*.js", "**/*.cjs"]
```

</WranglerConfig>

- `type` required

  - The module type, see the table below for acceptable options:

- `globs` required

  - UNIX-style [glob rules](https://docs.rs/globset/0.4.6/globset/#syntax) that are used to determine the module type to use for a given file in `dir`. Globs are matched against the module's relative path from `build.upload.dir` without the `./` prefix. Rules are evaluated in order, starting at the top.

- `fallthrough` optional

  - This option allows further rules for this module type to be considered if set to true. If not specified or set to false, further rules for this module type will be ignored.

---

## Example

To illustrate how these levels are applied, here is a Wrangler file using multiple environments:

<WranglerConfig>

```toml
# top level configuration
type = "javascript"
name = "my-worker-dev"
account_id = "12345678901234567890"
zone_id = "09876543210987654321"
route = "dev.example.com/*"
usage_model = "unbound"
kv_namespaces = [
  { binding = "FOO", id = "b941aabb520e61dcaaeaa64b4d8f8358", preview_id = "03c8c8dd3b032b0528f6547d0e1a83f3" },
  { binding = "BAR", id = "90e6f6abd5b4f981c748c532844461ae", preview_id = "e5011a026c5032c09af62c55ecc3f438" }
]

[build]
command = "webpack"
[build.upload]
format = "service-worker"

[site]
bucket = "./public"
entry-point = "workers-site"

[dev]
ip = "0.0.0.0"
port = 9000
local_protocol="http"
upstream_protocol="https"

# environment configuration
[env.staging]
name = "my-worker-staging"
route = "staging.example.com/*"
kv_namespaces = [
  { binding = "FOO", id = "0f2ac74b498b48028cb68387c421e279" },
  { binding = "BAR", id = "068c101e168d03c65bddf4ba75150fb0" }
]

# environment configuration
[env.production]
workers_dev= true
kv_namespaces = [
  { binding = "FOO", id = "0d2ac74b498b48028cb68387c421e233" },
  { binding = "BAR", id = "0d8c101e168d03c65bddf4ba75150f33" }
]
```

</WranglerConfig>

---

# Install / Update

URL: https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/wrangler-legacy/install-update/

import { Render } from "~/components";

<Render file="wrangler-v1-deprecation" />

## Install

### Install with `npm`

```sh
npm i @cloudflare/wrangler -g
```

:::note[EACCESS error]

You may have already installed npm. It is possible that an `EACCES` error may be thrown while installing Wrangler. This is related to how many systems install the npm binary. It is recommended that you reinstall npm using a Node version manager like [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) or [Volta](https://volta.sh/).

:::

### Install with `cargo`

Assuming you have Rust’s package manager, [Cargo](https://github.com/rust-lang/cargo), installed, run:

```sh
cargo install wrangler
```

Otherwise, to install Cargo, you must first install rustup. On Linux and macOS systems, `rustup` can be installed as follows:

```sh
curl https://sh.rustup.rs -sSf | sh
```

Additional installation methods are available [on the Rust site](https://forge.rust-lang.org/other-installation-methods.html).

Windows users will need to install Perl as a dependency for `openssl-sys` — [Strawberry Perl](https://www.perl.org/get.html) is recommended.

After Cargo is installed, you may now install Wrangler:

```sh
cargo install wrangler
```

:::note[Customize OpenSSL]

By default, a copy of OpenSSL is included to make things easier during installation, but this can make the binary size larger. If you want to use your system's OpenSSL installation, provide the feature flag `sys-openssl` when running install:

```sh
cargo install wrangler --features sys-openssl
```

:::

### Manual install

1. Download the binary tarball for your platform from the [releases page](https://github.com/cloudflare/wrangler-legacy/releases). You do not need the `wranglerjs-*.tar.gz` download – Wrangler will install that for you.

2. Unpack the tarball and place the Wrangler binary somewhere on your `PATH`, preferably `/usr/local/bin` for Linux/macOS or `Program Files` for Windows.

## Update

To update [Wrangler](https://github.com/cloudflare/wrangler-legacy), run one of the following:

### Update with `npm`

```sh
npm update -g @cloudflare/wrangler
```

### Update with `cargo`

```sh
cargo install wrangler --force
```

---

# Wrangler v1 (legacy)

URL: https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/wrangler-legacy/

import { DirectoryListing, Render } from "~/components";

The following documentation applied to Wrangler v1 usage.

<Render file="wrangler-v1-deprecation" />

<DirectoryListing />

---

# Webpack

URL: https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/wrangler-legacy/webpack/

import { Render, WranglerConfig } from "~/components";

<Render file="wrangler-v1-deprecation" />

Wrangler allows you to develop modern ES6 applications with support for modules. This support is possible because of Wrangler's [webpack](https://webpack.js.org/) integration. This document describes how Wrangler uses webpack to build your Workers and how you can bring your own configuration.

:::note[Configuration and webpack version]

Wrangler includes `webpack@4`. If you want to use `webpack@5`, or another bundler like esbuild or Rollup, you must set up [custom builds](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/configuration/#build) in your Wrangler file.

You must set `type = "webpack"` in your Wrangler file to use Wrangler's webpack integration. If you are encountering warnings about specifying `webpack_config`, refer to [backwards compatibility](#backwards-compatibility).

:::

## Sensible defaults

This is the default webpack configuration that Wrangler uses to build your Worker:

```js
module.exports = {
	target: "webworker",
	entry: "./index.js", // inferred from "main" in package.json
};
```

The `"main"` field in the `package.json` file determines the `entry` configuration value. When undefined or missing, `"main"` defaults to `index.js`, meaning that `entry` also defaults to `index.js`.

The default configuration sets `target` to `webworker`. This is the correct value because Cloudflare Workers are built to match the [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API). Refer to the [webpack documentation](https://webpack.js.org/concepts/targets/) for an explanation of this `target` value.

## Bring your own configuration

You can tell Wrangler to use a custom webpack configuration file by setting `webpack_config` in your Wrangler file. Always set `target` to `webworker`.

### Example

```js
module.exports = {
	target: "webworker",
	entry: "./index.js",
	mode: "production",
};
```

<WranglerConfig>

```toml
type = "webpack"
name = "my-worker"
account_id = "12345678901234567890"
workers_dev = true
webpack_config = "webpack.config.js"
```

</WranglerConfig>

### Example with multiple environments

It is possible to use different webpack configuration files within different [Wrangler environments](/workers/wrangler/environments/). For example, the `"webpack.development.js"` configuration file is used during `wrangler dev` for development, but other, more production-ready configurations are used when building for the staging or production environments:

<WranglerConfig>

```toml
type = "webpack"
name = "my-worker-dev"
account_id = "12345678901234567890"
workers_dev = true
webpack_config = "webpack.development.js"

[env.staging]
name = "my-worker-staging"
webpack_config = "webpack.staging.js"

[env.production]
name = "my-worker-production"
webpack_config = "webpack.production.js"
```

</WranglerConfig>

```js
module.exports = {
	target: "webworker",
	devtool: "cheap-module-source-map", // avoid "eval": Workers environment doesn’t allow it
	entry: "./index.js",
	mode: "development",
};
```

```js
module.exports = {
	target: "webworker",
	entry: "./index.js",
	mode: "production",
};
```

### Using with Workers Sites

Wrangler commands are run from the project root. Ensure your `entry` and `context` are set appropriately. For a project with structure:

```txt
.
├── public
│   ├── 404.html
│   └── index.html
├── workers-site
│   ├── index.js
│   ├── package-lock.json
│   ├── package.json
│   └── webpack.config.js
└── wrangler.toml
```

The corresponding `webpack.config.js` file should look like this:

```js
module.exports = {
	context: __dirname,
	target: "webworker",
	entry: "./index.js",
	mode: "production",
};
```

## Shimming globals

When you want to bring your own implementation of an existing global API, you may [shim](https://webpack.js.org/guides/shimming/#shimming-globals) a third-party module in its place as a webpack plugin.

For example, you may want to replace the `URL` global class with the `url-polyfill` npm package. After defining the package as a dependency in your `package.json` file and installing it, add a plugin entry to your webpack configuration.

### Example with webpack plugin

```js null {1,7,8,9,10,11}
const webpack = require("webpack");

module.exports = {
	target: "webworker",
	entry: "./index.js",
	mode: "production",
	plugins: [
		new webpack.ProvidePlugin({
			URL: "url-polyfill",
		}),
	],
};
```

## Backwards compatibility

If you are using `wrangler@1.6.0` or earlier, a `webpack.config.js` file at the root of your project is loaded automatically. This is not always obvious, which is why versions of Wrangler after `wrangler@1.6.0` require you to specify a `webpack_config` value in your Wrangler file.

When [upgrading from `wrangler@1.6.0`](/workers/wrangler/migration/v1-to-v2/wrangler-legacy/install-update/), you may encounter webpack configuration warnings. To resolve this, add `webpack_config = "webpack.config.js"` to your Wrangler file.

---

# Delegated

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/delegated-dcv/

import { Render } from "~/components"

Delegated DCV allows SaaS providers to delegate the DCV process to Cloudflare.

DCV Delegation requires your customers to place a one-time record at their authoritative DNS that allows Cloudflare to auto-renew all future certificate orders, so that there is no manual intervention from you or your customers at the time of the renewal.

***

## Setup

To set up Delegated DCV:

1. Add a [custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/create-custom-hostnames/) for your zone, choosing `TXT` as the **Certificate validation method**.
2. On **SSL/TLS** > **Custom Hostnames**, go to **DCV Delegation for Custom Hostnames**.
3. Copy the hostname value.
4. For each hostname, the domain owner needs to place a `CNAME` record at their authoritative DNS. In this example, the SaaS zone is `example.com`.
   ```txt
   _acme-challenge.example.com CNAME example.com.<COPIED_HOSTNAME>.
   ```

Once this is complete, Cloudflare will place two TXT DCV records - one for `example.com` and one for `*.example.com` - at the `example.com.<COPIED_HOSTNAME>` hostname. The CNAME record will need to stay in place in order to allow Cloudflare to continue placing the records for the renewals.

If desired, you could also manually fetch the DCV tokens and share them with your customers.

## Moved domains

If you [move your SaaS zone to another account](/fundamentals/manage-domains/move-domain/), you will need to update the `CNAME` record with a new hostname value.

---

# HTTP

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/http/

import { Details, Render } from "~/components"

HTTP validation involves adding a DCV token to your customer's origin.

***

## Non-wildcard custom hostnames

If your custom hostname does not include a wildcard, Cloudflare will always and automatically attempt to complete DCV through [HTTP validation](#http-automatic), even if you have selected **TXT** for your validation method.

This HTTP validation should succeed as long as your customer is pointing to your custom hostname and they do not have any [CAA records](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/troubleshooting/#certificate-authority-authorization-caa-records) blocking your chosen certificate authority.

## Wildcard custom hostnames

HTTP DCV validation is not allowed for wildcard certificates. You must use [TXT validation](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/txt/) instead.

***

## Validation methods

### HTTP (automatic)

If you value simplicity and your customers can handle a few minutes of downtime, you can rely on Cloudflare automatic HTTP validation.

Once you [create a new hostname](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/issue-certificates/) and choose the `http` validation method, all your customers have to do is add a CNAME to your `$CNAME_TARGET` and Cloudflare will take care of the rest.


<Details header="What happens after you create the custom hostname">

<Render file="cname-cert-verification" product="ssl" />


</Details>

:::note


Cloudflare is able to serve a random token from our edge due to the fact that `site.example.com` has a CNAME in place to `$CNAME_TARGET`, which ultimately resolves to Cloudflare IPs. If your customer has not yet added the CNAME, the CA will not be able to retrieve the token and the process will not complete.

We will attempt to retry this validation check for a finite period before timing out. Refer to [Validation Retry Schedule](/ssl/edge-certificates/changing-dcv-method/validation-backoff-schedule/) for more details.


:::

If you would like to complete the issuance process before asking your customer to update their CNAME (or before changing the resolution of your target CNAME to be proxied by Cloudflare), choose another validation method.

### HTTP (manual)

<Render file="ssl-for-saas-create-hostname" /> <br/>

* [**API**](/api/resources/custom_hostnames/methods/get/): Within the `ssl` object, store the values present in the `validation_records` array (specifically `http_url` and `http_body`).
* **Dashboard**: When viewing an individual certificate at **SSL/TLS** > **Custom Hostnames**, refer to the values for **Certificate validation request** and **Certificate validation response**.

At your origin, make the `http_body` available in a TXT record at the path specified in `http_url`. This path should also be publicly accessible to anyone on the Internet so your CA can access it.

Here is an example NGINX configuration that would return a token:

```txt
location "/.well-known/pki-validation/ca3-0052344e54074d9693e89e27486692d6.txt" {
       return 200 "ca3-be794c5f757b468eba805d1a705e44f6\n";
}
```

Once your configuration is live, test that the DCV text file is in place with `curl`:

```sh
$ curl "http://http-preval.example.com/.well-known/pki-validation/ca3-0052344e54074d9693e89e27486692d6.txt"
ca3-be794c5f757b468eba805d1a705e44f6
```

The token is valid for one check cycle. On the next check cycle, Cloudflare will ask the CA to recheck the URL, complete validation, and issue the certificate.

<Render file="ssl-for-saas-validate-patch" />

---

# Validate

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/

import { Render } from "~/components"

<Render file="dcv-definition" product="ssl" /> <br/>

## DCV situations

### Non-wildcard certificates

<Render file="http-dcv-situation" />

### Wildcard certificates

<Render file="txt-dcv-situation" /> <br/>

* [DCV Delegation](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/delegated-dcv/) (auto-issuance)
* [Manual](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/txt/)

### Minimize downtime

If you want to minimize downtime, explore one of the following methods to issue and deploy the certificate before onboarding your customers:

* [Delegated DCV](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/delegated-dcv/): Place a one-time record at your authoritative DNS that allows Cloudflare to auto-renew all future certificate orders.
* [TXT validation](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/txt/): Have your customers add a `TXT` record to their authoritative DNS.
* [Manual HTTP validation](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/http/#http-manual): Add a `TXT` record at your origin.

### Minimize customer effort

If you value simplicity and your customers can handle a few minutes of downtime, you can rely on Cloudflare [automatic HTTP validation](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/http/#http-automatic).

## Potential issues

To avoid or solve potential issues, refer to our [troubleshooting guide](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/troubleshooting/).

---

# Troubleshooting

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/troubleshooting/

## High-risk domains

Occasionally, a domain will be flagged as “high risk” by Cloudflare’s CA partners. Typically this is done only for domains with an Alexa ranking of 1-1,000 and domains that have been flagged for phishing or malware by Google’s Safe Browsing service.

If a domain is flagged by the CA, you need to contact Support before validation can finish. The API call will return indicating the failure, along with a link to where the ticket can be filed.

***

## Certificate Authority Authorization (CAA) records

CAA is a DNS resource record type defined in [RFC 6844](https://datatracker.ietf.org/doc/html/rfc6844) that allows a domain owner to indicate which CAs are allowed to issue certificates for them.

### For SaaS providers

If your customer has CAA records set on their domain, they will either need to add the following or remove CAA entirely:

```txt
example.com. IN CAA 0 issue "pki.goog"
example.com. IN CAA 0 issue "letsencrypt.org"
example.com. IN CAA 0 issue "ssl.com"
```

While it is possible for CAA records to be set on the subdomain your customer wishes to use with your service, it will usually be set on the domain apex. If they have CAA records on the subdomain, those will also have to be removed.

### For SaaS customers

In some cases, the validation may be prevented because your hostname points to a CNAME target where CAA records are defined.

In this case you would need to either select a Certificate Authority whose CAA records are present at the target, or review the configuration with the service provider that owns the target.

***

## Time outs

If a certificate issuance times out, the error message will indicate where the timeout occurred:

* Timed Out (Initializing)
* Timed Out (Validation)
* Timed Out (Issuance)
* Timed Out (Deployment)
* Timed Out (Deletion)

To fix this error, send a [PATCH request](/api/resources/custom_hostnames/methods/edit/) through the API or select **Refresh** for the specific custom hostname in the dashboard. If using the API, make sure that the `--data` field contains an `ssl` object with the same `method` and `type` as the original request.

If these return an error, delete and recreate the custom hostname.

***

## Immediate validation checks

You can send a [PATCH request](/api/resources/custom_hostnames/methods/edit/) to request an immediate validation check on any certificate. The PATCH data should include the same `ssl` object as the original request.

***

---

# TXT

URL: https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/txt/

import { Render, TabItem, Tabs } from "~/components";

<Render file="txt-validation-definition" product="ssl" /> <br />

## When to use

Generally, you should use TXT-based DCV when you cannot use [HTTP validation](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/http/) or [Delegated DCV](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/delegated-dcv/).

### Non-wildcard custom hostnames

If your custom hostname does not include a wildcard, Cloudflare will always and automatically attempt to complete DCV through [HTTP validation](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/http/#http-automatic), even if you have selected **TXT** for your validation method.

This HTTP validation should succeed as long as your customer is pointing to your custom hostname and they do not have any [CAA records](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/validate-certificates/troubleshooting/#certificate-authority-authorization-caa-records) blocking your chosen certificate authority.

### Wildcard custom hostnames

<Render file="wildcard-hostname-reqs" />

This means that - if you choose to use wildcard custom hostnames - you will need a way to share these DCV tokens with your customer.

---

### 1. Get TXT tokens

Once you [create a new hostname](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/issue-certificates/) and choose this validation method, your tokens will be ready after a few seconds.

<Render file="txt-validation_preamble" />

<Tabs syncKey="dashPlusAPI"> <TabItem label="API">

<Render file="txt-validation_api" />

</TabItem>

<TabItem label="Dashboard">

<Render file="txt-validation_dashboard" />

</TabItem> </Tabs>

### 2. Share with your customer

You will then need to share these TXT tokens with your customers.

### 3. Add DNS records (customer)

<Render file="txt-validation_post" />

<Render file="ssl-for-saas-validate-patch" />

### 4. (Optional) Fetch new tokens

Your DCV tokens expire after a [certain amount of time](/cloudflare-for-platforms/cloudflare-for-saas/reference/token-validity-periods/), depending on your certificate authority.

This means that, if your customers take too long to place their tokens at their authoritative DNS provider, you may need to [get new tokens](#1-get-txt-tokens) and re-share them with your customer.

---